fix(scripts): engine-double-contract vetoes a native Mongo Collection fake by its own members - #30499

Requested by Bill · project thread

domain:server#6 · os-bill · session_01Utp6CXCS98uhsFQYk64epE

维护者速读

• 改了什么：引擎替身检查门禁（check:engine-double-contract）新增一条否决：测试里伪造的 MongoDB 原生 Collection（带 insertOne / updateOne 这类只有原生驱动才有的方法）不再被当成 ObjectQL 引擎替身；driver-mongodb 那个为了过门禁被拆成两半的假对象恢复成原本的一个整体。
• 为什么改：这类假对象同时有 find、insertMany、findOne，门禁按方法名把它误判成引擎替身，逼着写测试的人把假对象拆开来绕门禁；它的 findOne(filter, options) 根本不收对象名，不是引擎。
• 风险与回滚：否决只在 findOne 第一个参数不是对象名时生效，真正的引擎替身照样被抓（自检有对照）；全仓前后读数一致（1230 已钉 / 120 欠账 / 3 豁免），否决只移走这一处、0 个已钉。回滚即撤本 PR，只动门禁脚本和一个测试文件。
• 先看：scripts/check-engine-double-contract.mjs 的 NATIVE_COLLECTION_ONLY_MEMBERS 和 isEngineVerbShape 里新增的否决分支；同文件自检里的 NATIVE COLLECTION 一组；packages/drivers/driver-mongodb/src/mongodb-declared-column-null-on-write.test.ts。
• 两分钟验证：node scripts/check-engine-double-contract.mjs --census，预期末尾一行 NATIVE_COLLECTION_ONLY_MEMBERS veto moves 1 construct(s); 0 of them pinned，点名的正是那个 Mongo 测试文件。
• 需要你做的：无，席位落地。

Fixes #29859

Clause-②: no
Metadata-protocol: none
Skills-docs: none — gate script only

What changes

The false red. scripts/check-engine-double-contract.mjs attributed an object literal to the ObjectQL engine contract by its member names. A fake of MongoDB's native Collection declaring insertOne / insertMany / updateOne / findOne / find held two engine siblings (find, insertMany) beside findOne, so it was discovered as a findOne engine double. isEngineVerbShape then admitted it on either arity path: a two-parameter findOne(filter, options) has a second parameter that is neither an id nor a string, and a short-arity findOne(filter) reads insertMany as ENGINE_ONLY_MEMBERS evidence.

Which evidence was wrong. Measured, not assumed: insertMany is a real member of the engine class (ObjectQL.insertMany(object, rows, options), packages/objectql/src/engine.ts), so removing it from ENGINE_ONLY_MEMBERS would weaken the engine-side evidence, and it would not have fixed the two-parameter case anyway. What was missing is positive evidence of the OTHER shape. So this adds a fourth arm to the existing evidence architecture:

• NATIVE_COLLECTION_ONLY_MEMBERS = insertOne, updateOne, deleteOne, replaceOne, bulkWrite, countDocuments, estimatedDocumentCount, findOneAndUpdate, findOneAndDelete, findOneAndReplace. Verified name by name: none is declared in packages/objectql/src/engine.ts, nor on IDataEngine, IDataDriver or IScopedObjectRepository (packages/spec/src/contracts/); the same grep's control leg hits insertMany in engine.ts and findOne in the contracts. updateMany / deleteMany are left out because DRIVER_ONLY_MEMBERS already vetoes them; distinct / createIndex / watch are left out as too generic to mean "Mongo".
• The veto in isEngineVerbShape runs right after the scoped-repository veto and under the same object-name guard (takesObjectNameFirst): the member is the evidence, and a verb that takes the object name first keeps the literal in scope however many Mongo-named helpers hang off it. So a real engine double cannot leave scan scope by declaring insertOne.
• Decided by signature evidence, not by a file name: no path is exempted and no ledger row is added (the baseline is untouched).
• --census now ablates this veto on its own, beside the repository veto, so its reach is re-derivable: on this tree it moves exactly 1 construct, 0 of them pinned.

The bent test, restored. packages/drivers/driver-mongodb/src/mongodb-declared-column-null-on-write.test.ts had been split into singleRowDb() / batchDb() only so the gate would not see insertMany + find beside findOne. It is one fakeDb() again, the natural shape the driver sees ((driver as any).db = { collection: () => collection }); the three tests are unchanged.

Changeset: none, skip-changeset: the diff publishes nothing. scripts/** is repo-root tooling, and the driver-mongodb file is a test (files: ["dist", "README.md", "CHANGELOG.md"], tsup entry src/index.ts).

Tests

• Red first, on main's gate (f273c9f) with the restored test: node scripts/check-engine-double-contract.mjs exit 1, x PINNED [findOne]: packages/drivers/driver-mongodb/src/mongodb-declared-column-null-on-write.test.ts declares 1 engine double(s) whose findOne() does not route through assertEngineFindOnePredicate (line 65).
• Green: the same run on HEAD exit 0, OK — 1230 pinned, 120 in the DEBT ledger, 3 exempt.
• New self-test battery The NATIVE COLLECTION, the fourth shape (#29859). (7 cases, floor pinned at 7, roster floor 34 → 35), as A/B pairs: the five-member native fake is out of scope for the findOne slice and the same literal without insertOne/updateOne is discovered; the same pair at one-parameter findOne(filter); the control the card names, an engine double holding find/insertMany plus engine members, is still an unpinned findOne double; an engine double that also declares insertOne stays in scope; a mixed fixture reports exactly the engine double.

Acceptance notes

• insertMany stays in both ENGINE_SIBLINGS and ENGINE_ONLY_MEMBERS, deliberately (engine member, measured above).
• A native fake that declares none of the ten names (for example only insertMany + find + findOne) is still discovered. That is the A/B control, and the restored test needs insertOne/updateOne anyway; widening further is a --census measurement, not part of this card.

Verification

All readings on head f443d8b1 (branch merged with origin/main at f506b79, a merge with no overlap with this diff) unless noted.

Generated by Claude Code