forked from eva/focus-flow
128 lines
5.3 KiB
Markdown
128 lines
5.3 KiB
Markdown
# 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/locked_time.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/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/locked_time.dart` | `LockedWeekday`, `LockedBlockOverrideType` |
|
|
| `src/quick_capture.dart` | `QuickCaptureStatus` |
|
|
| `src/scheduling_engine.dart` | `SchedulingNoticeType` |
|
|
| `src/task_actions.dart` | `FlexibleTaskQuickAction`, `RequiredTaskAction`, `PushDestination` |
|
|
| `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/locked_time.dart` | `ClockTime`, `LockedBlockRecurrence`, `LockedBlock`, `LockedBlockOccurrence`, `LockedBlockOverride`, `LockedScheduleExpansion`, `expandLockedBlocksForDay`, `lockedSchedulingIntervalsForDay`, `trackCompletedDuringLockedHours`, `completedDuringLockedHoursMinutes` |
|
|
| `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/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.
|
|
- Time is currently `DateTime`-based; civil-date, wall-time, clock, ID, and
|
|
timezone contracts are Chunk 11.4.
|
|
|
|
## 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.
|
|
|
|
## 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.
|