Circuit-Forge/focus-flow
6
0
Fork 0
forked from eva/focus-flow
Code Pull requests Activity
focus-flow/archive/Archived plans/V1_PUBLIC_API_BASELINE.md

30 KiB
Raw Blame History

V1 Public API Baseline

Status: Captured during Block 11.1.

Starting commit: 775c2ed406f03a73a9b0ca621dea5b4482468616

Public import:

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.