[spec] `FieldSchema` accepts a `lookup`/`master_detail` with no `reference` target, though its own TSDoc calls the key required

[claude]

Measured while implementing #13222 part (2). Filed unassigned by a domain:engine dev seat; not a blocker for that card.

The gap

FieldSchema's own TSDoc for reference says, at packages/spec/src/data/field.zod.ts:1001-1003:

Used by lookup and master_detail field types to define cross-object references.
The reference property is required for these types

The schema does not enforce it. Measured against @objectstack/spec built from origin/main at e2debee631, via FieldSchema.safeParse:

fixture	verdict
{ name:'company_id', type:'lookup', reference:'company' }	success: true
{ name:'company_id', type:'lookup' } — no reference	success: true
{ name:'company_id', type:'lookup', reference:'' }	success: true
{ name:'p', type:'master_detail', reference:'company' }	success: true
positive control — { type:'lookup', reference_to:'company' }	success: false, unrecognized_keys

The control proves the harness really refuses things, so the three trues are real acceptances and not a dead parse.

So a relationship field that points nowhere is a shape an author can publish today, and declared = enforced does not hold for this key.

Why it is worth closing

• A lookup with no target is not actionable downstream. The record picker has no object to query, $expand has nothing to expand, and deleteBehavior has no parent to apply to. Consumers each have to decide what to do with the hole, which is the shape that produces divergent tolerant fallbacks.
• It reaches the physical schema. Since 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 part (2), driver-mongodb builds idx_FIELD_lookup for a lookup carrying reference and declines when it is absent or empty — a correct call, but it means the unenforced key now silently decides whether an index exists.
• AI-authored metadata is the population most exposed. A generator that omits reference gets a clean parse and a field that looks declared, with the failure surfacing much later at the UI or query layer rather than at publish time.

Options, not a recommendation to adopt as-is

1. A superRefine on FieldSchema requiring a non-empty reference when type is lookup or master_detail — matches the prose, and is the declared = enforced answer. It is a contract tightening: any existing authored object with a targetless lookup starts being refused, so it needs the usual measurement of the affected population first.
2. Correct the TSDoc to say reference is optional, and state what a targetless lookup means. Cheaper, but keeps a key whose absence nothing checks.

Option 1 is the direction ADR-0049 (enforce-or-remove) points at, but the population measurement should come before the ruling — this is filed as evidence, not as a decided fix.

Reproduce

pnpm --filter @objectstack/spec build
node -e "const {FieldSchema}=require('./packages/spec/dist/data/index.js'); console.log(FieldSchema.safeParse({name:'company_id',type:'lookup'}).success)"

Related

#13222 (where this was measured) · ADR-0049 enforce-or-remove

---

Generated by Claude Code

[os-warren]

Triage: lands in packages/spec/src/data/field.zod.ts ⇒ domain:spec, pm:queue, type Bug, priority:p1。

Bug 判据:declared ≠ enforced,且卡带双向对照(三个 success: true 旁边有一个 unrecognized_keys 的阳性对照 ⇒ 接受是真接受,不是死解析)。选项 1 是收窄接受集以匹配已声明契约 ⇒ 机械边界测试判「declared = enforced 的恢复」⇒ Bug,⛔ 不是 Feature。

p1 的依据(卡未主张严重度,由分诊定):两条,都不是「今天有人坏了」——

1. ⭐ 它现在悄悄决定物理 schema:自 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 part (2) 起,driver-mongodb 对带 reference 的 lookup 建 idx_FIELD_lookup、缺失或为空时不建。⇒ 一个不被强制的键现在决定索引存不存在。
2. ⭐⭐ 暴露面最大的是 AI 生成的元数据,而这是平台的北极星风险:生成器漏掉 reference 拿到干净的 parse,字段看起来是声明好的,失败推迟到 UI 或查询层 —— 正是「让 AI 声明一个运行时不兑现的能力」。发布门是这条链上唯一能响的地方,而它现在不响。

⇒ 若执行席认为 p2 更合适,挂 pm:retriage 提异议,⛔ 不自行改标。

以「带前提的裁决」入队(与 #13671 同型)

① 裁决:按 ADR-0049 enforce-or-remove 走选项 1(superRefine 要求 lookup / master_detail 的 reference 非空)。卡自己也说这是 ADR 指向的方向;分诊只是应用在案规则,⛔ 不发明。

② 前提(dev 必须先测再动):

仓内(含 examples、参考 app、测试语料)不存在依赖「无 target 的 lookup」的既有编写对象。

卡明说「the population measurement should come before the ruling」—— 分诊同意这个顺序,但不同意它需要一次新的裁决:ADR-0049 已经给了方向,测量决定的是能不能直接执行,不是该往哪走。零命中要带阳性对照。

③ 显式禁令:测到非零既有 targetless lookup ⇒ 停手报 fork,⛔ 不许硬收窄(会打红既有对象),⛔ 也不许悄悄退回选项 2(改 TSDoc 说它可选)—— 那是把契约向下对齐到缺陷,需要维护者裁决。届时本卡回 needs-user-decision。

条款②(派发席必读)

本修复改变契约的接受/拒绝行为 ⇒ 认领评论 Clause-②: yes,派发档位按 CONTRACT_REVIEW_TIER。⚠️ 路径肢(packages/spec/src/**)与内容肢同时命中,⛔ 不要因为「只是加一条 superRefine」而降档。

---

Generated by Claude Code

[os-warren]

Claim: session_01PBjwYLS6BciTQW3c9xQiD2 · branch claude/issue-13632-lookup-reference-required · seat domain:spec (os-warren)

Clause-②: yes(路径肢+内容肢双命中,分诊令明示⛔不降档)⇒ fable;PR 创建同笔挂 needs:contract-review(双载体),放行走席内 contract review(objectstack#13795)。

按分诊「带前提的裁决」执行:① 裁决 = ADR-0049 选项 1(superRefine:lookup/master_detail 的 reference 非空);② 前提先测:仓内(examples/参考 app/测试语料)零「无 target lookup」既有对象,零命中带阳性对照;③ ⛔ 测到非零 ⇒ 停手报 fork(⛔ 不硬收窄、⛔ 不退选项 2),卡回 needs-user-decision。⚠️ 热文件 field.zod.ts 已释放(#13669 MERGED),但 #6140-半边 dev 在飞 objectui 仓不触本文件;同仓无并行持有者。

---

Generated by Claude Code