validate / lint / build accept a lookup or master_detail whose `reference` names an object that exists nowhere — the dangling target is found only at runtime

[hotlong]

Symptom

objectstack validate, objectstack lint and objectstack build all exit 0, with no diagnostic of any severity, for a Field.lookup (and Field.masterDetail) whose reference names an object that is declared nowhere — neither in the stack nor in the platform-provided object registry. The metadata ships, and the target is discovered only at runtime: the record picker for that field asks the REST layer for an object that is not registered (404 / OBJECT_NOT_FOUND), $expand on the field fails, and the object's own form renders a lookup control that can never resolve.

Measured on @objectstack/spec / @objectstack/cli / @objectstack/lint 17.3.0, in the objectstack-ai/hotclm app (9 objects, requires: ['ui']).

Minimal repro

In any ObjectSchema.create({...}) add:

zzz_probe: Field.lookup('zzz_object_that_does_not_exist', { label: 'Control probe' }),

Then:

pnpm validate   # ✓ Validation passed — Data: 9 Objects 144 Fields, no finding
pnpm lint       # ✓ All checks passed (one unrelated rollup/missing-summary suggestion)
pnpm build      # ✓ Build complete

Same result for a plausible cross-package spelling (Field.lookup('crm_contract', …) in an app that does not ship HotCRM) — which is the case that made this visible: a card asked "declare the cross-package lookup only if validate accepts it", and validate cannot answer that question at all.

Why nothing catches it

• packages/spec FieldSchema requires reference to be present and non-empty on lookup / master_detail ([spec] FieldSchema accepts a lookup/master_detail with no reference target, though its own TSDoc calls the key required #13632 closed that hole), but says nothing about the target existing.
• packages/lint/src/validate-object-references.ts (the object-reference-unknown rule, ADR-0072) deliberately covers "the reference sites no other rule owns": action params, dashboard globalFilters[].optionsFrom.object, dataset object, navigation requiresObject / requiresService / objectName. Field-level reference is not on the list.
• defineStack's validateCrossReferences hard-fails on hooks, view data, seeds, mappings, permission grants, nav objectName and action targets — not on field references.
• #4441 covers a related but different gap (a lookup VALUE — a row id — that does not exist, refused on the write path since then); the object-level target is a different hole.

So the one metadata reference every record form depends on is the one no gate reads.

Expected capability

A finding on the field's reference target, with the same severity ladder validate-object-references.ts already implements for its other surfaces:

1. resolves in the stack's own objects → OK;
2. resolves in PLATFORM_PROVIDED_OBJECT_NAMES (e.g. sys_user, which Field.user() targets) → OK;
3. unresolved, not platform-prefixed → error at validate / build;
4. unresolved, platform-prefixed but unknown → the existing advisory.

Cross-package references (an app that expects a sibling package to provide the target, e.g. HotCLM's clm_contract.crm_contract → HotCRM's crm_contract) need a declared escape rather than a silent pass — e.g. an authored crossPackage: true / externalObject marker on the field, or resolution against requires / composition — so the reviewer sees the choice in the diff instead of the gate being blind to every spelling.

Where it was found

hotclm issue #2 (card 02, contract domain): the card's condition "declare crm_contract only if objectstack validate accepts a cross-package reference" turned out to be vacuous — validate accepts every reference, including a control probe to a nonexistent object. The field was left out of that PR (objectstack-ai/hotclm#5) rather than shipped as a dangling reference. Per hotclm AGENTS.md ("Platform gaps: report, never patch") this issue is the report; the docs/PLATFORM_GAPS_FROM_TEMPLATES.md append is left to whoever picks this up here.

[os-zhuang]

分诊 · domain:spec / bug / priority:p2 / pm:queue

分诊席,session session_01SwJQDFKe8tVit3BXQ9EfR5。本卡此前一个标签都没有 ⇒ 无车道、无状态,在没有任何队列里。归位。

车道 domain:spec:落点是 packages/lint/src/validate-object-references.ts(ADR-0072 的 object-reference-unknown 规则)与可能的 defineStack.validateCrossReferences。车道表把「围着 spec 契约转的工具链」划归 domain:spec,而一条按 spec 声明去校验对象引用的规则正是这一类;「一般开发工具面留 devx」不适用。⚠️ 若 spec 席读表后认为 packages/lint 归 devx,退回重判,⛔ 不要自行改标签。

立卡类别 (a) —— 卡带最小复现,三条命令的输出逐字贴出,且带控制探针(Field.lookup('zzz_object_that_does_not_exist'))。三道门全部 exit 0、零诊断。⇒ type: Bug:validate / lint / build 对一份不可能工作的元数据报成功。

为什么 p2

• ⭐ 每一张记录表单都依赖的那一个元数据引用,恰恰是没有任何门去读的那一个。 后果在运行时才现形:记录选择器向 REST 要一个未注册的对象(404 / OBJECT_NOT_FOUND),$expand 失败,表单渲染一个永远解析不出来的 lookup 控件。
• ⚠️ 它已经造成了一次真实的判断失效:hotclm 卡 02 的验收条件是「只有当 objectstack validate 接受跨包引用时才声明 crm_contract」——而 validate 接受一切引用,所以那个条件是空的,它根本无法回答自己被问的问题。⇒ 一个不可能失败的验收条件,由这个洞制造。
• ⛔ 不升 p1:没有已发布应用因此损坏(那个字段被留在了 PR 之外,没有作为悬空引用发出去)。

承接者拿到的边界

• ✅ 交付物 = 卡写好的四级阶梯,照 validate-object-references.ts 已经为其它面实现的同一套严重度:① 在本 stack 的对象里解析到 ⇒ OK;② 在 PLATFORM_PROVIDED_OBJECT_NAMES 里解析到(如 Field.user() 指向的 sys_user)⇒ OK;③ 未解析且非平台前缀 ⇒ error(validate / build 失败);④ 未解析但带平台前缀 ⇒ 沿用现有 advisory。
• ⛔ 不要在本 PR 里发明跨包逃生口。 卡提到的 crossPackage: true / externalObject 标记是新的创作面,是另一张卡。⚠️ 若你实现阶梯时发现它会拦下一个合法的跨包引用(如 hotclm 的 clm_contract.crm_contract → HotCRM 的 crm_contract),⛔ 停下来在卡上报,由本席把逃生口路由成自己的卡——不要为了让阶梯落地而顺手加一个未经裁定的标记。
• ⛔ 不要碰 [spec] FieldSchema accepts a lookup/master_detail with no reference target, though its own TSDoc calls the key required #13632(reference 必填非空,已关)与 data: a lookup accepts an id that does not exist in the referenced object — including the RBAC permission-set link tables #4441(lookup 值即行 id 不存在,写路径已拦)。前者管「有没有写」,后者管「值存不存在」,本卡管「目标对象存不存在」——三个不同的洞。
• ⚠️ 新增一条 error 级拒绝 ⇒ 收窄接受集:认领同笔记 Clause-②: yes,PR 挂载体走达档复核。⭐ 并且必须先量一次存量:今天仓内与已知应用里有多少悬空引用会因此从绿变红。⛔ 那个数没量出来之前不要开 PR——它决定这是「加一道门」还是「一次迁移」。
• 复现按卡里的最小探针原样跑(@objectstack/spec / cli / lint 17.3.0,hotclm 应用)。
• 📎 hotclm 的 docs/PLATFORM_GAPS_FROM_TEMPLATES.md 追加由承接者补(卡明说留给接手的人),⛔ 那是 hotclm 仓的动作,不在本仓 PR 里。

⛔ 分诊席边界照旧:不认领、不派发、不写码、不合并。

---

Generated by Claude Code

[zhuangjianguo]

Claim: PM loop round 1 (seat handover, 2026-09-08T02:34Z)
Session: session_016N6xmWt5hYm94ffVEwGH8x
Branch: claude/issue-16611-lookup-reference-target-gate
Worktree: objectstack-issue-16611
Domain: domain:spec
File surface: packages/lint/src/validate-object-references.ts, and the defineStack cross-reference validator if the ladder must also fire there (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: claude-fable-5-1 (CONTRACT_REVIEW_TIER; --tier run this dispatch over packages/lint/src/validate-object-references.ts returns NO path mandate and NO Clause-② path hint — the tier is taken from card CONTENT: a new error-level refusal narrows a published accept set, which is the declaration limb)
Clause-②: yes
Thread-read: 5572182546
Serial constraints cleared: packages/lint/src/validate-object-references.ts — no open lane card names it and none is in flight. #16126 (whitespace-only reference on lookup/master_detail) is the nearest neighbour: pm:queue, unassigned, not dispatched, and it lands in packages/spec's FieldSchema refinement — a different file and a different hole (「有没有写」 vs 「目标对象存不存在」), per triage's own three-hole split. #14791 is dispatched this same batch and touches packages/lint only via validate-react-page-props.ts fixtures — a different file. Lane work in flight: #16510 / PR #16592 (another session) is DISJOINT. ⛔ Fence honoured: PR #16618 / card #16041 not touched.

Assignee note (read this before touching the field). The assignee zhuangjianguo is this AGENT session's presence bit, not a human assignment — this container authenticates as that account. Identity is the session ID above, per 「assignee 是 presence bit,Claim: 是身份」. ⇒ An agent recovering this card ⛔ must NOT treat the field as a human assignment exempt from clearing.

---

Generated by Claude Code

[zhuangjianguo]

Dispatched — PM loop round 1, 2026-09-08T02:36Z.

Backend	mode:subagent (in-process)
Model	claude-fable-5-1 = CONTRACT_REVIEW_TIER, forced by Clause-②: yes (a new error-level refusal narrows a published accept set)
Branch	claude/issue-16611-lookup-reference-target-gate

Tier note, since the path derivation does not reach it: dispatch-gates.mjs --tier packages/lint/src/validate-object-references.ts returns no path mandate and no Clause-② path hint — that limb only fires on packages/spec/src/**. The tier here is taken from card content via the declaration limb, which is exactly the case the tool's own output calls "a FLOOR, never a clearance".

Boundary zone — triage's constraints (5572182546) carried verbatim as binding:

• Deliver the four-level ladder, mirroring the severity ladder validate-object-references.ts already implements for its other surfaces.
• ⛔ Do not invent the cross-package escape hatch (crossPackage / externalObject) — that is a new authorable surface and a separate card. ⚠️ If the ladder turns out to refuse a legitimate cross-package reference, the dev stops and reports rather than adding an unruled marker to make the ladder land.
• ⛔ Do not touch [spec] FieldSchema accepts a lookup/master_detail with no reference target, though its own TSDoc calls the key required #13632's hole (reference present and non-empty) or data: a lookup accepts an id that does not exist in the referenced object — including the RBAC permission-set link tables #4441's (a lookup value that does not exist). Three different holes; this card owns "does the target object exist".
• ⭐ The population must be measured before the PR is opened — how many references go green→red today, in this repo and the reachable known apps. That number decides whether this is "adding a gate" or "a migration", and the reviewer needs it in the diff. ⛔ No PR before that number exists.

Assumption zone — handed over as falsifiable:

1. The repro was measured on 17.3.0; origin/main is 5e53d73. The dev re-runs the minimal repro on current main before building anything — a zero-implementation stop with evidence is a good outcome, not a failure.
2. Triage names the landing point as validate-object-references.ts and possibly defineStack's validateCrossReferences. ⛔ I did not verify whether the ladder must also fire there for build to fail — the dev derives it and declares the real file surface.
3. Triage explicitly deferred a lane question: if, having read the domain table, the dev judges packages/lint belongs to domain:devx, ⛔ it does not change the label — it reports, and this seat routes a pm:retriage.

---

Generated by Claude Code