# V1 Block 09 — Persistence Preparation

Status: In progress — Chunks 9.1 and 9.2 complete

Purpose: Prepare the domain layer for future MongoDB-backed persistence without adding a MongoDB driver, network behavior, sync behavior, or database runtime dependency too early.

MongoDB is the committed persistence target. This block should make the core persistence-friendly and MongoDB-document-friendly while keeping the scheduling engine independent from database APIs.

## Chunk 9.1 — Repository interface

Recommended Codex level: medium

Tasks:

Define repository interfaces for:

- tasks
- projects
- locked blocks
- scheduling operations/state snapshots

Rules:

- Do not couple the scheduling engine directly to MongoDB APIs.
- Use interfaces that a future MongoDB adapter can implement.
- Keep the current implementation in-memory if needed.
- Repository interfaces should preserve domain rules rather than bypassing services.
- Do not introduce alternative database assumptions.

Acceptance criteria:

- Domain services can depend on interfaces.
- Tests can use fake/in-memory repositories.
- Interfaces do not import MongoDB, Flutter, platform-specific APIs, or network/client APIs.
- Interface names and method shapes are compatible with document-style persistence.

Completed:

- Added pure Dart repository interfaces for tasks, projects, locked blocks/overrides, and scheduling state snapshots.
- Added in-memory repository implementations for tests and early app wiring.
- Added scheduling snapshot state that can rebuild `SchedulingInput` and `SchedulingResult` without persistence APIs.
- Exported repository interfaces through the public core library.
- Added repository tests covering task/project/locked-block/snapshot fake usage.
- Verified with `dart format lib test`, `dart analyze`, and `dart test`.

BREAKPOINT: Stop here. Confirm `extra high` mode before implementing the persistence edge-case test suite.

## Chunk 9.2 — Persistence edge-case regression test suite

Recommended Codex level: extra high

Tasks:

Before model serialization changes, add or expand tests that define persistence-sensitive behavior clearly.

Cover these cases:

- task IDs remain stable across copy/update operations
- project IDs remain stable across copy/update operations
- locked block IDs remain stable across copy/update operations
- DateTime values are stored and compared using the documented convention
- nullable fields can be intentionally preserved
- nullable fields that need clearing have explicit clear behavior or documented mapping behavior
- enum values have stable persistence names or a clearly tested mapping plan
- `RewardLevel.notSet` remains distinct from `RewardLevel.veryLow`
- backlog age behavior has a documented source timestamp or TODO before database work
- in-memory fake repositories can round-trip saved records without losing scheduling fields
- repository operations do not mutate input objects unexpectedly
- document-shaped maps preserve all fields needed by future MongoDB persistence
- generated document field names are stable and migration-friendly

Rules:

- This chunk may add tests and small model helpers needed to make persistence behavior testable.
- Do not add a MongoDB driver, MongoDB client, Atlas setup, connection string, local MongoDB service requirement, or database adapter yet.
- Do not add alternative database mappings or non-MongoDB terminology.
- Do not add sync, networking, cloud accounts, or background services.
- Do not mark this chunk complete unless `dart analyze` and `dart test` pass.

Acceptance criteria:

- Persistence-sensitive test group exists.
- Tests capture stable IDs, enum mapping, nullable-field behavior, DateTime convention, and document-shaped mapping expectations.
- Any unresolved persistence detail is documented as a TODO in the plan or architecture notes.
- No alternative-database references remain in the active persistence plan.

Completed:

- Added persistence edge-case regression tests for stable task, project, and locked-block IDs across copy/update helpers.
- Added UTC ISO-8601 DateTime persistence convention helpers and tests.
- Added enum persistence-name mapping tests, including `RewardLevel.notSet` remaining distinct from `RewardLevel.veryLow`.
- Added nullable-field preservation and explicit schedule-clearing tests.
- Added backlog age source tests documenting `Task.createdAt` as the current staleness source.
- Added in-memory repository round-trip and unmodifiable-read tests.
- Added MongoDB-oriented document field-name constants and tests for task/statistics, project, locked-block, override, scheduling snapshot, and embedded scheduling structures.
- Verified with `dart format lib test`, `dart analyze`, and `dart test`.

TODO for Chunk 9.3:

- Define document mapping behavior for clearing nullable non-schedule fields before adding model serialization helpers. Current explicit clear behavior only covers task schedule placement through `Task.copyWith(clearSchedule: true)`.

BREAKPOINT: Stop here. Confirm `high` mode before model serialization changes.

## Chunk 9.3 — MongoDB-document-safe models

Recommended Codex level: high

Tasks:

Make models persistence-friendly and MongoDB-document-friendly:

- stable IDs
- enum serialization helpers or clear mapping plan
- DateTime handling convention
- nullable fields documented
- nullable field clear helpers where needed
- migration-safe document field names where possible
- document-shaped map conversion helpers only if they do not over-couple the domain layer
- clear mapping rules for nested task statistics and future child-task ownership fields

Rules:

- Keep model helpers independent from MongoDB client libraries.
- Prefer plain Dart map/document shapes that a later adapter can translate into MongoDB documents.
- Do not introduce database connection logic in this chunk.
- Do not add table assumptions, joins, or relational schema requirements.

Acceptance criteria:

- Models can round-trip through document-shaped map/json-like structures or have a clear TODO for MongoDB document mappings.
- Tests cover at least task serialization if implemented.
- Tests cover enum persistence mapping if implemented.
- Tests cover intentional clearing of nullable fields if helper behavior is added.
- Tests confirm `not set` reward remains distinct from very low reward through mapping.

BREAKPOINT: Stop here. Confirm `low` mode before documenting the explicit non-sync boundary.

## Chunk 9.4 — Explicit non-sync / no-database-runtime boundary

Recommended Codex level: low

Tasks:

Document that V1 persistence work prepares for MongoDB but does not implement runtime database access, sync, accounts, or background services.

Rules:

- No network sync code.
- No cloud assumptions.
- No MongoDB connection strings.
- No Atlas setup.
- No local MongoDB server requirement.
- No background service implementation.
- No mobile notification or background reconciliation implementation in this block.

Acceptance criteria:

- README or architecture doc states MongoDB is the committed persistence target.
- README or architecture doc states this block does not require a running MongoDB instance.
- Docs distinguish MongoDB persistence preparation from actual sync or database adapter implementation.
- Wishlist/future notes contain sync as a later feature, not a V1 requirement.

Commit suggestion:

```text
feat(data): prepare MongoDB-friendly persistence interfaces
```