docs(types): correct the series and route-overview docblocks PRs #10802 and #10821 made false (objectui#10905) (#10939)

Fixes #10905

Clause-②: no — comment and describe text only; no accept set or public
surface moves.

## What changed

Two docblocks in `packages/types/src`, comment text only, plus an
empty-frontmatter changeset. No `.describe()` string, type, value or
accept set moves.

1. **`ObjectChartSchema.series`, the TS interface in `objectql.ts`.**
The sentence "A `type` written on this arm anyway is an excess property
on a literal typed by this interface" is replaced. Since PR #10802
(objectui#10770), each `series` entry is either the spec's `ChartSeries`
(the `{ name }` arm) or the internal `{ dataKey }` arm. The `{ name }`
arm declares `type`, and excess-property checking on that union accepts
a key that either arm declares, provided the value fits that
declaration. So `{ dataKey: 'amount', type: 'line' }` compiles. The zod
half of the paragraph (a plain `z.object`, which strips `type`, so the
entry parses clean and the key is dropped) is still true and is kept.
"The mirror's `.describe()` says the same" now reads "names the same
omission". The `.describe()` string names the omission and never made
the excess-property claim, so it is not touched.
2. **The route overview headed "WHERE THIS ARM IS INSTALLED", in
`zod/objectql.zod.ts`.** Its second-route paragraph made three claims.
It said a named view's `listViews` "is unmirrored". It said
`generateViewSchema` merges the same two nestings. It named a `custom`
issue at `listViews.KEY.options.kanban.groupBy`. Since PR #10821
(objectui#7928), `listViews` is
`stripImportedDefaults(SpecViewSchema).shape.listViews`. That record
refuses a named view's `options` bag whole, `generateViewSchema` reads
no `options` bag, and `checkNamedViewKanbanStrayGroupBy` reports at
`listViews.KEY.kanban.groupBy` only. The heading ("TWO NESTINGS EACH")
and the final sentence ("cannot depend on which route or nesting")
described the same pre-#10821 shape, so they are corrected in the same
docblock. Three nestings now take the one string. A named view's
`options.kanban.groupBy` meets the protocol's refusal of `options`
instead.

Route 1 of the overview (`list-view`: `kanban` plus `options.kanban`)
was re-read against `ListView` and `ListViewSchema.options` and is
unchanged.

## Measurements

The probes are kept outside the tree and were run once. Everything was
measured on `733fd5ac6`.

**Sentence 1, a `tsc` probe.** Three literals typed `ObjectChartSchema`,
run under the package's own tsconfig:
- `series: [{ dataKey: 'amount', type: 'line' }]` produced no
diagnostic, so the sentence under test is false.
- Positive control: `series: [{ dataKey: 'amount', zzzUnknownKey: 1 }]`
produced TS2353 ("Object literal may only specify known properties"), so
a genuinely unknown key IS refused.
- Value control: `series: [{ dataKey: 'amount', type:
'not-a-chart-family' }]` produced TS2322, so the value must fit the
spec's `ChartType`.

**The zod half, a parse probe** (`ObjectChartSchema.safeParse`):
- `{ dataKey: 'amount', type: 'line' }` succeeds with series
`[{"dataKey":"amount"}]`, so the key is stripped and that half stays
true.
- Controls: `{ dataKey, chartType: 'line' }` keeps `chartType`, and `{
name, type: 'line' }` keeps `type`.

**Sentence 2, a parse probe** (`ObjectViewSchema.safeParse`, a named
view carrying `columns` and `kanban.columns`):
- `kanban.groupBy` gives `unrecognized_keys` at `listViews.board.kanban`
naming `groupBy`, plus `custom` at `listViews.board.kanban.groupBy`.
- `options.kanban.groupBy` gives only `unrecognized_keys` at
`listViews.board` naming `options`. There is no `custom` under
`options`.
- Dark control (`groupByField` and `columns` only): success.
- `generateViewSchema` reads no `options` bag: a `.options` read pattern
hits `plugin-view`'s `ObjectView.tsx` zero times, and hits
`plugin-list`'s `ListView.tsx` (the positive control) 48 times.

**Lit control.** I extracted each of the
`checkNamedViewKanbanStrayGroupBy` and `namedViewKindRefusals`
docblocks, from its opening line through the declaration line, before
and after the edit. Both are byte-identical: `cmp` is silent, and the
sha256 prefixes are `aaa003254ab7127a` and `7c8aa1b4f5cd6a3d` on both
sides.

## Changeset

On the docblock commit alone, `node
scripts/check-changeset-presence.mjs` answered exit 1, because both
files are published source of `@object-ui/types`. So a declaration is
owed.

The declaration uses empty frontmatter, not `patch`. Nothing a consumer
acts on moves. Both docblocks reach the build output only as comment
text: after `pnpm --filter @object-ui/types build`, the new `series`
sentence is in `dist/objectql.d.ts` and the route overview is in the zod
module's JS. At the time of writing, both changes that made the
sentences false (PR #10802 and PR #10821) are still pending changesets,
so no release has carried the false text.

## Gates

I derived these by hand from the root `package.json` and
`.github/workflows/`, because the objectstack `dispatch-gates.mjs` does
not cover this repository.

At head `950bf6406`:
- Exit 0 for all of these: `check-control-bytes`,
`check-new-cross-file-line-citations` ("0 new citation(s)"),
`check-changeset-presence` (empty-frontmatter pass),
`check-changeset-fixed`, `check-changeset-no-major`,
`check-changeset-overwrite`, `check-changeset-claims`,
`check-pending-changeset-literals`, `check-spec-symbol-derivation`,
`check-handler-key-read-sites` and `check-unreferenced-sources`.
- `pnpm exec vitest run packages/types/`: 264 files and 5854 tests
passed, exit 0.
- `pnpm exec vitest run` on the three script tests that read
`objectql.zod.ts` as text (`check-eager-closure-budget`,
`check-handler-key-read-sites` and `vite-types-zod-lazy`): 3 files and
241 tests passed, exit 0.

At `7449bc6a9`, which differs from the head only in the changeset's
wording (`git diff --stat` shows one file under `.changeset/`):
- `pnpm --filter @object-ui/types build` exit 0, and the dist
completeness check reported complete.
- `pnpm --filter @object-ui/types type-check` exit 0.
- `pnpm --filter @object-ui/types lint` exit 0, with 0 errors.

`node scripts/check-governed-queue-guard.mjs --test` over the three
paths answered NOT GOVERNED.

NOT MEASURED:
- `check:eager-closure`, reason: it reads every package's built dist,
and a comment-only diff moves no import edge. Its script test above ran
green.
- A downstream consumer type-check, reason: the `.d.ts` changes JSDoc
text only, and no type bytes move.

Known repo-wide red, left alone: `Spec Main Shape Gate` (objectui#10916,
owned by another seat).

## Acceptance notes

- Nothing pins either half of the corrected `series` sentence: a `type`
on a `{ dataKey }` entry compiles, and the mirror strips it. The probes
above were run once. This is an observation, not filed. Carrier: none.
- `main` has not moved from `733fd5ac6` on either file. PR #10927 edits
`objectql.zod.ts` at its imports and its tail, which are disjoint from
this docblock.

Implemented by the dispatched dev run of the `domain:spec` seat, session
`https://claude.ai/code/session_012UwY3ahMixEFkfTUxMVkYm`.

---
_Generated by [Claude
Code](https://claude.ai/code/session_012UwY3ahMixEFkfTUxMVkYm)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/10905-types-stale-docblocks.md

@@ -0,0 +1,20 @@
+---
+---
+
+Comment-only correction in `@object-ui/types`; releases nothing (objectui#10905).
+
+Two source docblocks still described shapes that objectui#10770 and objectui#7928
+changed earlier in this same unreleased batch. The `ObjectChartSchema.series`
+docblock said a `type` written on the `{ dataKey }` arm is an excess property on
+a literal typed by the interface; since the `{ name }` arm is the spec's
+`ChartSeries`, which declares `type`, that literal compiles, and only the zod
+mirror still strips the key. The zod route overview headed "WHERE THIS ARM IS
+INSTALLED" said a named view's `listViews` is unmirrored and named a `custom`
+issue under `options.kanban` there; `listViews` is the protocol's strict record
+by reference, which refuses a named view's `options` bag whole, and the named-view
+check reports at `listViews.KEY.kanban.groupBy` only.
+
+No behaviour, type, accept set or `.describe()` string moves. Both docblocks reach
+the build output only as comment text (the `series` one in the emitted `.d.ts`,
+the route overview in the zod module's JavaScript), so there is nothing for a
+consumer to act on.

packages/types/src/objectql.ts

@@ -4821,11 +4821,14 @@ export interface ObjectChartSchema extends BaseSchema {
    * that writes `type` on a `{ dataKey }` entry of an `object-chart` node;
    * none was named. Until one is, the per-series family override on this arm
    * is `chartType`, the renderer-internal spelling of `type`, which wins when
-   * an entry writes both. A `type` written on this arm anyway is an excess
-   * property on a literal typed by this interface, and the zod mirror's
-   * element is a plain `z.object`, which strips it: it parses clean and is
-   * dropped. The mirror's `.describe()` says the same, because that string is
-   * what an author-facing tool renders.
+   * an entry writes both. A `type` written on this arm anyway is NOT refused
+   * on a literal typed by this interface: the `{ name }` arm declares `type`,
+   * and excess-property checking on this union accepts a key that either arm
+   * declares when its value fits that declaration, so
+   * `{ dataKey: 'amount', type: 'line' }` compiles. The zod mirror's element
+   * for this arm is a plain `z.object`, which strips it: it parses clean and
+   * is dropped. The mirror's `.describe()` names the same omission, because
+   * that string is what an author-facing tool renders.
    *
    * An entry with neither `name` nor `dataKey` matches no arm and is refused;
    * `normalizeChartSchema` would drop it from the chart.

packages/types/src/zod/objectql.zod.ts

@@ -919,7 +919,7 @@ const KanbanStrayGroupByRefusal = aliasKeyRefusal(
 );
 
 /**
- * WHERE THIS ARM IS INSTALLED — TWO ROUTES, TWO NESTINGS EACH, ONE STRING.
+ * WHERE THIS ARM IS INSTALLED — TWO ROUTES, THREE NESTINGS, ONE STRING.
  *
  * `ListView` merges `{ ...schema.options?.kanban, ...schema.kanban }` before it
  * reads anything, so a stored view can carry the stray key under EITHER. The
@@ -930,11 +930,13 @@ const KanbanStrayGroupByRefusal = aliasKeyRefusal(
  * `options.kanban.groupBy`) — see `ListViewSchema.options` below.
  *
  * The second route is a named view on an `object-view` document, whose
- * `listViews` is unmirrored: nothing `ListViewSchema` declares reaches it, and
- * `generateViewSchema` merges the same two nestings. It takes the SAME guidance
- * through the named-view door (`custom` at `listViews.KEY.kanban.groupBy` and
- * `listViews.KEY.options.kanban.groupBy`, objectui#10321) — see
- * `checkNamedViewKanbanStrayGroupBy` below.
+ * `listViews` is the protocol's strict record by reference (objectui#7928), so
+ * nothing `ListViewSchema` declares reaches it, and it has ONE nesting: the
+ * record refuses a named view's `options` bag whole (`unrecognized_keys` naming
+ * `options`), and `generateViewSchema` no longer reads that bag. The `kanban`
+ * block takes the SAME guidance through the named-view door (`custom` at
+ * `listViews.KEY.kanban.groupBy`, objectui#10321, beside the protocol's own
+ * `unrecognized_keys`) — see `checkNamedViewKanbanStrayGroupBy` below.
  *
  * ⚠️ Covering the legacy nesting is not optional politeness: the retired
  * producer (`app-shell`'s `kanbanViewOptions`, objectui#8213) wrote into
@@ -943,8 +945,8 @@ const KanbanStrayGroupByRefusal = aliasKeyRefusal(
  * population re-grouped in silence — option A, which the ruling did not take.
  *
  * ⛔ Every channel takes ONE string, read off this arm's own `.description`,
- * so the message an author meets cannot depend on which route or nesting they
- * wrote.
+ * so the message an author meets at the key cannot depend on which of those
+ * three nestings they wrote it in.
  */
 
 const KanbanConfig = stripImportedDefaults(SpecKanbanConfigSchema).partial().extend({