focus-flow/Codex Documentation/Current Software Plan/V1_BLOCK_09_Persistence_Preparation.md

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:

feat(data): prepare MongoDB-friendly persistence interfaces