focus-flow/Codex Documentation/Current Software Plan/V1_PUBLIC_API_BASELINE.md

# 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/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/quick_capture.dart`
- `src/repositories.dart`
- `src/scheduling_engine.dart`
- `src/task_actions.dart`
- `src/task_statistics.dart`
- `src/time_contracts.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/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/quick_capture.dart` | `QuickCaptureStatus` |
| `src/scheduling_engine.dart` | `SchedulingNoticeType`, `SchedulingOperationCode`, `SchedulingOutcomeCode`, `SchedulingIssueCode`, `SchedulingMovementCode`, `SchedulingConflictCode` |
| `src/task_actions.dart` | `FlexibleTaskQuickAction`, `RequiredTaskAction`, `PushDestination` |
| `src/time_contracts.dart` | `LocalTimeResolution`, `NonexistentLocalTimePolicy`, `RepeatedLocalTimePolicy` |
| `src/timeline_state.dart` | `TimelineItemCategory`, `TimelineBackgroundToken`, `TimelineRewardIconToken`, `TimelineDifficultyIconToken`, `TimelineQuickAction` |

## Public classes and top-level functions

| File | Public API |
|---|---|
| `src/models.dart` | `DomainValidationException`, `Task`, `ProjectProfile`, `TimeInterval` |
| `src/backlog.dart` | `BacklogStalenessSettings`, `BacklogView` |
| `src/child_tasks.dart` | `ChildTaskEntry`, `ChildTaskView`, `ChildTaskCompletionResult`, `ChildTaskCompletionService`, `ChildTaskSummary` |
| `src/document_mapping.dart` | `TaskDocumentExtension`, `TaskStatisticsDocumentExtension` |
| `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/quick_capture.dart` | `QuickCaptureRequest`, `QuickCaptureResult`, `QuickCaptureService` |
| `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_statistics.dart` | `TaskStatistics` |
| `src/time_contracts.dart` | `Clock`, `SystemClock`, `FixedClock`, `IdGenerator`, `SequentialIdGenerator`, `CivilDate`, `WallTime`, `TimeZoneResolutionOptions`, `ResolvedLocalDateTime`, `TimeZoneResolver`, `FixedOffsetTimeZoneResolver` |
| `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`, `parentTaskId`, `backlogTags`,
  `reminderOverride`, `createdAt`, `updatedAt`, `stats`
- `ProjectProfile`: `id`, `name`, `colorKey`, default priority/reward/
  difficulty/reminder profile/duration fields
- `TimeInterval`: `start`, `end`, optional `label`
- `TaskStatistics`: skip/push/backlog/missed/cancelled/late/locked-hour and
  parent-child counters

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 explicit completion timestamp or backlog-entered
  timestamp fields.
- 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.

## 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`.

Future MongoDB adapter work must remain behind repository interfaces and must
not import MongoDB APIs into the scheduling core.