# V1 Block 16 — MongoDB Runtime Adapter and Transaction Boundary

Status: In progress

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

Status: Complete

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.

Completed implementation:

- Re-checked current MongoDB official driver, transaction, and App Services
  deprecation documentation on 2026-06-25.
- Added `V1_ADR_003_MongoDB_Runtime_Topology.md`.
- Selected a trusted Node.js/TypeScript service boundary using the official
  MongoDB Node.js driver for the MongoDB-owning runtime.
- Explicitly rejected direct MongoDB access from Flutter/mobile binaries,
  production use of current Dart community MongoDB drivers, deprecated Atlas
  Data API/App Services/Device SDK paths, and non-MongoDB persistence fallbacks.
- Defined credential ownership, UI connection path, local/test/production
  configuration boundaries, deployment transaction requirements, and a
  threat/safety checklist.
- Kept the pure Dart package free of MongoDB dependencies and did not add
  credentials, connection strings, Atlas setup, accounts, sync, or provisioning.

Verification:

- `dart format lib test`: passed, 0 files changed
- `dart analyze`: passed, no issues found
- `dart test`: passed, 298 tests
- `git diff --check`: passed

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:

```text
feat(mongodb): add trusted transactional v1 persistence adapter
```