finding: 两个结构不兼容的 `CalendarEvent` 同名并存(`@object-ui/types` 授权型 vs `@object-ui/plugin-calendar` 运行时型),已造成一处文档示例不可编译

[yinlianghui]

发现于 #5010 的实施(plugin-calendar README)。Filed unassigned, not claiming.

现象

仓里有两个都叫 CalendarEvent 的公开导出类型,结构不兼容,分属两个包:

	@object-ui/types(packages/types/src/complex.ts:136)	@object-ui/plugin-calendar(packages/plugin-calendar/src/CalendarView.tsx:96)
语义	授权型(JSON 元数据里写的事件)	运行时型(CalendarViewProps['events'],React 组件收的事件)
id	string	string | number
start	string | Date	Date
end	string | Date(必填)	Date(可选)
description	有	无

CalendarViewSchema.events 要的是前者;CalendarView 组件收的是后者。两者互不可赋值(id 与 start 两处都冲突)。

已造成的实际损害

packages/plugin-calendar/README.md 的 "TypeScript Support" 一节把两者混用了,而且这个错误在 #5010 修掉导入路径之后依然存在 —— 因为它不是路径错、也不是虚构名,两个名字都是真导出。实测(#5010 实施中的编译探针,tsc 直接读源):

a-pathfix-only.ts(10,3): error TS2322: Type 'string' is not assignable to type 'Date'.
a-pathfix-only.ts(11,3): error TS2322: Type 'string' is not assignable to type 'Date'.
a-pathfix-only.ts(16,12): error TS2322: Type '…/plugin-calendar/src/CalendarView").CalendarEvent'
 is not assignable to type '…/types/src/complex").CalendarEvent'.
 Types of property 'id' are incompatible.
 Type 'string | number' is not assignable to type 'string'.

#5010 的 PR 已把该 README 的示例改成两个授权型都从 @object-ui/types 取,并加了一段并列说明两者区别 —— 但那只治了这一处文档,同名本身没动(动它是契约变更,不在 #5010 卡面内)。

为什么单独立这一单

这正是「让 AI 写的元数据难以出错」那条轴上的典型坑:两个名字一样、语义一层是授权一层是运行时、IDE 自动导入会按字母序或最近使用随机挑一个,挑错了报的还是一个绕远的 TS2322(而不是「你导错包了」)。一个 AI 生成 calendar 元数据的场景里,这个坑会被反复踩。README 那处漂移能活到今天,一部分原因就是它「看起来对」。

顺带一记:plugin-calendar 已经有过一次同源的同名撞车并留了注释 —— src/index.tsx:23-30 的 ObjectCalendarProps 被 @objectstack/spec/ui 从 17.0.0 起占用(objectui#4650),当时的处理是改名 + 留 deprecated alias(ObjectCalendarComponentProps)。CalendarEvent 是同一类问题的下一个实例,可参照那次的处置形。

可能的方向(未选定,交维护者裁)

• A. 运行时型改名(如 CalendarEventInput / CalendarViewEvent),沿用 Resolve the spec-named symbol collisions with 17.0.0 GA exports (check:spec-symbols): SECRET_MASK + ObjectCalendarProps/ObjectFormProps/ObjectGridProps/ObjectKanbanProps + one more #4650 的 rename + deprecated alias 形。授权型保住 CalendarEvent 这个「正名」,因为它是 spec 侧的契约名。
• B. 运行时型不再导出,只留 CalendarViewProps 让消费者用 CalendarViewProps['events'][number] 取。收窄导出面,但对现有 importer 是破坏性的。
• C. 什么都不改,只靠文档(plugin-calendar README 教的 calendarComponents 手动注册 API 不存在 —— 照抄即抛 #5010 已做的那段并列说明)。最便宜,但把「别踩」的责任留给每个读者,IDE 自动导入照样踩 —— 按 AGENTS.md #0.1 的精神,这是消费侧宽容,不是结构性预防。

倾向 A:它在「长期架构」和「结构上防止出错」两条轴上都成立 —— 授权型保留契约正名,运行时型有了自解释的名字,且 deprecated alias 让现有 importer 继续编译,迁移成本可控;仓里已有 #4650 的先例可循。

分级

交 PM 分诊。挂 finding:今天没有用户运行时因此出错(#5010 已把唯一已知的受害文档修好),这一单是结构性隐患 + 契约命名决策,需要维护者裁方向再动手。

[os-support-ai]

Triage (triage seat, session session_01HXzdkKx5WjwwCTT3c7U5kB): finding → needs-user-decision. Two structurally incompatible public exports share the name CalendarEvent (authoring type in @object-ui/types vs runtime type in @object-ui/plugin-calendar); resolving it renames or removes a published export — public-surface change, maintainer floor.

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

• platform long-term coherence: one name for one contract; the authoring type keeps the canonical CalendarEvent name (it is the spec-side contract), the runtime type gets a self-describing name — shrinks a special case rather than growing one. Precedent in-repo: Resolve the spec-named symbol collisions with 17.0.0 GA exports (check:spec-symbols): SECRET_MASK + ObjectCalendarProps/ObjectFormProps/ObjectGridProps/ObjectKanbanProps + one more #4650 (ObjectCalendarProps rename + deprecated alias).
• measured business pull: one documented victim already measured (README example uncompilable until plugin-calendar README 教的 calendarComponents 手动注册 API 不存在 —— 照抄即抛 #5010's workaround); IDE auto-import picks between the two names essentially at random, so every future calendar consumer is exposed.
• AI-agent error-resistance: same-name/different-shape is the exact trap an AI authoring calendar metadata falls into repeatedly, and the failure reads as a remote TS2322, not "wrong import" — a rename makes the wrong choice unrepresentable at the name level.
• startup scope discipline: option A is a small, bounded rename with a deprecated alias (no consumer breaks); option B (stop exporting the runtime type) is cheaper to maintain but breaking for existing importers; option C (docs only) leaves the trap armed.

Recommendation: A — rename the runtime type (e.g. CalendarViewEvent) with a deprecated alias per the #4650 precedent; authoring type keeps CalendarEvent. Options: A (rename runtime + alias) / B (unexport runtime type) / C (docs only).
Confidence gap: this analysis cannot see external importers of @object-ui/plugin-calendar's CalendarEvent (npm-published surface) — A is non-breaking for them, but B's true cost is unmeasurable from the repo.

---

Generated by Claude Code

[os-elon]

Maintainer ruling — recorded by the maintainer-directed PM session (session_01KspKtTajJmy3J37UhH8tcH, 2026-08-19). The 27-card objectui decision-inbox review (per-card four-axis analysis) was presented to the maintainer in that session's chat; the maintainer's verbatim reply: 「全部接受」. Adopted ruling, restated in full:

Ruling: Option A — rename the runtime type, per the #4650 precedent

• The authoring type (packages/types/src/complex.ts) keeps the canonical name CalendarEvent; the plugin-calendar runtime type gets a self-describing name (e.g. CalendarViewEvent) with a deprecated alias left behind, exactly as Resolve the spec-named symbol collisions with 17.0.0 GA exports (check:spec-symbols): SECRET_MASK + ObjectCalendarProps/ObjectFormProps/ObjectGridProps/ObjectKanbanProps + one more #4650 did for ObjectCalendarProps — non-breaking for existing importers, and IDE auto-import stops offering two structurally incompatible shapes under one name.
• B (stop exporting the runtime type) is rejected as breaking with unmeasurable external cost; C (docs note only) is rejected — it leaves the trap armed for every future consumer.

State: needs-user-decision → pm:queue.

---

Generated by Claude Code