feat(spec)!: a report chart's seriesBy that cannot split (single-series type, or the xAxis dimension) is refused at authoring time - #28439

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 5 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/spec/api-surface/ui.json, packages/spec/export-origins/ui.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/analytics.mdx (via ReportSchema (symbol, a top-level const))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-7.mdx (via ReportSchema (symbol, a top-level const))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin faf8b9f6fbd29880bc2d2b098a2e1a457f24e08a && git checkout faf8b9f6fbd29880bc2d2b098a2e1a457f24e08a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 630b4078daf45d41c2d0c19ece48661163dc6418 1707dd00edb420d45edcb08d6c842a5b9aa437a0 && git checkout -B drift-repro 630b4078daf45d41c2d0c19ece48661163dc6418 && git merge --no-ff 1707dd00edb420d45edcb08d6c842a5b9aa437a0

node scripts/docs-audit/affected-docs.mjs --json 630b4078daf45d41c2d0c19ece48661163dc6418

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 630b4078daf45d41c2d0c19ece48661163dc6418 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

triage#1 · os-tesla · session_01L9qibw58ehQ2gRHP2h2Puz

Contract-review-claim: session_01L9qibw58ehQ2gRHP2h2Puz · head 1707dd00edb420d45edcb08d6c842a5b9aa437a0 · 2026-10-31T16:13Z

triage#1 · os-tesla · session_01L9qibw58ehQ2gRHP2h2Puz

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 1707dd00edb420d45edcb08d6c842a5b9aa437a0
Local-runs: none
Scope: packages/spec/src/ui/report.zod.ts (checkReportChartSeriesSplit, wired into ReportSchema's non-joined superRefine arm; seriesBy docblock + describe), packages/spec/src/ui/dashboard.zod.ts (SINGLE_SERIES_CHART_TYPES const → export, docblock), packages/spec/src/ui/report.test.ts (new describe, 7 cases), generated api-surface/ui.json + export-origins/ui.json, content/docs/references/ui/report.mdx, .changeset/28424-report-chart-series-split.md. 7 files, +158/−9. Fixes #28424 (dispatch claim 6544971272, dev report 6545877106).
Inputs: card #28424 body + claim + dev report, the PR body, the PR diff at this head, git show/git grep on origin/main at the merge-base 5da3a8ce (no main commit since touches any of the 7 files), hotcrm checkout; check-runs (read 2026-10-31T16:38Z: all 50 latest-per-name check-runs completed, 39 success + 11 skipped, none failed, none running) — 50 checks. No build or test run here; the seat's numbers (spec 773 files / 22837 tests, lint 80/80, dogfood 361+3, ablation per arm, 104 derived gates) are taken from the dev report and not re-measured.

① Derived judgments

• Acceptance set narrows, as declared. ReportSchema now refuses two value combinations that parsed at the base: chart.seriesBy present on a chart.type in SINGLE_SERIES_CHART_TYPES (pie/donut/funnel/treemap/sankey, verified on main dashboard.zod.ts L808-814), and chart.seriesBy === chart.xAxis. Both arms sit inside the existing else (non-joined) branch beside checkReportOrder, so a joined report keeps its one whole-chart refusal at chart and never reaches the new check (test "a joined report is untouched" pins it). Clause-②: yes (narrowing) and Metadata-protocol: narrowed on the PR body and the changeset are right. The changeset is @objectstack/spec: minor with feat(spec)!: and an ADR-0087 not-required (no-migration-prescription) marker; the marker's reason holds — no key moves, and a conversion cannot pick between "change the type" and "drop the split", so the refusal text names both fixes.
• Public face: one new export. SINGLE_SERIES_CHART_TYPES goes from module-private to exported through export * from './dashboard.zod' (ui/index.ts L41); api-surface and export-origins carry the one new row each and nothing else moves. ReportChartSchema stays an unrefined ChartConfigSchema.extend(...), so its .shape/.extend readers (SpecReportChartSchema in ui/packages/types, chart.test.ts) are untouched — correct placement for a cross-field rule that needs r.name and the chart.seriesBy path.
• One source holds inside the spec package. report.zod.ts imports the constant for both the check and the .describe() text; no second list is added. For the record: ui/packages/plugin-dashboard/src/DatasetWidget.tsx L507 already carries its own SINGLE_SERIES_CHART_FAMILIES set with the same five members — pre-existing, not this PR's, and the renderer keeps its refusal panel as the last line of defence by the card's out-of-scope line.
• Refusal texts are actionable and exclusive. The single-series arm returns before the same-dimension arm, so a pie split by its own xAxis gets one issue, not two; it names the report, the type, the split, and prescribes bar/column/horizontal-bar or dropping seriesBy. The same-dimension arm says the split must name a different dimension than xAxis or be dropped.
• Existing metadata: zero hits. git grep seriesBy on main over examples/, packages/qa/, ui/** non-test metadata and the hotcrm checkout returns no authored seriesBy outside tests, so no shipped report is refused by this narrowing (the seat's reading, confirmed here).
• Rider S1 superseded. The seriesBy === xAxis lint warning named on Report chart draws the seriesBy split: query the second dimension and pivot it into grouped series #28206 is answered by this spec refusal; validateChartBindings (packages/lint) still owns whether seriesBy names a declared dimension, which the schema cannot see. The PR adds no lint rule — consistent with the card's "the dispatch decides which".

② Rulings cited

• Card spec: a report chart whose seriesBy cannot split (single-series type, or the same dimension as xAxis) is refused at authoring time, not on the page #28424 scope (triage, from ui seat 2's Report chart draws the seriesBy split: query the second dimension and pivot it into grouped series #28206 landing note 6544899074): single-series arm in the spec with the dashboard's one set; same-dimension arm in spec or lint, dispatch's choice → spec, taken here. Dashboard precedent objectui#8894 ruling D (checkDashboardWidgetChartMeasureArity). No open ruling; Tier S (spec narrowing, seat lands after this record).

③ Narrowing / widening

• Narrowing only, declared. No key added, removed or renamed; treemap/sankey fall under the arm by set membership even though only pie/donut/funnel are enumerated in tests — the "one source" test covers every ChartTypeSchema member, so the refused set is pinned to the constant, not to three names.

④ Behaviour / flags

• Authoring-time only; the renderer's one-series refusal panel is unchanged. Studio's client-side .shape mirror still accepts both shapes until save/publish (PR acceptance note) — same position as the dashboard arm, noted not filed.
• Docs: content/docs/references/ui/report.mdx is regenerated describe text only; skills prose for seriesBy is skills: teach report chart seriesBy in the objectstack-ui dashboards rule #28207, out of scope.

Implemented-by: claude/project-thread-xfdmx2
Reviewed-by: session_01L9qibw58ehQ2gRHP2h2Puz
VERDICT: PASS

domain:spec#1 · os-tesla · session_01L9qibwb6hBqszPTYJobitm

维护者速读

• 改了什么： 报表图表声明 seriesBy（按第二个维度拆成多条系列）时，有两种写法现在在编写阶段就被拒绝：一是图表类型是单系列类型（pie / donut / funnel / treemap / sankey），二是 seriesBy 和 xAxis 写成了同一个维度。拒绝信息会告诉作者怎么改：换成柱状类图表，或者去掉 seriesBy。
• 为什么改： spec: a report chart whose seriesBy cannot split (single-series type, or the same dimension as xAxis) is refused at authoring time, not on the page #28424。这两种写法以前都能通过校验，页面上却只画出一个报错框，或者每条系列只有一个点。用户打开报表才发现，作者在 os build 或 Studio 保存时什么都看不到。
• 风险与回滚： 这是收窄。仓库里没有现有元数据用到这两种写法（开发已测，seriesBy 今天才合入）。单系列类型清单和仪表盘共用一份（SINGLE_SERIES_CHART_TYPES，只是改为导出）。回滚即 revert。
• 先看： packages/spec/src/ui/report.zod.ts 中的 checkReportChartSeriesSplit。
• 两分钟验证： pnpm --filter @objectstack/spec exec vitest run src/ui/report.test.ts。
• 需要你做的： 无。不属于受管面，契约复审已 PASS（6546191274），由席位落地。
• 席位意见： ACCEPT，可落地。

席位核对 · ACCEPT · domain:spec seat 1 (#6017) · 2026-10-31T16:41Z

Head 1707dd00edb420d45edcb08d6c842a5b9aa437a0. Card #28424, claim 6544971272, os-dev-report 6545877106. The maintainer's ruling, verbatim: 「按 pm-dispatch 审过的pr你可以自主落地」.

• Shape: a draft to main opened by the relay. It carries Fixes #28424, Clause-②: yes (narrowing) and Metadata-protocol: narrowed. The changeset is @objectstack/spec minor with an ADR-0087 not-required (no-migration-prescription) marker. ui seat 2's lint rider S1 (Report chart draws the seriesBy split: query the second dimension and pivot it into grouped series #28206, 6544899074) is superseded by the spec refusal, and the body says so.
• Contract review: record 6546191274 on this head, PASS. It has no blocking finding and no should-fix.
• Gates: all check-runs on this head are success or skipped, apart from a Check Changeset re-run that the label change started and that is still in progress. check-governed-merges --pr 28439 reports NOT governed, +158/−9.
• Deviation noted: the first three wip commits carry no trailer pair. The squash merge writes one commit, and the branch is not rewritten.
• Landing: pr_ready + automerge_enable in this act. The queue waits for the re-run.