eva/focus-flow
6
0
Fork 1
Code Issues 14 Pull requests 1 Projects Releases Packages Wiki Activity Actions 1
focus-flow/Codex Documentation/Current Software Plan/V1_PUBLIC_API_BASELINE.md

12 KiB
Raw Blame History

V1 Public API Baseline

Status: Captured during Block 11.1.

Starting commit: 775c2ed406f03a73a9b0ca621dea5b4482468616

Public import:

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_lifecycle.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/task_lifecycle.dart TaskTransitionCode, TaskActivityCode, TaskTransitionOutcomeCode
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, ChildTaskBreakUpRequest, ChildTaskBreakUpResult, ChildTaskBreakUpService, 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_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/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
  • 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.

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.