328 lines
17 KiB
Markdown
328 lines
17 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/application_commands.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_commands.dart` | `ApplicationCommandCode` |
|
|
| `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_commands.dart` | `ApplicationChildTaskDraft`, `ApplicationCommandReadHint`, `ApplicationCommandResult`, `V1ApplicationCommandUseCases` |
|
|
| `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`.
|
|
|
|
Chunk 14.3 intentionally changed the public API:
|
|
|
|
- Added `src/application_commands.dart` and exported it from
|
|
`scheduler_core.dart`.
|
|
- Added `ApplicationCommandCode`, `ApplicationChildTaskDraft`,
|
|
`ApplicationCommandReadHint`, `ApplicationCommandResult`, and
|
|
`V1ApplicationCommandUseCases`.
|
|
- Added atomic V1 commands for quick capture, backlog scheduling, flexible
|
|
push/backlog/completion, required task actions, surprise logging, protected
|
|
Free Slot create/update/remove, child break-up, and parent/child completion.
|
|
- Command results return changed tasks, persisted activities, project aggregate
|
|
updates, scheduler notices/changes/overlaps, child ids, and read refresh
|
|
hints.
|
|
- Application command failures use stable `ApplicationFailureCode` values for
|
|
not found, stale revision, no slot, validation, persistence, and duplicate
|
|
operation outcomes.
|
|
|
|
## 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.
|