Circuit-Forge/focus-flow
6
0
Fork 0
forked from eva/focus-flow
Code Pull requests Activity
focus-flow/Codex Documentation/Current Software Plan/V1_PUBLIC_API_BASELINE.md

23 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/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 MongoDB adapter implementation prerequisites.

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.