finding(types/plugin-calendar): `CalendarViewSchema` declares 9 of its 13 keys that the `calendar-view` renderer never reads — including `events`, its only required key, which the renderer deliberately drops

[os-sales]

Found while implementing #5045 (correcting packages/plugin-calendar/README.md's "Schema API / CalendarView" block against CalendarViewSchema). Filed unassigned, not claiming.

#5045 was scoped to prose and is fixed as scoped. This card is the thing the measurement turned up underneath it: the published authored type and the registered renderer describe two nearly-disjoint surfaces.

Measured

CalendarViewSchema (packages/types/src/complex.ts:174, mirrored in packages/types/src/zod/complex.zod.ts:90) declares 13 own keys:

type (required)   events (required)   defaultView?   view?    defaultDate?   date?
views?            editable?           onEventClick?  onEventCreate?
onEventUpdate?    onDateChange?       onViewChange?

The renderer registered for calendar-view (packages/plugin-calendar/src/calendar-view-renderer.tsx) declares 10 registry inputs, and they are almost a different set:

data  titleField  startDateField  endDateField  allDayField  colorField
view  currentDate  allowCreate  className

Cross-referencing the two (grep for each key's read sites in packages/plugin-calendar/src/):

CalendarViewSchema key	read by the calendar-view path?
type	yes — registry dispatch
view	yes — resolveAuthoredView
onEventClick, onViewChange	only as host props — they are in HOST_CALLBACKS, forwarded when the value is a function, which authored JSON can never produce
events	explicitly dropped — destructured out as events: _authoredEvents and never used (objectui#4433)
defaultView, defaultDate, date, views, editable, onEventCreate, onEventUpdate, onDateChange	no read site anywhere — 0 occurrences outside packages/types

So 9 of the 13 keys (events plus those eight) do nothing when authored on a calendar-view node, and the events the component actually renders are computed from the node's data array plus titleField / startDateField / endDateField / colorField / allDayField — none of which CalendarViewSchema declares. data and className reach it only through BaseSchema.

Why this is worth a card rather than a note

The two halves are individually defensible and jointly misleading:

• The type requires a key the renderer refuses. events has no ?, so const schema: CalendarViewSchema = { type: 'calendar-view' } does not compile — an author must write events — and objectui#4433 then drops it by design, with a pin test. The one key TypeScript forces you to supply is the one key guaranteed to have no effect.
• It is the AI-authoring failure shape. A metadata author (human or model) reading the published type writes defaultView / views / editable / onDateChange and gets silence — no error, no console warning, no red panel. Declared-but-inert is exactly the state ADR-0049's enforce-or-remove framing says must not persist, and this repo has already answered that question twice on this very renderer, in opposite directions: objectui#4454 ENFORCED allowCreate, objectui#4493 REMOVED colorMapping. Both were registry inputs; nobody has yet asked the same question of the @object-ui/types layer above them.
• It keeps regenerating documentation defects. finding(plugin-calendar): README 的 "Schema API / CalendarView" 块把必填的 events 标成选填,且只列了 CalendarViewSchema 13 个键里的 6 个 #5045 is one. content/docs/api/schema-reference.md:1077 publishes onDateChange as a working callback. The README's "Basic Calendar" example still authors events: [...], which renders nothing. Each gets corrected in isolation because the underlying contradiction is not written down anywhere.

What this needs from a maintainer

Which side is authoritative? The answers differ a lot in cost and are not mine to pick:

• A — the renderer is authoritative: retire the inert keys from CalendarViewSchema and give it the keys the renderer actually reads (data, the field-name inputs, currentDate, allowCreate). Honest, and makes the type usable as authoring guidance. Breaking to any consumer type-annotating with it, and events becoming optional/absent is a published type change.
• B — the type is authoritative: implement the nine keys in the renderer. Large, and buys authoring surface nobody has been measured asking for — which the startup-scope principle argues against.
• C — declare the split explicitly: keep both, document that CalendarViewSchema is a component-shaped type and the authored node surface is the registry inputs. Cheapest, changes no bytes, but leaves the trap armed for the next author.

My read is A, scoped by measurement — retire only what a liveness check shows no app authors, rather than a blanket rewrite — because it is the option that makes the declared surface and the enforced surface the same thing, which is the property that stops this recurring. But packages/types/** is a published surface and #4972 / #4984 are already in flight there this round, so this wants sequencing rather than a fast follow.

Notes

• Not a duplicate of objectui#4454 or objectui#4493 (both closed): those are the registry inputs layer on the same renderer. This is the @object-ui/types layer above them, which neither touched.
• Point 3 of finding(plugin-calendar): README 的 "Schema API / CalendarView" 块把必填的 events 标成选填,且只列了 CalendarViewSchema 13 个键里的 6 个 #5045 overlaps objectui#5044's "authorable vs runtime same-name" question in prose only; this card is about read sites, not naming.
• finding(plugin-calendar): README 的 "Schema API / CalendarView" 块把必填的 events 标成选填,且只列了 CalendarViewSchema 13 个键里的 6 个 #5045's fix does not paper over this — its PR adds a "The type is not the renderer" note to the README naming the events drop, precisely so that correcting events to required did not ship as a new wrong instruction. That note is a signpost, not a resolution.

[huangyiirene]

Concentration-round first-touch (triage seat): finding → decision inbox (needs-user-decision; domain:spec seat context stands) — retiring keys from a published type is the manual floor, and this card's own A/B/C is well-formed.

[facets-block]

• 实际业务需求:类型强迫作者写的唯一必填键(events)恰是被设计丢弃的键;9/13 键静默无效——每个读类型写元数据的作者(人或 AI)都会踩,且已在持续产生文档缺陷(finding(plugin-calendar): README 的 "Schema API / CalendarView" 块把必填的 events 标成选填,且只列了 CalendarViewSchema 13 个键里的 6 个 #5045 是第三起)。
• 项目长远合理性:A(渲染器为权威、类型收敛到真实读集)让 declared=enforced 重新成立——正是终结此类反复的性质;B 为无人要的九键实现渲染,反向违反 implementation-first。
• 防 AI 写代码犯错:published type 是 AI 的第一参考;今天它教的是一门渲染器不讲的语言。A 最对症;C 把陷阱留给下一个作者。
• 创业阶段不扩散需求:A 按测量收窄(只退无人授权的键),零新能力;B 最贵。

一句话问题:CalendarViewSchema 以渲染器为权威收敛(退役九个无效键、纳入真实输入),还是实现九键,还是只写文档声明分裂?

推荐 A(按测量收窄),与 filer 建议一致,置信度中高。本分析看不见什么:仓外消费者是否用该 published type 做类型标注(决定 breaking 的真实半径);packages/types 在飞的 #4972/#4984 落地后形状(排序约束,非分歧)。裁决格式:回「A」/「B」/「C」。裁后执行:A ⇒ 晋级派 ui/spec@objectui 席(liveness 测量先行 → 类型收敛 + zod 镜像同步 + schema-reference.md:1077 等文档同批修),排在 #4972/#4984 之后。

---

Generated by Claude Code

[huangyiirene]

Maintainer ruling recorded — A: the renderer is authoritative; CalendarViewSchema converges on the measured read set

Provenance: maintainer, 2026-08-22, live session with the triage seat (「同意所有」, item 12 = A, scoped by measurement).

State: needs-user-decision → pm:queue (spec@objectui seat). Scope: liveness measurement first (retire only what no app authors — the card's own qualifier), then converge the type on what calendar-view actually reads (data, the five field-name inputs, view, currentDate, allowCreate, className), retiring the nine inert keys including the required-but-dropped events; zod mirror moves in the same change; the documentation instances (schema-reference.md:1077's onDateChange, the README example) are repaired in the same PR so the contradiction has no surviving copy. Published-type change ⇒ standard breaking/changeset discipline. Sequencing: after in-flight #4972/#4984 land on packages/types.

---

Generated by Claude Code

[os-sam]

Claim: PM loop round 1
Session: session_01E7snar5mwF7qoXJazqKhys
Branch: claude/issue-5667-calendar-type-converge
Worktree: objectui-issue-5667
Domain: domain:spec (spec @ objectui seat — #5734)
File surface: packages/types/src/complex.ts, packages/types/src/zod/complex.zod.ts, packages/plugin-calendar/** (README example), content/docs/api/schema-reference.md, plus a changeset (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: claude-fable-5
Clause-②: yes
Serial constraints cleared: see below — the ruling's own sequencing gate is satisfied, and both sibling lanes' in-flight surfaces are disjoint.

Tier basis. Clause ② trips: this retires nine declared keys from a published authoring type and its zod mirror, including the required events. That changes contract accept/reject behaviour (the content limb), independent of path. needs:contract-review does not exist in this repo (ensure-pm-labels.sh creates it for objectstack only), so per the maintainer's 2026-08-22 ruling the route here is at-tier dispatch (「直接入队」) — dispatched at CONTRACT_REVIEW_TIER, not compensated after the fact. ⛔ scripts/pm/dispatch-gates.mjs is the wrong tree for this repo and was not used for gate families; its --tier line is a floor only.

Sequencing gate — SATISFIED. The ruling conditioned this card on "after in-flight #4972/#4984 land on packages/types". Both verified closed, and verified on origin/main rather than from the issue state alone:

• [finding] ComponentInput 有三份结构副本(types 两份 + core 一份)外加一个窄孪生 WidgetInput,而 #4580 的裁定说的是「re-export 而不是 restate」—— 副本之间今天已经有一处分歧 #4972 — closed completed 2026-08-22T08:34:27Z
• finding(types,i18n): after #4167 pinned PRESET_RANGES, two unpinned copies/consumers of the date-range vocabulary remain — the defaultRange TS union and the 10-locale label table #4984 — closed completed 2026-08-22T08:30:31Z, PR Bind dashboard dateRange.defaultRange to the spec's DateRangeDefaultRange, and pin the preset label half #5670 MERGED
• On origin/main (9a5d669): f9e4f91 fix(types,i18n): bind dateRange.defaultRange to the spec, and pin the preset label half (#5670) touches packages/types/src/complex.ts

Serial constraints. packages/types is free — no in-flight claim touches it. The domain:ui seat's round-19 in-flight cards are fenced disjoint: #5717 (packages/components/src/renderers/basic/text-input.tsx + apps/console/src/__tests__/component-input-union-specimens.test.ts) and #5660 (apps/console/index.html + src/main.tsx). Neither reaches packages/types, packages/plugin-calendar, or content/docs/api/schema-reference.md. No domain:spec @ objectui card is in flight (this is the lane's first).

Premise re-verified on origin/main 9a5d669 — the card's citations reproduce, with one line-number correction and one measurement caveat:

• packages/types/src/complex.ts:175 — export interface CalendarViewSchema extends BaseSchema (card cites :174; f9e4f91 moved it by one). events: CalendarEvent[] is still required, no ?, and defaultView / view / defaultDate / date / views all still declared.
• packages/types/src/zod/complex.zod.ts:90 — the mirror, as cited.
• calendar-view-renderer.tsx:397-469 — the ten registry inputs reproduce exactly: data, titleField, startDateField, endDateField, allDayField, colorField, view, currentDate, allowCreate, className.
• content/docs/api/schema-reference.md:1077 — | onDateChange|function | Callback when the visible date range changes. | — still published as working, at the exact line cited.

⛔ Measurement caveat carried into the brief. A key-name grep across packages/plugin-calendar/src returns non-zero for events (91), date (82), defaultView (2), defaultDate (1), views (1) — but those are overwhelmingly the CalendarView.tsx React component's own props and its tests, which is a different surface from the authored calendar-view node path. editable / onEventCreate / onEventUpdate / onDateChange are a clean 0 under the same method, with controls healthy (titleField 23, currentDate 45, allowCreate 34, view 126). The component-prop-vs-authored-node distinction is the whole subject of this card, so the liveness measurement the ruling requires must be taken on the authored-node read path, not by grepping key names. Stated because the naive reading inverts the answer.

---

Generated by Claude Code