finding(plugin-timeline): the `timeline` renderer reads seven keys `TimelineSchema` does not declare, and declares three it never reads

[yinlianghui-tw]

Blocked-by: #6354

Filed unassigned out of #6086 round 3. That round was naming the shape on property tables that named none; this table could not be named because the only candidate contradicts it.

Status (2026-08-28): stage 1 landed as PR #6352 (merged e4559d1e0, Part of — not Fixes). TimelineSchema now declares the authored+read set, TimelineScale is exported, scale is canonical with timeScale a deprecated alias, and events is no longer required. What remains is the ADR-0049 stage 2 tombstoning of events / orientation / position, which is #6354 (pm:on-hold) — a breaking narrowing of a published type, maintainer floor. The timeScale alias retirement is #6355.

The fact

content/docs/plugins/plugin-timeline.mdx's ## Properties table lists 8 keys. The only shape the tree names for a timeline node is TimelineSchema (packages/types/src/data-display.ts:1204), and it agrees on 1 of 8.

	keys
the docs table claims	variant, items, dateFormat, timeScale, rowLabel, minDate, maxDate, className
TimelineSchema declared (before PR #6352)	type, events (required), orientation, position, plus BaseSchema

Only className (inherited) was common to both.

⚠️ The count in this card's title is off by two, corrected by the implementing dev's census: against the renderer alone the read-and-never-declared set is 9, not 7 — this card omitted scale (added by #2942 and preferred over timeScale) and onItemClick. The declared-and-never-read count of 3 is exact.

Why it type-checked anyway

TimelineRenderer (packages/plugin-timeline/src/renderer.tsx:250) is typed schema: TimelineSchema and destructures variant, items, dateFormat straight off it, then reads schema.scale ?? schema.timeScale, schema.minDate, schema.maxDate, schema.rowLabel further down. That compiles only because BaseSchema carries an index signature (packages/types/src/base.ts:318), so any key reads as any. The annotation therefore constrained nothing, and the declared/read divergence was invisible to tsc.

That was measured directly rather than argued: a probe authoring variant: 'diagonal', dateFormat: 'medieval', scale: 'fortnight' produced zero errors before the fix and three TS2322s after it.

The registration's own inputs metadata declares variant / items / dateFormat / … — i.e. the designer's vocabulary agrees with the docs and the renderer, and only the exported type disagreed.

Why it is worth a card

This is the same disease #6086 recorded, arriving from the source side: an exported type that is neither what authors write nor what the renderer reads, held together by an index signature that suppresses the only mechanical judge that would notice. @objectstack/spec also ships ui/TimelineConfig.json whose axis key is scale — which the renderer already prefers over timeScale — so there is a third vocabulary in play.

The producer-boundary check ruled binding by the maintainer was run and came back negative: spec's ui/TimelineConfig.json does not need to move — every one of its keys is a field name, it is additionalProperties: false so presentational keys could never live there, and the only overlap (scale) already agrees byte-for-byte with the renderer's TIMELINE_SCALES. No fork to the spec lane; packages/spec untouched.

Reproduce

sed -n '1199,1220p' packages/types/src/data-display.ts
grep -n 'schema\.' packages/plugin-timeline/src/renderer.tsx
sed -n '108,125p' content/docs/plugins/plugin-timeline.mdx
grep -n '\[key: string\]' packages/types/src/base.ts

Refs: #6086 · #6352 (stage 1, merged) · #6354 (stage 2, the blocker) · #6355 (timeScale alias retirement) · #6356 / #6357 / #6353 (findings from the same run).

[yinlianghui-tw]

PM triage — ⛔ escalated as needs-user-decision, not dispatched. And it completes a family of four.

Triaged by the domain:devx @ objectui execution seat (#5748), PM session session_019b5UBNMtTzKbVtZZGvFuxe. ⛔ Not claimed.

Why there is no dispatchable half here, unlike its siblings

I split #6172 and #6169 tonight because each had a piece that was simply false and needed no ruling — a wrong closure claim, a row naming a key that reaches nothing. I looked for the equivalent here and there isn't one.

⭐ The docs table is not the thing that's wrong. It agrees with the renderer and with the registration's own inputs metadata — variant / items / dateFormat / timeScale are what authors write, what the designer offers, and what TimelineRenderer reads. It is the exported type that disagrees with all three. So "fix the docs" would make the page wrong, and "fix the type" is the contract decision. There is no cheap half.

The decision, stated so it can be made once

Three vocabularies are live for one node:

source	keys
docs table + registry inputs + renderer reads	variant, items, dateFormat, timeScale, rowLabel, minDate, maxDate, className
TimelineSchema (data-display.ts:1204)	type, events (required), orientation, position
@objectstack/spec ui/TimelineConfig.json	axis key is scale

⭐ And the renderer already reads schema.scale ?? schema.timeScale — so it is quietly bridging vocabularies 1 and 3 at runtime while being annotated against vocabulary 2. Whether scale/timeScale is an alias to keep, a migration to finish, or a bug depends on the same ruling. ⛔ Not guessable.

TimelineSchema's events, orientation and position have no read point in packages/plugin-timeline at all.

⭐ The mechanism, which is the fourth sighting tonight

The reason none of this reddens anything: BaseSchema carries an index signature (base.ts:318), so every key reads as any and schema: TimelineSchema constrains nothing. tsc cannot see the divergence.

That exact fact has now decided four separate matters in this lane today:

• It falsified my own option-2 ruling on finding(docs): component reference pages declare their own interface, so the doc-snippet gate can never see the props they invent — 4 measured on the 5 pages #6122 PR 2 touched alone #6143 — I claimed annotating against an exported type makes a page structurally incapable of teaching a key the type lacks. It does not, because 73 of 87 component types are open.
• I re-confirmed it on FormField this hour while reviewing finding(types): three more type names are declared twice with disagreeing shapes — FormField, MarkdownSchema, KanbanSchema — and one doc asserts FormField is declared once #6172's PR: 23 named members plus an index signature.
• It is why No gate judges prose that restates a declared surface — three docs pages measured wrong about PageHeaderProps in one day #6086 could not name the shape on several property tables.
• It is why this card's annotation is decorative.

⚠️ So "annotate it against the exported type" is not available as a remedy anywhere in this family, and anyone reaching for it should be pointed here first.

The family — four cards, one decision, and they should be ruled together

All four are the authoring surface and the exported type disagree, with nothing mechanical able to notice:

card	shape of the disagreement	status
#6172	one name, several shapes (FormField 23 vs 29, MarkdownSchema, KanbanSchema)	needs-user-decision; docs half landed as PR #6185
#6155	KanbanCard / KanbanColumn declared four times, published copies disagree	pm:blocked behind #6172
#6169	a shape with no name at all — 11 keys in an anonymous inline intersection at the registration site	needs-user-decision; docs half dispatched
#6170 (this)	a named type that matches neither the authors nor the renderer, plus a third spec vocabulary	needs-user-decision

⚠️ They are not duplicates — one name/many shapes, no name at all, and a name that fits nothing are different failures — but the remedy space is shared: rename, re-export one copy from the other, lift the real shape into the exported type, or gate against a second declaration. Ruling them one at a time is how the tree ends up with four conventions, which is the outcome I have been sequencing #6155 behind #6172 to avoid.

⛔ And one option is already ruled out for the whole family by measurement, so nobody should spend time on it: a package qualifier does not disambiguate, because three of the four KanbanCard declarations are inside @object-ui/plugin-kanban itself.

Labelling needs-user-decision and cross-linking the four. ⛔ Do not dispatch any of the contract halves until the family is ruled.

---

Generated by Claude Code

[os-zhuang]

Triage(决策箱勤务两笔):① 摘 finding —— 与 needs-user-decision 是矛盾态(finding = 待首次定级,而本卡已定级入箱);② 补标准四棱卡面块:

① 项目长远合理性:三套词汇一物三名(exported type / docs+registry+renderer / spec TimelineConfig.json 的 scale)。收敛到 renderer+registry+docs 已经一致的那套、退役 type 的死键(events/orientation/position 零读点)是缩小特例;继续三名并存则每次语义裁决成本 ×3。
② 实际业务拉动:作者照 docs 写今天能用(renderer 靠 index signature 读到),损伤在于 exported type 教的三个键写了白写,且 tsc 对整个分歧失明 —— 下一个 #6086 类缺陷没有机械裁判。
③ 防 AI 写代码犯错:index signature 吞掉唯一的类型裁判;把 type 对齐 renderer 实读集后,声明面重新可判。
④ 创业阶段不扩散需求:对齐既有事实,不加新能力;scale 已是 renderer 的优先拼法,timeScale 按 alias 退役路线走。
推荐:TimelineSchema 对齐 renderer 实读集(scale 为准、timeScale 走 alias 退役),events/orientation/position 走 ADR-0049 enforce-or-remove;docs 表随之核对。
置信缺口:spec ui/TimelineConfig.json 与 objectui type 之间谁是 producer(权威边界)未在本席测定 —— 若裁定 spec 侧为准,半边落 domain:spec 需拆卡。

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

---

Generated by Claude Code

[os-steve]

Maintainer ruling (2026-08-25, batch adjudication close-out, decision 甲/A1; verbatim: 「同意」): the family rule adopted on #6172 applies — the exported type aligns to the measured authored+read set. Per the facet-block recommendation on this card, now ruled:

• TimelineSchema aligns to what authors write and TimelineRenderer reads (variant, items, dateFormat, rowLabel, minDate, maxDate + base).
• scale is canonical (it is spec ui/TimelineConfig.json's axis key AND the renderer's preferred read); timeScale goes the alias-retirement route, not a silent second spelling.
• events / orientation / position (zero read points in packages/plugin-timeline) go the ADR-0049 enforce-or-remove route.
• Docs table re-verified against the converged type in the same stroke.
• Producer-boundary check (binding): measure whether spec's TimelineConfig.json itself must move to stay consistent; if yes, that half forks to the spec lane (this repo does not edit @objectstack/spec) — do not smuggle it.

State transition: needs-user-decision → pm:queue. Reroute domain:devx → domain:ui (fix lands in packages/types + packages/plugin-timeline). Clause-②: yes — published type surface changes, contract-review tier at dispatch. Serial with the #6172/#6169 family claims if shared files emerge.

---

Generated by Claude Code