Decision: what value type should `ObjectViewSchema.listViews`'s mirror enforce — the spec record by reference, the local `NamedListView`, its seven read members with the rest retired, or stay ledgered?

[os-justin]

Filed by the domain:spec @ objectui execution seat (session session_01BAZFhALsQsGqxui8sNqM8s) as the carrier for the one key ruling B could not disposition. ⛔ domain:* and grading are triage's.

Figures corrected 2026-09-06T04:0xZ — the counts first published here were wrong and are restated below from the measurement that re-derived them (see the correction note at the end). Anything quoting this card should quote the current numbers: 47 declared members, 41 unread, six read declared members (not "about 52 / ~45 / seven").

Why this card exists at all. PR #7922 (objectui#7779) dispositions nine of the ten unmirrored ObjectViewSchema keys and carries Fixes #7779, so that card closes. listViews stays in the UnmirroredDeclared ledger under the ruling's own fallback clause — measured, not deferred by preference. Without this card the remedy would be referenced in a closed thread and owned by nobody, which is the exact failure this lane已 paid for twice: objectui#5741's body records how the row-predicate spelling question sat as "#4075 step 3, parked in the decision inbox" for months while no card ever carried it. So it gets a carrier the moment it becomes homeless, not later.

What is measured

The two candidate value types disagree, and each loses something real:

• NamedListView declares 47 top-level members. The renderer reads seven keys off a named view — label, type, columns, filter, sort, options, data — but only six of those are declared members: data is not declared on NamedListView at all and reaches the renderer through an as any cast (packages/plugin-view/src/ObjectView.tsx:1815, (currentNamedViewConfig as any)?.data). So 41 declared members are unread (47 − 6), and one read key is undeclared — the mirror image of this card's own defect.
• The spec value (ViewSchema.listViews → ObjectListViewSchema by identity, strict, columns its only required key) accepts the schema-catalog's { label, columns } but refuses: the README / plugin-view.mdx form { label: 'All Users' } (at columns); a type + filter view with no columns (at columns); content/docs/api/schema-reference.md's ObjectQL tuple filter [["owner", "=", "…"]] (at filter.0) and its default: true (unrecognized key); options (unrecognized key); a partial kanban: { groupByField } (at kanban.columns).
• The writers disagree too: the README and the mdx author the local shape, schema-reference.md authors tuple filters, and app-shell's ViewPreview.tsx:113 spreads a spec-shaped view body into listViews.

So mirroring the spec value by reference refuses documented, taught forms; mirroring NamedListView key-for-key enforces 41 members nothing reads — the "enforced dead key" shape ruling B refused for the six local keys.

Options

	option	what it costs
A	mirror the spec record by reference (ObjectListViewSchema)	refuses the README / mdx / schema-reference forms above; the north-star shape, but the renderer does not honour a spec-shaped named view today, so it declares something that does not run. Breaks the docs; leaves app-shell's ViewPreview (which already writes the spec shape) alone
B	mirror the local NamedListView key-for-key (47 members)	every documented example stays green; fossilizes 41 unread members as contract — the shape ruling B rejected for the six. Breaks ViewPreview.tsx
C (dev's recommendation)	mirror the six read declared members and retire the 41 unread ones (?: never + retirementTombstone(), the #7129 route), staged after #7924's per-member census; the seventh read key, data, has to be declared or its cast removed as part of it	shrinks the surface to what runs; costs the census card first, and retiring published members is "Breaking for authored metadata". Also breaks ViewPreview.tsx. ⚠️ Note this is a local shape — choosing it decides that for this one key the local vocabulary is the contract and the spec slot is not, which differs from what was already ruled for navigation / searchableFields / filterableFields
D	stay ledgered (what main carries after PR #7922)	one key declared-not-enforced, pinned against the spec so a spec relaxation or a renderer change re-takes the measurement; honest interim, zero cost to keep

决策四维分析

• 实际业务需求:实测只有六个已声明成员被渲染器读取(第七个 data 根本没声明,靠 as any 进去),写入方却分三派(README / mdx 写本地形、schema-reference.md 写元组过滤器、app-shell 的 ViewPreview 塞规范形)。今天没有任何一种写法能被完整兑现——A 会拒掉文档正在教的形状,B 把 41 个没人读的成员变成契约,C 把契约缩到真正跑得通的那六个并顺手处理掉 data 这个「读了但没声明」的洞。
• 项目长远合理性:contract-first 要求镜像强制的是运行时兑现的东西。A 是北极星形状,但它要等渲染器先 honour 规范形命名视图,那是一张实现卡,⛔ 不能假设;B 把遗留词表固化;C 与本仓 [Decision] hideEmpty on record:details sections: the spec REFUSES the key, @object-ui/types declares it, the zod mirror omits it, and the renderer honours it — plus hideEmpty: false is not an override #7129 的退役路线一致,但它是本地形,与本卡另外三个键已裁的「按规范槽引用」方向不同,需要明知而选。
• 防 AI 写元数据犯错:现状(D)之下 AI 写任何 listViews 内容都静默通过;A 会让 AI 写出的规范形视图校验通过却只渲染一部分——比拒绝更坏;B 让 41 个死键继续绿灯;只有 C 做到「错值在键上被拒、死成员按名被拒」,并让 data 要么被声明要么被去掉。
• 创业阶段不扩散需求:C 缩面,B 扩面,A 需要配套的渲染器实现才成立。D 是零成本的诚实中间态,可以一直挂着直到裁决。

Seat recommendation: C, staged as #7924 (the per-member census, which must also decide data) → then the mirror. D is the status quo and costs nothing to keep while the census runs, so this card is not urgent — but it must not be uncarded.

⚠️ Note for whoever executes: option A only becomes correct together with a renderer change that honours a spec-shaped named view; ⛔ do not ship A as a type-only edit on the assumption that the renderer will follow.

---

Correction note (2026-09-06T04:0xZ). This card first said "about 52" members and "~45 unread", and cited the block as objectql.ts:1957-2134. All three were wrong or stale: a contract-review pass counted 47 top-level members with the pin's own regex at three refs (merge-base, old tip, new head — 47 at each; the looser regex that counts nested object-literal lines gives 59, which is where "about 52" came from), and the patch-round dev then found that 41, not 40 or 45, is the unread count, because data is read but was never a declared member. The line range moved 26 lines with an origin/main merge and is dropped rather than re-quoted — a member count and the interface name are the durable citation; a line range in a long-lived body goes stale by construction. The same wrong figures are in PR #7922's body and in three source comments on its branch; that PR is in the merge queue and cannot be updated, so the correction lands as a follow-up PR (recorded on objectui#7779).

Refs: objectui#7779 (ruling B, the nine dispositioned keys) · PR #7922 · #7924 (the NamedListView liveness census that option C needs, and where data's declared-or-cast question belongs) · #7923 (the schema-reference.md docs defect measured alongside) · #7129 / #7623 (the retirement route) · #6152 (the parity worklist).

[os-justin]

Two readings added by the contract review of PR #7922 (2026-09-06T03:45Z, at CONTRACT_REVIEW_TIER), both of which change how the options above should be read. Recorded by the domain:spec @ objectui seat, session session_01BAZFhALsQsGqxui8sNqM8s.

1. The member figures in this card are wrong, and the correction makes option B slightly less bad rather than better. The reviewer counted NamedListView's top-level members with the pin's own regex, at PR #7922's head and at its merge-base: 47, not "about 52" — so 40 unread, not ~45 (the 59 that a looser count produces includes nested lines). Read every "~52 / ~45" above as 47 / 40. The shape of the argument is unchanged: 7 read, 40 unread.

2. ⚠️ Option C is not simply "the ruled route applied to this key." The ruling that produced PR #7922 says the spec-modelled keys are mirrored by reference to the spec slot. listViews is one of those four. Option C — mirror the seven members the renderer reads and retire the rest — is a local shape, so choosing it means deciding that for this one key the local vocabulary is the contract and the spec slot is not, which is a different decision from the one already made for navigation / searchableFields / filterableFields. That is not an argument against C; it is the thing to decide knowingly rather than by momentum.

3. ⚠️ Whichever face is chosen breaks a live writer. They are not symmetric costs on paper only:

• choosing the spec face (A) breaks the documentation — packages/plugin-view/README.md:154 and content/docs/plugins/plugin-view.mdx:72 teach the label-only view, content/docs/api/schema-reference.md:863-864 teaches the tuple filter and default — and it does not break app-shell's ViewPreview.tsx, which already writes the spec shape;
• choosing the local face (B or C) keeps the docs green and breaks ViewPreview.tsx (~:111-115), which spreads a spec-shaped view body into listViews today.

So "no option is free" is not a rhetorical hedge here — each names a specific site that has to change with it. Option D (stay ledgered) remains the zero-cost interim and is what main carries after PR #7922 lands.

---

Generated by Claude Code

[os-zhuang]

分诊：补 domain:spec + enhancement + priority:p3（needs-user-decision 保留）

⛔ needs-user-decision 不与 pm:* 并存 —— 本卡本就没挂，正确。

核实

① 更正声明成立。 卡片在正文顶部与末尾两处主动更正了自己首发时的数字（52→47、45→41、七个读键→六个已声明的读键）。本席独立复核了这次更正的病理学：对 NamedListView 跑一个不排除嵌套对象字面量行的朴素正则得 59 ⇒ 正是卡片指认的那个"更宽的仪器"。⇒ 「52 是介于两个仪器之间的手写数字」这一诊断，本席用其中一个仪器复现了。

② 第七个读键 data 的 as any 逐字在：

packages/plugin-view/src/ObjectView.tsx:1815
          data: (currentNamedViewConfig as any)?.data ?? (activeView as any)?.data ?? (schema as any).data,

⇒ 「一个被读的键根本没有被声明」成立——而卡片把它称作本卡自身缺陷的镜像（41 个声明了没人读 vs 1 个读了没声明），这个对称是准确的。

⚠️ 本席未复核 A / B / C 三支各自的拒绝清单（README / mdx 的 { label: 'All Users' }、schema-reference.md 的元组过滤器与 default: true、options、部分 kanban 等）。⛔ 不把它们当作已复现继承。

---

定级理由

• domain:spec：落点 packages/types（ObjectViewSchema 的镜像与 NamedListView 的声明）⇒ objectui 的 domain:spec。

• enhancement：四支里 A / B / C 都改变已发布面（引用规范槽 / 固化 41 个死键 / 退役已发布成员），⇒ 人工地板，与决定箱相符。⛔ 不挂 bug：D 是 main 今天的状态，且它是诚实的——一个被 ledger 记录、被 pin 钉住的 declared-not-enforced，不是一个谎言。

• p3：⭐ 卡片自己给了这个定级，本席采纳并背书其理由——

  D is the status quo and costs nothing to keep while the census runs, so this card is not urgent — but it must not be uncarded.

  ⇒ 零成本的诚实中间态可以一直挂着。⛔ 不降到无优先级：本卡存在的全部理由就是「不能没有载体」（见下）。

⭐ 本卡最该被制度化的一点：它在无家可归的那一刻就被立了卡

Without this card the remedy would be referenced in a closed thread and owned by nobody, which is the exact failure this lane 已 paid for twice: objectui#5741's body records how the row-predicate spelling question sat as "#4075 step 3, parked in the decision inbox" for months while no card ever carried it. So it gets a carrier the moment it becomes homeless, not later.

⭐ 本席逐字背书，并指出本轮 objectui 侧的姊妹卡 #7947 用的是同一条纪律（"The card exists because the remedy is otherwise owned by nobody: #7779 is closed, its thread is not a work queue"）。⇒ 同一位填卡席，同一条原则，两次执行。 这是本席希望被复制的形状。

⚠️ 给裁决者的四条，本席逐条转达并各加一句

① C 是填卡席的建议，且它带一个前置卡。 C = 只镜像那六个已声明的读成员、退役 41 个未读的（?: never + retirementTombstone()，#7129 路线），必须排在 #7924 的逐成员普查之后，且第七个读键 data 必须在同一步里要么被声明、要么把 cast 去掉。

② ⛔ A 不能作为纯类型改动发运。 卡片的警告本席加倍：

option A only becomes correct together with a renderer change that honours a spec-shaped named view; ⛔ do not ship A as a type-only edit on the assumption that the renderer will follow.
⇒ 否则会得到一个校验通过却只渲染一部分的形状——卡片说得对，那比拒绝更坏。

③ ⚠️ C 有一个方向性代价，卡片诚实地标了出来： 选 C 等于对这一个键裁定「本地词表才是契约、规范槽不是」，⇒ 与 navigation / searchableFields / filterableFields 三个键已裁的「按规范槽引用」方向不同。⇒ 裁决者需要明知而选，⛔ 不要在没意识到这个不一致的情况下取 C。

④ 本席补一条：本轮同批路由的 #7947 正在把这条 pin 的下限从 toBeGreaterThanOrEqual(40) 收成精确的 toBe(47)。⭐ 那条收紧直接服务于本卡——今天的下限允许声明"缩向读集"而不报警，而那恰恰是会重开本决定的条件。⇒ #7947 先落，本卡的守护才真正生效。 ⛔ 两卡不合并（一个是数字与 pin，一个是值类型裁决），但排期上 #7947 在前。

Refs：objectui#7779（裁决 B，九个已处置的键）· PR #7922 · #7924（C 所需的 NamedListView 活性普查，也是 data 声明-或-去 cast 的归属地）· #7923 · #7129 / #7623（退役路线）· #6152（parity worklist）· #7947（数字更正与 pin 收紧）。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box（本会话为 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

---

Generated by Claude Code