diff --git a/Codex Documentation/Current Software Plan/V1_ADR_003_MongoDB_Runtime_Topology.md b/Codex Documentation/Current Software Plan/V1_ADR_003_MongoDB_Runtime_Topology.md new file mode 100644 index 0000000..37354cb --- /dev/null +++ b/Codex Documentation/Current Software Plan/V1_ADR_003_MongoDB_Runtime_Topology.md @@ -0,0 +1,177 @@ +# V1 ADR 003: MongoDB Runtime Topology + +Status: Accepted during Block 16.1 + +Date: 2026-06-25 + +## Context + +MongoDB is the committed persistence target for V1, but the Flutter UI and pure +Dart scheduling core must not own production database credentials. Block 15 +completed the adapter-neutral document schema, codecs, repository contracts, +index catalog, payload limits, and migration contracts. + +Before adding a MongoDB dependency, Block 16 needs a runtime decision that keeps +credentials inside a trusted boundary, supports transactions, and avoids +deprecated MongoDB client-access products. + +Sources checked on 2026-06-25: + +- MongoDB official client libraries list: + `https://www.mongodb.com/docs/drivers/` +- MongoDB Node.js driver docs: + `https://www.mongodb.com/docs/drivers/node/current/` +- MongoDB Node.js transaction docs: + `https://www.mongodb.com/docs/drivers/node/current/crud/transactions/` +- MongoDB transaction manual: + `https://www.mongodb.com/docs/manual/core/transactions/` +- MongoDB Atlas App Services EOL notice: + `https://www.mongodb.com/docs/api/doc/atlas-app-services-admin-api-v3/` +- Deprecated Atlas Data API docs: + `https://www.mongodb.com/docs/api/doc/atlas-data-api-v1/` +- Dart package checks: + `https://pub.dev/packages/mongo_dart` and + `https://pub.dev/packages/mongo_db_driver` + +## Decision + +V1 selects a trusted service boundary for MongoDB persistence. + +The MongoDB-owning runtime is a separate Node.js/TypeScript service using the +official MongoDB Node.js driver. This service owns: + +- MongoDB connection strings and credentials; +- TLS/SRV driver configuration; +- client lifecycle and health checks; +- index bootstrap from the Block 15 index catalog; +- document reads/writes against the V1 collection contract; +- sessions and transactions for multi-record scheduling writes; +- redacted diagnostics and failure mapping. + +The Flutter UI never connects directly to MongoDB and never receives connection +strings, database credentials, raw MongoDB documents, driver clients, +collections, sessions, or cursors. + +The pure Dart package remains dependency-free with respect to MongoDB. Dart +domain and application code continue to use repository interfaces and typed use +case results. The trusted service exposes a narrow versioned application API +that maps to the Block 14 use cases and Block 15 document contract. + +During the UI foundation/design spike, the first Flutter UI should use the +existing in-memory application composition by default. Persisted development +flows may use a local trusted service process, but that process remains outside +the Flutter binary and reads secrets only from runtime configuration. + +## Rejected Options + +### Direct MongoDB from Flutter or mobile Dart + +Rejected. It would place database credentials in an untrusted binary and force +the UI to own network/database failure modes. It also couples the UI to driver +types and makes owner-scope/security mistakes harder to contain. + +### Pure Dart MongoDB adapter as the production V1 foundation + +Rejected for now. MongoDB's official client library list does not include Dart. +`mongo_dart` is active and useful for experiments, but it is community-supported +rather than an official MongoDB driver. `mongo_db_driver` advertises sessions and +transactions, but its package page explicitly identifies it as pre-alpha and not +suitable for production. Neither should become the V1 persistence foundation +without a later ADR reversing this decision. + +### Atlas Data API, Atlas Device SDKs, App Services, GraphQL, Functions, or +Custom HTTPS Endpoints + +Rejected. MongoDB's App Services notice says these paths reached end-of-life on +September 30, 2025, with database triggers remaining available. They are not a +stable V1 foundation. + +### SQLite or another local fallback + +Rejected. MongoDB remains the committed persistence target. A disconnected +fallback would add an unplanned sync/reconciliation problem and violate the +current persistence target rules. + +## Driver and Deployment Requirements + +The selected service must use the official MongoDB Node.js driver current major +line at implementation time. + +Mandatory capabilities: + +- `mongodb+srv://` and TLS-capable connections for Atlas; +- BSON fidelity at the adapter edge; +- sessions and multi-document transactions; +- explicit transaction retry handling for documented retryable categories; +- bounded connection and operation timeouts; +- graceful startup/shutdown and health checks; +- idempotent index creation; +- redacted logging; +- no raw driver values in public service DTOs. + +MongoDB deployment requirements: + +- Multi-document scheduling writes require MongoDB Server 4.0 or later. +- Transaction acceptance requires a transaction-capable deployment. V1 local and + CI testing must use a replica set or supported sharded deployment, not a + standalone server. +- If the service cannot verify transaction capability at startup for a + production Mongo-backed configuration, it must fail closed instead of falling + back to untracked in-memory writes. + +## Configuration Boundary + +Development configuration: + +- Uses environment variables or a local secret file excluded from git. +- May point to a disposable local replica set or scoped Atlas development + database. +- Must use a database name or prefix that is safe for destructive test cleanup. + +Test configuration: + +- Uses uniquely named disposable databases/collections. +- Fails if the configured target does not match the expected test scope. +- Redacts connection strings and credentials from test output. + +Production configuration: + +- Secrets come from deployment secret storage. +- The Flutter/mobile app receives only service endpoint configuration and + application-layer auth/session material once that future work is explicitly + planned. +- Production authentication, account management, cross-device sync, Atlas + provisioning, network allowlists, and cluster creation remain out of scope for + this block. + +## Threat and Safety Checklist + +- No MongoDB connection string is committed to source control. +- No MongoDB credential is embedded in Flutter, mobile, desktop, or web UI + assets. +- Normal logs do not include task titles, hidden locked-block names, full + documents, connection strings, or credential fragments. +- Every repository query and write includes owner scope. +- Hidden locked-time details remain hidden by default in service responses. +- Duplicate operation IDs are enforced by a unique owner-operation index. +- Revision predicates are required for authoritative updates. +- Transaction retries are bounded and observable. +- A production Mongo connection failure fails closed. +- In-memory composition remains available only as explicit local/design-spike + wiring, not as a silent production persistence fallback. + +## Consequences + +Block 16.2 must add any MongoDB dependency only in the trusted service/runtime +module, not in the pure Dart core package. + +The implementation path should provide two composition roots: + +- in-memory Dart application wiring for tests and UI design work; +- trusted service-backed persistence for MongoDB-backed development and future + deployment. + +If a later chunk cannot implement the selected service boundary without +duplicating scheduling rules unsafely, it must stop and record the blocker +rather than embedding credentials in Flutter or adopting an unmaintained driver +as a shortcut. diff --git a/Codex Documentation/Current Software Plan/V1_BLOCK_16_MongoDB_Runtime_Adapter.md b/Codex Documentation/Current Software Plan/V1_BLOCK_16_MongoDB_Runtime_Adapter.md index 3c2eafe..3a29cfe 100644 --- a/Codex Documentation/Current Software Plan/V1_BLOCK_16_MongoDB_Runtime_Adapter.md +++ b/Codex Documentation/Current Software Plan/V1_BLOCK_16_MongoDB_Runtime_Adapter.md @@ -1,6 +1,6 @@ # V1 Block 16 — MongoDB Runtime Adapter and Transaction Boundary -Status: Planned +Status: In progress Purpose: Implement the committed MongoDB persistence target behind the completed repository/application contracts while keeping credentials out of Flutter and @@ -10,6 +10,8 @@ making multi-record scheduling operations safe. Recommended Codex level: extra high +Status: Complete + Tasks: - Re-check current official MongoDB driver support, transaction requirements, @@ -54,6 +56,29 @@ Acceptance criteria: - 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`.