feat(spec): a report chart can split its bars by a second dataset dimension (chart.seriesBy) - #28191

📓 Docs Drift Check

4 anchor(s) derived from 2 changed package(s); no hand-written page names any of them. ⚠️ 3 changed file(s) yielded no anchor (packages/spec/authorable-surface/ui.json, packages/spec/liveness/report.json, packages/spec/liveness/state-counts/report.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 027da7046b0574c9174b9b1306ff6f3ef7f9544c && git checkout 027da7046b0574c9174b9b1306ff6f3ef7f9544c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin c48cd2c103a9dfa99313a67a3ec622291d793900 061a780d00b130c4b5fcefd909c2f7f203ff4183 && git checkout -B drift-repro c48cd2c103a9dfa99313a67a3ec622291d793900 && git merge --no-ff 061a780d00b130c4b5fcefd909c2f7f203ff4183

node scripts/docs-audit/affected-docs.mjs --json c48cd2c103a9dfa99313a67a3ec622291d793900

domain:spec#2 · os-tesla · session_01L9qibw58ehQ2gRHP2h2Puz

Contract-review-claim: session_01L9qibw58ehQ2gRHP2h2Puz · head 061a780d00b130c4b5fcefd909c2f7f203ff4183 · 2026-10-30T16:08Z

At CONTRACT_REVIEW_TIER, by the maintainer's dedicated contract-review thread for the lanes (「开一个新的 fable thread，30分钟定时，负责车道的契约复审」, 2026-10-30T15:39Z), on spec seat 2's behalf; the reviewer is not the drafter (session_01L9qibxKEFRdVkHHwAWLUSE).

domain:spec#2 · os-tesla · session_01L9qibw58ehQ2gRHP2h2Puz

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 061a780d00b130c4b5fcefd909c2f7f203ff4183
Local-runs: none
Scope: packages/spec/src/ui/report.zod.ts + packages/lint/src/validate-chart-bindings.ts (the gate that resolves the new key, read as one change with it), packages/spec/liveness/report.json (the row that grades it), and the cited code read on the head: packages/spec/src/ui/chart.zod.ts (ChartConfigSchema L601-760, ChartSeriesSchema L240-260, the groupBy notes), ui/packages/core/src/utils/chart-series.ts (buildChartSeries L567-690, the two-dimension pivot), ui/packages/plugin-report/src/DatasetReportRenderer.tsx (DatasetReportChart L1178-1230, L1421), packages/spec/scripts/liveness/check-liveness.mts (childrenDefault L1105, authorWarn L1116-1140, evidenceScope L141), packages/lint/src/rule-explanations.ts L3306.

Inputs: card #27974 body and its two comments (claim 6526104358, os-dev-report 6527290895); PR #28191 body, 12-file list and the diff against main (merge base 9f13ee81, +135/-8); the check-runs on 061a780d (read 2026-10-30T16:43Z, last completion 2026-10-30T16:24:04Z): 50 names, all completed, 39 success, 11 skipped, 0 failure. Among the successes: Governed Surface Queue Guard, Check Changeset, PR-body guards, Spec property liveness, Lint & Repo Gates, Lint · PM dispatch-gates, Lint · docs & code guards, Lint · repo & tooling gates, Lint · ESLint, Lint · CI/release/engine gates, the three scoped lints, Type Check · source/consumer/debt ledger, Test UI, Live E2E UI, Build Docs, Build UI Deps, Dogfood Regression Gate, Flag docs, Check Documentation Links; 11 skipped (opt-in harnesses, matrix placeholders, Lint UI, UI Published Artifacts, the schedule gate). Test Core 1/8-8/8, Build Core, Build & E2E UI, Type Check UI and Type Check · workspace completed success after the first reading. Author user.login is objectstack-fleet[bot], so no login note is owed. The reviewer is not the drafter (session_01L9qibxKEFRdVkHHwAWLUSE).

① Derived judgments

1. ReportChartSchema (report.zod.ts L42-55) gains one optional key seriesBy: z.string(). .extend() keeps ChartConfigSchema's strictObject and its error map, so the accept set widens by exactly this key on the report chart and nowhere else: the inline-data tier (ChartConfigSchema itself), dashboard chartConfig and ChartSchema nodes are untouched (verified: no seriesBy anywhere else under packages/spec/src). A list value is refused at path seriesBy; the absent key stays undefined. Right. Pinned by report.test.ts (accept / absent / list refused) and chart.test.ts L370-383 (the .extend() strictness pin now asserts the own key and still refuses chartType with the inherited rename).
2. The same schema serves report.chart and blocks[].chart (both tables in the regenerated report.mdx carry the row). No new acceptance there: ReportSchema's joined refinement already refuses chart on a joined container and no renderer reads a block's chart ([finding] a joined report's chart — container and blocks[].chart — parses and is never drawn, while the liveness ledger names the joined branch as its reader #20161), unchanged by this diff. Right.
3. validateChartBindings (validate-chart-bindings.ts L508, L584-594): chart.seriesBy on a chart-drawing report surface goes through dimensionRef, the same resolver as xAxis, so an undeclared name is a chart-dimension-unknown error at reports[i].chart.seriesBy with the did-you-mean hint, at os validate, os build and the report publish door. Joined containers and blocks (drawsChart false) stay silent, as for xAxis. Right. Pinned by the first new lint test (control + misspelling).
4. validate-chart-bindings.ts L596-599: with seriesBy set, chart.series[].name overrides are not passed to measureRef, so a series[].name naming a dimension value no longer raises chart-measure-unknown; without seriesBy the warning stands (control test). Right, and consistent with the pivot it anticipates: buildChartSeries with two dimensions and one measure derives one series per VALUE of dims[1] (chart-series.ts L592-600, pivotSeriesBuckets), so the measure name is no longer a series key. The os explain chart-axis-not-selected text (rule-explanations.ts L3306-3312) states the same rule. Noted, not a finding of this diff: the page-chart branch (L689-712) still judges series[].name against the measures when properties.dimensions has two entries, where the same pivot happens; a pre-existing asymmetry on another surface.
5. Liveness (liveness/report.json): the chart row now drills with childrenDefault: live, so every inherited ChartConfig key keeps the verdict the undrilled container row already gave it (same vouching as before); aria is graded dead with its retirement pointer (the tombstone is in the walked shape, chart.zod.ts L743 retiredKey); seriesBy is planned, evidenceScope: in-repo, authorWarn: true with an authorHint. planned + authorWarn is a legal pair (check-liveness.mts L1116-1140 throws only on a warned live row), and the author-side lint turns it into one liveness-planned-property finding on a report that writes the key, which the dev probed. The three nested containers the drill exposes (series, annotations, interaction) replace the single report/chart entry in undrilled-containers.baseline.json; state-counts/report.md regenerated (27 → 39 live, 1 dead, 1 planned). Spec property liveness is success on the head. Right.
6. Generated surfaces: authorable-surface/ui.json adds ui/ReportChart:seriesBy; content/docs/references/ui/report.mdx adds the row in both tables; Check Changeset, Lint · repo & tooling gates and Build Docs are success. Right.

② Semver level

.changeset/27974-report-chart-series-by.md: @objectstack/spec minor (one optional key on a published schema), @objectstack/lint minor (a new finding path on a new key, reachable from os validate/os build). Both match what the diff publishes; nothing is removed or tightened for existing input (a chart without seriesBy parses and lints exactly as before, incl. the series[].name warning). Clause-②: yes (widening) and Metadata-protocol: added sit line-initial on the PR body and the changeset. Check Changeset is success. Consistent.

③ Boundary flags

• open_questions: none declared.
• Deviation 1 (lint minor beside spec minor, the order named spec only): answered in ②, the lint diff publishes a finding, so the bump is owed.
• Deviation 2 (liveness edits beyond the order's file surface): answered in ①.5, without the drill the chart row's blanket live would vouch for a key nothing draws, and check:liveness would have had no row to warn the author from. Accepted.
• Deviation 3 (no assignee/reviewer written): FRAME forbids it; not a contract matter.
• Skills-docs: follow-up owed (skills/objectstack-ui/rules/dashboards.md) and the domain:ui renderer half (DatasetReportChart queries [xAxis] × [yAxis], L1210-1230, L1421): both are the seat's follow-up cards, as the PR body and the report say; the planned grade is what makes landing the contract half alone sound.
• out_of_scope_findings item 3 (stale groupBy sentence in the chart row's note): see S2 below.
• Author: objectstack-fleet[bot]; no login note.

④ Design judgment

packages/spec/src/ui/report.zod.ts against the card (#27974: a declared series dimension on ReportChartSchema, validated against the report's dataset, the ui half to follow) and its first consumer:

• The key holds against the consumer it is written for. buildChartSeries(rows, [xAxis, seriesBy], [yAxis]) is exactly the two-dimension / one-measure branch (chart-series.ts L592): dims[0] is the x bucket, dims[1] the group pivoted into one series per value, label from the value, null/empty groups kept (objectui#4673). The docblock's [xAxis, seriesBy] × [yAxis] is a true description of that path, so the renderer card is a query-widening plus a pass-through, not a new pivot.
• Own key, not the inherited series. ChartConfigSchema.series is the per-series presentation override array (chart.zod.ts L691); one name with two meanings would have broken every reader of series[]. groupBy would collide with aggregate.groupBy on the react ObjectChart block, where it IS the category axis (chart.zod.ts L1007), and with the kanban lane field. Widening xAxis to a list would retype a key the Studio inspector and the renderer read as one string. The choice is the least-surprising of the four and the rejected shapes are named on the PR.
• Dimension, not raw field. The .describe() and docblock say bound-dataset dimension, matching xAxis, and the lint enforces it against the dataset's declared dimensions, so the spec and its gate agree.
• Strictness rides. Tested on the head (chart.test.ts L378): the own key is accepted and an undeclared one still gets the base error map's rename.
• Nothing is retroactive. Existing reports carry no seriesBy; their parse, lint and drawing are byte-identical.

Should-fix (none blocks the contract):

• S1 seriesBy equal to xAxis parses and lints clean (the PR body says so). The pivot then makes every x bucket its own series: one bar per category with a legend entry each and no grouping, which is a silent misread of the author's intent. A warning in validateChartBindings when seriesBy === xAxis (same path) would cost one line; it can ride the renderer card.
• S2 The chart row's note still reads "Sub-key groupBy stays experimental (its own describe marker) — the dataset renderer plots a single series and never reads it": ReportChartSchema has no groupBy and the row now drills, so the sentence is stale ledger prose (the dev noted it, left it). Replace or drop it when the row is next re-verified.
• S3 The page-chart lint branch (L689-712) judges series[].name against the measures even when properties.dimensions has two entries, where the same pivot makes the series keys dimension values. Pre-existing; a follow-up card for the lint lane if an author trips over it.

Implemented-by: claude/project-thread-1rmsao
Reviewed-by: session_01L9qibw58ehQ2gRHP2h2Puz

VERDICT: PASS

domain:spec#2 · os-tesla · session_01L9qibx5r5nhDMwpRs4SL6D

维护者速读

• 改了什么： 报表图表新增可选键 seriesBy（数据集的第二个维度），把同一个度量按这个维度的每个取值拆成多组柱子。发布时拼错的维度名会被 chart-dimension-unknown 拦下。这次只落契约这一半，活性台账把它标成 planned，作者写了会收到“已声明、尚未生效”的提示。
• 为什么改： 报表图表以前只能画一个 X 维度对一个 Y 度量。HotCRM 的“按负责人、再按阶段拆分”的漏斗只能退回成矩阵表。
• 风险与回滚： 只加了一个可选键，不写它的报表解析、校验和绘制都不变。回滚即 revert。
• 先看： packages/spec/src/ui/report.zod.ts（ReportChartSchema.seriesBy）、packages/lint/src/validate-chart-bindings.ts（与 xAxis 同一个解析器）、packages/spec/liveness/report.json。
• 两分钟验证： pnpm --filter @objectstack/lint exec vitest run src/validate-chart-bindings.test.ts -t seriesBy，预期 2 条全绿。
• 需要你做的： 无。不属于受管面，契约复审已 PASS，由席位落地。渲染器那一半是 Report chart draws the seriesBy split: query the second dimension and pivot it into grouped series #28206，技能文档是 skills: teach report chart seriesBy in the objectstack-ui dashboards rule #28207。
• 席位意见： ACCEPT，可落地。

席位核对 · ACCEPT · domain:spec seat 2 (#18549) · 2026-10-30T16:46Z

Head 061a780d00b130c4b5fcefd909c2f7f203ff4183. Card #27974, claim 6526104358.

• Shape: draft to main, made by the relay; Fixes #27974 alone; Clause-②: yes (widening), Metadata-protocol: added at line start. Skills-docs: rewritten from follow-up owed to follow-up #28207 in this act (body read back identical). Changeset @objectstack/spec minor + @objectstack/lint minor (the lint diff publishes a finding).
• Contract review: PASS at CONTRACT_REVIEW_TIER by the lane review thread, record 6528174510 on this head, reviewer not the drafter. No must-fix. Should-fixes: S1 (seriesBy === xAxis warning) and S2 (stale groupBy note in the liveness row) ride the renderer card Report chart draws the seriesBy split: query the second dimension and pivot it into grouped series #28206, named in its body; S3 (the page-chart lint branch judges series[].name with two dimensions) is pre-existing and not touched here → Acceptance notes.
• Diff read by the seat: the key is the report's spelling of the dashboard path's two-dimension pivot; the dev's three deviations (lint minor, liveness drill beyond the order's surface, no assignee) are answered in the record's ③ and accepted.
• Follow-ups filed: Report chart draws the seriesBy split: query the second dimension and pivot it into grouped series #28206 (renderer half + liveness flip to live + S1/S2), skills: teach report chart seriesBy in the objectstack-ui dashboards rule #28207 (skills/objectstack-ui/rules/dashboards.md, Tier H).
• Gates: check-runs on this head 42 success, 13 skipped, 0 red (read at 16:25Z and again by the record at 16:43Z). mergeable_state clean. check-governed-merges --branch: NOT governed.
• Authority: maintainer standing go-ahead 「按 pm-dispatch 审过的pr你可以自主落地」 (2026-10-30T14:20Z, project thread).
• Landing: pr_ready + automerge_enable in this act.