finding(plugin-charts): `normalizeSeries` reads `chartType` FIRST on the authored path while the validator now refuses it by name — the two faces disagree

[claude]

Carved out of the contract review of PR #7737 (card objectui#7694) by the domain:ui PM seat. Filed so the finding survives that PR's Fixes #7694 close — this seat has a measured leak where review findings die as comments on a closed card.

The split, as the reviewer measured it

PR #7737 made chartType a named refusal on the authoring face (ChartDataSeriesSchema), deliberately without touching the reader — that fence was the card's and it was correct for that PR. The reader is byte-identical across the whole PR: git diff a00db9ef9..de8fda691 -- packages/plugin-charts is 0 lines, normalizeChartSchema.ts blob 05a66dfb… at both ends.

So today:

• normalizeSeries reads str(raw.chartType) ?? str(raw.type) — chartType first.
• ChartRenderer.tsx:65 declares chartType? on the internal dataKey shape. That is the legitimate carrier and ⛔ it is not the defect.
• ⭐ But the same function also normalizes authored spec-shape series. So an author who skips validation still gets chartType honoured at runtime, while the validator refuses it by name.

That is a pre-existing AGENTS.md #0.1 fallback: a tolerant renderer-side read fossilising a second de-facto contract. It was fenced out of #7737, not resolved.

The disposition, from the review

The dev raised this as its open question 1 with three options — A (leave the reader as is), B (docblock the limb as internal-only / file a card), C (retire the limb at the reader). The reviewer's disposition was B, and its reasoning is worth keeping: A leaves the two faces disagreeing with nothing written down, and C changes what internal producers render, which is a reader decision outside that card.

Suggested direction (⛔ not a ruling)

Make normalizeSeries read chartType only on the internal-shape path, so the authored path and the validator agree — or, if the two paths cannot be told apart at that point, docblock the limb as internal-only and pin the split so it cannot drift silently.

⛔ Do not simply delete the limb: it is lit. The ablation was run twice, most recently by the reviewer on 304 files / 5817 tests: deleting str(raw.chartType) ?? leaves 5817 passed, but deleting the sibling ?? str(raw.type) goes 2 failed (normalizeChartSchema.test.ts "carries stack / yAxis / color on a series"; ChartRenderer.specSeries.test.tsx "honours a spec series[].type override end to end"). The first limb being green on ablation is what makes it removable-looking and exactly why the decision needs to be made deliberately rather than by deletion.

Refs

objectui#7694 (the authoring-face refusal, PR #7737) · objectui#7546 (the parent measurement) · sibling cards from the same census: #7681, #7682, #7690, #7698 · AGENTS.md #0.1.

---

Generated by Claude Code

[claude]

Claim: PM loop, round 6 — all-opus lane (Clause-② no)
Session: session_01KbJQ1y1J12nZxYzFWhP8Q3
Branch: claude/issue-7744-charttype-internal-only
Worktree: objectui-issue-7744
Domain: domain:ui
File surface: packages/plugin-charts/src/normalizeChartSchema.ts（仅文档注释 / 内部形状标注）· packages/plugin-charts/src/__tests__/ 下钉住这道分裂的新用例 · 本卡自己的 .changeset/*.md. ⛔ Stop on breach: 任何让 normalizeSeries 运行期读出不同值的改动、任何对 ChartRenderer.tsx 的改动、任何 packages/types/ 的改动。Explain in the report.
Container & model: S, mode:subagent, model: opus
Clause-②: no —— 按下面的裁定走 B（文档 + pin），不改运行期行为。⚠️ Void condition: 任何删除或改写 str(raw.chartType) ?? 这条肢、或以任何方式改变 normalizeSeries 对同一输入的输出 —— 那是 C，会变成 Clause-② yes，停下上报。
Serial constraints cleared: 无在飞 PR 触碰 packages/plugin-charts/。PR #7737 已合并（本卡从它的契约复审析出）。在飞的 #7802（plugin-view）· #7798（react/core 文档块）· #7795（scripts）都不相交。

---

PM 裁定：走 B，⛔ 不走 A、⛔ 不走 C

复审席当时的处置就是 B，本席采纳并把它变成命令：

• ⛔ A（原样不动） —— 两个面继续互相矛盾，而且什么都没写下来。这正是本卡存在的原因。
• ⛔ C（在 reader 处退役这条肢） —— 它改变内部生产者的渲染结果，是 reader 侧的决策，超出本卡范围，且会把本卡变成 Clause-② yes。
• ✅ B（把这条肢标注为 internal-only，并把这道分裂钉住） —— 不改行为、可核、且让下一个人不必重新发现。

事实（复审席实测，⛔ 不必重测）

• normalizeSeries 读 str(raw.chartType) ?? str(raw.type) —— chartType 在先。
• ChartRenderer.tsx:65 在内部 dataKey 形状上声明 chartType? —— 那是合法载体，⛔ 不是缺陷。
• ⭐ 但同一个函数也在归一化「作者写的 spec 形状」的 series。 ⇒ 跳过校验的作者在运行期仍能让 chartType 生效，而校验器按名字拒绝它。
• PR feat(types): refuse chartType on a chart series by name, pointing at type #7737 全程没有碰过 reader：git diff a00db9ef9..de8fda691 -- packages/plugin-charts 0 行，normalizeChartSchema.ts blob 05a66dfb… 两端一致。

⇒ 这是一处先在的 AGENTS.md #0.1 形状：宽容的 renderer 侧读取把第二套事实契约化石化。#7737 把它围栏出去了，没有解决。

⛔ 最要紧的一条：不要删这条肢，它是活的

消融跑过两次，最近一次由复审席在 304 files / 5817 tests 上跑：

消融	结果
删掉 str(raw.chartType) ??	5817 passed —— 全绿
删掉兄弟肢 ?? str(raw.type)	2 failed（normalizeChartSchema.test.ts 「carries stack / yAxis / color on a series」；ChartRenderer.specSeries.test.tsx 「honours a spec series[].type override end to end」）

⭐ 第一条肢在消融下全绿，正是它"看起来可删"的原因，也正是必须慎重而不是一删了之的原因。 全绿只说明没有测试钉住它，不说明没有生产者依赖它。

交付物

1. 在 normalizeChartSchema.ts 把这条肢标注清楚：chartType 是内部 dataKey 形状的载体，不是作者面的键；作者面由 ChartDataSeriesSchema 按名字拒绝它（PR feat(types): refuse chartType on a chart series by name, pointing at type #7737）。⭐ 措辞里点名那个拒绝，让读者能一跳到位，⛔ 不要复述它的规则（委托，不要摘要 —— 见 objectui#7765 的落地记录）。
2. 一条钉住这道分裂的用例，使它不能静默漂移。⚠️ 形状由你判断，但必须满足：它在今天的行为下绿；若有人改变了作者面与 reader 的一致关系，它红并指名。⛔ 不许写一条宽松到两种行为都过的断言。
3. ⚠️ 若你判断「这两条路径在那一点上根本分不开」，那就只做第 1 项并把这个判断写进报告（卡面已预留这条退路）—— ⛔ 但要给出为什么分不开的读数，不能只是说分不开。

验收

• ⭐ 证明你没有改变行为：给出一个同输入同输出的读数 —— 例如对一组代表性输入，改动前后 normalizeSeries 的输出逐字段相同；或更强的：packages/plugin-charts/ 全套在改动前后用例数与通过数完全一致。
• 新 pin 的点亮控制：故意让作者面与 reader 的一致关系失效（例如临时把拒绝改成接受，或临时改动 reader 的读取顺序），确认新用例变红并指名；然后在 trap … EXIT INT TERM 下用 git checkout HEAD -- <绝对路径> 还原，以 blob hash 相等 + 空 git diff HEAD 证明 —— ⛔ 证明靠状态，不靠 trap 是否触发；变异前先用 hash 确认落盘（空 hash 读作失败）。
• pnpm --filter @object-ui/plugin-charts test 与 type-check（走 turbo），报出文件数/用例数与 exit code。

变更集

改动落在发版包 src/ 下 ⇒ 大概率需要。⛔ 不要凭规则推断：跑 node scripts/check-changeset-presence.mjs，判词原样抄进报告；欠就写空 frontmatter。⛔ 永不写 major。

⚠️ 五个仪器陷阱

① 裸 tsc --noEmit 不是本仓的门（turbo type-check dependsOn ^build，到不了非包目录；构建前的 TS2882 是未满足的前提、不是结果）② 本容器没有「未认证的探测」，匿名样子的 POST 是真写入，探通道只用 GET ③ scripts/__tests__/check-doc-links.test.ts 共享盒上 15s 超时是已知 flake ④ ⛔ new URL(rel, import.meta.url) 被 Vite 重写 ⑤ ⛔ 不用两点式 origin/main..HEAD 报文件数（并发落地会虚报，实测 4 vs 真实 2）。

契约复审

Clause-② 是 no（走 B）⇒ 不排在契约复审后面。⚠️ 走成 C 就是 yes —— 停下上报，不要自行改档。

---

Generated by Claude Code

[claude]

os-dev-report

{
  "issue": 7744,
  "status": "done",
  "branch": "claude/issue-7744-charttype-internal-only",
  "pr": "https://github.com/objectstack-ai/objectui/pull/7815",
  "premise_still_valid": true,
  "summary": "Took B per the PM ruling: annotated the limb as internal-only and pinned the split; no behaviour change. Premise re-confirmed rather than assumed: the pre-edit blob of normalizeChartSchema.ts is 05a66dfb5b9c9a322761e1e1a694ac7a57af1e54, the exact blob the card names at both ends of PR #7737. The normalizeSeries docblock now names which face owns which spelling and DELEGATES the refusal's rule to ChartDataSeriesSchema in packages/types/src/zod/data-display.zod.ts (objectui#7694 / PR #7737) plus its existing pin chart-series-chart-type-alias-refusal-7694.test.ts, rather than restating it; a two-line comment sits beside the limb. The new case packages/plugin-charts/src/__tests__/chartType-internal-only-7744.test.ts pins the RELATIONSHIP that neither existing file held: the key the validator refuses is the key the reader prefers. It reads ONE fixture writing both spellings with DIFFERENT values ({ name: 'margin', type: 'area', chartType: 'line' }), which is what makes a REORDER observable and not merely a deletion, and it carries a compile-time half over ChartRenderer's series? union arms (chartType is declared on the dataKey arm and on no other). Changeset is the empty-frontmatter form. ChartRenderer.tsx and packages/types/ are untouched; Clause-2 stays no.",
  "tests": "ALL COMMANDS FOREGROUND, exit codes captured after redirect (never through a pipe). [1] UNION, run AFTER the final commit, at head 1120ee392, uncached: `pnpm turbo run test type-check --filter=@object-ui/plugin-charts --concurrency=2 --force` exit=0 -- 'Test Files 46 passed (46)', 'Tests 416 passed (416)', 'Tasks: 11 successful, 11 total'. [2] BASELINE, same command before any edit: exit=0, 'Test Files 45 passed (45)', 'Tests 410 passed (410)'. Delta is exactly this PR's one new file and its six cases; no pre-existing test changed verdict. [3] SAME-INPUT/SAME-OUTPUT PROOF (no behaviour change): a probe imports the module and runs 336 input cases through normalizeChartSchema (the only public entry into normalizeSeries) plus comboBaseFamily/effectiveChartFamily/formatterFor/ticksFor/domainFor and the exported sets; 288 of the cases are the chartType/type limb exhaustively (present/absent x 12 values per spelling, incl. disagreeing pairs, empty strings, wrong-typed values, and the same matrix again via `categories`). before-blob 05a66dfb -> sha256 1681dfd534b7f01f798bc9fef45368abba0051bc136c67e3b7cd0c410c7fd896; after-blob 0a2b702c -> sha256 1681dfd534b7f01f798bc9fef45368abba0051bc136c67e3b7cd0c410c7fd896; byte-identical. The probe was itself shown SENSITIVE (otherwise 'identical' is vacuous): reordering the limb in a SCRATCH COPY (repo never touched) moves 49 of the 336 cases. [4] LIT CONTROLS, both run AFTER committing the implementation so HEAD is the correct restore reference. Each: mutation confirmed ON DISK by anchored text counts (old text 0 hits, new text 1 hit) AND by a changed blob hash read before anything else -- an empty hash would read as FAILURE; both ran under `trap restore EXIT INT TERM` with ABSOLUTE paths; restoration proved by blob-hash equality PLUS an empty `git diff HEAD`, i.e. by state, not by whether the trap fired. (a) READER reordered to str(raw.type) ?? str(raw.chartType): vitest exit=1, 'Tests 2 failed | 4 passed (6)'; the two reds are 'the READER honours chartType, and takes it OVER the declared type' and 'THE SPLIT'; message verbatim: \"objectui#7744: `normalizeSeries` no longer resolves the per-series family from `chartType` first. `\\\"area\\\"` here means the limb was REORDERED; `undefined` means it was DELETED...\" expected 'area' to be 'line'. HEAD 0a2b702c / mutated 1f53c339 / post 0a2b702c, git diff HEAD empty. (b) AUTHORING FACE made to accept (ChartDataSeriesSchema.chartType replaced by an accepting enum, the refusal parked on an unused key): vitest exit=1, 'Tests 2 failed | 4 passed (6)'; the two reds are 'the AUTHORING face refuses chartType...' and 'THE SPLIT'. HEAD 1cbacf06 / mutated ae8318b0 / post 1cbacf06, git diff HEAD empty. NO REBUILD WAS NEEDED for either leg and this is measured, not assumed: the root vitest.config.mts aliases '@object-ui/types/zod' to packages/types/src/zod/index.zod.ts (SOURCE, line 411), and the authoring-face mutation DID go red, which is the empirical proof the test read the mutated source rather than a stale dist. So the relationship case is red in BOTH directions while the side-specific cases name WHICH face moved. After both controls: `git status --short` empty, `git diff HEAD` empty, and the pin re-runs '6 passed', exit=0. [5] COMPILE-TIME HALF IS ACTUALLY COMPILED (not a phantom): `tsc -p tsconfig.test.json --noEmit --listFiles | grep -c chartType-internal-only-7744` = 1 (0 would read as NOT MEASURED). [6] DERIVED GATE FAMILY for the changed paths (.changeset/*.md, packages/plugin-charts/src/**), each exit=0, quoting each gate's own verdict line: check-control-bytes 'OK (scanned 6359 tracked text file(s))'; check-changeset-no-major 'No changeset declares a major bump.'; check-changeset-overwrite 'No pre-existing changeset was modified or deleted.'; check-changeset-fixed 'All workspace packages are in the changeset fixed group.'; check-lint-coverage 'lint coverage: 46/46 packages linted, 0 with outstanding errors'; check-type-check-coverage 'type-check coverage: 45/46 via type-check, 0 errors outstanding'; check-unreferenced-sources exit=0. Plus a self-scan for control bytes beyond the gate: `grep -naP '[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f]'` over both touched files, no hits. NOTE: objectui has no scripts/pm/dispatch-gates.mjs (that script lives only in objectstack and answers only about its own tree), so this family was derived by hand from .github/workflows/*.yml and package.json. [7] LINT, with the narrowing DECLARED: `pnpm --filter @object-ui/plugin-charts lint` exit=0, 0 errors / 334 pre-existing warnings; the new test file and the edited file contribute 0 errors and 0 new warnings. Repo-wide `pnpm lint` was NOT run locally. Three pieces of evidence that this narrowing excludes nothing: (i) the population is read from eslint's own config, not guessed; (ii) the count is read from `--format json` -- 57 files resolved in this package; (iii) this repo configures NO type-aware linting (no projectService / parserOptions.project in eslint.config.*), so a comment-only edit cannot move any untouched file's verdict. CI runs the full farm regardless. [8] CHANGESET GATE, verdict verbatim, exit=0: 'Compared the working tree with a617bb8d3 (merge-base with origin/main): 3 file(s) changed, 2 of them published source of a package the release covers, 0 of them a manifest whose published contract moved, 0 under a package changesets ignores, 1 changeset(s) added.' / '2 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s): .changeset/7744-chart-type-internal-only.md.' / 'Every one of them has an EMPTY frontmatter -- declared as releasing nothing, which is the explicit exemption and a complete answer to this gate.' (The first run, before the changeset existed, was exit=1 and named @object-ui/plugin-charts; the empty-frontmatter form is the gate's own named pass, not a workaround. Never major. No skip-changeset label applied -- in objectui that label reads nothing and exempts nothing.) [9] NOT MEASURED / NOT RUN, stated as such: I did not re-run the reviewer's repo-wide 304-file/5817-test ablation (the brief said not to re-measure it); I did not run repo-wide `pnpm lint`, `pnpm test` or `pnpm type-check`; I did not wait for CI. PR changed_files comes from GitHub's own API field (3), not from a two-dot diff.",
  "mcp_calls": "0 -- every GitHub read and write went through repo-scoped REST (probed with GET first, http=200); no MCP GitHub tool was invoked",
  "open_questions": [],
  "out_of_scope_findings": []
}

---

Generated by Claude Code