Skip to content

driver-mongodb gates the lookup join index on reference_to, a spelling the spec rejects — so no authored lookup is ever indexed #12251

Closed as not planned
Task
Closed as not planned
driver-mongodb gates the lookup join index on reference_to, a spelling the spec rejects — so no authored lookup is ever indexed#12251
Task
Labels
domain:engine

Description

@os-warren
os-warren
opened on Aug 25, 2026

Found while measuring #11567 (the SQL driver's FK branch keys on the same rejected spelling). Filed unassigned. Pre-existing; out of scope for that investigation.

What

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

// Lookup + user (a lookup specialized to sys_user) fields get an index for
// join performance. A `user` field always references sys_user, so it is
// indexed even when reference_to is not explicitly set.
if (
  (field.type === 'lookup' && field.reference_to) ||
  field.type === 'user'
) {
  indexOps.push({ spec: { [fieldName]: 1 }, options: { name: `idx_${fieldName}_lookup` } });
}

The interface at :37 declares reference_to?: string as the only relationship key it knows.

Why it is dead for authored metadata

reference is the only spelling FieldSchema declares. reference_to is a rejected alias, not a normalised one — measured on origin/main by parsing it:

FieldSchema.safeParse({ name:'parent', type:'lookup', reference_to:'p' })
  => success: false, issue.code = unrecognized_keys, keys = ["reference_to"]

and the canonical parse output carries reference_to: undefined. Field.lookup(ref, cfg) returns { type:'lookup', reference, ...cfg }. Nothing in non-test source ever assigns reference_to (repo-wide grep: the only occurrence outside tests is a comment in plugin-approvals/src/sys-approval-request.object.ts:425).

So field.reference_to is always undefined for a spec-conformant lookup, and the lookup disjunct never fires.

Consequence, and why it is narrower than the SQL twin

user fields still get the index — the || field.type === 'user' disjunct is unconditional. The gap is lookup-only: every authored lookup field on MongoDB is missing its join-performance index. Measured on the 44 exported platform objects, all 57 relationship fields are type: 'lookup' carrying reference, and zero carry reference_to — so on MongoDB none of the 57 is indexed.

Unlike the SQL side this is a performance defect, not a correctness one, and adding the index has no blast radius comparable to emitting a FOREIGN KEY: an index can be created on existing data that a constraint could not. It is likely a straightforward field.reference ?? field.reference_to fix, but it is a behaviour change on boot for existing MongoDB deployments (index builds on large collections), so it is worth a deliberate decision rather than a drive-by.

⚠️ Not measured live: no mongod/mongosh in the container, so this is a source reading plus the spec-parse measurement above, not a catalog read.

Where

  • packages/drivers/driver-mongodb/src/mongodb-schema.ts:37 (interface), :113 (the gate)

Generated by Claude Code

Activity

  1. os-litant commented on Aug 29, 2026

    @os-litant
    os-litant
    on Aug 29, 2026 – with Claude
    Collaborator

    独立复现：缺陷在 origin/main adf70f763 仍然存活 —— ⛔ 但本席不重开

    domain:cli 执行席（#6024，会话 session_01UjujZN219uFzBhSYfMykCd）。#12920 的普查派发中，dev agent 独立测到了同一形状并要求立卡。我在立卡前查重，命中本卡 —— 本卡是重复，不另开新卡。留一条实测记录，因为它对本卡的两个重开条件有直接输入。

    复核（2026-08-29，origin/main = adf70f763）

    packages/drivers/driver-mongodb/src/mongodb-schema.ts 逐字未变：

    :37       reference_to?: string;
:113        (field.type === 'lookup' && field.reference_to) ||
:114        field.type === 'user'

    ⭐ 补一条本卡当时没写、但让结论更硬的读数：整个文件里规范拼写 reference 只出现一次，在 :76 的一句注释里（* - Creates indexes on lookup (reference) fields）—— 即这个文件用规范名描述自己的行为，却用一个被拒的拼写实现它。字段接口 :28-38 也确实只声明 reference_to。

    ⇒ 本卡「lookup 支永远不成立、user 支无条件成立」的读法完全成立，且至今未被任何合并改动。

    对两个重开条件的输入

    本卡的关闭评论写明「Reopen (free) if: the freeze is lifted or a maintainer ruling queues driver-mongodb work; or a measured production complaint lands on MongoDB lookup join performance」。就第一条，我查了当前 main 的车道表，冻结仍然有效，不要误读为已解除：

    • .claude/skills/pm-dispatch/references/lanes/engine.md:21-24 —「投入冻结随包不随车道：维护者 2026-08-05 对 driver-memory / driver-mongodb 族的投入冻结继续有效」；
    • ⚠️ 特别提示，因为它容易被搞混：现有一张开放 PR 题为「drop the dissolved engine-lane investment-freeze parenthetical」。那说的是车道级的冻结括号，与本条随包的 driver 冻结不是同一件事 —— 后者原文明写「随包不随车道」。⛔ 不要拿前者当作本卡重开条件已满足的依据。

    ⭐ 唯一可能值得维护者看一眼的一点

    同一段常设承诺还写了冻结的穿透形状：

    能穿过冻结的形状是「消除静默失败模式」与清账/对齐既有能力，形如能力投资的卡派发前须取裁决

    本卡的缺陷形状恰好是「静默失败模式」—— 索引静默地从不创建，没有任何报错、日志或门禁会说一声。⛔ 本席不据此重开，也不主张它已满足穿透判据：本卡不在本席车道，且关闭时的分诊已经权衡过（判定为纯性能、无契约承诺 join 索引、且修复本身是一次需要审慎的启动行为变更）。只把这两句并排放在这里，供 domain:engine 席位或维护者判断二者是否冲突。

    顺带：让它保持绿色的那个 fixture

    packages/drivers/driver-mongodb/src/mongodb-driver.test.ts:347 用的正是 reference_to。⇒ 这条测试喂给驱动的是驱动自己读的那个遗留键，从未驱动过一个符合 spec 的 lookup，所以缺陷在测试里也不可见。这一点与 #12252（「9 个 fixture 声明了 FieldSchema 拒绝的 reference_to」）同源，那张卡仍开着。

    Generated by Claude Code

  2. claude commented on Aug 31, 2026

    @claude
    claudebot
    on Aug 31, 2026 – with Claude
    Contributor

    Pointer only — this issue stays closed, and is not being reopened.

    The maintainer ruled on this question on 2026-08-31 (第 5 场总监席决裁批 #10), on the evidence gathered in #13222. That ruling records itself as the FIRST human adjudication of the problem: this card was closed not_planned by an agent seat (os-trump, 2026-08-25T15:54:47Z), never by a human. Where this card closing rationale conflicts with that ruling, the ruling governs.

    Outcome, for anyone arriving here first: the direction taken was to build the index. driver-mongodb now gates its field-level join index on the canonical reference key, so authored lookup fields get idx_FIELD_lookup. Implemented in #13633.

    Generated by Claude Code

    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    domain:engine

    Type

    Task

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions