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

part of '../../application_layer.dart';

/// Per-operation application context.
class ApplicationOperationContext {
  /// Creates a `ApplicationOperationContext` 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.
  ApplicationOperationContext({
    required String operationId,
    required this.now,
    required this.ownerTimeZone,
    required this.clock,
    required this.idGenerator,
  }) : operationId = _requiredTrimmed(operationId, 'operationId');

  /// Convenience constructor that captures [Clock.now] once.
  factory ApplicationOperationContext.start({
    required String operationId,
    required OwnerTimeZoneContext ownerTimeZone,
    required Clock clock,
    required IdGenerator idGenerator,
  }) {
    return ApplicationOperationContext(
      operationId: operationId,
      now: clock.now(),
      ownerTimeZone: ownerTimeZone,
      clock: clock,
      idGenerator: idGenerator,
    );
  }

  /// Exactly-once key for this user command.
  final String operationId;

  /// Instant used by the operation. Use this instead of repeatedly reading the
  /// clock during one command.
  final DateTime now;

  /// Owner scope and time-zone data for date-sensitive rules.
  final OwnerTimeZoneContext ownerTimeZone;

  /// Injected clock available to lower-level services that need one.
  final Clock clock;

  /// Injected ID generator for records created by the operation.
  final IdGenerator idGenerator;
}
