From f8f9bc7742b74ee0a26e008ba75f392580e052b3 Mon Sep 17 00:00:00 2001
From: os-litant <litant.dev@proton.me>
Date: Wed, 2 Sep 2026 12:25:04 +0000
Subject: [PATCH] docs(components): stop teaching #6124's retired handler keys
 as authorable props
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

objectui#6124 (PR #7339) split the `on*` handler keys in two: 36 runtime
slots keep their function type, and 22 keys nothing reads became `?: never`
tombstones with named refusal arms on the zod mirror. Ten rows across eight
`content/docs` pages went on listing some of the retired 22 as callable
props — a key that is now a `tsc` error to assign and a refusal by name at
authoring time.

The card named three pages (`api/schema-reference.md`,
`data-display/tree-view.mdx`, `form/input-otp.mdx`, five rows); a whole-docs
census resolving each row's `(interface, key)` pair against the shipped
declaration found five more rows on five more pages —
`basic/button-group.mdx` (`ButtonGroupButton.onClick`), and `.onChange` on
`form/calendar.mdx`, `form/combobox.mdx`, `form/command.mdx`,
`form/radio-group.mdx`. A key NAME cannot decide this: `onChange` is retired
on 8 schemas and live on 14, and `input-otp.mdx` carries both dispositions
one line apart.

Seven pages have the retired rows REMOVED. `basic/button-group.mdx` is the
one "marked retired" page and not by taste: `button-group-doc-surface-6347`
asserts set equality between that page's `ButtonGroupButton` block and the
mirror's `.shape`, and a refusal arm is still a key of that shape, so the row
must stay — spelled `never`, with the node-type pointer the tombstone JSDoc
uses. That sibling pin's `onClick` case is updated to read the mirror's
refusal instead of restating the now-stale `() => void`.

The new pin measures the retired population off `packages/types/src` rather
than hand-listing it, flags rows (not prose), and carries six runtime-slot
rows as the blanket-sweep control — two of them on pages this change edits.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NRRumy89BYdW9ogbcdHTho
---
 .changeset/7340-docs-retired-handler-keys.md  |  17 +
 content/docs/api/schema-reference.md          |   2 -
 .../docs/components/basic/button-group.mdx    |   3 +-
 .../components/data-display/tree-view.mdx     |   4 +-
 content/docs/components/form/calendar.mdx     |   3 -
 content/docs/components/form/combobox.mdx     |   3 -
 content/docs/components/form/command.mdx      |   3 -
 content/docs/components/form/input-otp.mdx    |   1 -
 content/docs/components/form/radio-group.mdx  |   3 -
 .../button-group-doc-surface-6347.test.ts     |  28 +-
 ...ent-docs-retired-handler-keys-7340.test.ts | 383 ++++++++++++++++++
 11 files changed, 426 insertions(+), 24 deletions(-)
 create mode 100644 .changeset/7340-docs-retired-handler-keys.md
 create mode 100644 packages/types/src/__tests__/component-docs-retired-handler-keys-7340.test.ts

diff --git a/.changeset/7340-docs-retired-handler-keys.md b/.changeset/7340-docs-retired-handler-keys.md
new file mode 100644
index 0000000000..565c5caa64
--- /dev/null
+++ b/.changeset/7340-docs-retired-handler-keys.md
@@ -0,0 +1,17 @@
+---
+---
+
+Docs-only: ten rows across eight `content/docs` pages still listed one of
+objectui#6124's 22 RETIRED `on*` handler keys as a callable prop, after PR
+#7339 turned those keys into `?: never` tombstones with named refusal arms on
+the zod mirror. Seven pages have the rows removed;
+`components/basic/button-group.mdx` keeps its `ButtonGroupButton.onClick` row
+spelled `never` with the node-type pointer, because
+`button-group-doc-surface-6347.test.ts` asserts set equality between that block
+and the mirror's `.shape` and a refusal arm is still a key of that shape. A new
+test-only pin
+(`packages/types/src/__tests__/component-docs-retired-handler-keys-7340.test.ts`)
+measures the retired population off `packages/types/src` and holds every doc row
+whose `(interface, key)` pair resolves to a tombstone to the `never` spelling,
+with six runtime-slot rows as the blanket-sweep control (objectui#7340). No
+published package behaviour changes.
diff --git a/content/docs/api/schema-reference.md b/content/docs/api/schema-reference.md
index d4207cb9ca..7dd7b7d638 100644
--- a/content/docs/api/schema-reference.md
+++ b/content/docs/api/schema-reference.md
@@ -923,8 +923,6 @@ A drag-and-drop Kanban board with columns and cards.
 | `draggable` | `boolean` | Enable drag-and-drop between columns. |
 | `onCardMove` | `function` | Callback when a card is moved: `(cardId, fromColumn, toColumn, position)`. |
 | `onCardClick` | `function` | Callback when a card is clicked. |
-| `onColumnAdd` | `function` | Callback when a new column is added. |
-| `onCardAdd` | `function` | Callback when a new card is added to a column. |
 
 **Related:** [ObjectViewSchema](#objectviewschema), [ObjectGridSchema](#objectgridschema)
 
diff --git a/content/docs/components/basic/button-group.mdx b/content/docs/components/basic/button-group.mdx
index 71de2f2eb4..77d2f9bcc0 100644
--- a/content/docs/components/basic/button-group.mdx
+++ b/content/docs/components/basic/button-group.mdx
@@ -26,7 +26,8 @@ interface ButtonGroupButton {
   variant?: 'default' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link';
   size?: 'default' | 'sm' | 'lg' | 'icon';
   disabled?: boolean;             // Whether this button is disabled
-  onClick?: () => void;           // Runtime handler; not authorable in JSON
+  onClick?: never;                // RETIRED (objectui#6124) — author behaviour
+                                  // as a node type, e.g. an action:button node
   className?: string;             // Per-button CSS class
 }
 
diff --git a/content/docs/components/data-display/tree-view.mdx b/content/docs/components/data-display/tree-view.mdx
index 91b90a055d..6d3b17cc91 100644
--- a/content/docs/components/data-display/tree-view.mdx
+++ b/content/docs/components/data-display/tree-view.mdx
@@ -43,9 +43,7 @@ interface TreeViewSchema {
   showLines?: boolean;                  // Show connecting lines (default: true)
   
   // Events
-  onSelectChange?: (selectedIds: string[]) => void;  // Selection change handler
-  onExpandChange?: (expandedIds: string[]) => void;  // Expand change handler
-  onNodeClick?: (node: TreeNode) => void;            // Node click handler
+  onNodeClick?: (node: TreeNode) => void; // Node click handler
   
   // Styling
   className?: string;                   // Tailwind CSS classes
diff --git a/content/docs/components/form/calendar.mdx b/content/docs/components/form/calendar.mdx
index b86f54454a..c0e0213976 100644
--- a/content/docs/components/form/calendar.mdx
+++ b/content/docs/components/form/calendar.mdx
@@ -38,9 +38,6 @@ interface CalendarSchema {
   maxDate?: Date | string;                  // Maximum selectable date
   disabled?: boolean | string;              // boolean, or a predicate expression
   
-  // Events
-  onChange?: (date: Date | Date[] | undefined) => void;  // Date change handler
-  
   // Styling
   className?: string;                       // Tailwind CSS classes
   
diff --git a/content/docs/components/form/combobox.mdx b/content/docs/components/form/combobox.mdx
index a792335541..ac3713b0fb 100644
--- a/content/docs/components/form/combobox.mdx
+++ b/content/docs/components/form/combobox.mdx
@@ -38,9 +38,6 @@ interface ComboboxSchema {
   // Text
   placeholder?: string;           // Button placeholder
   
-  // Events
-  onChange?: (value: string) => void;
-  
   // States
   disabled?: boolean | string;   // boolean, or a predicate expression
   
diff --git a/content/docs/components/form/command.mdx b/content/docs/components/form/command.mdx
index 818d001722..b9ee3ed166 100644
--- a/content/docs/components/form/command.mdx
+++ b/content/docs/components/form/command.mdx
@@ -37,9 +37,6 @@ interface CommandSchema {
   groups: CommandGroup[];         // Command groups
   emptyText?: string;             // Text when no results
   
-  // Events
-  onChange?: (value: string) => void;
-  
   // Styling
   className?: string;
 }
diff --git a/content/docs/components/form/input-otp.mdx b/content/docs/components/form/input-otp.mdx
index 0598b05721..d68079ad04 100644
--- a/content/docs/components/form/input-otp.mdx
+++ b/content/docs/components/form/input-otp.mdx
@@ -33,7 +33,6 @@ interface InputOTPSchema {
   
   // Events
   onChange?: (value: string) => void;
-  onComplete?: (value: string) => void;
   
   // States
   disabled?: boolean | string;   // boolean, or a predicate expression
diff --git a/content/docs/components/form/radio-group.mdx b/content/docs/components/form/radio-group.mdx
index dab355e15c..2b28b631f7 100644
--- a/content/docs/components/form/radio-group.mdx
+++ b/content/docs/components/form/radio-group.mdx
@@ -46,9 +46,6 @@ interface RadioGroupSchema {
   // Layout
   orientation?: 'horizontal' | 'vertical';
   
-  // Events
-  onChange?: (value: string | number) => void;
-  
   // States
   disabled?: boolean | string;   // boolean, or a predicate expression
   
diff --git a/packages/types/src/__tests__/button-group-doc-surface-6347.test.ts b/packages/types/src/__tests__/button-group-doc-surface-6347.test.ts
index 684c9b6478..a77366b3b5 100644
--- a/packages/types/src/__tests__/button-group-doc-surface-6347.test.ts
+++ b/packages/types/src/__tests__/button-group-doc-surface-6347.test.ts
@@ -39,6 +39,17 @@
  * subset the card enumerated. A one-directional pin is what let the omissions
  * sit beside the corrections through two earlier passes over these pages.
  *
+ * ⚠️ `.onClick` is in that UNDER-stated list as HISTORY. objectui#6124 (PR
+ * #7339, ruling of 2026-08-30) RETIRED the key: the `button-group` renderer
+ * renders each `<Button>` without a click handler and never reads it, so the
+ * TypeScript face is now `onClick?: never` and the mirror member is a named
+ * refusal, `handlerKeyRefusal('onClick', 'retired', …)`. The page owes the row
+ * either way — a refusal arm is still a key of `.shape`, so the set equality
+ * above is what forced objectui#7340 to spell the row `never` on the page
+ * rather than delete it — but the row must no longer name a callable type.
+ * The `onClick` case below therefore reads the mirror's refusal instead of
+ * restating `() => void`.
+ *
  * ## The authority is the mirror's `.shape`, never parse acceptance
  *
  * `BaseSchema` is `.passthrough()` and carries `[key: string]: any`, so an
@@ -235,11 +246,18 @@ describe('button-group.mdx: the `ButtonGroupButton` block IS the shipped mirror
     expect(documentedLiterals(buttonDoc.get(key)?.typeText ?? '')).toEqual(shipped);
   });
 
-  it('documents `onClick` as a runtime slot, not something a JSON author supplies', () => {
-    // `onClick` is `() => void` / `z.function()`; objectui#4453 narrowed the
-    // runtime to `typeof === 'function'`, so an authored object is dropped.
-    expect(buttonDoc.get('onClick')?.typeText).toBe('() => void');
-    expect(buttonBody).toContain('not authorable in JSON');
+  it('documents `onClick` as the RETIRED tombstone it now is (objectui#6124)', () => {
+    // Read off the mirror rather than restated: a `handlerKeyRefusal` arm
+    // refuses EVERY value, a function included, which is what distinguishes a
+    // retired key from the runtime slots that kept `z.function()`. If #6124 is
+    // ever reversed this goes red here — at `packages/types`, where the
+    // decision would live — instead of leaving the page silently understated.
+    expect(buttonShape.onClick.safeParse(() => undefined).success).toBe(false);
+    expect(buttonShape.onClick.safeParse('anything').success).toBe(false);
+    expect(buttonDoc.get('onClick')?.typeText).toBe('never');
+    expect(buttonBody).toContain('RETIRED');
+    // The remedy the tombstone JSDoc and the refusal message both point at.
+    expect(buttonBody).toContain('action:button');
   });
 });
 
diff --git a/packages/types/src/__tests__/component-docs-retired-handler-keys-7340.test.ts b/packages/types/src/__tests__/component-docs-retired-handler-keys-7340.test.ts
new file mode 100644
index 0000000000..6fcd8dfdf9
--- /dev/null
+++ b/packages/types/src/__tests__/component-docs-retired-handler-keys-7340.test.ts
@@ -0,0 +1,383 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * No `content/docs` page teaches a RETIRED handler key as an authorable prop
+ * (objectui#7340, the docs half of the objectui#6124 ruling of 2026-08-30).
+ *
+ * ## Why a pin rather than "the docs gates went green"
+ *
+ * No gate can see this drift. These pages declare their own illustrative
+ * `interface` blocks and prop TABLES (objectui#6143):
+ * `check-doc-component-types` reads only the `type` STRING LITERALS out of docs
+ * code blocks, and `check-doc-snippet-types` compiles `ts`/`tsx` fences — every
+ * fence involved here is `plaintext`, and a markdown table is not a fence at
+ * all. So a member row may name any key at all and every gate stays green. Same
+ * hole `component-docs-disabled-inherited-7239.test.ts` and
+ * `button-group-doc-surface-6347.test.ts` record, one surface over.
+ *
+ * ## The defect this pins shut
+ *
+ * objectui#6124 (PR #7339) split the `on*` handler keys in two. 36 keys whose
+ * function value actually reaches a renderer keep their function type — a
+ * RUNTIME SLOT a React host supplies through props. 22 keys nothing reads
+ * became `?: never` tombstones on the TypeScript face and named refusal arms on
+ * the zod mirror (`handlerKeyRefusal(key, 'retired', …)`). Doc pages went on
+ * listing some of the retired 22 as callable props, teaching a key that is now
+ * a `tsc` error to assign and a refusal by name at authoring time.
+ *
+ * ## Why membership is `(interface, key)` and never the key NAME alone
+ *
+ * A name-level blacklist would be both wrong and unimplementable here: on this
+ * tree `onChange` is RETIRED on 8 schemas and LIVE on 14, `onClick` is RETIRED
+ * on 3 and LIVE on 8, `onComplete` is RETIRED on `InputOTPSchema` and LIVE on
+ * `BatchOperationConfig`. `input-otp.mdx` is the sharpest case: its `onChange`
+ * row is a live runtime slot sitting one line above the retired `onComplete`.
+ * The unit of the defect is therefore the pair, resolved against the shipped
+ * declaration — which is also what keeps this pin honest in the other
+ * direction: un-retiring a key makes the page right and this file's premise
+ * wrong, and it goes red pointing at `packages/types` instead of silently
+ * going on asserting a removal.
+ *
+ * ## What this file asserts, and why in this shape
+ *
+ *   1. CENSUS — the retired population is MEASURED off `packages/types/src`
+ *      (`on*?: never` members, anchored, attributed to their enclosing
+ *      interface), not hand-listed, and pinned at the count and per-file split
+ *      this card measured. #6124 moving its own population must be a decision,
+ *      not a silent widening of what this file waves through.
+ *   2. PAIR RULE — every doc row whose `(owner, key)` resolves to a retired
+ *      shipped member spells `never`. A page may still NAME a tombstone (that
+ *      is the "marked retired" disposition the card allows), but it may not
+ *      present a callable type for it. Offenders are reported as
+ *      `page:line owner.key -> typeText`, so a failure names the row.
+ *   3. NAME NET — for the retired keys with NO live declaration anywhere
+ *      (`onColumnAdd`, `onCardAdd`, `onSlideChange`, `onSendMessage`,
+ *      `onSelectChange`, `onExpandChange`, `onCollapsedChange`, `onConfirm` on
+ *      this tree), no row anywhere spells them callable, whatever owner name
+ *      the page used. This is the net for doc-LOCAL interface names, which rule
+ *      2 cannot resolve by construction (`plugins/*.mdx` document `Overview` /
+ *      `Features` / `Properties` blocks with no shipped counterpart).
+ *   4. CONTROL — six measured runtime-slot rows are present, callable, and
+ *      cross-checked against source as NOT `?: never`. This is the
+ *      blanket-sweep control: an edit that deleted every `on*` row under
+ *      `content/docs` turns these red, and rules 2 and 3 alone would call that
+ *      a pass. Two of the six sit on pages this card edited (`input-otp.mdx`
+ *      `onChange`, `schema-reference.md` `onCardMove` / `onCardClick`), which
+ *      is where an over-broad edit would land first.
+ *   5. PROSE — the reader flags rows, never mentions. Counter-probes feed it a
+ *      sentence naming a retired key and a JSON example key and assert neither
+ *      becomes a row, because "the retired `onComplete`" in running prose is
+ *      not a teaching row (and pages are free to write one).
+ *
+ * ## Dispositions, recorded so a later reader does not read them as drift
+ *
+ * Seven pages had the retired rows REMOVED (the card's preferred disposition;
+ * no page's prose depended on one). `basic/button-group.mdx` is the single
+ * "marked retired" page, and not by taste: `button-group-doc-surface-6347.test`
+ * asserts SET EQUALITY between that page's `ButtonGroupButton` block and the
+ * shipped mirror's `.shape`, and `onClick` is still a key of that shape (a
+ * refusal arm is a declared member). Removing the row would break that pin's
+ * central assertion; spelling it `never` with the node-type pointer satisfies
+ * both files. Assertion 6 pins that disposition explicitly so it reads as a
+ * decision rather than a page someone forgot.
+ *
+ * ## Boundary, stated rather than implied
+ *
+ * The scan covers `content/docs/**` only — the published docs site, which is
+ * the authoring surface this card is about. Package `README.md` files are a
+ * different population and are not read here (`plugin-chatbot/README.md` shows
+ * `onSendMessage` as a REACT PROP on `<ObjectChatbot>`, not as a schema key;
+ * that is a different contract and out of this card's scope).
+ *
+ * ## Predictions, written before the first run (red-first)
+ *
+ * On the unmodified `origin/main` @ `4704aa4bb` pages, with this file in place:
+ *
+ *   - rule 2 fails listing exactly 10 rows on 8 pages —
+ *     `api/schema-reference.md:926,927` (`KanbanSchema.onColumnAdd`,
+ *     `onCardAdd`), `components/basic/button-group.mdx:29`
+ *     (`ButtonGroupButton.onClick`), `components/data-display/tree-view.mdx:46,47`
+ *     (`TreeViewSchema.onSelectChange`, `onExpandChange`),
+ *     `components/form/calendar.mdx:42`, `components/form/combobox.mdx:42`,
+ *     `components/form/command.mdx:41`, `components/form/radio-group.mdx:50`
+ *     (`.onChange` on each), `components/form/input-otp.mdx:36`
+ *     (`InputOTPSchema.onComplete`);
+ *   - rule 3 fails listing the 4 of those whose key name is unambiguously
+ *     retired (`onColumnAdd`, `onCardAdd`, `onSelectChange`, `onExpandChange`);
+ *   - assertion 6 fails, because `button-group.mdx` spells `() => void`;
+ *   - the CENSUS, CONTROL and PROSE blocks stay GREEN — the defect is in the
+ *     pages' retired rows, and nothing about it touches the runtime-slot rows
+ *     or the reader. A run that reddened the control too would mean the reader
+ *     is broken, not that the pages are.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(HERE, '..', '..', '..', '..');
+const TYPES_DIR = join(REPO_ROOT, 'packages', 'types', 'src');
+const DOC_DIR = join(REPO_ROOT, 'content', 'docs');
+
+/* ── The shipped surface: every `on*` member, with its enclosing interface ── */
+
+const INTERFACE_RE = /^\s*(?:export\s+)?interface\s+([A-Za-z0-9_]+)/;
+const CLOSE_RE = /^\}/;
+const SHIPPED_MEMBER_RE = /^\s{2}(on[A-Z][A-Za-z0-9]*)\?:\s*(.+?);?\s*$/;
+
+interface ShippedMember {
+  readonly file: string;
+  readonly line: number;
+  readonly iface: string;
+  readonly key: string;
+  readonly type: string;
+}
+
+function shippedMembers(): ShippedMember[] {
+  const out: ShippedMember[] = [];
+  for (const file of readdirSync(TYPES_DIR)
+    .filter((f) => f.endsWith('.ts'))
+    .sort()) {
+    const lines = readFileSync(join(TYPES_DIR, file), 'utf8').split('\n');
+    let iface: string | null = null;
+    lines.forEach((raw, idx) => {
+      const decl = INTERFACE_RE.exec(raw);
+      if (decl) {
+        iface = decl[1];
+        return;
+      }
+      if (CLOSE_RE.test(raw)) {
+        iface = null;
+        return;
+      }
+      const member = SHIPPED_MEMBER_RE.exec(raw);
+      if (member && iface) {
+        out.push({ file, line: idx + 1, iface, key: member[1], type: member[2].trim() });
+      }
+    });
+  }
+  return out;
+}
+
+const SHIPPED = shippedMembers();
+const RETIRED = SHIPPED.filter((m) => m.type === 'never');
+const LIVE = SHIPPED.filter((m) => m.type !== 'never');
+
+/** `Iface.key` of every tombstoned member. */
+const RETIRED_PAIRS = new Set(RETIRED.map((m) => `${m.iface}.${m.key}`));
+/** `Iface.key` of every member that kept a callable type. */
+const LIVE_PAIRS = new Set(LIVE.map((m) => `${m.iface}.${m.key}`));
+/** Key NAMES that are retired everywhere they are declared. */
+const LIVE_NAMES = new Set(LIVE.map((m) => m.key));
+const UNAMBIGUOUSLY_RETIRED_NAMES = [...new Set(RETIRED.map((m) => m.key))]
+  .filter((name) => !LIVE_NAMES.has(name))
+  .sort();
+
+/* ── The documented surface: `on*` rows under `content/docs` ─────────────── */
+
+/** An interface member row: `  onFoo?: (x: T) => void;  // comment`. */
+const DOC_MEMBER_RE = /^\s{0,8}(on[A-Z][A-Za-z0-9]*)\?:\s*(\S.*)$/;
+/** A markdown prop-table row: ``| `onFoo` | `function` | … |``. */
+const DOC_TABLE_RE = /^\|\s*`(on[A-Z][A-Za-z0-9]*)`\s*\|\s*([^|]*)\|/;
+/** A section heading that owns the rows below it: `### KanbanSchema`. */
+const DOC_HEADING_RE = /^#{2,4}\s+`?([A-Za-z0-9_]+)`?\s*$/;
+const DOC_DECL_RE = /^\s*(?:export\s+)?(?:interface|type)\s+([A-Za-z0-9_]+)/;
+
+interface DocRow {
+  readonly page: string;
+  readonly line: number;
+  readonly owner: string;
+  readonly key: string;
+  readonly type: string;
+  readonly shape: 'member' | 'table';
+}
+
+/** Everything the row declares as the member's type, comments stripped. */
+function typeTextOf(rest: string): string {
+  const semi = rest.indexOf(';');
+  const body = semi === -1 ? rest : rest.slice(0, semi);
+  const comment = body.indexOf('//');
+  return (comment === -1 ? body : body.slice(0, comment)).trim();
+}
+
+function docPages(): string[] {
+  const out: string[] = [];
+  const walk = (dir: string, prefix: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+      a.name.localeCompare(b.name),
+    )) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(join(dir, entry.name), rel);
+      else if (/\.mdx?$/.test(entry.name)) out.push(rel);
+    }
+  };
+  walk(DOC_DIR, '');
+  return out;
+}
+
+/** Every `on*` row on one page, attributed to the declaration above it. */
+function rowsIn(page: string, source: string): DocRow[] {
+  const lines = source.split('\n');
+  const rows: DocRow[] = [];
+  lines.forEach((raw, idx) => {
+    const member = DOC_MEMBER_RE.exec(raw);
+    const table = DOC_TABLE_RE.exec(raw);
+    if (!member && !table) return;
+    const key = member ? member[1] : (table as RegExpExecArray)[1];
+    const type = typeTextOf(member ? member[2] : (table as RegExpExecArray)[2].replace(/`/g, ''));
+    let owner = '(unattributed)';
+    for (let i = idx - 1; i >= 0; i -= 1) {
+      const decl = DOC_DECL_RE.exec(lines[i]);
+      if (decl) {
+        owner = decl[1];
+        break;
+      }
+      const heading = DOC_HEADING_RE.exec(lines[i]);
+      if (heading) {
+        owner = heading[1];
+        break;
+      }
+    }
+    rows.push({ page, line: idx + 1, owner, key, type, shape: member ? 'member' : 'table' });
+  });
+  return rows;
+}
+
+const ROWS = docPages().flatMap((page) => rowsIn(page, readFileSync(join(DOC_DIR, page), 'utf8')));
+const rowFor = (page: string, owner: string, key: string): DocRow | undefined =>
+  ROWS.find((r) => r.page === page && r.owner === owner && r.key === key);
+const describeRow = (r: DocRow): string => `${r.page}:${r.line} ${r.owner}.${r.key} -> ${r.type}`;
+
+/** Runtime-slot rows measured present on this tree — the blanket-sweep control. */
+const CONTROL = [
+  { page: 'api/schema-reference.md', owner: 'KanbanSchema', key: 'onCardMove' },
+  { page: 'api/schema-reference.md', owner: 'KanbanSchema', key: 'onCardClick' },
+  { page: 'components/basic/pagination.mdx', owner: 'PaginationSchema', key: 'onPageChange' },
+  { page: 'components/data-display/tree-view.mdx', owner: 'TreeViewSchema', key: 'onNodeClick' },
+  { page: 'components/form/button.mdx', owner: 'ButtonSchema', key: 'onClick' },
+  { page: 'components/form/input-otp.mdx', owner: 'InputOTPSchema', key: 'onChange' },
+] as const;
+
+describe('the retired population is measured off the shipped tree (objectui#7340)', () => {
+  it('counts the `?: never` handler members #6124 left behind', () => {
+    const split: Record<string, number> = {};
+    for (const m of RETIRED) split[m.file] = (split[m.file] ?? 0) + 1;
+    expect({ total: RETIRED.length, split }).toEqual({
+      total: 22,
+      split: {
+        'complex.ts': 4,
+        'data-display.ts': 4,
+        'feedback.ts': 1,
+        'form.ts': 8,
+        'navigation.ts': 3,
+        'overlay.ts': 2,
+      },
+    });
+  });
+
+  it('the same reader still sees the runtime-slot half — the census is not a filter that eats everything', () => {
+    expect(LIVE.length).toBeGreaterThan(RETIRED.length);
+    // The pair is what the rules below resolve against, so it must be able to
+    // hold both dispositions for one NAME at once.
+    expect(RETIRED_PAIRS.has('InputOTPSchema.onComplete')).toBe(true);
+    expect(LIVE_PAIRS.has('InputOTPSchema.onChange')).toBe(true);
+  });
+
+  it('names the keys no shipped interface declares callable', () => {
+    expect(UNAMBIGUOUSLY_RETIRED_NAMES).toEqual([
+      'onCardAdd',
+      'onCollapsedChange',
+      'onColumnAdd',
+      'onConfirm',
+      'onExpandChange',
+      'onSelectChange',
+      'onSendMessage',
+      'onSlideChange',
+    ]);
+  });
+});
+
+describe('no page presents a retired member as callable (objectui#7340)', () => {
+  it('every documented row resolving to a tombstone spells `never`', () => {
+    const offenders = ROWS.filter(
+      (r) => RETIRED_PAIRS.has(`${r.owner}.${r.key}`) && r.type !== 'never',
+    ).map(describeRow);
+    expect(offenders.sort()).toEqual([]);
+  });
+
+  it('no row anywhere spells an unambiguously retired key as callable', () => {
+    const names = new Set(UNAMBIGUOUSLY_RETIRED_NAMES);
+    const offenders = ROWS.filter((r) => names.has(r.key) && r.type !== 'never').map(describeRow);
+    expect(offenders.sort()).toEqual([]);
+  });
+
+  it('`basic/button-group.mdx` keeps its tombstone row, marked retired with the node-type pointer', () => {
+    // The one "marked retired" disposition, forced by the set-equality
+    // assertion in `button-group-doc-surface-6347.test.ts`: a refusal arm is
+    // still a key of the mirror's `.shape`, so the page owes a row for it.
+    const row = rowFor('components/basic/button-group.mdx', 'ButtonGroupButton', 'onClick');
+    expect(row, 'no `onClick` row attributed to ButtonGroupButton').toBeDefined();
+    expect(row?.type).toBe('never');
+    expect(RETIRED_PAIRS.has('ButtonGroupButton.onClick')).toBe(true);
+    const page = readFileSync(join(DOC_DIR, 'components/basic/button-group.mdx'), 'utf8');
+    expect(page).toContain('RETIRED');
+    expect(page).toContain('action:button');
+  });
+
+  it('the walk-back reader attributed every row it found', () => {
+    expect(ROWS.filter((r) => r.owner === '(unattributed)').map(describeRow)).toEqual([]);
+  });
+});
+
+describe('runtime-slot rows are NOT flagged — the blanket-sweep control (objectui#7340)', () => {
+  it.each(CONTROL)('$page still documents $owner.$key', ({ page, owner, key }) => {
+    const row = rowFor(page, owner, key);
+    expect(row, `no \`${key}\` row attributed to ${owner} in ${page}`).toBeDefined();
+    expect(`${owner}.${key} -> ${row?.type}`).not.toBe(`${owner}.${key} -> never`);
+  });
+
+  it.each(CONTROL)('$owner.$key is a live member in the shipped tree', ({ owner, key }) => {
+    expect({ pair: `${owner}.${key}`, live: LIVE_PAIRS.has(`${owner}.${key}`) }).toEqual({
+      pair: `${owner}.${key}`,
+      live: true,
+    });
+    expect(RETIRED_PAIRS.has(`${owner}.${key}`)).toBe(false);
+  });
+});
+
+describe('the reader flags rows, never prose (objectui#7340)', () => {
+  it('a sentence naming a retired key is not a row', () => {
+    const prose = [
+      'The retired `onComplete` key is refused by name; author behaviour as a node type.',
+      'Use an action:button node instead of onSelectChange.',
+      '> Note: onColumnAdd was removed in objectui#6124.',
+    ].join('\n');
+    expect(rowsIn('probe.mdx', prose)).toEqual([]);
+  });
+
+  it('a JSON example key is not a row', () => {
+    expect(rowsIn('probe.mdx', '  "onColumnAdd": "doSomething",')).toEqual([]);
+  });
+
+  it('but a member row and a table row both ARE', () => {
+    const member = rowsIn('probe.mdx', 'interface KanbanSchema {\n  onColumnAdd?: () => void;\n}');
+    expect(member.map((r) => `${r.shape} ${r.owner}.${r.key} -> ${r.type}`)).toEqual([
+      'member KanbanSchema.onColumnAdd -> () => void',
+    ]);
+    const table = rowsIn(
+      'probe.mdx',
+      '### KanbanSchema\n\n| Property | Type |\n|---|---|\n| `onCardAdd` | `function` | Adds a card. |',
+    );
+    expect(table.map((r) => `${r.shape} ${r.owner}.${r.key} -> ${r.type}`)).toEqual([
+      'table KanbanSchema.onCardAdd -> function',
+    ]);
+  });
+
+  it('the scan really read the docs tree — non-vacuity for every rule above', () => {
+    expect(ROWS.length).toBeGreaterThan(50);
+    expect(ROWS.filter((r) => r.shape === 'table').length).toBeGreaterThan(0);
+    expect(ROWS.filter((r) => r.shape === 'member').length).toBeGreaterThan(0);
+  });
+});