582 lines
30 KiB
Markdown
582 lines
30 KiB
Markdown
# V1 Public API Baseline
|
|
|
|
Status: Captured during Block 11.1.
|
|
|
|
Starting commit: `775c2ed406f03a73a9b0ca621dea5b4482468616`
|
|
|
|
Public import:
|
|
|
|
```dart
|
|
import 'package: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/application_management.dart`
|
|
- `src/application_recovery.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_management.dart` | `ApplicationManagementCommandCode`, `OwnerSettingsWarningCode` |
|
|
| `src/application_recovery.dart` | `AppOpenRecoveryOutcome` |
|
|
| `src/application_layer.dart` | `ApplicationFailureCode` |
|
|
| `src/document_mapping.dart` | `DocumentMappingFailureCode` |
|
|
| `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`, `NoticeAcknowledgementRecord`, `OwnerSettings`, `TaskActivityRepository`, `ProjectStatisticsRepository`, `OwnerSettingsRepository`, `NoticeAcknowledgementRepository`, `ApplicationOperationRepository`, `ApplicationUnitOfWorkRepositories`, `ApplicationUnitOfWork`, `ApplicationSchedulingLoader`, `InMemoryApplicationUnitOfWork` |
|
|
| `src/application_management.dart` | `GetBacklogRequest`, `BacklogItemReadModel`, `BacklogQueryResult`, `GetProjectDefaultsRequest`, `ProjectDefaultsQueryResult`, `ProjectProfileDraft`, `ProjectProfileUpdate`, `LockedBlockDraft`, `LockedBlockUpdate`, `OwnerSettingsUpdateResult`, `OwnerSettingsUpdate`, `NoticeAcknowledgementResult`, `V1ApplicationManagementUseCases` |
|
|
| `src/application_recovery.dart` | `RunAppOpenRecoveryRequest`, `AppOpenRecoveryResult`, `V1AppOpenRecoveryUseCases` |
|
|
| `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` | `DocumentMappingException`, `DocumentMetadata`, `PersistenceEnumMapping`, `TaskDocumentMapping`, `TaskStatisticsDocumentMapping`, `ProjectDocumentMapping`, `ProjectStatisticsDocumentMapping`, `LockedBlockRecurrenceDocumentMapping`, `LockedBlockDocumentMapping`, `LockedBlockOverrideDocumentMapping`, `TaskActivityDocumentMapping`, `OwnerSettingsDocumentMapping`, `BacklogStalenessDocumentMapping`, `NoticeAcknowledgementDocumentMapping`, `ApplicationOperationDocumentMapping`, `SchedulingSnapshotDocumentMapping`, `SchedulingWindowDocumentMapping`, `TimeIntervalDocumentMapping`, `SchedulingNoticeDocumentMapping`, `SchedulingChangeDocumentMapping`, `SchedulingOverlapDocumentMapping`, `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` | `v1SchemaVersion`, `PersistenceDateTimeConvention`, `PersistenceCivilDateConvention`, `PersistenceWallTimeConvention`, `PersistenceEnumName`, V1 document field-name classes |
|
|
| `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, `archivedAt`
|
|
- `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.
|
|
|
|
Chunk 14.4 intentionally changed the public API:
|
|
|
|
- Added `src/application_management.dart` and exported it from
|
|
`scheduler_core.dart`.
|
|
- Added management query/command contracts for backlog, project defaults,
|
|
project create/update/archive, locked-block create/update/archive, one-day
|
|
locked overrides, owner settings updates, and notice acknowledgement.
|
|
- Added `ProjectProfile.archivedAt` and `LockedBlock.archivedAt` soft-archive
|
|
fields.
|
|
- Added `NoticeAcknowledgementRecord` and
|
|
`NoticeAcknowledgementRepository`.
|
|
- Added stable notice IDs to `TodayPendingNotice` and Today-state filtering for
|
|
acknowledged notices.
|
|
|
|
Chunk 14.5 intentionally changed the public API:
|
|
|
|
- Added `src/application_recovery.dart` and exported it from
|
|
`scheduler_core.dart`.
|
|
- Added `AppOpenRecoveryOutcome`, `RunAppOpenRecoveryRequest`,
|
|
`AppOpenRecoveryResult`, and `V1AppOpenRecoveryUseCases`.
|
|
- Added `InMemoryApplicationUnitOfWork.currentSchedulingSnapshots` for
|
|
application/recovery contract tests.
|
|
|
|
Chunk 15.2 intentionally changed the public API:
|
|
|
|
- Replaced legacy enum `.name` document encoding in `document_mapping.dart` with
|
|
explicit stable V1 code tables through `PersistenceEnumMapping`.
|
|
- Added `DocumentMappingFailureCode`, `DocumentMappingException`, and
|
|
`DocumentMetadata`.
|
|
- Expanded document codecs to every V1 persisted entity: project profiles,
|
|
project statistics, locked blocks/overrides, activities, owner settings,
|
|
notice acknowledgements, operation records, scheduling snapshots, notices,
|
|
changes, overlaps, windows, intervals, civil dates, and wall times.
|
|
- Changed top-level document `toDocument` helpers/extensions to require owner
|
|
scope and V1 metadata where the domain model does not carry it directly.
|
|
- Expanded `persistence_contract.dart` with `v1SchemaVersion`, common document
|
|
fields, and V1 field sets for every persisted repository entity.
|
|
|
|
Chunk 15.3 intentionally changed the public API:
|
|
|
|
- Added `src/document_migration.dart` and exported it from `scheduler_core.dart`.
|
|
- Added `V1DocumentMigrationService` for pure Dart V0-to-V1 migration of task,
|
|
project, locked block, and locked override documents.
|
|
- Added typed migration surface area:
|
|
`DocumentMigrationEntity`, `DocumentMigrationStatus`,
|
|
`DocumentMigrationFailureCode`, `DocumentMigrationNoteCode`,
|
|
`DocumentMigrationProvenance`, `DocumentMigrationNote`,
|
|
`DocumentMigrationReport`, and `DocumentMigrationResult`.
|
|
- Migration results expose `document`, `isSuccess`, and `shouldWrite` so
|
|
persistence adapters can dry-run migrations and refuse to overwrite unreadable
|
|
source documents.
|
|
- Legacy backlog tasks now carry explicit provenance when `backlogEnteredAt` is
|
|
approximated from `createdAt`.
|
|
|
|
Chunk 15.4 intentionally changed the public API:
|
|
|
|
- Added adapter-neutral repository conflict/paging/record contracts:
|
|
`RepositoryFailureCode`, `RepositoryFailure`, `RepositoryMutationResult`,
|
|
`RepositoryRecord`, `RepositoryPageRequest`, `RepositoryPage`, and
|
|
`BacklogCandidateQuery`.
|
|
- Expanded `TaskRepository` with owner, project, parent, backlog-candidate,
|
|
local-day/window, record/revision, insert, and compare-and-set save methods.
|
|
- Expanded `ProjectRepository` and `LockedBlockRepository` with owner-scoped
|
|
paged queries, revision records, compare-and-set saves, duplicate insert
|
|
failures, archive methods, and date-scoped locked override lookup.
|
|
- Expanded application-layer repository interfaces for task activity owner
|
|
queries/appends, project statistics/settings revision saves, notice
|
|
acknowledgement insert/paging, and idempotent operation lookup/insert.
|
|
- In-memory unit-of-work repositories now track owner/revision metadata in the
|
|
staged transaction state.
|
|
|
|
Chunk 15.5 intentionally changed the public API:
|
|
|
|
- Added V1 collection/index contract types and constants:
|
|
`PersistenceCollections`, `PersistenceIndexDirection`,
|
|
`PersistenceIndexField`, `PersistenceIndexSpec`, `RepositoryQueryNames`, and
|
|
`PersistenceIndexCatalog`.
|
|
- Added bounded payload/retention guard surface:
|
|
`PersistencePayloadLimits`, `PersistenceGuardResult`, and
|
|
`PersistencePayloadGuard`.
|
|
- Added repository integrity failure codes for invalid revisions and owner
|
|
mismatches.
|
|
- Added `V1_BLOCK_16_REPOSITORY_ADAPTER_CHECKLIST.md` for the former document
|
|
adapter implementation prerequisites, archived after the SQLite-first pivot.
|
|
|
|
Chunk 19.1 intentionally changed the public/package API:
|
|
|
|
- Rehomed the core library under `packages/scheduler_core` with public import
|
|
`package:scheduler_core/scheduler_core.dart`.
|
|
- Added shared repository value objects exported from `scheduler_core`:
|
|
`OwnerId`, `Revision`, `PageRequest`, and `Page<T>`.
|
|
- Added `packages/scheduler_persistence` with domain-only repository
|
|
interfaces for tasks, projects, locked blocks, settings, and schedule
|
|
snapshots.
|
|
- Added `RepositoryFailure` variants, sealed `Either<L, R>`, and
|
|
`RepoResult<T>` for expected repository success/failure paths.
|
|
|
|
Chunk 19.2 intentionally changed the public/package API:
|
|
|
|
- Added `packages/scheduler_persistence_memory` with
|
|
`InMemoryTaskRepository`, `InMemoryProjectRepository`,
|
|
`InMemoryLockedBlockRepository`, `InMemorySettingsRepository`, and
|
|
`InMemoryScheduleSnapshotRepository`.
|
|
- Added package entry points
|
|
`package:scheduler_persistence_memory/persistence_memory.dart` and
|
|
`package:scheduler_persistence_memory/memory.dart`.
|
|
- Added shared adapter conformance test surface
|
|
`runRepositoryComplianceTests()` and `RepositoryComplianceFactories` under
|
|
`packages/scheduler_persistence/test/repo_conformance.dart`.
|
|
|
|
Chunk 20.1 intentionally changed the public/package API:
|
|
|
|
- Added `packages/scheduler_persistence_sqlite` with Drift-backed schema
|
|
package entry point `package:scheduler_persistence_sqlite/sqlite.dart`.
|
|
- Added `SchedulerDb` with schema version 1 and generated Drift table/data
|
|
classes for `tasks`, `projects`, `locked_blocks`, `locked_overrides`,
|
|
`settings`, and `snapshots`.
|
|
- Added generated accessor classes: `TaskDao`, `ProjectDao`, `LockedBlockDao`,
|
|
`SettingsDao`, and `SnapshotDao`.
|
|
|
|
Chunk 20.2 intentionally changed the public/package API:
|
|
|
|
- Added SQLite repository implementations exported from
|
|
`package:scheduler_persistence_sqlite/sqlite.dart`:
|
|
`SqliteTaskRepository`, `SqliteProjectRepository`,
|
|
`SqliteLockedBlockRepository`, `SqliteSettingsRepository`, and
|
|
`SqliteScheduleSnapshotRepository`.
|
|
- Added SQLite adapter conformance and write-latency tests under
|
|
`packages/scheduler_persistence_sqlite/test/`.
|
|
|
|
Chunk 21.1 intentionally changed the public/package API:
|
|
|
|
- Added `packages/scheduler_notifications` with package entry points
|
|
`package:scheduler_notifications/notifications.dart` and
|
|
`package:scheduler_notifications/scheduler_notifications.dart`.
|
|
- Added notification abstraction types: `NotificationRequest`,
|
|
`NotificationFeedbackType`, `NotificationFeedback`, `NotificationAdapter`,
|
|
and `FakeNotificationAdapter`.
|
|
|
|
Chunk 22.1 intentionally changed the public/package API:
|
|
|
|
- Added `packages/scheduler_notifications_desktop` with package entry points
|
|
`package:scheduler_notifications_desktop/desktop_notifications.dart` and
|
|
`package:scheduler_notifications_desktop/scheduler_notifications_desktop.dart`.
|
|
- Added desktop notification types: `DesktopNotificationPlatform`,
|
|
`DesktopNotificationBackend`, `DesktopNotificationAdapter`,
|
|
`StdoutNotificationBackend`, and the IO backends for Linux/macOS.
|
|
|
|
Chunk 23.1 intentionally changed the public/package API:
|
|
|
|
- Added `packages/scheduler_export` with package entry points
|
|
`package:scheduler_export/export.dart` and
|
|
`package:scheduler_export/scheduler_export.dart`.
|
|
- Added readable export contracts and orchestration types: `ExportContext`,
|
|
`ExportWriter`, `ExportWriterFactory`, `ExportWriterRegistry`,
|
|
`ExportController`, `ExportException`, and `ExportRepositoryException`.
|
|
- Added sink-backed writer implementations `JsonExportWriter` and
|
|
`CsvExportWriter`.
|
|
|
|
Chunk 24.1 intentionally changed the public/package API:
|
|
|
|
- Added `packages/scheduler_backup` with package entry points
|
|
`package:scheduler_backup/backup.dart` and
|
|
`package:scheduler_backup/scheduler_backup.dart`.
|
|
- Added encrypted backup functions `createEncryptedBackup`,
|
|
`restoreEncryptedBackup`, `defaultSchedulerSqliteFile`, and
|
|
`defaultSchedulerBackupDirectory`.
|
|
- Added backup constants `defaultSchedulerDirectoryName`,
|
|
`defaultSchedulerDatabaseFileName`, and
|
|
`defaultSchedulerBackupDirectoryName`.
|
|
- Added backup exceptions `BackupException` and
|
|
`BackupDecryptionException`.
|
|
|
|
Chunk 24.2 intentionally changed the public/package API:
|
|
|
|
- Added `packages/scheduler_export_json` with package entry points
|
|
`package:scheduler_export_json/export_json.dart` and
|
|
`package:scheduler_export_json/scheduler_export_json.dart`.
|
|
- Added readable writer factory `readableExportWriterRegistry`.
|
|
- Added concrete readable export writers `JsonExportWriter` and
|
|
`CsvExportWriter`.
|
|
- Added CLI export command `bin/export.dart`.
|
|
|
|
Chunk 25.1 intentionally changed the workspace test surface:
|
|
|
|
- Added test-only package `packages/scheduler_integration_tests`.
|
|
- Added integration harness `integration/scheduler_flow_test.dart` covering
|
|
scheduler placement, fake notification scheduling, SQLite save, and reload.
|
|
|
|
Chunk 26.1 intentionally changed the verification surface:
|
|
|
|
- Added executable `scripts/test.sh` as the required analyze/test/coverage gate.
|
|
- Added `tool/check_coverage.dart` for LCOV threshold enforcement.
|
|
- Added shared notification adapter contract test helper
|
|
`packages/scheduler_notifications/test/notification_adapter_contract.dart`.
|
|
- Desktop notification adapter cancellation now normalizes ids before backend
|
|
cancellation.
|
|
|
|
Chunk 27.1 intentionally changed the dev/CI surface:
|
|
|
|
- Added `scripts/dev.dart` for local build-runner watch plus Flutter desktop
|
|
launch with a SQLite path define.
|
|
- Added `scripts/test.dart` for cross-platform coverage collection and LCOV
|
|
combination.
|
|
- Added `scripts/bootstrap_dev.sh` and `scripts/dev.sh` shell entry points for
|
|
agent-compatible setup and desktop development.
|
|
- Added GitHub Actions test matrix in `.github/workflows/ci.yml`.
|
|
|
|
Chunk 27.2 intentionally changed the packaging surface:
|
|
|
|
- Added `scripts/build.dart` for platform-specific Flutter desktop packaging.
|
|
- Added `scripts/package_release.sh` shell entry point for release packaging.
|
|
- Added tagged CI release artifact upload steps.
|
|
- Replaced README content with workspace test, dev, packaging, and prerequisite
|
|
instructions.
|
|
|
|
Chunk 28.1 intentionally changed the documentation verification surface:
|
|
|
|
- Added `tool/check_docs.dart` to generate package docs and fail on warnings.
|
|
- Added generated docs upload under the CI artifact step.
|
|
- Added generated `doc/api/` output to `.gitignore`.
|
|
- Fixed unresolved public API documentation references in core and export
|
|
packages.
|
|
|
|
Chunk 29.1 intentionally changed the UI surface:
|
|
|
|
- Added provisional Flutter app `apps/focus_flow_flutter` outside the root Dart
|
|
workspace.
|
|
- Added app-local path dependency on `packages/scheduler_core`.
|
|
- Added `FocusFlowApp`, `DemoSchedulerComposition`, `SchedulerHome`,
|
|
`TodayPane`, and `BacklogPane` in the Flutter app.
|
|
- Added widget test coverage for rendering Today and Backlog read-model data.
|
|
|
|
Chunk 29.2 intentionally changed the UI surface:
|
|
|
|
- Split the Flutter shell into `app.dart`, `composition/`, `controllers/`,
|
|
`theme/`, and `widgets/`.
|
|
- Added `UiReadController<T>`, `ApplicationReadController<T>`, and
|
|
`SchedulerReadState<T>` variants for loading, data, empty, and typed failure
|
|
states.
|
|
- Added `SchedulerVisualTokens` for centralized project/task/reward/difficulty
|
|
and staleness visual mappings.
|
|
- Added component widgets for Today, Backlog, compact panels, timeline rows,
|
|
backlog rows, notice banners, empty states, and failure retry states.
|
|
- Expanded Flutter widget coverage to 4 tests.
|
|
|
|
## Repository contracts
|
|
|
|
The current repository surface is pure Dart and adapter-backed:
|
|
|
|
- Core legacy repository fakes remain in `scheduler_core` for existing domain
|
|
services and tests.
|
|
- The Block 19 repository abstraction lives in `scheduler_persistence`.
|
|
- The Block 19 conformance-tested memory adapter lives in
|
|
`scheduler_persistence_memory`.
|
|
- The Block 20 conformance-tested SQLite adapter lives in
|
|
`scheduler_persistence_sqlite`.
|
|
- Application transaction behavior is represented by
|
|
`InMemoryApplicationUnitOfWork`.
|
|
- Application read-query behavior uses `ApplicationUnitOfWork.read`, which
|
|
stages repository access without committing operation records.
|
|
|
|
Future SQLite adapter work must remain behind repository interfaces and must not
|
|
import storage APIs into the scheduling core.
|