driver-mongodb: `bulkUpdate`'s single `bulkWrite` is only atomic when the caller supplies a session — a mid-batch refusal without one leaves earlier ops applied

[os-support-ai]

Measured while implementing #13854 (SqlDriver.bulkUpdate transaction wrapper). #13854's dispatch owed one reading: does driver-mongodb carry the same shape? This card records the answer, which is "not the same shape, but a related exposure" — filed separately rather than widened into #13854's PR, exactly as that card's scope required.

The reading (measured on origin/main, by symbol)

packages/drivers/driver-mongodb/src/mongodb-driver.ts:

• bulkUpdate (:505) is NOT driver-sql's shape. It does not loop over N awaited update() calls. It maps updates into a bulkOps array of updateOne descriptors and issues one collection.bulkWrite(bulkOps, { session }), then re-reads the affected ids.
• bulkDelete (:534) is one collection.deleteMany({ id: { $in: ids } }, { session }) — the same "single statement" shape as SqlDriver.bulkDelete, which driver-sql: bulkUpdate is a sequential per-row loop with no transaction — a mid-batch refusal leaves earlier rows committed (driver-turso inherits it via super.) #13854 measured and correctly left out of scope.
• session in both comes from getSession(options) (:687), which is exactly options.transaction as ClientSession | undefined — the same options.transaction parameterisation the SQL driver uses.

So the per-row autocommit loop #13854 repaired does not exist here. That half of the reading is settled.

Why this is still worth a card

The consequence class may nevertheless be reachable, through a different mechanism. bulkWrite defaults to ordered: true, which stops at the first failing operation — but operations already applied are not undone unless the operation is running inside a transaction. When the caller passes no options.transaction, session is undefined, so a batch refused partway through would leave the earlier updateOne ops applied: the same end state #13340 / #13435 / #13854 closed on the other two drivers, arrived at by a different route.

⚠️ Split by evidence, because the two halves are not equally established:

• Measured (read from the source in this repo): the shapes and the session plumbing described above.
• NOT measured, and the reason this is a card rather than a patch: that a mid-batch refusal actually leaves earlier ops applied here. That is standard MongoDB bulkWrite semantics rather than something observed against this driver, and it was deliberately not driven to a repro — driver-sql: bulkUpdate is a sequential per-row loop with no transaction — a mid-batch refusal leaves earlier rows committed (driver-turso inherits it via super.) #13854's scope was explicit that driver-mongodb is read-only, measure and report. It needs a real refusal driven through this door before anyone acts on it.

Why the #13854 fix does not simply transfer

⛔ Do not assume the repair is "wrap it in a transaction like the SQL driver". MongoDB multi-document transactions require a replica set (or a sharded cluster) — they are unavailable on a standalone mongod, which is a supported deployment. So an unconditional driver-opened transaction would turn a currently-working call into a hard failure on those deployments. That is a genuine decision, not a mechanical port, which is the other reason this is filed rather than fixed in passing.

Sketch of the option space, for whoever picks this up:

1. Open a transaction only when the topology supports one, and document the weaker guarantee elsewhere — declared ≠ enforced, which is the shape this project usually refuses.
2. Require the caller to supply a session for atomicity, and say so in the contract — honest, but leaves the bulk door's implied promise unmet by default.
3. Decide the bulk door does not promise atomicity on this driver, and record that as an explicit, tested difference rather than an accident.

Related

#13854 (driver-sql, the card this reading was owed to) · #13435 · #13340 (the driver-memory half of the same defect class)

Filed unassigned and unlabelled for triage, per the dispatch's out-of-scope rules.

Generated by Claude Code

[huangyiirene]

Triage (R+89, triage seat, session session_019kDRpB7D2XzVzkaLp57T5D): graded → pm:on-hold · priority:p2 · domain:engine · type Task. finding removed.

Why hold, not queue: the standing maintainer ruling of 2026-08-05 recorded on #5499 freezes defect-repair and semantic-completion investment in driver-memory / driver-mongodb ("driver-mongodb 暂无客户;创业团队集中精力,不铺大"), and its standing triage rule for new cards is verbatim: 「driver-memory / driver-mongodb 族新单照常按落点打 domain:engine,但直接挂 pm:on-hold 引用本单,不入 pm:queue」. This card's landing file is packages/drivers/driver-mongodb/src/mongodb-driver.ts (bulkUpdate), so the rule applies by construction. The freeze's escalation exception (a driver-memory defect that corrupts CI verdicts) does not reach a driver-mongodb atomicity question.

What is preserved for the day it restarts: the card's own split — the measured half (single bulkWrite, session from options.transaction) and the unmeasured half (that a mid-batch refusal leaves earlier ops applied here) — plus the three-way option space, of which option 3 (declare and test that the bulk door does not promise atomicity on this driver) is the one that stays inside the freeze's "no investment" letter if a customer ever forces the question.

Restart-when: closed #5499
Restart-touch: packages/drivers/driver-mongodb/src/mongodb-driver.ts

(Hold provenance: triage seat grading under the #5499 maintainer ruling, 2026-09-02.)

---

Generated by Claude Code