Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit ca5d671

Browse files
docs(types): the content-channel tombstones state the BaseSchema premise in the tense it is true (objectui#9933) (#10417)
Fixes #9933 Clause-②: no `Clause-②: no` — JSDoc text only: every input's accept/reject verdict is byte-identical before and after, and no published declaration, member or export changes. Implemented by the `os-dev` dispatched from `domain:ui` seat 2, session `https://claude.ai/code/session_014mXUNuFomfj24w7s1pZzhN` (`mode:subagent`). Base `a707197`, head `f30b2c8`. ## What changed JSDoc comment text only, in `packages/types/src/{ai,complex,data-display,disclosure,feedback,form,layout,navigation,objectql,overlay,reports,views}.ts`, plus `.changeset/9933-stale-baseschema-premise-docblocks.md` (`'@object-ui/types': patch`). Every changed diff line in the 12 source files is a JSDoc continuation line (non-comment changed lines: 0), so no declaration, member, type or export moves. The stale premise came in two shapes. Each shape is byte-identical across its sites. Each was rewritten by an exact-match replacement that refused to write unless the per-file match count equalled the census count: | shape | sites | members | docblock header | |---|---|---|---| | A — "`body` and `children` are inherited-and-optional from {@link BaseSchema}, whose own docblock admits …" | 137 | 67 `body?: never`, 70 `children?: never` | REFUSED BY NAME (objectui#9256) — reads NEITHER content channel | | B — "`body` is inherited-and-optional from {@link BaseSchema}, whose own docblock admits …", with a line break between "whose own" and "docblock admits" | 9 | `body?: never` on `box`, `span`, `container`, `flex`, `stack`, `grid`, `scroll-area` (layout.ts), `form`, `toggle` (form.ts) | REFUSED BY NAME (objectui#8284) — reads `children` | Shape A now reads: > Before objectui#9256 tombstoned them here, `body` and `children` were both inherited-and-optional from {@link BaseSchema} — so authoring either here type-checked, parsed green through `.passthrough()`, and rendered NOTHING: no error, no warning, no element. objectui#6771 has since retired `body` on `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's own tombstone is what refuses it here. `SchemaRenderer` strips both keys out of the props bag it spreads, so neither reaches the component by another route either. Shape B now reads: > Before objectui#8284 tombstoned it here, `body` was inherited-and-optional from {@link BaseSchema} — so authoring it here type-checked, parsed green through `.passthrough()`, and rendered an EMPTY element with no error and no warning. Per component, the channel a renderer does not read is now tombstoned on both published faces (maintainer ruling, summon #17 decision batch #2, 2026-09-07), and objectui#6771 has since retired `body` on `BaseSchema` itself. Why this wording: - Each statement stays inline on its own member. This follows the reasoning of the objectui#9930 ruling C: no central block to cite, and no extra jump for a declarations reader. - The historical tail stays, written as history. - The quote of `BaseSchema`'s former docblock is dropped rather than moved into the past tense. `BaseSchema.children`'s own docblock already records it ("This docblock used to read …"). - Each present-tense clause was checked on the base: - `BaseSchema.body?: never` carries `@deprecated Retired spelling of children`. - `BaseSchema.children` is still declared as `SchemaNode | SchemaNode[]`. - `SchemaRenderer`'s metadata destructuring still strips `children` and `body` before it spreads the props. - All 137 shape-A headers name objectui#9256, and all 9 shape-B headers name objectui#8284. - Those tombstones predate PR objectui#9895 (objectui#6771), merged 2026-09-19T00:59Z, because the card counted them on that PR's head. ## Measurements — base `a707197` vs head `f30b2c8` | instrument | pathspec | base | head | |---|---|---|---| | the card's line-bound `git grep -c "whose own docblock admits"` | `packages/types/src` | 137 hits, 12 files | 0 (exit 1) | | comment-joined "whose own docblock admits" (command 1) | `packages/types/src` | 146 | 0 | | comment-joined present tense "(are or is) inherited-and-optional from {@link BaseSchema}" (command 1) | `packages/types/src` | 146 | 0 | | comment-joined "whose own docblock admits" (command 2) | whole tree | 146 | 0 | | comment-joined quote "some components use `children` instead of" (command 2) | whole tree | 149 | 3, all out of surface, see Acceptance notes | | firing control `git grep -c "REFUSED BY NAME"` | `packages/types/src` | 158 hits, 18 files | 158 hits, 18 files | | absent-token control `qqzz_absent_token_9999` | `packages/types/src` | 0 | 0 | | new text "has since retired `body` on `BaseSchema` itself;" / "… itself." (command 1) | `packages/types/src` | 0 / 0 | 137 / 9 | | the same new text in emitted `packages/types/dist/*.d.ts` after the build | `dist` | — | 137 / 9 | ⚠️ The card's 137 comes from a line-bound grep. The same premise also sits on 9 more sites (shape B) where "whose own" and "docblock admits" fall on different lines, so a single-line pattern cannot match them. All 9 are in `form.ts` and `layout.ts`, which are inside the claimed file surface, so this PR rewrites all 146. Command 1 (REF = `a707197` or `f30b2c8`). The enumeration and the read come from the same ref: ``` git archive REF packages/types/src | tar -xO | perl -0777 -ne 's/\n[ \t]*\*[ \t]?/ /g; my $a = () = /whose\s+own\s+docblock\s+admits/g; my $p = () = /\b(?:are|is)\s+inherited-and-optional\s+from\s+\{\@link\s+BaseSchema\}/g; my $c = () = /REFUSED\s+BY\s+NAME/g; my $z = () = /qqzz_absent_token_9999/g; my $na = () = /has\s+since\s+retired\s+`body`\s+on\s+`BaseSchema`\s+itself;/g; my $nb = () = /has\s+since\s+retired\s+`body`\s+on\s+`BaseSchema`\s+itself\./g; print "stale=$a present-tense=$p control=$c absent=$z newA=$na newB=$nb\n"' ``` Printed at `a707197`: `stale=146 present-tense=146 control=158 absent=0 newA=0 newB=0`. Printed at `f30b2c8`: `stale=0 present-tense=0 control=158 absent=0 newA=137 newB=9`. Command 2 (whole tree): ``` git archive REF | tar -xO 2>/dev/null | perl -0777 -ne 's/\n[ \t]*(?:\*|\/\/|>|#)?[ \t]?/ /g; my $a = () = /whose\s+own\s+docblock\s+admits/g; my $q = () = /some\s+components\s+use\s+[`\x27]children[`\x27]\s+instead\s+of/g; print "stale=$a quoted-sentence=$q\n"' ``` Emitted declarations, from `packages/types/dist/ai.d.ts` after `pnpm --filter '@object-ui/types^...' --filter @object-ui/types build`. The build ran on `54612db`, whose source is byte-identical to `f30b2c8`: the only later change is the changeset. ``` * Before objectui#9256 tombstoned them here, `body` and `children` were both * inherited-and-optional from {@link BaseSchema} — so authoring either here * type-checked, parsed green through `.passthrough()`, and rendered NOTHING: * no error, no warning, no element. objectui#6771 has since retired `body` on * `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's * own tombstone is what refuses it here. `SchemaRenderer` strips both keys * out of the props bag it spreads, so neither reaches the component by * another route either. ``` ## Local verification at `f30b2c8` - `pnpm --filter '@object-ui/types^...' --filter @object-ui/types build` (under the shared lock): `VERDICT command-exit 0`, `✓ dist completeness: 1 package(s) complete (130 emitted files verified)`. - `pnpm --filter @object-ui/types type-check` (`tsc --noEmit && tsc -p tsconfig.examples.json && tsc -p tsconfig.test.json`), then `pnpm exec vitest run --maxWorkers=2 packages/types/ scripts/__tests__/changeset-polarity-census.test.ts scripts/__tests__/check-changeset-no-major.test.ts scripts/__tests__/check-changeset-presence.test.ts` from the repo root: `Test Files 232 passed (232)`, `Tests 5249 passed (5249)`, `VERDICT command-exit 0`. - `node scripts/check-changeset-presence.mjs`: `✅ 12 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s): .changeset/9933-stale-baseschema-premise-docblocks.md.` Without the changeset it read `❌ 12 source file(s) of 1 released package(s) changed, and this change adds no changeset`. The bump is a `patch` and not an empty frontmatter, because of the gate header's own section "Comment text in `src` DOES reach a published `.d.ts`": the emitted `.d.ts` text moved, as the dist counts above show. - `node scripts/check-changeset-claims.mjs`: exit 0 (report-only). Self-contradiction reading: `✅ Every package declared across those 1 body(ies) is either not negated in its own prose`. The went-false reading lists 56 pending changesets that name a file this change touches. I re-read the ones about content channels (see the Acceptance notes). - `node scripts/check-changeset-overwrite.mjs`: `✅ No pre-existing changeset was modified or deleted.` - `node scripts/check-changeset-no-major.mjs`: `✅ No changeset declares a major bump.` - `node scripts/check-control-bytes.mjs`: `✅ check-control-bytes: OK (scanned 8472 tracked text file(s); skipped 85 binary).` Also self-scanned the changed files for control bytes: grep exit 1, no match. - `node scripts/check-new-cross-file-line-citations.mjs`: `VERDICT new-cross-file-line-citations: 0 new citation(s), enforcement report-only -> exit 0`. - `node scripts/check-pending-changeset-literals.mjs`: `✅ No test source names a pending changeset.` - `node scripts/check-doc-component-types.mjs`: `✅ Every documented component type is registered.` - `node scripts/check-comment-mask-corpus.mjs` (on `df2d696`, same source): `1 disagree … within the residue objectui#7882 is holding open`, exit 0. - `node scripts/check-governed-queue-guard.mjs --test` over the changed paths: `✅ NOT GOVERNED — 13 path(s) checked against 5 governed surface(s); none matched.` - Lint was narrowed to the 12 changed files. This is a measurement, not a skipped run, because of three pieces of evidence: 1. Population: `eslint.config.js` applies its `**/*.{ts,tsx}` blocks to these files. `pnpm exec eslint --format json` over the 12 files returned 12 result entries and no ignored-file notices. 2. Result: 12 files, 0 errors, 100 warnings, all `@typescript-eslint/no-explicit-any` on code lines. 3. Invariance: `eslint.config.js` has no `projectService`, `parserOptions.project` or `*TypeChecked` preset (grep count 0), so linting is not type-aware. A comment-only diff therefore cannot move the result for any untouched file. - NOT MEASURED: repo-wide `pnpm lint`, the full `pnpm test` shards, and E2E. CI runs these. ## Acceptance notes Out-of-surface findings. These were measured but not edited. None is class a, b or c, so no card is filed. - The former `BaseSchema` quote still appears in two places: - `.changeset/8284-content-channel-per-component.md`, as "`BaseSchema` declares two optional content channels and its own docblock admits that …". This changeset is pending, so it will publish into the CHANGELOG verbatim, in the same release as objectui#6771's changeset. - the header of `packages/types/src/__tests__/content-channel-per-component-8284.test.ts`, under "The defect this pins closed". Both are the defect as it stood when those files were written. The third quote hit, in `packages/types/src/base.ts`, is already in the past tense ("This docblock used to read …"). Carrier: none. - `.changeset/9256-content-channel-family-d.md`, in its AMENDED paragraph, says "The two twins are unchanged and go on inheriting `body` as the content slot". That became false with objectui#6771. The family-D test file records that each chatbot twin now refuses `body` with the NEITHER-channel tombstone, pointing at `requestBody`. The changeset is pending and will publish verbatim. Carrier: none. - The runtime refusal messages of shape B's zod twins say "`body` is inherited from `BaseSchema`, so an authored `body` parsed green here and rendered an EMPTY element". There are 2 in `packages/types/src/zod/form.zod.ts` and 7 in `packages/types/src/zod/layout.zod.ts`, one per `aliasKeyRefusal('body', 'children', …)` of the same nine components. They ship in `dist/zod/index.zod.js` and are shown to authors. The remedy they name (`children`) is correct; only the premise is out of date. They are not edited because this dispatch excludes `packages/types/src/zod/`: objectui#7715 is in flight there. Carrier: none — objectui#7715's branch has no diff yet, so it is not known to touch these messages. Guard: none added. A pin on the absence of the phrase would block only this wording, not the class, which is a premise about another declaration restated per member that goes stale when that declaration changes. After this change the tree holds no copy of the paragraph to paste from. So this PR adds no test pin and no CI gate. Overlap: draft PR objectui#8941 edits the `BulkActionDef.icon` docblock in `objectql.ts`. This PR's `objectql.ts` hunks sit only in the `ObjectGallerySchema` and `ObjectDataTableSchema` content-channel tombstones, so the two PRs do not share a hunk. Nothing under `packages/types/src/zod/` is touched. Labels: this PR writes none. objectui path labels come from `labeler.yml`. --- _Generated by [Claude Code](https://claude.ai/code/session_014mXUNuFomfj24w7s1pZzhN)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent ff14e29 commit ca5d671

13 files changed

Lines changed: 1170 additions & 876 deletions
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
'@object-ui/types': patch
3+
---
4+
5+
Correct a stale premise in the published declaration docs of the content-channel tombstones (objectui#9933).
6+
7+
The `body?: never` / `children?: never` docblocks of the components that read neither content channel (objectui#9256), and the `body?: never` docblocks of the components that read `children` (objectui#8284: `box`, `span`, `container`, `flex`, `stack`, `grid`, `scroll-area`, `form`, `toggle`), justified each tombstone with a present-tense premise: that `body` (and `children`) are inherited-and-optional from `BaseSchema`, and that `BaseSchema`'s own docblock concedes the two spellings without saying which component reads which. Since objectui#6771 retired the `body` spelling, that premise is false: `BaseSchema.body` is `never`, and `BaseSchema`'s own docblock no longer admits the two-spelling ambiguity. These docblocks ship in the emitted `.d.ts`, so a declarations reader was taught the premise the retirement removed.
8+
9+
Each paragraph now dates the inherited-and-optional state to before its own tombstone and states the present: `BaseSchema` refuses `body` itself and still declares `children`, which the neither-channel tombstone refuses. The rest of each docblock — what the renderer reads, how that was measured, and the `@deprecated` remedy — is unchanged.
10+
11+
Comment text only: no declaration, member, type or export moves, and every authored document type-checks and parses exactly as it did before.

‎packages/types/src/ai.ts‎

Lines changed: 48 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -201,12 +201,14 @@ export interface AIFormAssistSchema extends BaseSchema {
201201
* the props bag `SchemaRenderer` spreads rather than from `schema.*`, and
202202
* carries zero `body` / `children` reads either way.
203203
*
204-
* `body` and `children` are inherited-and-optional from {@link BaseSchema},
205-
* whose own docblock admits "some components use `children` instead of
206-
* `body`" without saying which — so authoring either here type-checked,
207-
* parsed green through `.passthrough()`, and rendered NOTHING: no error, no
208-
* warning, no element. `SchemaRenderer` strips both keys out of the props bag
209-
* it spreads, so neither reaches the component by another route either.
204+
* Before objectui#9256 tombstoned them here, `body` and `children` were both
205+
* inherited-and-optional from {@link BaseSchema} — so authoring either here
206+
* type-checked, parsed green through `.passthrough()`, and rendered NOTHING:
207+
* no error, no warning, no element. objectui#6771 has since retired `body` on
208+
* `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's
209+
* own tombstone is what refuses it here. `SchemaRenderer` strips both keys
210+
* out of the props bag it spreads, so neither reaches the component by
211+
* another route either.
210212
*
211213
* @deprecated Not a channel `ai-form-assist` reads — nothing renders it.
212214
*/
@@ -225,12 +227,14 @@ export interface AIFormAssistSchema extends BaseSchema {
225227
* the props bag `SchemaRenderer` spreads rather than from `schema.*`, and
226228
* carries zero `body` / `children` reads either way.
227229
*
228-
* `body` and `children` are inherited-and-optional from {@link BaseSchema},
229-
* whose own docblock admits "some components use `children` instead of
230-
* `body`" without saying which — so authoring either here type-checked,
231-
* parsed green through `.passthrough()`, and rendered NOTHING: no error, no
232-
* warning, no element. `SchemaRenderer` strips both keys out of the props bag
233-
* it spreads, so neither reaches the component by another route either.
230+
* Before objectui#9256 tombstoned them here, `body` and `children` were both
231+
* inherited-and-optional from {@link BaseSchema} — so authoring either here
232+
* type-checked, parsed green through `.passthrough()`, and rendered NOTHING:
233+
* no error, no warning, no element. objectui#6771 has since retired `body` on
234+
* `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's
235+
* own tombstone is what refuses it here. `SchemaRenderer` strips both keys
236+
* out of the props bag it spreads, so neither reaches the component by
237+
* another route either.
234238
*
235239
* @deprecated Not a channel `ai-form-assist` reads — nothing renders it.
236240
*/
@@ -384,12 +388,14 @@ export interface AIRecommendationsSchema extends BaseSchema {
384388
* the props bag `SchemaRenderer` spreads rather than from `schema.*`, and
385389
* carries zero `body` / `children` reads either way.
386390
*
387-
* `body` and `children` are inherited-and-optional from {@link BaseSchema},
388-
* whose own docblock admits "some components use `children` instead of
389-
* `body`" without saying which — so authoring either here type-checked,
390-
* parsed green through `.passthrough()`, and rendered NOTHING: no error, no
391-
* warning, no element. `SchemaRenderer` strips both keys out of the props bag
392-
* it spreads, so neither reaches the component by another route either.
391+
* Before objectui#9256 tombstoned them here, `body` and `children` were both
392+
* inherited-and-optional from {@link BaseSchema} — so authoring either here
393+
* type-checked, parsed green through `.passthrough()`, and rendered NOTHING:
394+
* no error, no warning, no element. objectui#6771 has since retired `body` on
395+
* `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's
396+
* own tombstone is what refuses it here. `SchemaRenderer` strips both keys
397+
* out of the props bag it spreads, so neither reaches the component by
398+
* another route either.
393399
*
394400
* @deprecated Not a channel `ai-recommendations` reads — nothing renders it.
395401
*/
@@ -408,12 +414,14 @@ export interface AIRecommendationsSchema extends BaseSchema {
408414
* the props bag `SchemaRenderer` spreads rather than from `schema.*`, and
409415
* carries zero `body` / `children` reads either way.
410416
*
411-
* `body` and `children` are inherited-and-optional from {@link BaseSchema},
412-
* whose own docblock admits "some components use `children` instead of
413-
* `body`" without saying which — so authoring either here type-checked,
414-
* parsed green through `.passthrough()`, and rendered NOTHING: no error, no
415-
* warning, no element. `SchemaRenderer` strips both keys out of the props bag
416-
* it spreads, so neither reaches the component by another route either.
417+
* Before objectui#9256 tombstoned them here, `body` and `children` were both
418+
* inherited-and-optional from {@link BaseSchema} — so authoring either here
419+
* type-checked, parsed green through `.passthrough()`, and rendered NOTHING:
420+
* no error, no warning, no element. objectui#6771 has since retired `body` on
421+
* `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's
422+
* own tombstone is what refuses it here. `SchemaRenderer` strips both keys
423+
* out of the props bag it spreads, so neither reaches the component by
424+
* another route either.
417425
*
418426
* @deprecated Not a channel `ai-recommendations` reads — nothing renders it.
419427
*/
@@ -549,12 +557,14 @@ export interface NLQuerySchema extends BaseSchema {
549557
* the props bag `SchemaRenderer` spreads rather than from `schema.*`, and
550558
* carries zero `body` / `children` reads either way.
551559
*
552-
* `body` and `children` are inherited-and-optional from {@link BaseSchema},
553-
* whose own docblock admits "some components use `children` instead of
554-
* `body`" without saying which — so authoring either here type-checked,
555-
* parsed green through `.passthrough()`, and rendered NOTHING: no error, no
556-
* warning, no element. `SchemaRenderer` strips both keys out of the props bag
557-
* it spreads, so neither reaches the component by another route either.
560+
* Before objectui#9256 tombstoned them here, `body` and `children` were both
561+
* inherited-and-optional from {@link BaseSchema} — so authoring either here
562+
* type-checked, parsed green through `.passthrough()`, and rendered NOTHING:
563+
* no error, no warning, no element. objectui#6771 has since retired `body` on
564+
* `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's
565+
* own tombstone is what refuses it here. `SchemaRenderer` strips both keys
566+
* out of the props bag it spreads, so neither reaches the component by
567+
* another route either.
558568
*
559569
* @deprecated Not a channel `nl-query` reads — nothing renders it.
560570
*/
@@ -573,12 +583,14 @@ export interface NLQuerySchema extends BaseSchema {
573583
* the props bag `SchemaRenderer` spreads rather than from `schema.*`, and
574584
* carries zero `body` / `children` reads either way.
575585
*
576-
* `body` and `children` are inherited-and-optional from {@link BaseSchema},
577-
* whose own docblock admits "some components use `children` instead of
578-
* `body`" without saying which — so authoring either here type-checked,
579-
* parsed green through `.passthrough()`, and rendered NOTHING: no error, no
580-
* warning, no element. `SchemaRenderer` strips both keys out of the props bag
581-
* it spreads, so neither reaches the component by another route either.
586+
* Before objectui#9256 tombstoned them here, `body` and `children` were both
587+
* inherited-and-optional from {@link BaseSchema} — so authoring either here
588+
* type-checked, parsed green through `.passthrough()`, and rendered NOTHING:
589+
* no error, no warning, no element. objectui#6771 has since retired `body` on
590+
* `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's
591+
* own tombstone is what refuses it here. `SchemaRenderer` strips both keys
592+
* out of the props bag it spreads, so neither reaches the component by
593+
* another route either.
582594
*
583595
* @deprecated Not a channel `nl-query` reads — nothing renders it.
584596
*/

0 commit comments

Comments
 (0)