# V1 Public API Baseline Status: Captured during Block 11.1. Starting commit: `775c2ed406f03a73a9b0ca621dea5b4482468616` Public import: ```dart import 'package:adhd_scheduler_core/scheduler_core.dart'; ``` The public library entry point is `lib/scheduler_core.dart`. It exports the following source files: - `src/models.dart` - `src/application_layer.dart` - `src/backlog.dart` - `src/child_tasks.dart` - `src/document_mapping.dart` - `src/free_slots.dart` - `src/locked_time.dart` - `src/occupancy_policy.dart` - `src/persistence_contract.dart` - `src/project_statistics.dart` - `src/quick_capture.dart` - `src/reminder_policy.dart` - `src/repositories.dart` - `src/scheduling_engine.dart` - `src/task_actions.dart` - `src/task_lifecycle.dart` - `src/task_statistics.dart` - `src/time_contracts.dart` - `src/today_state.dart` - `src/timeline_state.dart` This baseline is used by later chunks to distinguish intentional breaking changes from accidental API drift. ## Public enums | File | Enums | |---|---| | `src/application_layer.dart` | `ApplicationFailureCode` | | `src/models.dart` | `DomainValidationCode`, `TaskType`, `TaskStatus`, `PriorityLevel`, `RewardLevel`, `DifficultyLevel`, `ReminderProfile`, `BacklogTag` | | `src/backlog.dart` | `BacklogFilter`, `BacklogSortKey`, `BacklogStalenessMarker` | | `src/free_slots.dart` | `RequiredCommitmentScheduleStatus` | | `src/locked_time.dart` | `LockedWeekday`, `LockedBlockOverrideType` | | `src/occupancy_policy.dart` | `OccupancyCategory`, `OccupancySource` | | `src/project_statistics.dart` | `ProjectCompletionTimeBucket`, `ProjectSuggestionType`, `ProjectSuggestionConfidence` | | `src/quick_capture.dart` | `QuickCaptureStatus` | | `src/reminder_policy.dart` | `ReminderDirectiveAction`, `ReminderDirectiveReason`, `EffectiveReminderProfileSource` | | `src/scheduling_engine.dart` | `SchedulingNoticeType`, `SchedulingOperationCode`, `SchedulingOutcomeCode`, `SchedulingIssueCode`, `SchedulingMovementCode`, `SchedulingConflictCode` | | `src/task_actions.dart` | `FlexibleTaskQuickAction`, `RequiredTaskAction`, `PushDestination` | | `src/task_lifecycle.dart` | `TaskTransitionCode`, `TaskActivityCode`, `TaskTransitionOutcomeCode` | | `src/time_contracts.dart` | `LocalTimeResolution`, `NonexistentLocalTimePolicy`, `RepeatedLocalTimePolicy` | | `src/today_state.dart` | `TodayTimelineItemSource` | | `src/timeline_state.dart` | `TimelineItemCategory`, `TimelineBackgroundToken`, `TimelineRewardIconToken`, `TimelineDifficultyIconToken`, `TimelineQuickAction` | ## Public classes and top-level functions | File | Public API | |---|---| | `src/application_layer.dart` | `OwnerTimeZoneContext`, `ApplicationOperationContext`, `ApplicationFailure`, `ApplicationResult`, `ApplicationFailureException`, `ApplicationPersistenceException`, `ApplicationOperationRecord`, `OwnerSettings`, `TaskActivityRepository`, `ProjectStatisticsRepository`, `OwnerSettingsRepository`, `ApplicationOperationRepository`, `ApplicationUnitOfWorkRepositories`, `ApplicationUnitOfWork`, `ApplicationSchedulingLoader`, `InMemoryApplicationUnitOfWork` | | `src/models.dart` | `DomainValidationException`, `Task`, `ProjectProfile`, `TimeInterval` | | `src/backlog.dart` | `BacklogStalenessSettings`, `BacklogView` | | `src/child_tasks.dart` | `ChildTaskEntry`, `ChildTaskBreakUpRequest`, `ChildTaskBreakUpResult`, `ChildTaskBreakUpService`, `ChildTaskView`, `ChildTaskCompletionResult`, `ChildTaskCompletionService`, `ChildTaskSummary` | | `src/document_mapping.dart` | `TaskDocumentExtension`, `TaskStatisticsDocumentExtension`, `ProjectStatisticsDocumentExtension` | | `src/free_slots.dart` | `ProtectedFreeSlotConflict`, `RequiredCommitmentScheduleResult`, `FreeSlotService` | | `src/locked_time.dart` | `ClockTime`, `LockedBlockRecurrence`, `LockedBlock`, `LockedBlockOccurrence`, `LockedBlockOverride`, `LockedScheduleExpansion`, `expandLockedBlocksForDay`, `lockedSchedulingIntervalsForDay`, `trackCompletedDuringLockedHours`, `completedDuringLockedHoursMinutes` | | `src/occupancy_policy.dart` | `OccupancyEntry`, `OccupancyPolicy` | | `src/persistence_contract.dart` | `PersistenceEnumName` | | `src/project_statistics.dart` | `ProjectStatistics`, `ProjectStatisticsApplicationResult`, `ProjectStatisticsAggregationService`, `ProjectSuggestionPolicy`, `ProjectSuggestion`, `ProjectSuggestionSet`, `ProjectDefaultResolution`, `ProjectSuggestionService` | | `src/quick_capture.dart` | `QuickCaptureRequest`, `QuickCaptureResult`, `QuickCaptureService` | | `src/reminder_policy.dart` | `EffectiveReminderProfile`, `ReminderDirective`, `ReminderPolicyService` | | `src/repositories.dart` | `SchedulingStateSnapshot`, `InMemoryTaskRepository`, `InMemoryProjectRepository`, `InMemoryLockedBlockRepository`, `InMemorySchedulingSnapshotRepository` | | `src/scheduling_engine.dart` | `SchedulingWindow`, `SchedulingInput`, `SchedulingChange`, `SchedulingOverlap`, `SchedulingNotice`, `SchedulingResult`, `SchedulingEngine` | | `src/task_actions.dart` | `FlexibleTaskActionResult`, `PushDestinationResult`, `RequiredTaskActionResult`, `SurpriseTaskLogRequest`, `SurpriseTaskLogResult`, `FlexibleTaskActionService`, `RequiredTaskActionService`, `SurpriseTaskLogService` | | `src/task_lifecycle.dart` | `TaskActivity`, `TaskActivityApplicationResult`, `TaskActivityAccountingService`, `TaskTransitionResult`, `TaskTransitionService` | | `src/task_statistics.dart` | `TaskStatistics` | | `src/time_contracts.dart` | `Clock`, `SystemClock`, `FixedClock`, `IdGenerator`, `SequentialIdGenerator`, `CivilDate`, `WallTime`, `TimeZoneResolutionOptions`, `ResolvedLocalDateTime`, `TimeZoneResolver`, `FixedOffsetTimeZoneResolver` | | `src/today_state.dart` | `GetTodayStateRequest`, `TodayTimelineItem`, `TodayCompactState`, `TodayPendingNotice`, `TodayState`, `GetTodayStateQuery` | | `src/timeline_state.dart` | `TimelineItem`, `CompactTimelineState`, `TimelineItemMapper` | ## Current model baseline `TaskType` values: - `flexible` - `inflexible` - `critical` - `locked` - `surprise` - `freeSlot` `TaskStatus` values: - `planned` - `active` - `completed` - `missed` - `cancelled` - `noLongerRelevant` - `backlog` Current notable model fields: - `Task`: `id`, `title`, `projectId`, `type`, `status`, `priority`, `reward`, `difficulty`, `durationMinutes`, `scheduledStart`, `scheduledEnd`, `actualStart`, `actualEnd`, `completedAt`, `parentTaskId`, `backlogTags`, `reminderOverride`, `createdAt`, `updatedAt`, `stats` - `ProjectProfile`: `id`, `name`, `colorKey`, default priority/reward/ difficulty/reminder profile/duration fields - `ProjectStatistics`: completion count, duration sample counts, completion-time buckets, pushes-before-completion totals, reward/difficulty distributions, and reminder-profile observations - `TimeInterval`: `start`, `end`, optional `label` - `TaskStatistics`: skip/push/backlog/missed/cancelled/late/locked-hour, completed-after-shield, and push-before-completion counters. Parent/child completion patterns are carried as activity metadata. Known baseline gaps to preserve as explicit later work: - `TaskStatus` does not include `pushed` or `skipped`; Chunk 11.2 resolves the status/event distinction. - `Task` does not yet have an explicit backlog-entered timestamp field. - Instant ranges still use `DateTime`; locked recurrence dates, wall-clock rules, clocks, IDs, and timezone resolution are explicit Chunk 11.4 contracts. ## Intentional API Changes After Baseline Chunk 11.3 intentionally changed the public API: - Added `DomainValidationCode` and `DomainValidationException`. - Added `Task.actualStart`, `Task.actualEnd`, and `Task.reminderOverride`. - Added explicit `copyWith` clear flags for nullable task fields. - Added `ProjectProfile.copyWith(clearDefaultDuration: true)`. - Changed several public value constructors from `const` to runtime-validating constructors. - Public collection fields now expose unmodifiable snapshots instead of caller mutable collections. Chunk 11.4 intentionally changed the public API: - Added clock, ID, civil-date, wall-time, timezone resolver, DST policy, and fixed-offset resolver contracts in `src/time_contracts.dart`. - Exported `src/time_contracts.dart` from `scheduler_core.dart`. - Added `nonexistentLocalTime` and `ambiguousLocalTime` validation codes. - Changed `ClockTime` to a backwards-compatible alias of `WallTime`. - Changed locked block dates and override dates from `DateTime` to `CivilDate`. - Changed locked-time expansion helpers and override interval conversion to require explicit `timeZoneId` and `TimeZoneResolver`. - Added injected `Clock` boundaries to scheduling/action/child completion services and optional `IdGenerator` convenience wrappers for quick capture and surprise logging. - Added civil-date and wall-time persistence conventions that store strings without timezone conversion. Chunk 12.1 intentionally changed the public API: - Added `src/occupancy_policy.dart` and exported it from `scheduler_core.dart`. - Added `OccupancyCategory`, `OccupancySource`, `OccupancyEntry`, and `OccupancyPolicy`. - Added policy-derived `SchedulingInput.occupancyEntries`, `SchedulingInput.movablePlannedFlexibleTasks`, and `SchedulingInput.conflictReportingOccupancies`. - Changed `SchedulingInput.blockedIntervals` to derive from the central occupancy policy rather than from duplicated task-type filters. Chunk 12.2 intentionally changed the public API: - Added `src/free_slots.dart` and exported it from `scheduler_core.dart`. - Added `RequiredCommitmentScheduleStatus`, `ProtectedFreeSlotConflict`, `RequiredCommitmentScheduleResult`, and `FreeSlotService`. - Added validated Free Slot create/update helpers and a typed explicit required commitment scheduling result for protected-rest conflicts. Chunk 12.3 intentionally changed the public API: - Added optional `revealHiddenLockedDetails` parameters to `SurpriseTaskLogService.log` and `SurpriseTaskLogService.logNew`. - Defined `SurpriseTaskLogRequest.id` as the idempotency key for retrying the same surprise log operation. - Surprise tasks with known time now populate `actualStart` and `actualEnd` in addition to the existing scheduled interval compatibility fields. Chunk 12.4 intentionally changed the public API: - Added stable scheduler code enums: `SchedulingOperationCode`, `SchedulingOutcomeCode`, `SchedulingIssueCode`, `SchedulingMovementCode`, and `SchedulingConflictCode`. - Added `SchedulingResult.operationCode` and `SchedulingResult.outcomeCode`. - Added `SchedulingNotice.issueCode`, `SchedulingNotice.movementCode`, `SchedulingNotice.conflictCode`, and immutable `SchedulingNotice.parameters`. - Changed `SchedulingNotice` from a `const` constructor to a runtime constructor so notice parameters can be defensively copied. - Added a `SchedulingResult` assertion that each notice uses at most one issue, movement, or conflict code. Chunk 13.1 intentionally changed the public API: - Added `src/task_lifecycle.dart` and exported it from `scheduler_core.dart`. - Added `TaskTransitionCode`, `TaskActivityCode`, `TaskTransitionOutcomeCode`, `TaskActivity`, `TaskTransitionResult`, and `TaskTransitionService`. - Added `Task.completedAt` and `Task.copyWith(clearCompletion: true)`. - Added `TaskActivityDocumentFields` and `TaskDocumentFields.completedAt`. - Added activity and transition outcome fields to flexible, push-destination, and required task action results. - Routed flexible/required direct action services through the canonical transition service while preserving existing scheduling helper compatibility. Chunk 13.2 intentionally changed the public API: - Added `TaskActivityApplicationResult` and `TaskActivityAccountingService`. - Added `TaskStatistics.completedAfterShieldCount`, `TaskStatistics.completedAfterPushCount`, and `TaskStatistics.totalPushesBeforeCompletion`. - Added `TaskStatistics.recordPushesBeforeCompletion`. - Added matching `TaskStatisticsDocumentFields` constants and document mapping. - Added `appliedActivityIds` and `lockedIntervals` parameters to `TaskTransitionService.apply`. - Added actual/locked interval parameters to flexible and required action completion paths. - Added `SurpriseTaskLogResult.activities` and routed surprise completion through the same accounting boundary. Chunk 13.3 intentionally changed the public API: - Added `ChildTaskBreakUpRequest`, `ChildTaskBreakUpResult`, and `ChildTaskBreakUpService`. - Added `activities` and `transitionOutcomeCodes` to `ChildTaskCompletionResult`. - Added `transitionService` injection to `ChildTaskCompletionService`. - Added `operationId`, existing-activity, and applied-activity parameters to child and parent completion methods. - Added `ChildTaskCompletionService.completeParentFromChild`. - Routed parent/child completion through canonical lifecycle transitions and parent/child completion metadata. Chunk 13.4 intentionally changed the public API: - Added `src/project_statistics.dart` and exported it from `scheduler_core.dart`. - Added project-statistics enums, aggregate model, exactly-once aggregation result/service, suggestion policy/result types, and configured-default resolution. - Added `ProjectStatisticsDocumentFields`, `ProjectStatisticsDocumentMapping`, and `ProjectStatisticsDocumentExtension`. - Added project-statistics field sets to the persistence field registry. - Expanded completion activity metadata with duration, reward, difficulty, and reminder-profile observations for project aggregation. Chunk 13.5 intentionally changed the public API: - Added `src/reminder_policy.dart` and exported it from `scheduler_core.dart`. - Added reminder directive action/reason enums and effective-profile source enum. - Added `EffectiveReminderProfile`, `ReminderDirective`, and `ReminderPolicyService`. - Added deterministic effective-profile resolution using task override, project configured default, then fallback. - Added typed reminder directives for normal delivery, suppression, deferral, and required-task acknowledgement, including protected Free Slot suppression. Chunk 14.1 intentionally changed the public API: - Added `src/application_layer.dart` and exported it from `scheduler_core.dart`. - Added application operation context, owner time-zone context, typed result/failure contracts, and expected application/persistence exceptions. - Added activity, project-statistics, owner-settings, operation-record, and unit-of-work repository contracts for application orchestration. - Added `OwnerSettings`, `ApplicationOperationRecord`, `ApplicationSchedulingLoader`, and `InMemoryApplicationUnitOfWork`. - Added in-memory staged transaction behavior with exactly-once operation records and rollback on typed failures or persistence failures. Chunk 14.2 intentionally changed the public API: - Added `src/today_state.dart` and exported it from `scheduler_core.dart`. - Added `GetTodayStateQuery`, `GetTodayStateRequest`, `TodayState`, `TodayTimelineItem`, `TodayCompactState`, and `TodayPendingNotice`. - Added `TodayTimelineItemSource` for stable task-vs-overlay source metadata. - Added `ApplicationUnitOfWork.read` so application queries can access repositories without creating operation records. - Added an optional `occurrenceDate` parameter to `TimelineItemMapper.fromLockedOccurrence` so Today read models can produce date-stable locked overlay IDs. - Updated compact next-flexible selection so the current flexible item is not also returned as `nextFlexibleItem`. ## Repository contracts The current repository surface is pure Dart and in-memory only: - Task repository behavior is represented by `InMemoryTaskRepository`. - Project repository behavior is represented by `InMemoryProjectRepository`. - Locked block repository behavior is represented by `InMemoryLockedBlockRepository`. - Snapshot repository behavior is represented by `InMemorySchedulingSnapshotRepository`. - Application transaction behavior is represented by `InMemoryApplicationUnitOfWork`. - Application read-query behavior uses `ApplicationUnitOfWork.read`, which stages repository access without committing operation records. Future MongoDB adapter work must remain behind repository interfaces and must not import MongoDB APIs into the scheduling core.