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

V1 Block 16 — MongoDB Runtime Adapter and Transaction Boundary

Status: Planned

Purpose: Implement the committed MongoDB persistence target behind the completed repository/application contracts while keeping credentials out of Flutter and making multi-record scheduling operations safe.

Chunk 16.1 — Trusted runtime topology and MongoDB client decision

Recommended Codex level: extra high

Tasks:

• Re-check current official MongoDB driver support, transaction requirements, and deprecation status at execution time.
• Write an architecture decision record selecting the trusted runtime that owns MongoDB credentials and executes the repository adapter.
• Explicitly reject embedding production MongoDB connection strings or database credentials in Flutter/mobile binaries.
• Do not choose deprecated Atlas Data API, Atlas Device SDK, or App Services paths as the V1 foundation.
• Evaluate candidate clients for maintenance, TLS/SRV support, BSON fidelity, sessions/transactions, retry behavior, cancellation/timeouts, and supported Dart/runtime platforms.
• Prefer a separate adapter package/module so the pure core remains dependency free.
• If no acceptable maintained Dart client satisfies the contract, document the blocker and choose a thin trusted service using a current official MongoDB driver rather than silently accepting an unsafe/unmaintained dependency.
• Define development, test, and production configuration boundaries without provisioning Atlas or implementing accounts.
• Define whether the first UI will use in-memory application wiring, a local trusted process, or a service API during the design spike.

Rules:

• This chunk is a decision gate; do not add a database dependency before the ADR is accepted.
• Use primary/official documentation for current driver and MongoDB capability claims.
• Secrets come from runtime configuration/secret storage and must never be committed, logged, or returned to UI DTOs.
• Do not add SQLite or another persistence fallback.
• Production authentication and cross-device sync remain out of scope.

Acceptance criteria:

• The selected topology identifies the trust boundary, credential owner, supported platforms, and UI connection path.
• The selected client/runtime satisfies all mandatory adapter capabilities or an explicit service-boundary alternative is chosen.
• Deprecated client-access paths are excluded.
• A threat/configuration checklist exists.
• No database package or credentials were added before this decision.

BREAKPOINT: Stop here. Review and accept the runtime topology ADR before adding a MongoDB dependency, even if the Codex level remains extra high.

Chunk 16.2 — MongoDB repository adapter and index bootstrap

Recommended Codex level: extra high

Tasks:

• Add the selected MongoDB client dependency only in the trusted adapter/runtime package.
• Implement all repository interfaces from Block 15 using the V1 codecs.
• Implement scoped CRUD, indexed queries, archive behavior, activity append, settings/notices, revisions, and idempotent operation lookup.
• Add client lifecycle, connection timeout, retryable-read configuration, health check, and graceful shutdown.
• Implement idempotent index bootstrap from the Block 15 index contract.
• Keep BSON conversion at the adapter edge; domain/application layers continue to use plain Dart values and typed repository results.
• Add secret-safe configuration loading and redacted diagnostics.
• Add adapter smoke tests against a disposable test deployment.

Rules:

• Never return raw MongoDB collection/client objects across the adapter boundary.
• Do not auto-create production users, Atlas projects, network allowlists, or clusters.
• Do not log full documents that may contain task titles or hidden locked names at normal levels.
• A connection failure must not fall back to untracked in-memory writes in a production configuration.
• Index bootstrap must be safe to run repeatedly.

Acceptance criteria:

• The MongoDB adapter passes the repository conformance suite.
• Required indexes are created idempotently.
• Configuration and logs do not expose secrets.
• Health/startup/shutdown behavior is tested.
• The pure core has no MongoDB dependency.

Chunk 16.3 — Atomic scheduling writes, revisions, and retry safety

Recommended Codex level: extra high

Tasks:

• Implement the application unit of work using MongoDB sessions/transactions on a supported replica-set or sharded deployment.
• Persist task movements, activity records, project/task statistics, notices, and idempotent operation records atomically.
• Apply optimistic revision predicates to every authoritative update.
• Use a unique owner+operation ID to make command retries exactly-once.
• Implement transaction retry only for documented retryable categories and keep the operation payload deterministic.
• Fail closed when the selected deployment cannot provide the required atomicity; do not knowingly commit partial multi-task scheduling results.
• Add conflict handling for two concurrent commands that touch the same flexible queue.
• Add tests for duplicate operation, stale revision, transient transaction retry, rollback, and post-commit response retry.

Rules:

• Do not treat a standalone MongoDB instance as transaction-capable if it is not.
• Retry logic must be bounded and observable.
• A retry must reuse the same operation ID, clock instant, and generated IDs.
• Do not hide conflicts by last-write-wins replacement.
• Transaction errors map to typed application failures; driver exceptions stay inside the adapter.

Acceptance criteria:

• Multi-record scheduling commands are atomic in integration tests.
• Duplicate/retried commands apply once.
• Concurrent conflicting commands return a stale/conflict result rather than losing data.
• Rollback leaves no task/activity/stat fragment.
• Transaction capability requirements are documented for local and hosted tests.

BREAKPOINT: Stop here. Confirm high mode before failure, security, and runtime handoff testing.

Chunk 16.4 — Adapter failure and security regression suite

Recommended Codex level: high

Tasks:

• Run the full repository conformance suite against MongoDB.
• Add integration tests for malformed documents, unsupported schema versions, duplicate keys, stale revisions, timeouts, disconnects, reconnects, and index bootstrap races.
• Verify secret/configuration redaction in logs and exception mapping.
• Verify hidden locked details are not exposed by default API/read DTOs.
• Verify owner-scope predicates exist on every query and write.
• Add a tagged integration-test command and deterministic disposable-database setup/cleanup instructions.
• Add migration dry-run and V0→V1 integration tests.
• Record supported MongoDB/server/client versions used by CI or local acceptance.

Rules:

• Integration tests must never point at an unscoped production database.
• Test databases/collections need unique disposable names.
• Destructive cleanup must verify the expected test scope first.
• Do not print connection strings in test output.
• A skipped integration suite does not count as adapter acceptance.

Acceptance criteria:

• Failure modes map to stable repository/application codes.
• No tested log/error path leaks credentials.
• Owner scoping and hidden-data behavior are verified.
• Migration and repository suites pass against a disposable MongoDB deployment.
• Test setup is repeatable by another developer.

Chunk 16.5 — Runtime boundary handoff for the future UI

Recommended Codex level: high

Tasks:

• Expose the application facade through the topology selected in Chunk 16.1 without exposing repository/driver types.
• If the selected topology is a service, define versioned request/response DTOs, error envelopes, idempotency key handling, and a minimal health endpoint; keep production auth/deployment out of scope and clearly blocked.
• If the selected topology is a trusted in-process/local runtime, document which Flutter targets may use it and which targets must use a service boundary.
• Provide in-memory and Mongo-backed composition roots with the same application interface.
• Add one non-UI smoke scenario through the selected boundary: quick capture, schedule, read Today, complete, and read persisted state.
• Document startup, shutdown, configuration, and local development commands.
• Record any production deployment/auth decision that remains unresolved before a networked UI can ship.

Rules:

• Do not invent insecure placeholder authentication and call it production-ready.
• UI code receives use-case DTOs, never MongoDB documents or credentials.
• Keep API surface limited to Block 14 use cases.
• Do not implement sync, push notifications, or background reconciliation.
• The in-memory composition root remains available for widget/design work.

Acceptance criteria:

• The same smoke scenario passes through in-memory and Mongo-backed composition.
• UI-facing DTOs contain no driver-specific values or secrets.
• Runtime limitations by target platform are explicit.
• Local development setup is documented.
• Any unresolved production trust/auth boundary is clearly marked as a release blocker rather than hidden.

BREAKPOINT: Stop here. Confirm extra high mode before the final backend acceptance suite.

Commit suggestion:

feat(mongodb): add trusted transactional v1 persistence adapter