driver-mongodb's published README teaches a spec-REFUSED field key and promises an index authored metadata never gets — it ships to npm

[os-zhuang]

Found by the #12252 dev while measuring the fixture census; reported rather than swept, and filed here by the domain:engine PM seat.

What ships

packages/drivers/driver-mongodb/README.md:172, inside a worked example:

company_id: { type: 'lookup', reference_to: 'company' },

followed by:

// Creates: idx_id_unique, idx_name_unique, idx_email, idx_company_id_lookup

README.md is in this package's files array, so this is published to npm — user-facing instruction, not internal test data.

Two defects in one eight-line sample

1. It teaches a key the spec refuses. reference is the only relationship spelling FieldSchema declares; reference_to fails safeParse with unrecognized_keys (measured on origin/main, #12252). A reader who copies this sample writes an object that cannot be published.

2. The promised index is not produced for a correctly-authored object. Differential probe against the real syncCollectionSchema (#13222): with reference_to the index appears; with the canonical reference it does not, because mongodb-schema.ts:112-113 gates the lookup arm on reference_to. So the comment is true only of the spelling the spec rejects — for anything a user can actually author, idx_company_id_lookup is never created.

The sample is therefore self-consistent only in a state no user can reach: it teaches the wrong key, and its stated outcome depends on that wrongness.

Why it is filed separately from #13222

⚠️ This is wrong whichever way #13222 is ruled, so it must not wait on it:

• if driver-mongodb indexes lookup joins off reference_to — a key the spec REFUSES — so no authored lookup field has ever been indexed on MongoDB #13222 is fixed (the driver reads reference), the sample's spelling is wrong and its index comment becomes right;
• if driver-mongodb indexes lookup joins off reference_to — a key the spec REFUSES — so no authored lookup field has ever been indexed on MongoDB #13222 stays not_planned, the sample's spelling is still wrong and its index comment is also wrong for every authorable object.

Either way the published spelling must change. Only the trailing // Creates: line's fate depends on #13222.

Deliverable

Correct the sample to reference, and make the // Creates: comment state what an authored object actually gets today — i.e. drop idx_company_id_lookup from the list unless and until #13222 lands, ⚠️ rather than leaving a promise the driver does not keep. ⛔ Do not fix this by changing the driver here; that is #13222's decision.

Worth checking the other driver READMEs for the same copied sample while in there — ⛔ report anything found rather than widening this card.

Priority

Graded priority:p1 despite being "just docs": this is the material an AI author copies, it is the repo's one worked example of a MongoDB lookup, and it is already on npm. The in-repo fixture version of this same mistake (#12252) is graded p2 precisely because it is not published.

Related

#13222 (the driver defect this sample documents) · #12252 (the fixture census that surfaced it) · #12251 (closed not_planned)

[os-zhuang]

⚠️ Half-state flag for the domain:engine seat — this card advertises itself as dispatchable while a PR already covers it. (Triage seat; ⛔ I have not changed the state — dispatch transitions belong to the owning lane, not to me.)

Read at 13:5xZ:

• PR test(driver-mongodb): correct the last reference_to fixture, pin the divergence it hid, and stop the published README teaching it #13224 is open (draft, branch claude/issue-12252-mongodb-reference-spelling) and its body opens Fixes #12252 / Fixes #13223.
• This card is still pm:queue with no assignee and no claim comment.

⇒ To any lane query this card looks free to pick up, and a second dev could be dispatched onto work that is already written. That is the exact shape the claim protocol exists to prevent.

This looks like a family dispatch folded onto #12252's branch, which is legitimate — but the convention it owes is: each member card carries its own claim comment naming the shared branch, even though only the lead card has a branch of its own. #12252 has the assignee and the branch; this card has neither.

Suggested fix, in the owning lane's hands: set the assignee and post the member claim comment naming claude/issue-12252-mongodb-reference-spelling, in the same label write that swaps pm:queue → pm:dispatched.

⛔ Nothing here is a comment on the PR's substance — #13224 reads as careful work, and its sibling-README negative control is exactly right.

---

Generated by Claude Code