test(driver-mongodb): correct the last reference_to fixture and pin the divergence it was hiding (#13224)

`mongodb-driver.test.ts` declared its lookup as `reference_to: 'company'`, a key
`FieldSchema` refuses (`unrecognized_keys`), so it described an object no author
could publish. It was also the only thing in the tree reaching
`mongodb-schema.ts`'s lookup arm, which gates on `field.reference_to` and reads
no other relationship key.

Correcting the spelling therefore does not leave the outcome alone: measured
differentially against the real `syncCollectionSchema`, `idx_company_id_lookup`
is the one index that disappears, while a `type: 'user'` field still gets its
own — so the gate is live, not dead code. The assertion is inverted in place
with a comment recording what was measured, what falsified the old fact, and
that #13222 owns the disposition. It records what the driver DOES, not what it
should do.

The published README taught the same refused spelling and promised the same
index; it now shows `reference`, lists only the indexes an authored object
actually gets, and names #13222.

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: os-zhuang <jack@objectstack.ai>

Author: 3 people

.changeset/mongodb-readme-lookup-index-honest.md

@@ -0,0 +1,30 @@
+---
+"@objectstack/driver-mongodb": patch
+---
+
+docs(driver-mongodb): stop teaching the spec-refused `reference_to` in the published README, and stop promising a lookup index the driver does not build (#12252 / #13223)
+
+The schema-sync example in this package's README — which ships to npm — declared
+its lookup as `company_id: { type: 'lookup', reference_to: 'company' }` and
+closed with `// Creates: … idx_company_id_lookup`. Both halves were wrong, in
+opposite directions:
+
+- `reference` is the only relationship spelling `@objectstack/spec` declares.
+  `reference_to` is a **rejected alias**, answered by `FieldSchema` with
+  `unrecognized_keys` and *"Did you mean `reference_to` → `reference`?"* — so
+  the sample instructed authors to write a key the platform refuses, in the one
+  place a reader is most likely to copy verbatim.
+- The `// Creates:` line promised an index that a *correctly* spelled lookup
+  does not get. `syncCollectionSchema`'s lookup arm gates on
+  `field.reference_to`, so it cannot fire for a spec-conformant lookup. Fixing
+  only the spelling would have left the sample promising an outcome the driver
+  had just stopped producing.
+
+The sample now uses `reference`, lists only the three indexes an authored object
+actually gets, and the surrounding prose no longer claims lookup fields index
+themselves — it names the defect and points at #13222, which owns the fix.
+
+**No runtime behaviour changes here.** Whether the lookup arm learns to read
+`reference` — which would index 57 relationship fields across the 44 exported
+platform objects that get no join index today — is #13222's decision, not this
+change's.

packages/drivers/driver-mongodb/README.md

@@ -158,22 +158,26 @@ try {
 
 Schema sync creates collections and indexes:
 
-Field-level `unique` and lookup fields index themselves; everything else is
-declared in the object's `indexes[]` — the one surface an index is declared on
-(a field-level `indexed` flag is not a `FieldSchema` key and never built an
-index, #2377 / #6810).
+Field-level `unique` fields index themselves; everything else is declared in the
+object's `indexes[]` — the one surface an index is declared on (a field-level
+`indexed` flag is not a `FieldSchema` key and never built an index,
+#2377 / #6810).
+
+⚠️ Lookup fields are **not** indexed today. The lookup arm gates on
+`reference_to`, a spelling `FieldSchema` refuses, so a canonically-spelled
+`reference` lookup gets no join index — see #13222, which owns that fix.
 
 ```typescript
 await driver.syncSchema('account', {
   name: 'account',
   fields: {
     name: { type: 'string', unique: true },
     email: { type: 'email' },
-    company_id: { type: 'lookup', reference_to: 'company' },
+    company_id: { type: 'lookup', reference: 'company' },
   },
   indexes: [{ fields: ['email'] }],
 });
-// Creates: idx_id_unique, idx_name_unique, idx_email, idx_company_id_lookup
+// Creates: idx_id_unique, idx_name_unique, idx_email
 ```
 
 ### Aggregation

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

@@ -344,7 +344,7 @@ describe.skipIf(!sharedMongod)('MongoDBDriver', () => {
         fields: {
           name: { type: 'string', unique: true },
           email: { type: 'email' },
-          company_id: { type: 'lookup', reference_to: 'company' },
+          company_id: { type: 'lookup', reference: 'company' },
         },
         // [#6810] `email` used to carry a field-level `indexed: true` here. That
         // was never a `FieldSchema` key (#2377 / ADR-0049); the index is
@@ -361,7 +361,32 @@ describe.skipIf(!sharedMongod)('MongoDBDriver', () => {
       expect(indexNames).toContain('idx_id_unique');
       expect(indexNames).toContain('idx_name_unique');
       expect(indexNames).toContain('idx_email');
-      expect(indexNames).toContain('idx_company_id_lookup');
+      /**
+       * ⚠️ [#12252] DIVERGENCE PINNED, DISPOSITION OPEN (#13222) — a
+       * canonically-spelled lookup gets NO join index here.
+       *
+       * This fixture used to spell the field `reference_to: 'company'` and
+       * assert `idx_company_id_lookup` was CREATED. `reference_to` is a key
+       * `FieldSchema` REFUSES (`unrecognized_keys`), so the object it described
+       * was one no author could publish — and the assertion passed only because
+       * this fixture was the sole thing in the tree reaching the lookup arm of
+       * `mongodb-schema.ts`, which gates on `field.reference_to` and reads no
+       * other relationship key.
+       *
+       * So correcting the spelling does not leave the outcome alone. Measured
+       * differentially against the real `syncCollectionSchema`,
+       * `idx_company_id_lookup` is the ONE index that disappears; a
+       * `type: 'user'` field still gets its index, so the gate is live rather
+       * than dead code. The consequence in production is that EVERY authored
+       * lookup on MongoDB is unindexed — 57/57 relationship fields across the
+       * 44 exported platform objects (#13222).
+       *
+       * ⛔ This records what the driver DOES, not what it SHOULD do. Whether
+       * the lookup arm learns to read `reference` is #13222's to settle, ⛔ not
+       * this pin's — when it lands, this line flips back to `toContain`
+       * deliberately rather than the divergence reopening in silence.
+       */
+      expect(indexNames).not.toContain('idx_company_id_lookup');
     });
 
     it('should be idempotent (safe to call multiple times)', async () => {