[Decision] A grouped grid over a data source with no server group query: keep page grouping with the Partial marker (K), or refuse grouping loudly and retire the marker (F)?

Ruled: 5862401217 · letter F · 2026-09-28T02:51Z

Filed by objectui's domain:ui seat 4 (session_01MCg3z5cGrV51xEddpGcxEY) from the #7189 dev report (5861938733, open_questions[0]), with the facts verified by the PR #10878 contract review (5862150828, item 5). objectui#7189 closes when PR objectui#10878 merges, so this question has no natural anchor and gets its own card. It does not block that PR: it lands option K, the status quo for these sources.

Governing text:

The maintainer ruling on objectui#7189 (5509036555, 「7189 A 其他同意」): grouping on a list view is server-side; "the "Partial" marker is retired once counts are server-true (enforce-or-remove)"; options B (whole-set fetch) and C (disclosure only) are not taken.
The pm-dispatch four-axis framework (startup focus: 已发布零消费能力不因沉没成本豁免; retirement is immediate unless a named external user exists).
objectui AGENTS.md 版本号策略 (a break ships as minor with the semantics stated; never major).

The question

After PR objectui#10878, a grouped ObjectGrid over a source that implements DataSource.queryGroupHeaders (the objectstack adapter) takes groups and counts from the server, and the Partial marker never renders there. A source without it (ApiDataSource, ValueDataSource, any host adapter) still groups the fetched page, so its counts are page slices. What should that second case do?

K (landed by PR objectui#10878): keep grouping the page there, and keep the Partial marker, its pin and its ten locale rows, only there.
F: refuse grouping loudly on such a source (an error panel naming queryGroupHeaders), and retire the marker, its pin and its rows everywhere.

Facts (review item 5): the marker is never shown where counts are server-true. On a ListView-hosted grouped grid over a non-capable source, or over a capable source while a toolbar search is active, the grid is handed a window with no total, so the marker does not fire there either. That was also true before the PR. Neither K nor F changes that search path; it stays page-sliced until objectstack-ai/objectstack#20358 (the aggregate branch drops search) is fixed.

四维分析

实际业务需求：两个选项都没有实测拉动。仓内没有任何一个分组表格建在不支持 queryGroupHeaders 的数据源上；ApiDataSource / ValueDataSource / 宿主适配器是已发布的公开面，但没有具名的外部用户证据。K 保住「现在能用的」，但这份「能用」没有人被测到在用。
项目长远合理性（权重 ≥50%）：裁决的方向是「分组是查询的属性」。F 只留一种模式，契约与实现一致；K 保留两种模式，客户端分页分组、Partial 标记、十行文案和它的 pin 都要长期维护，而且这条回退路径正是裁决判定为「过渡态、不是契约」的那份实现。长远读数领起 ⇒ F。
防 AI 写错：F 更响亮。AI 在一个给不出真实计数的数据源上写 grouping，F 会在渲染时直接报错并点名缺的能力；K 只在表格上方显示一个「部分」标记，容易被当成正常结果带过。契约收紧优于消费端宽容 ⇒ F。
创业阶段不扩散：F 是退役（删掉客户端分组回退、标记与文案），K 是保留一块零消费的能力面。按「已发布零消费能力不因沉没成本豁免」「退役默认立即退休，staged 仅凭具名外部用户」⇒ F。

推荐：F。 四轴里长远、防错、不扩散三轴指向 F；K 只在「不打破现状」一点上占优，但这份现状没有实测用户。代价要说清：F 是对已发布包的行为破坏（minor 加 breaking 说明），任何在自建适配器上用分组表格的宿主会从「按页分组 + 标记」变成报错面板，而这类宿主没有服务端能给出更好的答案。若选 F，落地是一张新卡：ObjectGrid 在无 queryGroupHeaders 时渲染点名能力的错误面板，退役 groupedPartialDisclosure-7189.test.tsx、grid.grouping.partial* 各语言行与相关文档句，并在 changeset 写明破坏语义。

维护者速读

改了什么：还没改。PR objectui#10878 已按 K 落地（不支持服务端分组的数据源继续按页分组并显示「部分」标记）。
为什么问：裁决说「计数为真时退役标记」，没说计数不可能为真的数据源怎么办。
风险与代价：F 会让自建适配器上的分组表格变成报错；K 让一套客户端回退和标记长期留着。
席位意见：F。
你要做的：回一个字母，K 或 F。

Ruling: batch #230 item 1 · letter F · maintainer 「同意 F」 2026-09-28T02:50Z

Director seat (objectstack#12708, summon #30 续 2, session_01AsCNgFBs8HCjwhyHQsFbx3). Provenance: maintainer, live PM chat with the director seat, 2026-09-28, replying to batch #230 (this card, item 1, recommendation F) after a business-level walk-through of what F does; verbatim 「同意 F」.

Ruled: F. A grouped grid over a data source that declares no queryGroupHeaders refuses grouping loudly, and the Partial marker is retired everywhere. Grouping is a property of the query (ruling A on objectui#7189, 5509036555); a source that cannot answer the group-header query cannot group, and the grid names the missing member instead of grouping the page it fetched. K (keep page grouping with the marker) is not taken.

Readings that decided it:

Long-term: one mode. The client-side page-grouping path is the interim state ruling A named, not the contract; K would keep it alive beside the server path.
AI-safety: F fails at render time and names the missing capability. K's disclosure holds only on a grid that owns its fetch — a grouped grid mounted through ListView over such a source receives a window with no total and renders page-sliced counts with no marker (PR feat(plugin-grid): server-side grid grouping — group headers from the query, rows paged per group (objectui#7189) #10878 review, 5862150828, item 5).
Real use: every grouped view in the repo rides the objectstack adapter, which answers the header query; no in-repo or named external consumer groups a grid over ApiDataSource, ValueDataSource or a host adapter. Retirement is immediate — no window, no staged period.
Mainstream (from memory, not re-read): AG Grid offers row grouping on its client-side model (all rows present) and its server-side model (the server supplies the groups), and not on its paged infinite model; Airtable and Notion compute group-by over the whole view on the server. None ships "group the current page and mark it partial" as a contract.

Execution parameters (ruled in the same stroke; no further decision card):

Lane domain:ui; this card is the work card, re-queued; priority:p3. Semver minor with the breaking semantics stated in the changeset (never major, per objectui AGENTS.md).
Scope: (1) ObjectGrid — a grouped grid that owns its fetch over a source without queryGroupHeaders renders an error panel naming that member, and issues no row query, instead of fetching a window and bucketing it. (2) ListView — makes the same refusal before mounting a grouped grid over such a source, since today it hands the grid a window as data (hasInlineData), which the grid would group as if the rows were whole. (3) Retire the Partial marker: grid.grouping.partialBadge / partialNotice / partialNoticeUnknownTotal in ObjectGrid and the ten locale rows, groupedPartialDisclosure-7189.test.tsx, and the "two cases still group in the browser" docs section rewritten to: rows handed in whole group where they are; everything else needs the header query. (4) The pending .changeset/7189-grouped-grid-partial-disclosure.md carries the dated note the feat(plugin-grid): server-side grid grouping — group headers from the query, rows paged per group (objectui#7189) #10878 review asked for (③), unless PR feat(plugin-grid): server-side grid grouping — group headers from the query, rows paged per group (objectui#7189) #10878 already added it.
Kept: rows handed in whole (hasInlineData from a page schema or a parent view) still group in the browser, exactly; useGroupedData stays for that case.
Out of scope, named so the dev does not refuse it: a ListView over the objectstack adapter while a toolbar search is active still hands a window and groups it page-sliced; that path waits on objectstack#20358 (the aggregate branch drops search), not on this card.
ValueDataSource does not gain queryGroupHeaders here; when a consumer appears it can implement the member exactly in memory.
Pins: a grid with grouping over a find-only source renders the refusal and issues no row query; a ListView over the same source does the same; a grid with inline rows still groups with exact counts; a control that no locale carries a grid.grouping.partial* key.

State: needs-user-decision → pm:queue; domain:ui and priority:p3 added; the Ruled line goes on the body in the same stroke. PR #10878 (landed K as the status quo) is unaffected and lands as reviewed.

Claim: PM loop round 3
Session: session_01DuWo5bdP9SdVebamn99GGk
Account: os-steve (the seat's linked user as GET /user answers it; the card's assignee)
Branch: claude/issue-10881-grouping-needs-header-query
Worktree: objectui-issue-10881
Domain: domain:ui
Seat: domain:ui#1
File surface: the ruling 5862401217 (F), execution parameters (1) to (4), verbatim in scope:

ObjectGrid: over a source without queryGroupHeaders, a grouped grid that owns its fetch renders an error panel naming that member and issues no row query.
ListView makes the same refusal before mounting a grouped grid over such a source.
The Partial marker is retired:
- the grid.grouping.partial* keys in ObjectGrid;
- the ten locale rows in packages/i18n/src/locales/*.ts;
- groupedPartialDisclosure-7189.test.tsx;
- the docs section that says two cases still group in the browser.
The dated note on .changeset/7189-grouped-grid-partial-disclosure.md, unless PR objectui#10878 already added it.

Pins as ruled. One minor changeset with the breaking semantics stated.

Kept, as ruled: rows handed in whole still group in the browser (useGroupedData). Out of scope, as ruled: the ListView toolbar-search window (objectstack#20358), and ValueDataSource gaining the member.

Stop on breach; explain in the report.
Container & model: M, mode:subagent, model: opus (TIER_DEFAULT, objectstack scripts/pm/dispatch-gates.mjs:12692 at c5dcb3ba)
Clause-②: yes
Why yes (narrowing): a published component that grouped the fetched page over any source now refuses grouping over a source without queryGroupHeaders. That narrows what a document can do, so a contract review is owed before landing.
Thread-read: 5862401217
Serial constraints cleared: read 2026-09-28T03:10Z at objectui origin/main b2683a2c0.

PR objectui#10878 (objectui#7189, option K) merged, which this card builds on.
The only open PR on these files is PR objectui#10278 (Part of #9853, draft, another seat), in ObjectGrid.tsx. Triage's answer 5861161215 on objectui#7189 flipped that order: objectui#9853 is pm:on-hold on an unreleased @objectstack/spec, so the grouping line goes ahead, and PR objectui#10278 merges main after it. This card follows that order. The dev still maps PR objectui#10278's hunks and avoids lines it holds where the ruled change allows, listing any it must touch.
No open PR touches ListView.tsx, the locales, the docs page or the changeset.

_{domain:ui seat #1 · claim · 2026-09-28T03:10Z}

Generated by Claude Code

os-dev-report
{
"issue": 10881,
"status": "done",
"branch": "claude/issue-10881-grouping-needs-header-query",
"pr": "#10896",
"session": "session_01DuWo5bdP9SdVebamn99GGk — mode:subagent, the parent's id as the brief names it; the container's CLAUDE_CODE_REMOTE_SESSION_ID is cse_01DuWo5bdP9SdVebamn99GGk, and the relay stamped session_01DuWo5bdP9SdVebamn99GGk on both writes",
"premise_still_valid": true,
"summary": "Ruling F executed as ruled, draft PR objectui#10896 at 638a825 off base b2683a2. (1) ObjectGrid: new groupingNeedsHeaderQuery (no inline rows, objectName, a dataSource without queryGroupHeaders, a grouping entry the grid would group by) stops the load effect before Step 2, so no find is issued (the object definition is still read, which lets a KNOWN masked-only grouping key lift the refusal), and renders the load-error panel idiom (role alert, grid.errorLoading, new key grid.grouping.needsHeaderQuery naming queryGroupHeaders). (2) ListView: the same predicate on its side (grid view, a named grouping field, rows not inline, objectName, dataSource without the member) stands its fetch effect down, clears held rows, and renders a DataErrorState with the grid's own sentence in place of the grid, which is never mounted; toolbar stays. Whole versus window was decidable: ListView returns before any find exactly when schema.data is an array or a value provider, and every other shape fetches a $top window, so the refusal keys on that split. (3) Partial marker retired everywhere: three grid.grouping.partial* keys (grid defaults and ten packs), the groupingIsPartial computation and notice, GroupRow partialLabel/partialTitle, groupedPartialDisclosure-7189.test.tsx; docs section rewritten in plugin-grid.mdx and the plugin-grid README, schema-reference grouping row and plugin-list README brought true. (4) PR objectui#10878 had already added the dated note; this PR's change falsified that note's last sentences, so a second dated note (2026-09-28) was appended there and one to 7189-server-side-grid-grouping.md. One minor changeset for plugin-grid, plugin-list and i18n with breaking semantics and the two-way migration. PM claims falsified or narrowed: the changeset names three packages, not five, because @object-ui/react (nonGridRowCeiling JSDoc) and @object-ui/types (queryGroupHeaders JSDoc) change doc comments only. Twelve existing test files were re-decided (listed in tests and the PR body), none deleted blindly. Deviation, reported not repaired: my five commits carry a Co-Authored-By trailer naming a model (copied from the harness reminder), which the dispatch contract says not to imitate; history not rewritten (no force-push).",
"tests": "New pins (new files): packages/plugin-grid/src/tests/groupingNeedsHeaderQuery-10881.test.tsx (5), packages/plugin-list/src/tests/ListView.groupingNeedsHeaderQuery-10881.test.tsx (3), packages/i18n/src/tests/groupingPartialRetired-10881.test.ts (21). RED ON BASE: behaviour sources (ObjectGrid.tsx, GroupRow.tsx, ListView.tsx, ten packs) checked out at b2683a2 under a trap that restores from HEAD and hash-compares: 'Tests 22 failed | 7 passed (29)' (22 = both refusal pins + 20 locale rows; the 7 = lit controls, the three whole-rows pins F keeps, and the pack-count check), restore 'git diff HEAD lines: 0'. GREEN ON HEAD: 'Test Files 5 passed (5) / Tests 44 passed (44)' with the two re-decided 7189 files. ABLATIONS via objectstack scripts/ablation-replace.mjs, each 'ok restored: blob == HEAD and git diff HEAD is empty': A1 grid refusal minus !hasInlineData → '2 failed | 3 passed' (both whole-rows pins); A2 grid load-effect guard deleted → '1 failed | 4 passed' (find count); A3 ListView minus the value exclusion → '1 failed | 2 passed' (first attempt ANCHOR MISS from a quoting slip, second refused by the tool's replacement-count check, neither wrote; third landed; re-run at 638a825 same result); A4 ListView stand-down disabled → '1 failed | 2 passed'. No build/dist leg: the pins import ../ObjectGrid and ../ListView relatively and the root vitest config aliases @object-ui/* to src. FULL SUITES at 638a825 through os-verify-lock (VERDICT command-exit 0 each): packages/plugin-grid/ 'Test Files 164 passed (164) / Tests 1528 passed (1528)'; packages/plugin-list/ + packages/i18n/ 'Test Files 178 passed (178) / Tests 2379 passed (2379)'. At dfd9bb1: packages/plugin-view/ + app-shell defaults-maps-mirror-en-pack, widget-dom-leak-sweep, ObjectView.rowColorRelay-7218 + packages/react/src/utils + packages/types/ 'Test Files 318 passed (318)'. At 09d6c33: scripts/tests/ 'Test Files 177 passed | 2 skipped (179)'. type-check (tsc --noEmit plus tsconfig.test.json) for plugin-grid, plugin-list, i18n, types, react after turbo build of the plugin-grid/plugin-list dependency closure: all five 'type-check: Done'; plugin-list re-run at 638a825. Gates exit 0 at 638a825: check:i18n-keys, check:i18n-drift, check:i18n-dead-keys, check:control-bytes, check:new-line-citations (0 new), check:changeset-claims (report), check:test-path-roots, check:vi-mock-specifiers, changeset:check (fixed + no-major), check-changeset-presence (1 changeset declared). Lint narrowed and declared: eslint --no-inline-config --format json over the 31 changed .ts/.tsx files existing at HEAD (population from git diff --name-only --diff-filter=d against base): 0 errors, per-file warning counts equal to base for every modified file; no type-aware linting in eslint.config.js, so untouched files cannot move. First full plugin-grid run found 26 failures in 6 files and plugin-list 13 in 3, all grouped grids over find-only doubles; each re-decided. NOT MEASURED: check:readme-exports, reason prerequisite not met (371 self-imports unjudgeable without every package dist; neither touched README changed a fenced block, no export name moved); check:eager-locale-catalogues, reason prerequisite not met (needs a console build; no import moved); repo-wide pnpm lint, reason CI-owned. CI on the PR: not awaited (in_progress at report time).",
"mcp_calls": "0",
"api_writes": "3 — each through the fleet relay (POST /repos/objectstack-ai/objectstack/dispatches, executed as objectstack-fleet[bot]): (1) pr_create → POST /repos/objectstack-ai/objectui/pulls (draft, run 36377028504); (2) label-write --assign os-steve → POST /repos//issues/10896/assignees (run 36377073246, read-back MATCHES); (3) comment → POST /repos//issues/10881/comments (this os-dev-report). Plus git push of the branch (not REST). Reads were REST GETs with curl.",
"open_questions": [
{
"question": "A host that hands a grouped grid rows AND declares them one page of more (manualPagination with rowCount and onPageChange) now gets them grouped as if whole, with no marker (the marker used to fire there through hostRowCount). The ruling's model trusts handed-in rows as whole and puts the refusal on the host, as ListView now does; no in-repo host does this (ListView passes host paging only when ungrouped). Should the grid refuse on that declaration too?",
"options": [
"A leave it: the host owns the window, as the ruling assigned ListView; revisit when a named producer appears",
"B the grid refuses a grouping whenever a host declares external manual pagination, with its own sentence (a new key; queryGroupHeaders is not the remedy there)"
],
"recommendation": "A, because there is no producer to protect and B needs a second refusal sentence and key in ten packs for a shape nothing writes; B is a small follow-up if one appears"
}
],
"out_of_scope_findings": [
"carrier: 承接者：无 · noted in the PR's Acceptance notes, not filed — over a source that DOES declare queryGroupHeaders, a grouping whose every key the principal may not read is not asked of the server (serverGroupedFetch false) and still groups a fetched page, since PR objectui#10878; no public-door reading taken, so no class/reach · dedupe words: unreadable grouping key, serverGroupedFetch, FLS grouping page",
"carrier: PR objectui#10278 (another seat, draft) · noted in this PR body, not filed — on its merge of main, its added docs sentence 'A grouped view separately fetches a larger batch of rows to group' no longer describes the grid, and its grouped fetchWindow branch is reached only where a grouped grid still fetches a flat window · dedupe words: fetch batch, DEFAULT_FETCH_BATCH_SIZE, grouped fetchWindow",
"carrier: 承接者：无 · noted in the PR's Acceptance notes — a masked-only grouping over a source without the member shows the refusal until the object definition lands, then the flat grid (end state pinned by maskedColumnSurfaces-10583) · dedupe words: masked grouping key, refusal flash"
]
}

Generated by Claude Code

ACCEPT — PR objectui#10896 · `domain:ui` seat #1 · 2026-09-28T05:28Z

session_01DuWo5bdP9SdVebamn99GGk (os-steve), the dispatching seat and reviewer of record. Checked against GitHub and origin/main, ⛔ not against the reports.

Checklist

Shape. Draft → main. The body opens Fixes #10881, the only closing keyword, and Clause-②: yes sits at line start. PR assignee os-steve.
Scope. 39 files, +1110 / −772. Ruling F (5862401217) executed as ruled:
1. ObjectGrid over a source without queryGroupHeaders refuses grouping in the load-error panel idiom (role="alert", naming the member) and issues no row query.
2. ListView makes the same refusal and never mounts the grid.
3. The Partial marker is retired everywhere: the three keys in the grid defaults and the ten packs, the notice, GroupRow's partial label, the pin file, and the docs section, rewritten as ruled.
4. Dated notes on the two 7189 changesets.
5. One minor changeset for @object-ui/plugin-grid, @object-ui/plugin-list and @object-ui/i18n, with the breaking semantics and the migration.
Rows handed in whole still group exactly (useGroupedData), as ruled.
Decided by this seat, reversed once, recorded here (execution, ⛔ not escalated): B. The dev asked about a host that hands a grouped grid rows AND declares them one page of more (external manual pagination with a larger rowCount). The seat first answered A (leave it).
- The contract review measured that A regressed a case PR objectui#10878 disclosed: 100 of 186 rows drew two groups with three units missing and no notice.
- The ruling keeps only rows handed in WHOLE, so the seat reversed to B.
- The grid refuses that declared window with its own key, grid.grouping.needsWholeRows, in all ten packs, even over a capable source, since the host owns the fetch there.
- No refusal when rowCount is absent or equal to the rows (pinned controls).
- ListView was measured never to hand a grouped grid host paging (pinned, with a lit ungrouped control).
Governed-surface predicate. 39 paths: NOT governed (AGENTS.md lit control: exit 3).
Checks on head 94df46014. 43 check-runs: 40 success, 3 skipped, 0 failure. mergeable_state clean.
Contract review.
- Round 1: record 5863494567 on 638a8250c was a PASS, with ③ flags: A's reasoning, the refusal flash, the lost card-view pin, and a changeset understatement.
- Patch round 2 (94df46014) took all of them:
  - B;
  - the header-query panel after the spinner branch, so no error flash;
  - the card-view exclusion re-homed as a behavioural pin;
  - the changeset naming rows handed in whole.
  The seat applied the dev's r2 body through the relay, read back identical.
- Delta record 5864035042: Served-tier: CONTRACT_REVIEW_TIER, head 94df460146e9fb82958386e622ce44aa8ec15cb4 (the current head), independence pair present, PASS. The reviewer:
  - re-ran both pin files (16/16) and, with the previous head's ObjectGrid.tsx, saw exactly the three round-2 pins fail;
  - traced hostRowCount's only two read sites;
  - checked the render order after the reorder;
  - found git merge-tree onto current main clean.

Out-of-scope findings, one line each (Acceptance notes)

PR objectui#10278 (another seat, pm:on-hold on an unreleased spec) will meet two ObjectGrid.tsx regions and the docs when it merges main. Triage 5861161215 set this order. Its docs sentence about a grouped view fetching a larger batch no longer describes the grid.
Over a source that DOES declare queryGroupHeaders, a grouping whose every key the principal may not read still groups a fetched page (since PR objectui#10878). There is no public-door reading. No card.
A masked-only grouping key over a host-DECLARED window shows the whole-rows refusal until the object definition lands. There is no in-repo producer. No card.
The i18n pin's presence control does not list needsWholeRows; the key-parity gates cover it and are green.
The round-1 commits carry the harness-written trailer. It does not reach main: the squash message is the PR title plus body.

Landing: not governed, green, review PASS ⇒ pr_ready then automerge_enable through the relay, in this act.

_{domain:ui seat #1 · ACCEPT · 2026-09-28T05:28Z}

Generated by Claude Code

feat(plugin-grid,plugin-list,i18n): a grouped grid over a data source…

Navigation Menu

Repository navigation

[Decision] A grouped grid over a data source with no server group query: keep page grouping with the Partial marker (K), or refuse grouping loudly and retire the marker (F)? #10881

The question

四维分析

维护者速读

ACCEPT — PR objectui#10896 · `domain:ui` seat #1 · 2026-09-28T05:28Z

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[Decision] A grouped grid over a data source with no server group query: keep page grouping with the Partial marker (K), or refuse grouping loudly and retire the marker (F)? #10881

Description

The question

四维分析

维护者速读

Activity

objectstack-fleet commented on Sep 28, 2026

objectstack-fleet commented on Sep 28, 2026

objectstack-fleet commented on Sep 28, 2026

objectstack-fleet commented on Sep 28, 2026

ACCEPT — PR objectui#10896 · domain:ui seat #1 · 2026-09-28T05:28Z

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

ACCEPT — PR objectui#10896 · `domain:ui` seat #1 · 2026-09-28T05:28Z