@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/packs/mongo/checks/mongoclient-cached-and-named.json

@@ -0,0 +1,34 @@
+{
+  "id": "mongoclient-cached-and-named",
+  "why": "A MongoClient created without the globalThis cache stacks a new pool on every hot reload, and without appName it is anonymous in the Atlas connection view.",
+  "rule": ".claude/rules/one-client-one-pool.md",
+  "concepts": [
+    "db-gateway"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**",
+    "**/scripts/**",
+    "**/migrations/**",
+    "**/seeds/**",
+    "**/bin/**"
+  ],
+  "code": true,
+  "mode": "needs",
+  "pattern": "\\bnew\\s+MongoClient\\s*\\(",
+  "needs": [
+    "\\bglobalThis\\b|\\b(?:let|var)\\s+\\w*[Cc]lient\\b|\\b\\w*[Cc]lient\\s*\\?\\?=",
+    "\\bappName\\s*:",
+    "\\bmaxPoolSize\\s*:"
+  ],
+  "bad": "client = new MongoClient(uri, { ignoreUndefined: true });",
+  "good": "const g = globalThis as { __mongoClient?: MongoClient };\ng.__mongoClient ??= new MongoClient(env.MONGODB_URI, { appName: env.APP_NAME, maxPoolSize: 10 });\nlet client;\nexport const getClient = () => (client ??= new MongoClient(uri, { appName: name, maxPoolSize: 10 }));\n"
+}

package/packs/mongo/checks/mongoclient-outside-gateway.json

@@ -0,0 +1,24 @@
+{
+  "id": "mongoclient-outside-gateway",
+  "why": "A second MongoClient is a second connection pool. The client lives in the gateway (cached on globalThis) or in a one-off script, nowhere else.",
+  "rule": ".claude/rules/one-client-one-pool.md",
+  "concepts": [
+    "db-callers"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**"
+  ],
+  "code": true,
+  "pattern": "\\bnew\\s+MongoClient\\s*\\(",
+  "bad": "const client = new MongoClient(uri);",
+  "good": "const db = await getDb();"
+}

package/packs/mongo/checks/no-count-plus-one-ids.json

@@ -0,0 +1,25 @@
+{
+  "id": "no-count-plus-one-ids",
+  "why": "countDocuments()+1 as an id races: two concurrent creates get the same number and the unique index throws an opaque E11000. Use an $inc counter document with findOneAndUpdate.",
+  "rule": ".claude/rules/writes-are-atomic.md",
+  "concepts": [
+    "db-gateway",
+    "db-scripts"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**"
+  ],
+  "code": true,
+  "pattern": "countDocuments\\s*\\([^;]*\\)\\s*\\)?\\s*\\+\\s*1\\b|\\bn\\s*\\+\\s*1\\s*\\}`|\\(await\\s+[\\w.]*countDocuments[^;]*\\)\\s*\\+\\s*1",
+  "bad": "return `WO-${(await scope.countDocuments({ kind: 'work' })) + 1}`;",
+  "good": "const c = await counters.findOneAndUpdate({ _id: `wo:${sessionId}` }, { $inc: { n: 1 } }, { upsert: true, returnDocument: 'after' });\nreturn `WO-${c.n}`;"
+}

package/packs/mongo/checks/no-db-write-in-loop.json

@@ -0,0 +1,25 @@
+{
+  "id": "no-db-write-in-loop",
+  "why": "A write per iteration is a round trip per iteration. Collect the ops and run one bulkWrite, or update one document with arrayFilters.",
+  "rule": ".claude/rules/writes-are-atomic.md",
+  "concepts": [
+    "db-gateway",
+    "db-scripts"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**"
+  ],
+  "code": true,
+  "pattern": "\\bfor\\s*(?:await\\s*)?\\([^)]*\\)\\s*\\{[^{}]*?\\bawait\\s+[\\w.()]*\\.(?:insertOne|updateOne|deleteOne|replaceOne|findOneAndUpdate)\\s*\\(",
+  "bad": "for (const s of steps) {\n  await scope.workorders.updateOne({ number }, { $set: { [`plan.$[s].status`]: 'done' } });\n}",
+  "good": "await scope.workorders.bulkWrite(steps.map((s) => ({ updateOne: { filter: { number }, update: { $set: { 'plan.$[s].status': 'done' } }, arrayFilters: [{ 's.qid': s.qid }] } })));"
+}

package/packs/mongo/checks/no-drop-in-code.json

@@ -0,0 +1,27 @@
+{
+  "id": "no-drop-in-code",
+  "why": "dropDatabase()/drop() in application code is an ops runbook action with a human gate, not a script line.",
+  "rule": ".claude/rules/deletes-name-what-dies.md",
+  "concepts": [
+    "db-gateway",
+    "db-scripts",
+    "db-callers"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**",
+    "**/data/**"
+  ],
+  "code": true,
+  "pattern": "\\.(dropDatabase|dropCollection)\\s*\\(|\\bcollection\\([^)]*\\)\\s*\\.drop\\s*\\(",
+  "bad": "await db.dropDatabase();",
+  "good": "await col.deleteMany({ sessionId });"
+}

package/packs/mongo/checks/no-empty-deletemany.json

@@ -0,0 +1,26 @@
+{
+  "id": "no-empty-deletemany",
+  "why": "deleteMany with an empty filter wipes the collection. Name what to delete; if the store upserts on a stable key, ask whether the delete is needed at all.",
+  "rule": ".claude/rules/deletes-name-what-dies.md",
+  "concepts": [
+    "db-gateway",
+    "db-scripts",
+    "db-callers"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**"
+  ],
+  "code": true,
+  "pattern": "\\.deleteMany\\s*\\(\\s*(\\{\\s*\\})?\\s*\\)",
+  "bad": "await col.deleteMany({});",
+  "good": "await col.deleteMany({ sessionId, status: 'expired' });"
+}

package/packs/mongo/checks/no-find-reads.json

@@ -0,0 +1,26 @@
+{
+  "id": "no-find-reads",
+  "why": "Reads are aggregation pipelines: shaping happens in the database and the pipeline is composable data. Add '// mongo: allow find' with a reason for a real exception.",
+  "rule": ".claude/rules/reads-aggregate-writes-bulk.md",
+  "concepts": [
+    "db-gateway",
+    "db-scripts"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**"
+  ],
+  "code": false,
+  "pattern": "^(?!.*//\\s*mongo:\\s*allow find)(?![^\\n]*\\.(?:limit|sort)\\s*\\()[^\\n]*[Cc]ollection\\b[^\\n]*\\.find\\s*\\(|^(?![^\\n]*\\.(?:limit|sort)\\s*\\()[^\\n]*\\.find\\s*\\(\\s*\\{[^\\n]*\\)\\s*\\.(?:toArray|skip)\\s*\\(",
+  "flags": "m",
+  "bad": "const docs = await collection.find({ a: 1 }).toArray();\nconst rows = await collection.find(q).toArray();\n",
+  "good": "const docs = await col.aggregate([{ $match: { a: 1 } }, { $limit: 50 }]).toArray();\nconst x = items.find((i) => i.id === id);\nconst last = await collection.find(q).sort({ at: -1 }).limit(20).toArray();\n"
+}

package/packs/mongo/checks/no-input-spread-into-write.json

@@ -0,0 +1,24 @@
+{
+  "id": "no-input-spread-into-write",
+  "why": "Whatever field the server trusts later can be set by the client today.",
+  "rule": ".claude/rules/keys-hashed-input-picked.md",
+  "concepts": [
+    "js"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "code": true,
+  "pattern": "(?:insertOne\\(|insertMany\\(|document:\\s*|\\$set:\\s*)\\{\\s*\\.\\.\\.(?:req\\.body|body|payload|input|event|data|params)\\b|\\.\\.\\.(?:req\\.body|body)\\s*,\\s*\\n\\s*\\w+At\\b|\\.map\\(\\(?(?:event|e|doc|item)\\)?\\s*=>\\s*\\(\\{\\s*\\.\\.\\.(?:event|e|item)\\s*,",
+  "bad": "await col.insertOne({ ...body, receivedAt: new Date() });",
+  "good": "await col.insertOne({ error: input.error, receivedAt: new Date() });"
+}

package/packs/mongo/checks/no-mongoose.json

@@ -0,0 +1,23 @@
+{
+  "id": "no-mongoose",
+  "why": "Mongoose is not used: the native driver plus Zod is the data layer.",
+  "rule": ".claude/rules/driver-only-in-gateway.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.js",
+    "**/*.mjs",
+    "**/package.json"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**"
+  ],
+  "code": false,
+  "pattern": "[\\\"']mongoose[\\\"']",
+  "bad": "import mongoose from 'mongoose';",
+  "good": "import { MongoClient } from 'mongodb';"
+}

package/packs/mongo/checks/no-negation-delete.json

@@ -0,0 +1,26 @@
+{
+  "id": "no-negation-delete",
+  "why": "A delete filter on $ne/$nin/$not deletes everything EXCEPT one value; one wrong constant empties the store while reading as a cleanup. Name what to delete, not what to keep, and count first.",
+  "rule": ".claude/rules/deletes-name-what-dies.md",
+  "concepts": [
+    "db-gateway",
+    "db-scripts",
+    "db-callers"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**"
+  ],
+  "code": true,
+  "pattern": "\\.delete(Many|One)\\s*\\([^)]*\\$(ne|nin|not)\\b",
+  "bad": "await col.deleteMany({ version: { $ne: current } });",
+  "good": "await col.deleteMany({ version: { $in: staleVersions } });"
+}

package/packs/mongo/checks/no-non-null-after-findone.json

@@ -0,0 +1,25 @@
+{
+  "id": "no-non-null-after-findone",
+  "why": "(await findOne())! after a write turns a race (purge, archive) into a TypeError reported as INTERNAL. Return the document from findOneAndUpdate, or handle null.",
+  "rule": ".claude/rules/writes-are-atomic.md",
+  "concepts": [
+    "db-gateway",
+    "db-callers"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**"
+  ],
+  "code": true,
+  "pattern": "\\(\\s*await\\s+[^()]*findOne\\s*\\((?:[^()]|\\([^()]*\\))*\\)\\s*\\)\\s*!|\\bawait\\s+[\\w.]*findOne\\s*\\((?:[^()]|\\([^()]*\\))*\\)\\s*;[^;]{0,120}?\\b(\\w+)!\\)",
+  "bad": "return (await goals.findOne({ _id: r.insertedId }))!;\nconst experiment = await scope.experiments.findOne({ _id });\nreturn { experiment: toResponse(experiment!) };",
+  "good": "const doc = await goals.findOneAndUpdate(filter, update, { upsert: true, returnDocument: 'after' });\nif (doc === null) throw new AdmiralError(ErrorCodes.NOT_FOUND, 'goal vanished');"
+}

package/packs/mongo/checks/objectid-equals.json

@@ -0,0 +1,26 @@
+{
+  "id": "objectid-equals",
+  "why": "Comparing ObjectIds by toHexString() is four calls and a string compare where ObjectId.equals exists and also accepts a string.",
+  "rule": ".claude/rules/writes-are-atomic.md",
+  "concepts": [
+    "db-gateway",
+    "db-callers",
+    "db-scripts"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**"
+  ],
+  "code": true,
+  "pattern": "toHexString\\(\\)\\s*[!=]==?\\s*[\\w.]*toHexString\\(\\)",
+  "bad": "if (o._id.toHexString() === parent._id.toHexString())",
+  "good": "if (o._id.equals(parent._id))"
+}

package/packs/mongo/checks/update-then-reread.json

@@ -0,0 +1,24 @@
+{
+  "id": "update-then-reread",
+  "why": "updateOne followed by findOne/findOrder to return the document is two round trips where findOneAndUpdate({ returnDocument: 'after' }) is one.",
+  "rule": ".claude/rules/writes-are-atomic.md",
+  "concepts": [
+    "db-gateway"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**"
+  ],
+  "code": true,
+  "pattern": "\\.updateOne\\s*\\((?:[^()]|\\([^()]*\\))*\\)\\s*;\\s*(?:return\\s+)?(?:\\w+\\s*=\\s*)?(?:await\\s+)?[\\w.]*find(?:One|Order|Session|Message)\\s*\\(",
+  "bad": "await scope.workorders.updateOne({ number }, { $set: { status: 'sent' } });\nreturn findOrder(scope, number);",
+  "good": "return scope.workorders.findOneAndUpdate({ number }, { $set: { status: 'sent' } }, { returnDocument: 'after' });"
+}

package/packs/mongo/checks/watch-not-poll.json

@@ -0,0 +1,25 @@
+{
+  "id": "watch-not-poll",
+  "why": "A deadline loop that sleeps and re-queries is ~130 round trips per wait. A change stream or a findOneAndUpdate wake-up costs one.",
+  "rule": ".claude/rules/writes-are-atomic.md",
+  "concepts": [
+    "db-gateway",
+    "db-callers"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**"
+  ],
+  "code": true,
+  "pattern": "\\bwhile\\s*\\(\\s*Date\\.now\\s*\\(\\)\\s*<[^{]*\\{[\\s\\S]{0,400}?\\bawait\\s+(?:sleep|delay|setTimeout|wait)\\s*\\(",
+  "bad": "while (Date.now() < deadline) {\n  const op = await fileops.findOne({ _id });\n  if (op?.status !== 'pending') return op;\n  await sleep(150);\n}",
+  "good": "const stream = fileops.watch([{ $match: { 'documentKey._id': _id } }]);\nconst next = await Promise.race([stream.next(), timeout]);"
+}

package/packs/mongo/pack.json

@@ -0,0 +1,52 @@
+{
+  "name": "mongo",
+  "version": "1.0.0",
+  "description": "MongoDB with the native driver: one client, one gateway, aggregation reads, bulkWrite writes, safe deletes.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/mongo"
+  },
+  "keywords": [
+    "mongodb"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "folders": {},
+  "concepts": {
+    "db-gateway": [
+      "**/gateway.ts",
+      "**/gateway/**",
+      "**/db/**",
+      "**/lib/db.*",
+      "**/lib/db/**",
+      "**/adapters/**",
+      "**/repositories/**",
+      "**/*.repository.*",
+      "**/*mongo*"
+    ],
+    "db-scripts": [
+      "**/scripts/**",
+      "**/migrations/**",
+      "**/seeds/**",
+      "**/bin/**"
+    ],
+    "db-callers": [
+      "**/routes/**",
+      "**/handlers/**",
+      "**/services/**",
+      "**/app/**",
+      "**/pages/**",
+      "**/components/**",
+      "**/ui/**",
+      "**/lifecycle/**"
+    ]
+  },
+  "skillsIn": null,
+  "hooks": {}
+}

package/packs/mongo/rules/deletes-name-what-dies.md

@@ -0,0 +1,21 @@
+---
+# concepts: db-gateway, db-scripts
+paths:
+  - "placeholder"
+---
+
+# A delete names what to delete, never what to keep
+
+<constraints>
+Always do:
+- Count first: run the filter as a count or `$match` + `$count`, log the number, then delete. A delete whose match count surprises you was about to be an incident.
+- Prefer an upsert on a stable key over a purge-and-reload: overwriting in place makes most deletes unnecessary.
+- Identity in the filter, never in the body of a write (`_id` in `$set` after a JSON round-trip throws code 66).
+- `_id` is an `ObjectId`. A string `_id` against an ObjectId document matches nothing, silently.
+- `null` is not "missing": `{ f: null }` matches null **and** absent. Use `$exists: false` for missing.
+
+Never do:
+- `deleteMany({})` or `deleteMany()` outside test cleanup (`no-empty-deletemany` check).
+- A delete filter built on a negation (`$ne`, `$nin`, `$not`) against a status or version field: it deletes everything except one value, and one wrong constant empties the store while reading as a cleanup (`no-negation-delete` check).
+- `dropDatabase()` / `drop()` in application code: that is an ops runbook action with a human gate (`no-drop-in-code` check).
+</constraints>

package/packs/mongo/rules/driver-only-in-gateway.md

@@ -0,0 +1,26 @@
+---
+# concepts: db-callers
+paths:
+  - "placeholder"
+---
+
+# The driver is touched in one gateway; features import functions from it
+
+The model writes new code by imitating the imports it sees. One obvious gateway gets reused; a scattered one gets reinvented, and with it the session scoping, the id rehydration and the error mapping that the gateway was built to centralise.
+
+<constraints>
+Always do:
+- Reach the database only by importing a named function from the gateway (`findSessionById`, `appendActivity`). New collection, new query shape: **a new function in the gateway**, never a driver call at the call site.
+- Keep the gateway's header contract (five lines, at the top of its entry module) so whoever extends it reads the rules at that moment:
+  ```ts
+  // DATABASE GATEWAY: the ONLY module that touches the driver.
+  // Features import query/write functions from here; no MongoClient or db.collection() anywhere else.
+  // Reads are aggregation pipelines; multi-doc writes go through bulkWrite.
+  // New collection => new function here. Rule: driver-only-in-gateway.
+  ```
+- Rehydrate at the boundary: JSON turns `ObjectId` and `Date` into strings; the gateway function takes a string id and wraps it with `new ObjectId(id)` itself.
+
+Never do:
+- `MongoClient`, `db.collection(`, `getDb()` in routes, handlers, services, UI or lifecycle code. The `driver-outside-gateway` check refuses them. The gateway's **typed scope** (`forSession(id).experiments.insertOne(...)`) is its exported surface and is fine to call; a raw `Collection` is not.
+- Pass a raw `Collection` out of the gateway "just this once".
+</constraints>

package/packs/mongo/rules/keys-hashed-input-picked.md

@@ -0,0 +1,21 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# Keys are matched by hash, and a stored document is built from named fields
+
+<constraints>
+Always do:
+- Look up API keys and tokens by their hash.
+- Build a stored document from the fields you name.
+- Make a filter sanitiser throw on what it cannot pass: one that drops a condition widens the query.
+- Put a limit on every list read.
+
+Never do:
+- Spread a request object into a write.
+</constraints>
+
+## Check
+`key-lookup-is-hashed`, `no-input-spread-into-write`.

package/packs/mongo/rules/one-client-one-pool.md

@@ -0,0 +1,32 @@
+---
+# concepts: db-gateway, db-scripts
+paths:
+  - "placeholder"
+---
+
+# One MongoClient per process: it IS the pool
+
+The client owns the connection pool (`maxPoolSize`, default 100 per server). A second client is a second pool. Five clients at defaults can claim a free Atlas cluster's whole 500-connection budget before one query runs, and `client.close()` per request does not help: it adds a full TCP/TLS/auth handshake per request and pools still overlap under load.
+
+<constraints>
+Always do:
+- Create the client **once, in the gateway**, cached on `globalThis`, because hot reload (Next.js dev, tsx watch) re-runs module scope and a plain module-level client stacks a new pool per save:
+  ```ts
+  const g = globalThis as { __mongoClient?: MongoClient };
+  export function mongoClient(): MongoClient {
+    g.__mongoClient ??= new MongoClient(env.MONGODB_URI, { appName: env.APP_NAME, maxPoolSize: env.MONGO_POOL_SIZE, ignoreUndefined: true });
+    return g.__mongoClient;
+  }
+  ```
+- Set `appName`: it tags every connection in the Atlas dashboard, so "who is eating our connections" becomes a lookup.
+- Set `maxPoolSize` on purpose. The real ceiling is pool size × running instances, and that product must fit under the cluster's connection limit. Serverless and Next.js route handlers: 5–10.
+- URI from the config module only (`env-through-config`). **Never log, print or paste it.**
+- Export `closeDb()` from the gateway and call it from the process lifecycle **after** the HTTP server has closed (`process-lifecycle` in js-ts). Nowhere else closes the client.
+- One-off scripts, seeds and migrations: connect, work, `close()`, exit. That is the one place connect-work-close is right, because the process ends.
+
+Never do:
+- `new MongoClient` outside the gateway or a script. The `mongoclient-outside-gateway` check refuses it.
+- `new MongoClient` in the gateway without `globalThis` and `appName`. The `mongoclient-cached-and-named` check refuses it.
+- `client.close()` after a query, in a route, or in a `finally` of request code.
+- `connect()` lazily inside a request handler: connect at startup so the first request is not the one that discovers a bad URI.
+</constraints>

package/packs/mongo/rules/reads-aggregate-writes-bulk.md

@@ -0,0 +1,25 @@
+---
+# concepts: db-gateway, db-scripts
+paths:
+  - "placeholder"
+---
+
+# Reads shape and bound in the database; multi-document writes are one bulkWrite
+
+<constraints>
+Always do:
+- Read with `.aggregate([{ $match }, { $sort }, { $limit }, { $project }])`: the shaping happens in the database and the pipeline is data you can log, test and compose. `Array.prototype.find` on a plain array is fine; `collection.find()` is not.
+- Paginate by keyset: `$match: { sortKey: { $gt: last }, ... }` on an indexed sort with `_id` as tie-breaker. `$skip` rescans everything before the page.
+- Build the ops in the loop, run **one** `bulkWrite` after it. Never a database call inside a loop.
+- Make writes idempotent (stable keys, set-to-value over blind `$inc`) so a retry is safe. After a partial `bulkWrite` failure retry only the failed ops (`writeErrors[].index`).
+- Upsert is `updateOne(filter, { $set, $setOnInsert }, { upsert: true })` paired with a unique index. Uniqueness is the index, never check-then-insert: the race window is real traffic.
+- Independent queries go in one `Promise.all` (`parallel-independent-awaits`).
+- `createIndex` runs in a deploy or startup step, never in request code.
+- Count with `estimatedDocumentCount` for "roughly how many"; `countDocuments` only when a filter demands it.
+
+Never do:
+- An unbounded `collection.find(` (`no-find-reads` check): a `find` with `.sort()` or `.limit()` in the database is fine; anything that joins or reshapes is a pipeline. Add `// mongo: allow find` with the reason for the rare exception.
+- `insertMany` / `updateMany` / `deleteMany` as the multi-document write path (`bulk-over-many` check). `deleteMany` stays for test cleanup.
+- `$skip` for pagination; an unanchored `$regex` (it forces a collection scan; anchor with `^`).
+- `findOne` then `insertOne` as a uniqueness check.
+</constraints>

package/packs/mongo/rules/writes-are-atomic.md

@@ -0,0 +1,27 @@
+---
+# concepts: db-gateway
+paths:
+  - "placeholder"
+---
+
+# A write is one atomic operation; what spans collections is a transaction
+
+<constraints>
+Always do:
+- A counter is `findOneAndUpdate({ _id: key }, { $inc: { n: 1 } }, { upsert: true, returnDocument: 'after' })`, never `countDocuments() + 1` (`no-count-plus-one-ids`): two concurrent creates get the same number, and the count is wrong after the first delete.
+- A conditional update puts the condition **in the filter** (`{ _id, 'budget.max_turns': { $lt: value } }`), never read → check in JS → write (`no-read-merge-write`).
+- Update-and-return is one `findOneAndUpdate(..., { returnDocument: 'after' })`, not `updateOne` then `findOne` (`update-then-reread`).
+- Writes to two or more collections that must succeed together run inside `session.withTransaction(...)` (the replica set is already there), and the transaction body is idempotent so a retry is safe.
+- Uniqueness is a (partial) unique index: `{ name: 1 }` with `partialFilterExpression: { deleted: false }` lets a soft-deleted name be reused and still blocks live duplicates.
+- Every field a query filters or sorts on is in `indexes.ts`, compound indexes start with the chain key (`session_id`), and GridFS `*.files` metadata queries are indexed too.
+- Driver errors are mapped **in the gateway** to typed app errors: E11000 → `CONFLICT`, code 121 → `VALIDATION`; nobody upstream sees a `MongoServerError`.
+- A changed `facts`/payload from outside is parsed with Zod before it is used (`facts-validated-by-zod`); `as GateResult[]` is not validation.
+
+Never do:
+- `insertOne`/`updateOne` inside a `for` loop (`no-db-write-in-loop`): collect ops, one `bulkWrite` (or `arrayFilters` for one document).
+- `$set: { created_at: … }` on an existing document (`created-at-immutable`): add `queued_at` for re-sorting.
+- `a.toHexString() === b.toHexString()` (`objectid-equals`): `a.equals(b)`.
+- `while (Date.now() < deadline) { …; await sleep(150) }` against the database (`watch-not-poll`): a change stream or a `findOneAndUpdate` wake-up.
+- `(await col.findOne(...))!` right after a write (`no-non-null-after-findone`): return the document from the write.
+- `.find(...)` then `.filter(...)` in JS: the `$nin`/`$match` belongs in the query.
+</constraints>

package/packs/multi-tenant/checks/role-sees-all-tenants.json

@@ -0,0 +1,26 @@
+{
+  "id": "role-sees-all-tenants",
+  "why": "A role inside a tenant must never decide a query across tenants.",
+  "rule": ".claude/rules/no-role-crosses-a-tenant.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.cjs"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "role\\s*===\\s*(?:UserRole\\.)?['\"]?[Oo]wner['\"]?\\s*\\?\\s*\\[\\]|role\\s*!==\\s*(?:UserRole\\.)?['\"]?[Oo]wner['\"]?\\s*&&\\s*\\w+\\._id",
+  "bad": "const pipeline = user.role === UserRole.Owner\n  ? []\n  : [{ $match: { _id: id } }];",
+  "good": "const pipeline = [{ $match: { _id: new ObjectId(user.company_id) } }];",
+  "kind": "security"
+}

package/packs/multi-tenant/checks/tenant-filter-from-url.json

@@ -0,0 +1,25 @@
+{
+  "id": "tenant-filter-from-url",
+  "why": "A query that takes its key from the URL and carries no tenant key reads or writes any tenant.",
+  "rule": ".claude/rules/no-role-crosses-a-tenant.md",
+  "globs": [
+    "**/routes/**/*.ts",
+    "**/routes/**/*.js",
+    "**/app/api/**/route.ts"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "\\b(?:queryOne|updateOne|deleteOne|updateMany|deleteMany|findOne|findOneAndUpdate)(?:<[^(]*?>)?\\(\\s*'[\\w-]+'\\s*,\\s*\\{(?:(?!company_id|tenant_id|org_id|account_id|\\.\\.\\.)[^{}])*(?:req\\.params|\\bslug\\b)(?:(?!company_id|tenant_id|org_id|account_id|\\.\\.\\.)[^{}])*\\}",
+  "bad": "await deleteOne('companies', { slug: req.params.slug });",
+  "good": "await deleteOne('companies', { slug: req.params.slug, company_id: user.company_id });",
+  "kind": "security"
+}