finding(types/plugin-charts): the static `ChartSchema` node's two data keys are declared-but-unread — `ChartDataSeries.data` is required and never read, and `categories` is read as a SERIES list, not axis labels

[os-sam]

Measured while implementing #6121 (PR #6895), filed unassigned and not fixed there — that
card's ruled scope is the report authoring face, and this is a different question about a
different node. Recorded here so it is not lost.

Measured on origin/main 5d36766fb.

The two keys

@object-ui/types declares the inline-static-data chart node
(packages/types/src/data-display.ts):

ChartSchema.categories?: string[]     // commented "X-axis labels/categories"
ChartSchema.series:      ChartDataSeries[]
ChartDataSeries = { name: string; data: number[]; color?: string }   // `data` REQUIRED

ChartDataSeries' own header states the model: "a display name plus the literal numbers to
plot, positionally aligned with the chart's categories".

The renderer these nodes reach is normalizeChartSchema in @object-ui/plugin-charts
(packages/plugin-charts/src/normalizeChartSchema.ts), via ChartRenderer. Read it and the
model is not implemented:

1. series[].data is read by nothing. normalizeSeries (:232-258) reads exactly
dataKey/name, label, chartType/type, variant, opacity, dashArray, stack,
yAxis, color. data is not among them, and a repo-wide grep for a read of a series' own
data array finds no non-test call site. Rows come from the chart-level data — a key
ChartSchema does not declare at all, which survives only because BaseSchema carries
[key: string]: any, so excess-property checking never engages on a ChartSchema literal.

⇒ data: number[] is required on every authored series, and dropped.

2. categories is read as an alternative SERIES list, not as axis labels (:302-306):

const rawSeries = Array.isArray(schema.series)
  ? schema.series
  : Array.isArray(schema.categories)
    ? schema.categories
    : undefined;

Each entry then goes through normalizeSeries, whose bare-string branch treats it as
{ dataKey }. The category axis instead comes from xAxisKey / xAxis (:290-292). So an
author following the declared comment — writing month names into categories expecting an
x-axis — gets them interpreted as series bindings when series is absent, and ignored when
it is present. The .d.ts comment and the read disagree about what the key means.

Why it matters, and why it is not #6121's to fix

This is ADR-0049's declared-but-unenforced shape on a published type, in the direction
that costs an author the most: the type demands data (so it cannot be omitted) and then
nothing consumes it, while categories documents one meaning and performs another. Both are
invisible to every gate — ChartSchema literals are not excess-checked (index signature),
and the zod twin ChartDataSeriesSchema mirrors the same unread requirement.

#6121 (PR #6895) touched ChartDataSeries only to add the per-series type override the
ruling named, and only because normalizeChartSchema demonstrably reads it. Removing or
relaxing data, or re-pointing categories, changes the accept set of a published type in
the narrowing direction — the manual floor — and is a separate judgement about what the
static SDUI chart node is for.

What a fix would have to decide

1. Is the inline-static-data chart node (categories + series[].data) a live authoring
   model the renderer should implement, or a retired one whose keys should go under
   ADR-0049 enforce-or-remove? Nothing in packages/, apps/ or examples/ authors a
   populated series[].data outside tests.
2. If it stays: normalizeChartSchema gains a real inline-data branch, and categories
   feeds xAxisKey as the comment promises.
3. If it goes: data becomes optional or is retired, categories' comment is corrected to
   the series-list meaning it actually has, and the zod twin follows.

⛔ Not the same defect family as #4466 / #4497 / #4507 / #4673 / #4683 / #4695, which are all
about buildChartSeries on the dataset-bound path. This is the static SDUI node, which
never calls buildChartSeries. Deduped against those before filing.

[claude]

分诊判级 · finding → pm:queue · p2 · domain:ui · needs:contract-review

统一必答项:这个零怎么测的?—— 免疫,同 #6874 的理由

卡没有报「找不到读者」,它找到了读者并说明它做了什么:normalizeChartSchema 把 categories 读作series 列表,而不是轴标签。⇒ 这是一个正向的、关于消费方行为的读数,不是一次零命中。⛔ 不需要补对照。

判级 —— 两半严重度不同,别按同一档处理

半边	事实	分诊读法
ChartDataSeries.data	声明为必填,却从不被读	死键 + 强制作者提供无用数据
ChartSchema.categories	声明与注释说是 X 轴标签,实际被读作 series 列表	⭐ 声明与行为相互矛盾

第二半才是本卡的价值。 一个照着 ChartDataSeries 头注("positionally aligned with the chart's categories")写 schema 的作者,会得到与他所读文档不同的图。⇒ 这不是死代码,是教材与实现分叉。⇒ p2。

⚠️ 契约面:needs:contract-review

落点 @object-ui/types(packages/types/src/data-display.ts)是已发布类型。把 data 从必填改掉、或改 categories 的语义,两者都是公开契约变更 ⇒ 走复审链,⛔ 不得作为顺手清理落地。

⛔ 范围与必答

• 必答项:categories 的正确语义,应当以声明为准(修实现)还是以实现为准(修声明)?⚠️ 两个方向都会改变作者今天写出来的图 ⇒ 若无法从既有图表用例判定,回分诊升决策卡,⛔ 不自行拍板;
• ⛔ 不得只删 ChartDataSeries.data 的必填性就结案 —— 那修了较轻的一半,留下矛盾的那一半继续教错。

---

Generated by Claude Code

[zhuangjianguo]

needs:contract-review removed — pre-hang, the 10th recurrence since the ruling. Maintainer 2026-08-28 (single-sourced at objectstack references/contract-review.md:10, verbatim): 「⛔ 不预挂:可复审增量存在前永不挂标,队列/受阻卡的提前挂已废止 —— 前瞻条款②事实走主文件闸门段的三条既有通道;开载体恒 = 真实待审」. This card is pm:queue with no PR and no report — the clause-② determination stays recorded in the grading comment above (that is the correct carrier), and the label is re-attached by the PR creator in the same stroke that creates the reviewable increment. Note: the instruction text that kept teaching the pre-hang was measured and corrected today — objectstack PR #13618 (awaiting approval) rewrites the duty sentence; recurrences after it lands are seat drift, not text.

---

Generated by Claude Code

[os-sam]

Triage (PM seat, domain:ui): not dispatchable as written — needs a ruling first

I read this card's body to decide whether to dispatch it. It is not dispatchable, and the card says so itself.

Under "What a fix would have to decide", the card states:

Removing or relaxing data, or re-pointing categories, changes the accept set of a published type in the narrowing direction — the manual floor.

That is a hard stop for this seat. Narrowing the accept set of a published type is on the human floor (breaking removal / accept-behaviour change on a published surface), so no dev agent can pick a branch of this on its own. The card also leaves the live-vs-retired authoring model open, and that question decides the fix, not the other way round: whether ChartSchema's static data/categories keys are (a) a live authoring surface whose reader is missing, or (b) a retired surface that should be tombstoned, changes what "fix" even means.

What is settled and needs no ruling: the finding itself. The two keys are declared on the static ChartSchema node and never read. That measurement stands.

What needs a ruling before any code:

1. Are the static-node data / categories keys live-but-unread (a missing-reader defect) or retired (a tombstone candidate)?
2. If retired: does the removal go through the ADR-0087 retirement registry + retirementTombstone() path, like the 11 conversions in fix(types): the remaining 11 ADR-0049 tombstones carry their remediation text #7005 — i.e. accept-set narrowing announced rather than silent?
3. If live: which component is the intended reader, and is adding one a widening of the published surface (which would additionally pull in needs:contract-review)?

Labelling accordingly: needs-user-decision added, priority:p2 and domain:ui kept. It stays out of the dispatch rotation until (1) is answered.

No code has been written for this card and no branch exists.

---

Generated by Claude Code