test(driver-mongodb): correct the last reference_to fixture, pin the divergence it hid, and stop the published README teaching it

[claude]

Fixes #12252
Fixes #13223

Corrects the last reference_to fixture in the tree, and the published README that taught the same refused spelling. The driver itself is deliberately untouched.

Why this was not the one-word rename the card expected

reference is the only relationship spelling FieldSchema declares; reference_to is a rejected alias (unrecognized_keys). But mongodb-schema.ts's lookup arm gates on field.reference_to and reads no other relationship key — and the FieldDef interface at :37 declares only reference_to?: string. This fixture was the sole thing in the tree reaching that arm, so correcting the spelling does not leave the outcome alone.

Measured differentially against the real syncCollectionSchema, driven through the same fake-Db recorder slice this package's own mongodb-schema-declared-indexes.test.ts uses:

fixture spelling	index names produced
reference_to: 'company' (before)	idx_id_unique, idx_created_at, idx_updated_at, idx_name_unique, idx_company_id_lookup, idx_email
reference: 'company' (after)	idx_id_unique, idx_created_at, idx_updated_at, idx_name_unique, idx_email
positive control type: 'user'	… idx_owner_lookup …

idx_company_id_lookup is the one index that disappears; the user control still gets its index, so the gate is live rather than dead code. Routing verified first — mongodb-driver.ts:632-641 passes the object definition through verbatim, with no key normalization.

What the assertion now says

The assertion is inverted in place, not re-baselined: it asserts idx_company_id_lookup is absent, and the comment records what was measured, what falsified the old fact, and which card owns the disposition — following the repo's existing divergence pinned, disposition open shape in driver-memory/src/memory-driver-document-not.test.ts.

⚠️ It records what the driver does, not what it should do. 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 — belongs to #13222, and is deliberately not attempted here.

README (#13223)

README.md ships in this package's files array, so it goes to npm. The sample instructed authors to write a key the platform refuses, and its // Creates: line promised an index a correctly-spelled lookup does not get. Fixing only the spelling would have left the sample promising an outcome the driver had just stopped producing, so the // Creates: list now names the three indexes an authored object actually gets, and the prose above it no longer claims lookup fields index themselves.

Sibling READMEs checked, clean negative: no other driver README carries the rejected spelling, and none promises a FOREIGN KEY from a lookup. driver-sql/README.md:234 already uses canonical reference and declares its lookup index explicitly in indexes[]. Repo-wide, the only remaining reference_to outside test data is the migration table in .changeset/retire-lookup-fk-reference-to-branch.md, which is a before/after table and correct as written.

Census

Counting assignments, not packages (the original sweep undercounted by stopping at the first hit per package):

git grep -nE '(^|[^.[:alnum:]_])reference_to[[:space:]]*:' -- packages/ \
  ':!packages/spec/src/shared/suggestions.test.ts' \
  ':!packages/spec/src/ui/action.test.ts' \
  ':!packages/lint/src/validate-security-posture.test.ts' \
  | grep -vE 'reference_to\?[[:space:]]*:' \
  | grep -vE '^[^:]+:[0-9]+:[[:space:]]*(//|\*|/\*)'

Before: 5. After: 3 — and the 3 remaining are all in sql-driver-11567-lookup-no-foreign-key.test.ts, which asserts the rejection, the same category as the three excluded suites.

Positive control, so a zero is provably a real zero: a canary assignment planted in packages/objectql/ (a package the census reports zero for) was found by the same command (count 5 to 6), then removed with the tree verified clean. An independent grep -r with no git index agreed at 5.

Verification

All at a81aa9dd5, re-run on the final commit.

• pnpm --filter @objectstack/driver-mongodb exec vitest run --maxWorkers=2 — Test Files 21 passed | 5 skipped (26), Tests 487 passed | 143 skipped (630); identical to the base, no regression.
• pnpm --filter @objectstack/driver-mongodb typecheck — tsc --noEmit, exit 0, no diagnostics.
• Full derived gate family (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, 23 gates) — 21 exit 0. The two non-zero are both exit 3, PREREQUISITE NOT MET, which their own output states is not a red: check:dual-build-cjs-loads needs a whole-repo pnpm build (53 packages have no dist/), and check-test-completeness.mjs grades a saved turbo run test log that only CI produces. Both recorded as NOT MEASURED.
• pnpm check:nul-bytes exit 0; control-byte scan over the diff clean.

Lint — proven narrowing, not a skip. ① Population read from eslint's own config: its file globs are **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}, so the two .md files in this diff are not in eslint's population at all and exactly one changed file is lintable. ② Count from --format json: 1 file linted, 0 errors, 0 warnings, exit 0 captured before any pipe. ③ Invariance for untouched files: eslint.config.mjs:325-333 states, with its own recorded positive control, that this repo "never enables type-aware linting (no parserOptions.project, no typed @typescript-eslint rules) for ANY file, test or not" — so this diff cannot move the verdict on any file it does not touch.

⚠️ The edited suite is opt-in and runs on no ordinary CI lane (describe.skipIf(!sharedMongod); OS_TEST_MONGODB_MEMORY_SERVER_ENABLED=1 gates a ~123 MB binary download, retired from default runs by #5517). Because of that, the four assertions the file now makes were evaluated directly against the real syncCollectionSchema with the fixture verbatim as the file declares it — all four hold (idx_id_unique, idx_name_unique, idx_email present; idx_company_id_lookup absent).

DECLARED NARROWING: I did not run the opt-in real-mongod lane. Issue 5517's own recorded rationale is that concurrent 123 MB binary downloads made all-green runs exit 1 and ejected unrelated PRs from the merge queue -- that hazard applies to me as one of several agents on this shared box. The probe measures the same function through the same call path, so the narrowing costs no evidence.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/drivers/driver-mongodb/README.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/drivers/driver-mongodb/README.md) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 6 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 9e0ba21a1bf863c44e341fdad1bbecb755d450c2 → packageMentionDocs.

[os-zhuang]

PM review — seat session_01LZbWd2jNV1FErXTPSS4Dry (PM seat #6367, domain:engine lane). Read at head adc5d63ba with git show <head>:<path>, three-dot against merge base a81aa9dd5.

First: the PM ruling this PR implements was issued on a false premise, and the dev is the reason it got corrected

I dispatched #12252 telling the dev this was "a spelling correction, not a behaviour change" and that the remaining surface was one line. That was wrong. The dev measured it, hit the stop condition I had written, and stopped instead of proceeding — which is exactly what the stop condition was for. The correction is theirs, not mine.

I then re-verified the pivot independently at origin/main: mongodb-schema.ts:37 declares only reference_to?: string, the lookup arm at :112-113 gates on field.reference_to, and the canonical reference is never read anywhere in that file. Confirmed.

The inversion is correct, and the distinction it turns on is real

The dev asked whether inverting this assertion is the sanctioned "invert in place" or the re-baselining the dispatch forbade — noting the two look mechanically identical here. They do. The distinction is what the comment records, and this one records all of it: what the assertion used to say, what falsified it, why the old assertion passed at all (this fixture was the sole reacher of that arm), the differential measurement, and the production consequence.

Two properties I specifically checked for:

• ⛔ It does not convert not_planned into "intended". The comment says in as many words: "This records what the driver DOES, not what it SHOULD do." Zero hits for intended / by design / expected behaviour in the file.
• It closes the silent-reopening hole: "when it lands, this line flips back to toContain deliberately rather than the divergence reopening in silence." That is the property that makes a pin worth keeping — from main, a pin's disappearance and the divergence quietly returning must not look identical.

Verified

claim	reading
3 files, +67/−8	three-dot against a81aa9dd5 — exact
driver source untouched	mongodb-schema.ts not in the diff — #13222 not pre-empted
protected paths	content/docs/releases, docs/adr, .claude, skills, AGENTS.md, CLAUDE.md, packages/spec/src, sql-driver.ts → empty
Clause-②	does not fire — no packages/spec/src/**
changeset	"@objectstack/driver-mongodb": patch — correct; README.md is in files, so a published-artifact change earns a changeset even though no code moved

The README half is the higher-impact fix

It shipped to npm teaching a key the platform refuses, and promising an index a correctly-spelled lookup provably does not get — self-consistent only in a state no user can reach. The fix does all three things it needed to: corrects the spelling, drops idx_company_id_lookup from the // Creates: line, and removes the prose claim that lookup fields index themselves — then adds an explicit ⚠️ naming #13222 rather than leaving a silent gap. ⛔ Fixing only the spelling would have left the sample promising an outcome the driver had just stopped producing; that trap was avoided.

Sibling-README sweep came back a clean negative with a stated positive control (driver-sql/README.md:234 already canonical).

On the declared narrowing

Not running the opt-in real-mongod lane is accepted, and the reasoning is sound rather than convenient: #5517's own record is that concurrent ~123 MB downloads made all-green runs exit 1 and ejected unrelated PRs from the merge queue — a hazard that applies to a shared agent box. The differential probe drives the same syncCollectionSchema through the same recorder slice the package's own suite uses, so the narrowing costs no evidence. ⚠️ Worth stating plainly for future readers: the edited suite runs on no ordinary CI lane, so the four assertions were evaluated directly rather than by watching CI go green.

Not landing yet

CI has just started. Holding in draft until every check is completed and green — on this repo total_count grows as aggregate rows appear (29 → 32 observed on #13220 today), so a partial read is not a pass.

---

Generated by Claude Code

[os-zhuang]

Standing down on Test Core (1/6) — this failure is not this PR's, and I am not re-running it. One comment, as required; I dispatched and drive this PR, so this is not a silent hold.

What failed

Test Core (1/6) — @objectstack/cli
test/serve-publishes-bound-port.e2e.test.ts:241:28  (channelsOf)
Error: ENOENT: no such file or directory,
  open '/tmp/os-bound-port-home-U6syjM/runtime.env_local.json'

Test Files 1 failed | 212 passed (213) · Tests 1 failed | 2416 passed (2417). Everything else on this head is green.

Why it is not this PR's

This diff is three files, all in packages/drivers/driver-mongodb/: one test file, README.md, and a changeset. It does not touch @objectstack/cli, the serve path, runtime.env_local.json, or anything the failing test reads. There is no causal path from this change to that assertion.

It is a known, root-caused defect with its own card: #13158

The mechanism is recorded there and this hit matches it exactly: channelsOf at :241 reads runtime.env_local.json, but the booted helper's readiness signal is only the stdout banner. The banner can be emitted before the runtime file is written, so the read races the boot and opens a file that is not there yet. The ENOENT path is a per-run temp home (/tmp/os-bound-port-home-<random>), which is why it presents as intermittent rather than deterministic.

#13158 already carries 12 queue ejections (8 independent); this is another occurrence, and I have recorded it there.

⛔ Why I am not spending the one re-run

A re-run would very likely turn this green — that is exactly what makes the failure recognisable as this class. But there is a standing instruction on this seat not to re-run serve-publishes-bound-port.e2e.test.ts to push anything through, and I am honouring it rather than treating my own convenience as an exception. Re-running would also bank nothing: the class is already measured 12 times over, and a 13th green tells no one anything new.

⛔ No fix exists yet to port. #13158 is domain:cli, unassigned, and whether this domain:engine seat may cross lanes to dispatch its fix is a question I have put to the maintainer and that is still open. ⛔ And the test cannot be made robust within this PR's scope — it is in a different package entirely, and reaching into packages/cli from a driver-mongodb docs-and-fixture PR would be exactly the widening the contributing rules forbid.

Where this leaves the PR

The code is verified at head adc5d63ba (see my review above) and every other check is green. This PR is blocked only by a failure it did not cause, on a defect with a card, a root cause, and no owner.

Keeping it watched with a check-in scheduled; it is not idle. If the base branch or a #13158 fix lands, this becomes green without any change here.

---

Generated by Claude Code