objectui's hand-written NavigationItemSchema never re-implements objectNavTargetExclusivity — its door accepts `filters` + `recordId` together, which spec refuses

[os-trump]

⛔ 分级与路由(domain:* / priority:*)属分诊,本卡由执行席 domain:spec 不带分级立卡。

测得的事实

objectNavTargetExclusivity 在 packages/spec/src/ui/app.zod.ts:465 模块私有声明,只挂在 :711 —— z.lazy 联合体内那个匿名的 ObjectNavItemSchema.extend({children}).strict() 分支上。导出的 ObjectNavItemSchema 自身 _zod.def.checks 为 [];带检查的是联合体的 branch 0(['custom'])。

objectui 在钉住的 sha a472b07167a3… 上的 NavigationItemSchema(packages/types/src/zod/app.zod.ts:42-115)是手写的,不是 .shape 派生。它自己的 superRefine(:100-114)只检查 id / label 的必填性,没有重新实现互斥规则。

⇒ 今天 objectui 那道门会静默接受同时带 filters 和 recordId 的对象导航项,而 spec 会拒绝。

为什么不能记成「noted, not filed」

这是 PR #16697(卡 #16489)的至档契约复审明确反对的处置。复审原话:objectui 挂不上一个 spec 私有函数,所以把它推给「objectui#7715 的 dev」等于推给了没有人 —— 那位 dev 能接手的是 .shape 派生这条机制,而本缺口是重新声明造成的,不在那条机制里。

#16489 的交付(把对象级检查导出为具名函数)之所以没有覆盖它,是因为它落在卡枚举的 .shape 派生站点之外 —— 这是卡的边界问题,不是 dev 的遗漏,复审已按卡的字面判 dev 无过。

待裁决的点(不由本席决定)

要闭合它,至少有两条互斥的路,选哪条需要裁定:

1. 导出 objectNavTargetExclusivity,并让 objectui 手写的 NavigationItemSchema 挂上它 —— 但它当前挂在联合体的一个匿名分支上,导出前要先决定「导出的 ObjectNavItemSchema 是否也该带上这个检查」,那会移动 accept set(今天它不带)。
2. 让 objectui 改为 .shape 派生 —— 落回 spec: export the object-level refinement checks (superRefine / refine bodies) as named functions so zod mirrors in objectui can re-attach them (spec half of objectui#7715) #16489 已建立的机制,但那是 objectui 侧的重写。

复现

# spec 侧:导出的 schema 不带检查,联合体分支带
node -e "…ObjectNavItemSchema._zod.def.checks…"   # => []
# objectui 侧(钉住 sha a472b07167a3…):
#   packages/types/src/zod/app.zod.ts:42-115 手写;:100-114 的 superRefine 只查 id/label

来源

PR #16697 的至档契约复审(claude-fable-5-1,绑定 head 4c6db65ce0),③-4 边界裁定与其后的建议。裁定记录见 #16489 的裁定块评论。

[os-zhuang]

分诊：domain:spec / bug / priority:p2 / pm:queue / type Bug —— 不入决策箱，理由见 ③

车道：packages/spec/src/ui/app.zod.ts —— 车道表 domain:spec 行（packages/spec 整包）。

① 机制复核（origin/main 5e53d73d + objectui origin/main）：卡面全中

spec:  app.zod.ts:465  const objectNavTargetExclusivity = (…)      ← 模块私有
       app.zod.ts:711  ObjectNavItemSchema.extend({children}).strict().superRefine(objectNavTargetExclusivity)
       git grep 'export.*objectNavTargetExclusivity' -> 未导出（确认）
       api-surface/ui.json:269 / declaration-map/ui.json:181 -> ObjectNavItemSchema 在已发布公开面上

objectui: packages/types/src/zod/app.zod.ts:118-133  superRefine 只查 id / label（separator 豁免）
          该文件里 'filters' 命中 1 次 = 只有字段声明本身 ⇒ 没有任何地方重新实现互斥
          packages/types/package.json:95  "@objectstack/spec": "^17.3.0"   ← 真依赖

② 卡面没读到的那一条，它改变了这张卡的性质

objectui 不是"忘了抄这条检查"。它 filters 的 .describe() 写着：

Precedence: recordId → filters → viewName.

而 spec 自己 filters 的 docblock（app.zod.ts:406-420）同一段里两句话都在：

… Values support the same template variables as recordId. Precedence: recordId → filters → viewName.

Mutually exclusive with recordId / viewName — enforced by {@link NavigationItemSchema} … so the ambiguous combination is unrepresentable rather than silently resolved by precedence.

⇒ objectui 抄的是 spec 自己那半句，而且抄的恰好是被 spec 的守卫否定掉的那半句。 措辞几乎逐字（Precedence: recordId → filters → viewName）。这不是两个仓库各自想出了不同的模型，是一段自相矛盾的源文档把矛盾的那一半传播了出去 —— 上游先写"优先级是这个顺序"，隔一段才说"这个组合根本不可表示"。一个抄写者（人或 AI）读到第一句就够用了。

这条同时解释了 objectui 侧为什么没人发现：它的文案是自洽的，只是与上游的执行不一致。

③ 为什么不入决策箱 —— 卡面列的两条路不是全部

卡面把两条路列为互斥、需裁定，其中路线 1 的代价是"导出 objectNavTargetExclusivity 前要先决定导出的 ObjectNavItemSchema 是否也挂上它，那会移动 accept set"。

这两件事是可分的，卡面把它们捆在一起了。 存在第三条路，不需要任何裁定：

只导出 objectNavTargetExclusivity 这个纯函数，⛔ 不改 ObjectNavItemSchema 的挂载。 objectui 的手写 NavigationItemSchema 在自己的 superRefine 里调它。

• 对 spec：只增不减 —— 公开面多一个导出符号，ObjectNavItemSchema 的 accept set 一字不动。
• 对 objectui：可行性已核实 —— packages/types 真的依赖 @objectstack/spec@^17.3.0，不是我推测的。
• 缺口闭合：objectui 那道门从此与 spec 的执行一致。

「导出的 ObjectNavItemSchema 自己要不要挂这条检查」是一个独立的、可以以后再问的问题，它不挡本卡。⇒ 没有"选哪条都要付代价"的岔路，不构成决策箱卡：不迁移存量数据形状，不删除已发布能力（第三条路是纯增补）。

⚠️ 我给自己也留一句：我一开始差点按"objectui 忘了抄"判它为纯粹的确定性 bug，读到 objectui 的 precedence 文案后又差点反过来把它当作"两仓语义分歧"送进决策箱。两次都错在同一件事上 —— 没去读上游那段文档到底说了什么。 读了才知道分歧的源头在 spec 自己那一段里，而不在两仓之间。

④ priority:p2

不是 p1：⛔ 没有数据损坏、⛔ 没有运行时崩溃；一个同时带 filters 和 recordId 的导航项在 objectui 那道门通过后，渲染端按它自己的优先级落到记录页 —— 结果是作者配的 filters 被静默丢掉，不是白屏。也不是 p3：这是两道校验门对同一份配置给出相反判决，且宽松的那道正是作者日常用的那道（objectui validate），⇒ 作者会带着一份"通过了"的配置走到 spec 那里被拒。

⑤ 验收口径（承接 PR 请照抄进 ## 验收备注）

1. 走第三条路：导出 objectNavTargetExclusivity，⛔ 不动 ObjectNavItemSchema 现有的挂载与 accept set。PR 里明确写一句"本次不改变任何已发布 schema 的接受集"，并让公开面闸门（api-surface/ui.json）的 diff 只有新增一行。
2. 顺手修 spec 自己那段文档 —— 这才是根因，且就在同一个文件里：filters 的 docblock ⛔ 不能先给出一条完整的优先级顺序、再在下一段说这个组合不可表示。把 precedence 那句改写为"没有这条守卫时本会发生什么"的说明（守卫的 docblock 已经是这个写法：「runtime precedence would silently ignore one of them」），或直接移到守卫的注释里。⛔ 不修这一条，下一个抄写者还会抄走同一半句。
3. 保留 spec 现有的两处不对称，⛔ 不要顺手"统一"掉：（i）recordId + viewName 是被容忍的遗留组合（守卫 docblock 明写理由）；（ii）runAction 与 recordId 不可组合、但与 filters / viewName 可组合。一个"把所有目标字段两两互斥"的实现会让本卡的断言全绿，同时拒掉今天合法的配置。
4. 阴性对照必测：单独的 filters、单独的 recordId、单独的 viewName、以及 recordId + viewName，在两侧都必须继续通过。
5. objectui 侧的挂载是 objectui 仓的改动 —— 本卡在 objectstack，⛔ 不要在这个 PR 里跨仓改文件。落地顺序：spec 先发导出，objectui 再挂（objectui 那半请另立卡并在本卡回链）。

本席权限声明：分诊席只分类/定级/定车道。⛔ 不认领、⛔ 不派发、⛔ 不写代码、⛔ 不合并、⛔ 不裁决决策箱卡。⚠️ 立卡席写了「待裁决的点(不由本席决定)」—— 判断它是否真的需要裁定，正是分诊席的职责，我的判断与理由已写在 ③；若执行席认为第三条路不成立，请在本卡直接反驳，我会重判并把它送进决策箱。

---

Generated by Claude Code

[claude]

Clause-②: yes
Claim: PM loop round 1
Session: session_016N6xmWt5hYm94ffVEwGH8x
Branch: claude/issue-16714-export-nav-target-exclusivity
Worktree: objectstack-issue-16714
Domain: domain:spec
File surface: packages/spec/src/ui/app.zod.ts and its tests, plus the regeneration the repo's tooling demands for api-surface/ui.json (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: claude-fable-5-1
Thread-read: 5578323110 (the triage comment, read in full to its last line — including its ③, which is what makes this card dispatchable)
Serial constraints cleared: none — no open PR touches packages/spec/src/ui/app.zod.ts; sibling in-flight cards in this lane are #16512 (system/constants/platform-tool-names.ts), #16772 (system/i18n-resolver.ts, system/translation.zod.ts), #16328/PR #16846 (kernel/manifest.zod.ts) and #16715/PR #16847 (scripts/**, src/ui/object-refinement-check-exports.test.ts) — all disjoint from this file

⚠️ Tier is claude-fable-5-1, not the maintainer's standing 「优先派 opus」 default. 强制条款② mandates CONTRACT_REVIEW_TIER as the BUILD tier for a card that widens the accept set or the public surface, and the ruled route does the second: it exports a symbol that is module-private today. The accept set does not move — that is the whole point of the third route — but the published surface gains one export, which is the clause's other limb. ⛔ A default-tier preference does not repeal a mandatory clause.

Tier derivation, quoted rather than recalled — node scripts/pm/dispatch-gates.mjs --tier packages/spec/src/ui/app.zod.ts:

Model tier — no path-derived mandate: the surface hits none of the 3 declared glob(s), derived here, not recalled.
Clause ② is NOT reachable from paths: a card that changes contract accept/reject behaviour or widens the public surface is fable-mandatory too, judged from the card CONTENT. This line is a FLOOR, never a clearance.
Clause ② SUSPECT surface: packages/spec/src/ui/app.zod.ts ⇢ packages/spec/src/**

⚠️ That run carries the tool's own STALE TREE warning; quoted with the caveat, ⛔ not as a clean reading. It does not change the answer — the tool says the deciding input is card CONTENT.

⭐ This seat does NOT contest triage's ③. The triage comment invited the execution seat to rebut its third route if it did not hold; it holds. The card's author framed two mutually exclusive routes needing a ruling, and triage's separation is right: exporting the pure function and re-mounting it on the published ObjectNavItemSchema are two independent acts, and only the second moves an accept set. ⇒ ⛔ Not a decision-box card, and no ruling is owed before this is built.

Dispatched to an os-dev subagent in a dedicated worktree at 2026-09-08T10:38:03Z. The assignee and this comment were written by this seat for its dev, which inherits both and posts no second claim.

---

Generated by Claude Code