template-app/profiles/mongodb/README.md

<!-- SPDX-License-Identifier: LicenseRef-ConusAI-Template-1.0 -->
# The mongodb profile

**Status (2026-11-01): a selectable app profile; local evidence only.** `kit template:prune --profile
mongodb` selects it: it sets `PROFILE` in `config/src/env.ts`, copies this folder's `conusai.json`,
`compose.yaml` and `compose.dev.yaml` to the app root and moves its `migrations/` to `migrations/mongodb/`.
Every process then reads the one `MONGODB_URL` login and `REDIS_URL` (`config/src/env.ts`); the web
(`apps/web/src/server/dialect/`) and the worker and migrate job (`apps/worker/src/dialect/`) compose the
mongodb data source, BullMQ on Valkey and the kit's outbox relay. The modules `account`, `notes` and
`documents` ship mongodb migrations and adapters, so self-service account export and erasure work here;
`agent` and `knowledge` declare Postgres only and are not part of an app on this profile. Live collections
run (the web follows the live collections' change stream; the migrate job enables pre-images per collection). Module cron: the worker installs the modules' schedules that this profile ships as BullMQ job
schedulers when it starts (`apps/worker/src/dialect/schedules.ts`: `files.recover` and the account
sweeps, commit 589a06079; the agent module's run retention is Postgres-only). Source and local
tests only; no live worker has run them yet. No generated app on this profile has been deployed on a
ConusAI install. Adapter, migration and live-conformance tests do not establish a deployment.


The persistence profile for an app whose primary store is MongoDB instead of Postgres
(spec §5.1): the same procedures, the same modules, the same migrations discipline, on the
official `mongodb` driver (`@conusai-kit/data-mongo`) with jobs on BullMQ over Valkey
(`@conusai-kit/jobs-bullmq`).

| | postgres (default) | mongodb (this profile) |
|---|---|---|
| Primary store | Postgres 18 | MongoDB 8.0, **single-node replica set** (below) |
| Data adapter | `@conusai-kit/data-kysely` | `@conusai-kit/data-mongo` |
| Jobs | pg-boss (Postgres) | BullMQ on Valkey (`@conusai-kit/jobs-bullmq`) |
| Tenant wall | repository predicate + RLS (three roles, AT-D20) | repository predicate + compound indexes leading with `org_id` — MongoDB has no RLS |
| Links | `postgres`, `identity` | `mongodb`, `redis`, `identity` |
| Process env | `POSTGRES_URL`, `POSTGRES_READER_URL`, `POSTGRES_MIGRATE_URL` | `MONGODB_URL`, `REDIS_URL` |

Registered modules must support the selected persistence profile. The web, worker and migrate
compositions refuse unsupported modules by name before connecting to services; their data-rights
hooks and adoption history are preserved. Fresh backend conformance fixtures explicitly author a
compatible module set for both the registry and data source. These fixtures do not migrate an adopted
starter or establish a public scaffold command; the existing CLI custody refusal still applies.

## The replica_set requirement (AT-D15)

**Create the MongoDB service with `replica_set` set.** A managed MongoDB is a standalone server
unless `replica_set` is given at creation (the console's create form offers it and states it
cannot be changed afterwards), and a standalone server has no multi-document transactions — a
`unitOfWork.run` on it would be silently non-atomic. `@conusai-kit/data-mongo` therefore asks the
server what it is at boot (`hello`'s `setName`) and refuses to start against a standalone mongod
with a `MongoTopologyError` that names this setting. A single-node replica set is enough: with
`replica_set` set, the platform starts mongod with `--replSet` and `rs.initiate()`, and the
injected `MONGODB_URL` carries `directConnection=true`. The `conusai.json` in this folder links
`mongodb` — that link is only valid for an app whose MongoDB service was created this way.

## What this folder carries

- `conusai.json` — the profile's deployment contract: the same three services, links `mongodb` +
  `redis` + `identity`. There is no `mongodb.migrate` flag: the three-role split the postgres
  profile declares (data-services DS21) exists to make row-level security bind, and MongoDB has
  none, so every process holds the one `MONGODB_URL` and ordering is compose's
  `service_completed_successfully` alone (AT-D14).
- `compose.yaml`, `compose.dev.yaml` — the profile's compose files. The dev overlay runs
  `mongo:8.0` as a single-node replica set (`--replSet` plus a one-shot `mongo-init` that runs
  `rs.initiate()`) and `valkey/valkey:9-alpine`, the images the platform's catalog offers.
- `migrations/` — the kernel collections (tenancy, sign-in, files, proposals, outbox, idempotency
  keys) as declarative MongoDB commands in JSON — a collection with its `$jsonSchema` validator
  generated from the entity's zod schema, and every unique group and index as a compound index
  leading with `org_id` — generated by `mongoSchemaCommands` from the same entity definitions as
  the postgres files and committed, forward-only. A module's own MongoDB migrations live with the
  module: `modules/<id>/adapters/mongo/migrations/`, declared in its manifest as
  `migrations: { postgres: "migrations", mariadb: "...", mongodb: "adapters/mongo/migrations" }`.

## The composition (wired)

The profile is chosen at generation time (`.conusai/template.json` `profile`), and
`kit template:prune --profile mongodb` removes the other dialects. What it selects:

1. `config/src/env.ts` reads `MONGODB_URL` (every process) instead of the three Postgres URLs --
   one login, because there is no RLS to bind (AT-D20 is Postgres-only) -- and `REDIS_URL` for the queue.
2. `apps/web` (`src/server/dialect/stores.ts`) and `apps/worker` (`src/dialect/runtime.ts`) compose
   `connectMongoDataSourceFromEnv` (which refuses a standalone server, above) and the queue is `createBullmqJobQueue`/`createBullmqWorker` over `REDIS_URL`, with the
   kit's outbox relay over the same data source.
3. The migrate job (`apps/worker/src/migrate.ts`, `migrateDialect`) runs `runMongoMigrationsFromEnv` (each JSON file a `mongoCommandsMigration`) over
   `migrations/mongodb/` (moved there from this folder) and the modules' `adapters/mongo/migrations/`, then the job
   adapter's table and the live capture of each collection.
4. This folder's `conusai.json`, `compose.yaml` and `compose.dev.yaml` replace the root ones.

The dialect differences are explicit, never generated at run time (spec §5.3): a module's MongoDB
schema is its own numbered folder, reviewed like any migration.

## Proof

- `@conusai-kit/data-mongo` passes the shared repository and capability contract suites in
  testcontainers against MongoDB 8 running as a single-node replica set, including a multi-entity
  UnitOfWork commit and rollback — the tenant predicate is the wall, and the contract is what
  proves it. Against a standalone mongod the adapter refuses to boot with `MongoTopologyError`,
  naming `replica_set` (AT-D15). The suite's image is `mongo:8.2`, not `mongo:8.0`: the 8.0 binary
  refuses to start on Linux kernels 6.19 and newer (SERVER-121912, the TCMalloc/rseq
  incompatibility — the refusal is compiled into the server), which covers current development
  hosts; the topology under test is the same on either minor, and the platform's managed image is
  `mongodb-walg:8.0`. The same applies to this folder's `compose.dev.yaml` on such a kernel: bump
  its `mongo:` tag to 8.2.
- `@conusai-kit/jobs-bullmq` passes the shared JobQueue contract against `valkey/valkey:9` in
  testcontainers.
- `scripts/vendor/test-template.sh app --profile mongodb` runs the template's gate and then
  applies this folder's and the modules' MongoDB migrations to a real MongoDB 8 container
  started as a single-node replica set, and probes that the adapter boots on it and refuses a
  standalone server — so the committed schema is proven against the engine, not just generated.