# V1 Block 11 — Backend Baseline and Domain Contracts Status: Planned Purpose: Re-establish a trustworthy executable baseline after the archived Blocks 01–10, resolve remaining V1 specification ambiguities, and harden the core domain/time contracts before adding more scheduling, persistence, or UI surface area. ## Chunk 11.1 — Fresh verification and V1 traceability baseline Recommended Codex level: medium Status: Complete on 2026-06-24. Baseline: - Starting commit: `775c2ed406f03a73a9b0ca621dea5b4482468616` - Dart SDK: `3.12.2` - Current test count: 143 passing tests Verification commands: - `dart pub get`: passed - `dart format lib test`: passed, 0 files changed - `dart analyze`: passed, no issues found - `dart test`: passed, 143 tests - `git diff --check`: passed Documentation outputs: - Updated `Codex Documentation/Archived plans/V1_TEST_COVERAGE_MATRIX.md` to remove a stale reference to missing `test/quick_capture_test.dart` and record the fresh verification result. - Added `V1_REQUIREMENTS_TRACEABILITY_MATRIX.md`. - Added `V1_PUBLIC_API_BASELINE.md`. - Updated `V1_BACKEND_COMPLETION_GAP_MATRIX.md` so it no longer describes the 143-test result as only historical. Tasks: - Install or select a Dart SDK compatible with `pubspec.yaml`. - Run and record: ```bash dart pub get dart format lib test dart analyze dart test git diff --check ``` - Record the starting commit and actual current test count. - Repair stale or incorrect entries in `V1_TEST_COVERAGE_MATRIX.md`, including references to test files that do not exist. - Add a V1 requirements traceability matrix that maps each human-document MVP acceptance criterion to production APIs, tests, and one of: complete, incomplete, intentionally deferred, or contradictory. - Capture a public API baseline so later chunks can distinguish intentional breaking changes from accidental ones. - Turn every verified gap into either an active-plan reference or a narrowly scoped issue/TODO; do not leave vague “future” claims in the completion matrix. Rules: - This chunk is verification and documentation only unless a minimal formatting or test-reference correction is required. - Do not claim the archived 143-test result is current until the suite is rerun. - If a command cannot run, document the exact environment blocker and keep this chunk incomplete. - Do not edit archived plan completion notes to hide a newly discovered gap. - Do not begin feature implementation in this chunk. Acceptance criteria: - All standard verification commands pass in the active environment. - The current test count and starting commit are recorded. - Every V1 acceptance criterion has a traceable implementation/test status. - Stale coverage references are corrected. - The gap matrix agrees with the active Block 11–18 plan index. BREAKPOINT: Stop here. Confirm `high` mode before resolving domain semantics. ## Chunk 11.2 — Resolve V1 lifecycle and metadata semantics Recommended Codex level: high Tasks: - Add an architecture decision record that defines the durable task lifecycle states used by V1. - Keep movement such as manual push, automatic push, move to backlog, and restore from backlog as activity/stat events rather than durable lifecycle statuses. - Keep `skipped during burnout` compatible as a future activity/stat concept, but do not add V2 shield or catch-up transitions. - Define exact behavior for each task type in each relevant lifecycle state, including flexible, critical, inflexible, locked, surprise, and free slot. - Define which fields represent planned placement, actual work time, completion time, backlog-entry time, and last modification time. - Define critical-missed behavior as missed plus backlog placement, and inflexible-missed behavior as missed history that retains its original scheduled interval. - Define how configured project defaults, learned suggestions, and task-level overrides differ. - Define the reminder-profile inheritance order and the boundary between backend policy decisions and platform notification delivery. - Update human-facing architecture notes only where needed to resolve a real contradiction; preserve the original product intent. Rules: - Do not introduce V2 behavior to make the status table symmetrical. - Do not turn every activity into a task status. - Preserve calm, non-punitive terminology. - The decision record must be specific enough to drive model, mapping, and test changes in later chunks. - Prefer one durable meaning per field; do not overload `updatedAt` as a proxy for backlog age, completion, or actual work time. Acceptance criteria: - The status/event distinction is documented and covered by focused tests or compile-time model expectations. - Critical and inflexible missed semantics are unambiguous. - Planned versus actual time semantics are unambiguous. - Project defaults, learned suggestions, and task overrides have a defined precedence model. - No V2-only workflow has been added. ## Chunk 11.3 — Domain invariants and explicit patch semantics Recommended Codex level: high Tasks: - Enforce non-blank stable IDs, titles, and project IDs at model boundaries. - Enforce positive durations when a duration is present. - Enforce that scheduled start/end values are either both absent or both present and that end is after start. - Enforce valid `TimeInterval`, scheduling-window, recurrence, and override intervals. - Reject self-parenting and define the direct-child-only ownership boundary. - Add explicit patch/clear semantics for nullable fields that must be removable, including duration, priority, parent ownership, schedule placement, actual interval, and reminder override. - Prevent mutable input collections from leaking into immutable domain objects. - Introduce typed validation failures/codes that application and persistence layers can map without parsing English strings. - Add regression tests for every invariant and every intentional clear path. Rules: - Keep constructors/factories consistent; do not leave a public constructor that bypasses all invariants without a documented internal-only reason. - Do not use magic sentinel enum values to mean “clear this field.” - Validation must remain UI- and database-independent. - Existing valid fixtures must continue to construct or be migrated explicitly in Block 15. - Error codes are stable contracts; explanatory text may change later. Acceptance criteria: - Invalid partial/negative/empty model states are rejected deterministically. - Every nullable field that the product can remove has an explicit tested clear path. - All domain collections exposed publicly are immutable views or immutable values. - Application callers can distinguish validation categories without matching message text. - Existing scheduling behavior still passes its regression suite. BREAKPOINT: Stop here. Confirm `extra high` mode before changing civil-time and clock contracts. ## Chunk 11.4 — Deterministic clock, IDs, and civil-time semantics Recommended Codex level: extra high Tasks: - Introduce injectable clock and ID-generation contracts for application/domain operations that currently fall back to `DateTime.now()` or caller-created IDs. - Remove hidden wall-clock reads from deterministic core methods; convenience wrappers may delegate to injected services at an outer boundary. - Introduce explicit civil-date and wall-clock value types for recurring locked rules and date-only overrides. - Introduce a time-zone identifier/resolver boundary that converts a local day and wall time into instants used by the scheduling engine. - Define and test daylight-saving behavior for nonexistent and repeated local times. - Persist date-only values as date-only values and wall times as wall times; do not convert them to UTC timestamps that can change the calendar day. - Define whether overnight locked rules are rejected or normalized into explicit split occurrences; implement the selected safe behavior. - Update locked-block expansion, scheduling windows, and tests to use the new deterministic time contracts. - Add boundary tests for midnight, month/year transitions, leap day, DST gaps, DST repeats, and non-UTC time zones. Rules: - Keep IANA/platform time-zone implementation behind an interface so the core does not import Flutter or platform APIs. - Do not use the machine’s implicit local zone as persistent business data. - Do not silently reinterpret legacy UTC timestamps; migration belongs in Block 15 and must be fixture-tested. - Every scheduling operation must receive an explicit operation time and owner time-zone context through the application boundary. - Locked and inflexible time must remain immovable through this refactor. Acceptance criteria: - Core tests no longer depend on the machine clock or default local time zone. - Recurring locked blocks expand to the intended local calendar dates across DST transitions. - Date-only overrides round-trip without a day shift. - Invalid/ambiguous time input follows a documented deterministic policy. - The full verification suite passes after the time-model migration. Commit suggestion: ```text feat(domain): harden v1 contracts and time semantics ```