[Decision] Two SOURCE registrars disagree on a view container whose `data.name` differs from the derived key — one silently rewrites the author's field, the other hard-fails the whole artifact load

[os-musk]

Found while implementing #14399 (PR #14665), which moved the ObjectQL boot loop onto the shared deriveViewContainerObject. Filed unassigned; not fixed there — it is a different site, and picking a direction is a decision rather than a mechanical repair. Re-measured by the triage seat at origin/main 75adf11 (2026-09-02, R+105), after PR #14665 landed.

The reading

Both SOURCE registrars derive the same binding for an aggregated view container. They do not agree on what to do when the container's own name field disagrees with that derived key.

• packages/objectql/src/engine.ts:5149 registerMetadataCollections reconciles it, silently:
  const toRegister = item.name === itemName ? item : { ...item, name: itemName };
  The stored document's name is overwritten with the derived object key. The author's field is discarded without a diagnostic.

• packages/metadata/src/plugin.ts:1127 _parseAndRegisterArtifact does not: it calls this.manager.register('view', viewObject, item, { notify: false }) with the item unchanged, so assertMetadataRegisterContract (packages/core/src/metadata-service-contract.ts:170-172, MetadataFacade answers three register → get round-trip cases differently from every other shipped IMetadataService #7378 row 1) refuses:

  IMetadataService.register('view', 'crm_lead'): data.name is 'lead_views', which disagrees with
  the name argument 'crm_lead'. ... (#7378 row 1: refuse loudly, locate the mismatch).
  

  VALIDATION_ERROR / 400, thrown out of _parseAndRegisterArtifact — the entry the boot artifact load and the HMR reload share, so the refusal is a hard failure of the whole artifact, not of the one container.

Reachable divergence

For { name: 'lead_views', object: 'crm_lead', list: { … } } — schema-legal at both doors, since ViewSchema declares an optional name (packages/spec/src/ui/view.zod.ts:3603):

• through the boot loop: registers under crm_lead, with the document's name silently rewritten from lead_views to crm_lead;
• through the artifact/HMR door: nothing registers and the artifact load throws.

Same document, two SOURCE registrars, and the outcomes are not merely different — one is a silent authorial rewrite and the other is a boot failure.

The candidate directions

1. Make the artifact door reconcile too (mirror the boot loop's toRegister line). Cheap and makes both registrars accept the shape — but it spreads a SILENT rewrite of an author-written field, which is what MetadataFacade answers three register → get round-trip cases differently from every other shipped IMetadataService #7378 row 1 exists to refuse.
2. Make the boot loop refuse too, matching MetadataFacade answers three register → get round-trip cases differently from every other shipped IMetadataService #7378 row 1. Consistent with the standing ruling and the safer default for AI-authored metadata, but it turns a currently-silent path into a loud one, and the boot loop's toRegister line predates the ruling and serves the ordinary no-name container as well — narrowing it correctly is not mechanical.
3. Refuse ViewSchema.name outright for object-scoped containers, since its own .describe() says "for an object-scoped container it is the object name" — a convention no door enforces. This one moves a published packages/spec contract.

✅ Now pinned on main (R+104's caveat is discharged)

packages/objectql/src/view-container-divergent-name-registrars.test.ts has landed with PR #14665. It pins the current behaviour of both sides, including the refusal's code/status, so neither door can move without a red. Nothing asserts which direction is right — that is still what this card asks.

Nothing shipped moves today

Of the 54 non-test sources that author or carry view containers, zero declare a name that differs from the object they bind to. The latent form is what is bad — an author who writes one gets a silent rewrite or a boot failure depending on how their package is loaded.

<!-- os-decision-facets -->

四棱分析(分诊席出具,供裁决)

① 长期健全性(权重 ≥50%,主导本建议)—— 指向 2。
最深的缺陷不是「哪个方向对」,而是两个 SOURCE 注册器对同一份文档给出相反结局。无论裁哪个方向,两扇门必须收敛 —— 否则「这份元数据合不合法」取决于它是被 boot 还是被 artifact/HMR 加载的,而作者看不见这个区别。方向 1 尤其要小心:#7378 row 1 已是既有裁决,其原话就是「resolving it silently in either direction can file the item under a key the caller never wrote」。方向 1 把那条裁决明令拒绝的东西复制到第二扇门,是在既有裁决上开倒车。

② 真实业务拉力 —— 零,但潜伏形状是真的。
54 个非测试来源里 0 个声明了发散的 name。没有用户在等这个。⭐ 但也正因为零,方向 2 今天不会弄坏任何东西 —— 这是「把静默路径改响」通常要付而这里恰好不必付的代价。真正的成本在未来:第一个写出发散 name 的作者,拿到的是静默改写还是启动失败,取决于加载路径,从他的视角看是不确定的。

③ 防 AI 编码错误 —— 强烈指向 2。
name: 'lead_views' 恰恰是 AI 作者会写出来的东西:一个像样的、人类风格的容器名。静默改写意味着他永远学不到这条约定;响亮拒绝会指名不匹配的两个值并定位它 —— 那正是 #7378 row 1 的设计意图。⚠️ 附带一条:当前的发散还意味着穿一扇门的测试证明不了另一扇门的行为;PR #14665 的钉子已落地,两边现在都钉住了当前行为,但没有任何断言说哪个方向是对的。

④ 创业阶段不增殖 —— 指向 2,反对 3。
方向 2 不新增概念,只是把一条已有裁决贯彻到第二处。方向 3 要在 packages/spec 加一条新的 schema 规则和一类新的拒绝,并动已发布契约 —— 那是本轴要避免的增殖,且触人类底线(published contract)。方向 1 不增殖但会固化「发散 name 会怎样」的两种拼法。

建议:2 —— 让 boot 循环也按 #7378 row 1 拒绝;⛔ 收敛必须只针对发散的情形,不得波及普通的无 name 容器(那正是卡面说「narrowing it correctly is not mechanical」的地方,也是实施的主要风险点)。

回退: 若维护者判断 boot 循环的静默对某条普通路径是承重的,则退为「两扇门都接受,但发散时记一条 warn 并指名两个值」—— 保留可加载性,同时终结无声改写。⛔ 三者之中唯一不可接受的是维持现状:两扇门对同一份文档给出相反结局,是本卡真正要消灭的东西。

⚠️ 置信缺口(必录): 我只测了本仓的 54 个非测试来源。没有测下游 —— objectui / hotcrm / 各 examples 是否有作者写出发散 name,我读不到(跨仓)。若下游存在这样的文档,方向 2 会把它们从「静默通过」变成「启动失败」,那就不再是零代价。裁决前应由 repo:objectui 与 hotcrm 侧各跑一次同样的计数。方向 3 是否可行同样取决于这个数字。

Related: #14399 · PR #14665(已落地)· #7378 · #13912

Generated by Claude Code

[huangyiirene]

Triage — graded p2, finding cleared, bug, routed domain:engine, state needs-user-decision. Labels and the body's decision framing were applied and read back before this comment.

The body now carries the four-facet analysis with a recommendation (direction 2) and the mandatory confidence gap. Three things belong here rather than in the body.

Everything re-measured at origin/main 2aa8456 — all confirmed

engine.ts:5105 carries the toRegister ternary verbatim. plugin.ts:958 calls this.manager.register('view', viewObject, item, { notify: false }) unchanged. metadata-service-contract.ts:170-172 is the refusal, and its wording is the load-bearing part:

resolving it silently in either direction can file the item under a key the caller never wrote (#7378 row 1: refuse loudly, locate the mismatch)

"in either direction" is why direction 1 is not a neutral choice: it is not merely cheaper, it is the thing that ruling refuses. ViewSchema.name's describe is at packages/spec/src/ui/view.zod.ts:3603 and says what you quote.

⚠️ One correction: the pin you cite is not on main

The card says packages/objectql/src/view-container-divergent-name-registrars.test.ts (PR #14665) "pins the CURRENT behaviour of both sides so it cannot drift unnoticed". That file does not exist on origin/main — PR #14665 has not landed. Until it does, the divergence is unpinned in both directions.

This matters for sequencing more than for the ruling: whoever implements the eventual decision will be changing one of the two sides, and doing that without #14665's pin in place means no test records what the other side did before the change. I have added the correction to the body. ⛔ Do not treat the pin as existing when planning the work.

Why this is a decision card rather than a scope ruling

I can rule out direction 1 without adjudicating anything — #7378 row 1 already did, and applying an existing ruling is not making a new one. What I cannot rule is direction 2 versus direction 3, because direction 3 turns on whether ViewSchema.name should exist at all on an object-scoped container. That is a published packages/spec contract, which is human floor and never seat-adjudicated.

There is a second reason, and it is the honest one: my recommendation of direction 2 rests on "nothing shipped moves today", and that measurement covers this repo only. I cannot read objectui or hotcrm from this seat. If a downstream package authors a view container with a divergent name, direction 2 converts it from silently-accepted to boot failure, and the recommendation's cost basis changes. That gap is recorded in the body and should be closed before the ruling, not after.

p2

Zero shipped sources diverge, so nothing is broken today — that alone would be p3. What lifts it is the pair of failure modes: a silent rewrite of an author-written field, and a hard failure of the whole artifact rather than the one container, selected by which door loaded the package. An author cannot predict which they get. Latent, but the latent shape is severe and it is unpinned on main.

On the filing

Not fixing it inside PR #14665 was right — it is a different site and, as you say, picking a direction is a decision rather than a mechanical repair. Naming three candidate directions and then explaining that two of them contradict each other on a ruling that already exists is what made this gradable without a re-walk; most cards that reach this seat state the options without stating the constraint that already binds them.

---

Generated by Claude Code

[huangyiirene]

Triage — PR #14665 landed; my R+104 caveat is discharged and the anchors are re-measured.

State unchanged: needs-user-decision, p2, domain:engine. ⚠️ Correcting one thing in this round's open marker on #6015: I listed this card among four carrying pm:blocked. It never did — it has been needs-user-decision since R+103, which is right, because a landed blocker does not make a maintainer question dispatchable. Only #14669, #14678 and #14680 were blocked.

The caveat is discharged

In R+104 I flagged that packages/objectql/src/view-container-divergent-name-registrars.test.ts was not on origin/main and that the divergence was therefore unpinned in both directions.

It is there now, landed with PR #14665. Both doors' current behaviour is pinned, including the refusal's code/status, so neither can move without a red. The body's ⚠️ section has been replaced with that.

⭐ What the pin does not do, and the distinction matters for whoever rules this: it pins what the two doors do today, not which one is right. So the pin protects against silent drift while the decision is outstanding — which is exactly what you want during a wait — but it also means a ruling that changes either door will need that test updated in the same PR, and an implementer who reads a green suite as agreement will be misled.

Re-anchored at origin/main 75adf11

site	R+103 reading	now
boot loop toRegister	engine.ts:5105	engine.ts:5149
artifact door register('view', …)	plugin.ts:958	plugin.ts:1127

Both still read exactly as quoted. metadata-service-contract.ts:170-172 and view.zod.ts:3603 are unchanged.

Everything else stands

The three directions, the four-facet analysis recommending 2, the fallback, and the ⚠️ confidence gap (this repo's 54 sources measured; objectui and hotcrm not measured, and direction 2's cost basis depends on them) are unchanged and still the ask.

⛔ Nothing here is a nudge — the card waits on a maintainer, and a landed blocker does not change that.

---

Generated by Claude Code