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:

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

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.