basalt-ui 1.25.0 → 1.27.0

package/configs/oxlint-plugin.js

@@ -102,6 +102,15 @@ export const KNOWN_RULE_IDS = new Set([
   'hand-rolled-shell',
   'shadow-basalt-export',
   'raw-scroll-container',
+  'hand-rolled-filter',
+  'control-outside-home',
+  'control-size-literal',
+  'page-bar-budget',
+  'responsive-twin',
+  'search-literal-link',
+  'use-search-from-literal',
+  // `in-body-page-title` is BOTH a plugin rule and a guard kind — one id, two lanes, so one
+  // annotation waives both. It is listed once, below, with the guard kinds.
   'visx-boundary',
   'visx-tooltip',
   'token-layer-boundary',
@@ -136,6 +145,8 @@ export const KNOWN_RULE_IDS = new Set([
   'css-raw-surface',
   'inline-font-size',
   'hidden-inline-style',
+  'in-body-page-title',
+  'raw-selection-control',
 ])
 
 const ALLOW_RULE_TOKEN = /^(?:basalt\/)?([a-z][a-z0-9-]*)(?=$|[\s,:—–])/
@@ -654,12 +665,42 @@ const RAW_SCROLL_CONTAINER_MESSAGE =
   'node (BasaltStickToBottom, BasaltVirtualList) — add a theme-allow comment there. ' +
   '(basalt/raw-scroll-container)'
 
-// `overflowX` is deliberately absent: a horizontal bar doesn't reserve gutter width in a chrome
-// column, so a horizontally-scrolling code block or pinned-column table is its own legitimate
-// pattern, not a ScrollArea candidate. Only the vertical axis carries the doctrine.
+// `overflowX` is absent from the UNIVERSAL set for the original reason: a horizontal bar doesn't
+// reserve gutter width in a chrome column, so a horizontally-scrolling code block or pinned-column
+// table is its own legitimate pattern, not a ScrollArea candidate. It IS policed inside a home,
+// where the doctrine is the opposite one — see RAW_SCROLL_CONTAINER_HOME_MESSAGE.
 const OVERFLOW_KEYS = new Set(['overflow', 'overflowY'])
 const SCROLLING_VALUES = new Set(['auto', 'scroll'])
 
+const RAW_SCROLL_CONTAINER_HOME_MESSAGE =
+  'Horizontal scroll region inside a home — a page bar, a section header and a chart card never ' +
+  'scroll sideways and never wrap: overflow folds into a `More` menu (actions) or a `Filters (n)` ' +
+  'sheet (filters), computed by basalt from the typed BarAction[] (law C7). A sideways-scrolling ' +
+  'row of controls is the shape that law replaces. (basalt/raw-scroll-container)'
+
+/**
+ * The basalt home SLOT this node is written in — the owner binding of the enclosing `actions` /
+ * `filters` / `tabs` / `sync` / `filtersEnd` attribute, or undefined.
+ *
+ * The C7 widening is scoped to slot VALUES, not to "anywhere under a `Section`/`ChartCard`". It
+ * used to accept any such ancestor, body children included, which made every horizontally
+ * scrolling `<Table>`, `<pre>` or `CodeBlock` on a page an `error` carrying the C7 message about
+ * "a sideways-scrolling row of controls" — a claim that was false for exactly the pattern this
+ * rule's own comment above calls legitimate. A section BODY is page content, not a control row, so
+ * it is out of scope again, and the walk stops at the slot ATTRIBUTE (the boundary `SLOT_ATTRS`
+ * draws for every control rule).
+ *
+ * Scoped by ANCESTRY only, with no hoisted-binding lookup: a style object hoisted to a `const` has
+ * no JSX ancestor at all, so a hoisted `{ overflowX: 'auto' }` handed to a slot is a known false
+ * negative here — the same gap `chart-legend-literal` documents for a hoisted `items` array, and
+ * for the same reason (following it means local flow analysis for a bypass nobody reaches by
+ * accident).
+ */
+function enclosingHomeOwner(node) {
+  const attr = enclosingSlotAttribute(node)
+  return attr === undefined ? undefined : slotOwnerBinding(attr)
+}
+
 /**
  * Reports a `style` object property that turns a node into its own scroll container. Whether a raw
  * scroll box is wrong depends on who owns the scroll node, which no AST check can see — so the
@@ -668,6 +709,16 @@ const SCROLLING_VALUES = new Set(['auto', 'scroll'])
  * `BasaltVirtualList`, `ThreadTranscript`'s virtualized pane) declares that ownership with the
  * comment and moves on. Severity went `off` → `warn` (1.12.0) → `error` (1.13.0) once every live
  * site in the repo carried that declaration; the opt-out mechanism is identical at either level.
+ *
+ * **The C7 widening (wave 6) inherits that `error` with no grace runway, and that is a LIMITATION,
+ * not a decision.** oxlint severity is per rule ID, so a widened branch cannot ship `warn` while
+ * the incumbent branch stays `error` — the only way to buy a runway would have been a second rule
+ * id, which is the bundled-vs-split trade the three boundary rules were split apart over, in the
+ * opposite direction. What the widening does instead is stay narrow: `overflowX` and
+ * `ScrollArea scrollbars="x"` are policed ONLY inside a basalt home SLOT (see
+ * {@link enclosingHomeOwner}), which is where C7 actually applies, so the set of newly-rejected
+ * code is small enough to fix rather than schedule. A consumer who disagrees turns the whole rule
+ * down in their own config.
  */
 const rawScrollContainer = {
   meta: {
@@ -678,15 +729,57 @@ const rawScrollContainer = {
     schema: [],
   },
   create(context) {
+    const homes = new Set()
+    const mantineImports = new Map()
+    const ownTree = isBasaltOwnSource(getFilename(context))
+    // Both halves report at `Program:exit`: whether the enclosing `Section` is BASALT's is an
+    // import-list question, and the ancestry that finds the slot is only walkable during the visit.
+    const candidates = []
+
     return {
+      ImportDeclaration(node) {
+        collectBasaltImports(node, homes, ownTree)
+        collectMantineImports(node, mantineImports)
+      },
       Property(node) {
         const key = node.key
         const keyName =
           key.type === 'Identifier' ? key.name : key.type === 'Literal' ? key.value : undefined
-        if (typeof keyName !== 'string' || !OVERFLOW_KEYS.has(keyName)) return
+        if (typeof keyName !== 'string') return
+        const universal = OVERFLOW_KEYS.has(keyName)
+        if (!universal && keyName !== 'overflowX') return
         if (!isStringLiteral(node.value) || !SCROLLING_VALUES.has(node.value.value)) return
-        if (hasThemeAllow(context, node, 'raw-scroll-container')) return
-        context.report({ node, message: RAW_SCROLL_CONTAINER_MESSAGE })
+        candidates.push({ node, universal, home: universal ? undefined : enclosingHomeOwner(node) })
+      },
+      // `<ScrollArea scrollbars="x">` — the same horizontal scroll region written as a component.
+      // Only inside a home, exactly like the `overflowX` half above; a ScrollArea is otherwise the
+      // shape this whole rule steers people TOWARD. Mantine-provenanced like every other tag test:
+      // a consumer's own `ScrollArea` wrapper is not the component this doctrine is about.
+      JSXAttribute(node) {
+        if (node.name?.name !== 'scrollbars') return
+        const value = unwrapExpressionContainer(node.value)
+        if (!isStringLiteral(value) || value.value !== 'x') return
+        const owner = node.parent
+        if (owner === null || owner === undefined || owner.type !== 'JSXOpeningElement') return
+        candidates.push({
+          node,
+          universal: false,
+          home: enclosingHomeOwner(node),
+          name: owner.name,
+        })
+      },
+      'Program:exit'() {
+        for (const { node, universal, home, name } of candidates) {
+          // The C7 widening: only inside a BASALT home slot (see enclosingHomeOwner).
+          if (!universal && (home === undefined || !homes.has(home))) continue
+          if (name !== undefined && resolveMantineTag(name, mantineImports) !== 'ScrollArea')
+            continue
+          if (hasThemeAllow(context, node, 'raw-scroll-container')) continue
+          context.report({
+            node,
+            message: universal ? RAW_SCROLL_CONTAINER_MESSAGE : RAW_SCROLL_CONTAINER_HOME_MESSAGE,
+          })
+        }
       },
     }
   },
@@ -1463,6 +1556,107 @@ const BASALT_EXPORTS = (() => {
   return names
 })()
 
+/**
+ * Renames that ARE the collision, spelled out because the name no longer collides.
+ *
+ * `BASALT_EXPORTS` catches a fork that kept basalt's name. The commoner shape is a fork that
+ * renamed it: argo's `PageHeader`, linewatch's `WindowSelector`, rb's `HeroCard`. Each of these is
+ * the same composite under a different word, so the tripwire has to name the words — and unlike the
+ * barrel read, this table is hand-maintained by construction: there is no artifact to derive
+ * "someone else's word for `Section`" from. Keep it in step with `docs/CONTROLS-SPEC.md` §6.
+ *
+ * Advisory, permanently (see {@link PLUGIN_RULE_ADVISORY}): a name is evidence, never proof.
+ */
+const SHADOW_ALIASES = {
+  PageSection: 'Section',
+  SectionTitle: 'Section',
+  SectionHeading: 'Section',
+  WindowSelector: 'RangeFilter',
+  RangeSelector: 'RangeFilter',
+  DateFilter: 'RangeFilter',
+  ViewSwitch: 'ViewTabs',
+  ViewToggle: 'ViewTabs',
+  RefreshButton: 'SyncButton',
+  SyncControl: 'SyncButton',
+  SyncStatusButton: 'SyncButton',
+  PageHeader: 'PageBar',
+  FilterBar: 'PageBar',
+  HeroCard: 'StatCard',
+  HeroStats: 'StatCard',
+  ButtonGroup: 'ControlGroup',
+  ButtonRow: 'ControlGroup',
+  JoinedButtons: 'ControlGroup',
+}
+
+/**
+ * The basalt export NAMES a file imports, each mapped to the LOCAL bindings it arrived under —
+ * `StatCard → {StatCard}` for `import { StatCard }`, `StatCard → {BaseStatCard}` for
+ * `import { StatCard as BaseStatCard }`.
+ *
+ * The counterpart of {@link collectBasaltImports}, keyed the other way round: that one collects
+ * LOCAL names (is this `<Section>` basalt's?), this one is keyed by the CANONICAL export (does this
+ * file compose basalt's `StatCard` at all?). An alias is precisely the case that separates them —
+ * a wrapper importing `StatCard as BaseStatCard` composes `StatCard`, and a set of local names
+ * would answer `BaseStatCard`. The local half is carried alongside because an import alone is not
+ * composition: the caller has to check the binding is REFERENCED (see
+ * {@link isValueReferencePosition}).
+ *
+ * TYPE-ONLY specifiers are skipped, declaration-level and per-specifier, exactly as
+ * `agent-no-raw-usechat` skips them: `import type { StatCard }` is erased at compile time, so a fork
+ * copying the original's props through `ComponentProps<typeof StatCard>` composes nothing at all.
+ *
+ * Only the package name and its subpaths; no relative half, because `shadow-basalt-export` already
+ * returns early inside basalt's own source, where a relative import would be the dogfood lane.
+ */
+function collectBasaltImportedNames(node, into) {
+  const source = node.source?.value
+  if (typeof source !== 'string' || !BASALT_IMPORT_SOURCE.test(source)) return
+  if (node.importKind === 'type') return
+  for (const spec of node.specifiers ?? []) {
+    if (spec.importKind === 'type') continue
+    const imported = spec.imported?.name ?? spec.imported?.value
+    const local = spec.local?.name
+    if (typeof imported !== 'string' || typeof local !== 'string') continue
+    const locals = into.get(imported)
+    if (locals === undefined) into.set(imported, new Set([local]))
+    else locals.add(local)
+  }
+}
+
+/** The positions an `Identifier`/`JSXIdentifier` occupies WITHOUT referencing a value. */
+const NON_VALUE_IDENTIFIER_PARENTS = new Set([
+  // The binding's own declaration, not a use of it.
+  'ImportSpecifier',
+  'ImportDefaultSpecifier',
+  'ImportNamespaceSpecifier',
+  // A JSX attribute's NAME (`value={…}`), not its value.
+  'JSXAttribute',
+])
+
+/**
+ * Does this identifier REFERENCE a value, rather than declare or type-position it?
+ *
+ * The type half matters as much as the import half: `typeof StatCard` parses as a `TSTypeQuery`
+ * around a plain `Identifier`, so a value import used only in a type is indistinguishable from a
+ * rendered one without this test — and that shape (a fork copying the original's props) is the
+ * whole reason the composition check exists.
+ */
+function isValueReferencePosition(node) {
+  const parentType = node.parent?.type
+  if (typeof parentType !== 'string') return false
+  return !parentType.startsWith('TS') && !NON_VALUE_IDENTIFIER_PARENTS.has(parentType)
+}
+
+function shadowAliasMessage(name, canonical) {
+  return (
+    `Local component '${name}' is a renamed '${canonical}' — basalt ships that composite, and a ` +
+    'renamed fork is the shape the name-collision half of this rule can never see (laws C8/C12). ' +
+    `Import ${canonical} from 'basalt-ui' (or 'basalt-ui/controls') instead of re-rolling it; if ` +
+    'this genuinely is a different component, rename it and the rule goes quiet. ' +
+    '(basalt/shadow-basalt-export)'
+  )
+}
+
 function shadowBasaltExportMessage(name) {
   return (
     `Local component '${name}' collides with the basalt-ui export of the same name — import it ` +
@@ -1501,26 +1695,86 @@ const shadowBasaltExport = {
     // obsidian's React-free `obsidian-vault-core` took the report and had to waive it.
     if (filename.length === 0 || !isBasaltScopedFile(filename)) return {}
 
-    const report = (node, name) => {
-      if (typeof name !== 'string' || !BASALT_EXPORTS.has(name)) return
-      if (hasThemeAllow(context, node, 'shadow-basalt-export')) return
-      context.report({ node, message: shadowBasaltExportMessage(name) })
+    // Candidates are BUFFERED and judged at `Program:exit`, the same shape the chart and control
+    // rules use: the alias exemption below needs the file's whole import list AND every reference in
+    // the file, and a declaration hoisted above its imports would otherwise be judged against an
+    // empty one.
+    /** Canonical basalt export → the local bindings it was imported under (value imports only). */
+    const basaltImportedNames = new Map()
+    /** Every local name the file REFERENCES as a value — the composition half of the exemption. */
+    const referencedLocals = new Set()
+    const candidates = []
+
+    /** Does the file compose basalt's `canonical` — imported as a value AND referenced? */
+    const composes = (canonical) => {
+      const locals = basaltImportedNames.get(canonical)
+      if (locals === undefined) return false
+      for (const local of locals) {
+        if (referencedLocals.has(local)) return true
+      }
+      return false
+    }
+
+    const noteReference = (node) => {
+      if (typeof node.name !== 'string' || !isValueReferencePosition(node)) return
+      referencedLocals.add(node.name)
+    }
+
+    const note = (node, name) => {
+      if (typeof name !== 'string') return
+      const alias = Object.hasOwn(SHADOW_ALIASES, name) ? SHADOW_ALIASES[name] : undefined
+      if (!BASALT_EXPORTS.has(name) && alias === undefined) return
+      candidates.push({ node, name, alias })
     }
 
     return {
+      ImportDeclaration(node) {
+        collectBasaltImportedNames(node, basaltImportedNames)
+      },
+      // Both halves are needed and neither subsumes the other: a JSX tag is a `JSXIdentifier`
+      // (`<Base/>`), while every other use of the same binding is an `Identifier`
+      // (`component={Base}`, `createElement(Base)`, `memo(Base)`).
+      Identifier(node) {
+        noteReference(node)
+      },
+      JSXIdentifier(node) {
+        noteReference(node)
+      },
       FunctionDeclaration(node) {
-        report(node, node.id?.name)
+        note(node, node.id?.name)
       },
       VariableDeclarator(node) {
         if (!isComponentInit(node.init)) return
-        report(node, node.id?.name)
+        note(node, node.id?.name)
       },
       // A class only counts when it EXTENDS something — a legacy class component. basalt ships no
       // class components, so a standalone `class X {}` sharing a name with one of its exports is a
       // collision between two unrelated things, not a fork.
       ClassDeclaration(node) {
         if (node.superClass === null || node.superClass === undefined) return
-        report(node, node.id?.name)
+        note(node, node.id?.name)
+      },
+      'Program:exit'() {
+        for (const { node, name, alias } of candidates) {
+          // A file that COMPOSES the export it renames is a wrapper, not a fork, and the advice
+          // ("import StatCard instead of re-rolling it") is already followed — argo's three hero
+          // cards each imported `StatCard` and wrapped it, and each took a warn for it.
+          //
+          // COMPOSES, not "imports": an import the file never references is not composition, and the
+          // two shapes that reach here silently are the ones a fork actually writes — a type-only
+          // `import type { StatCard }` feeding `ComponentProps<typeof StatCard>` (props copied,
+          // nothing rendered) and a dead import left behind after the body was re-rolled. Both used
+          // to exempt the whole file.
+          //
+          // The collision half is deliberately NOT exempted either way: a local `StatCard` beside an
+          // `import { StatCard as Base }` is a fork that kept the name AND kept a piece of the
+          // original, which is the shape this rule most wants to see.
+          if (alias !== undefined && composes(alias)) continue
+          if (hasThemeAllow(context, node, 'shadow-basalt-export')) continue
+          const message =
+            alias === undefined ? shadowBasaltExportMessage(name) : shadowAliasMessage(name, alias)
+          context.report({ node, message })
+        }
       },
     }
   },
@@ -1600,35 +1854,1202 @@ const handRolledShell = {
   },
 }
 
+// ── Control homes — the shared slot-ancestry walk (C1/C5, docs/CONTROLS-SPEC.md §6) ─────────────
+
+/**
+ * The slot props a control enters a TIERED home through (law C1). A control is only ever IN one of
+ * these homes by being the value of one of these props — never by sitting in a home's children,
+ * which is the body form (a `Section`'s own content, a `SettingsSection`'s rows) and carries no tier
+ * obligation at all.
+ *
+ * **`control` is deliberately absent, and `SettingsRow` with it** (see {@link SLOT_OWNER_TAGS}):
+ * `SettingsRow.control` is law C1's THIRD home, the form row, and a form keeps Mantine's own `md`
+ * tier (`controlHeight` 42 — `docs/CONTROLS-SPEC.md` §5, unchanged). So a raw `Select` bound to a
+ * setting is legitimate there and a `size` literal there is not a tier violation; only
+ * `control-outside-home` cares about a settings row at all, and it treats it as a home
+ * (`CONTROL_HOST_TAGS`) so nothing fires inside one. The two tier rules would otherwise have told
+ * every settings page in every consumer to drop a prop that is what keeps the row at the form tier
+ * — `src/dashboard/settings-section.tsx` wraps `actions` in `CtlSlot`, never `control`.
+ */
+const SLOT_ATTRS = new Set(['actions', 'filters', 'tabs', 'sync', 'filtersEnd'])
+
+/**
+ * The elements whose slot props ARE tiered homes. All THREE halves of the test matter: `actions` on
+ * a consumer's own `<Toolbar actions={…}>` is not a basalt home, a `Section`'s CHILDREN are not a
+ * slot (so the walk stops at the slot ATTRIBUTE, never at the element), and the tag must resolve to
+ * a component imported FROM basalt ({@link collectBasaltImports}) — `Section` is one of the most
+ * common local component names there is, and matching it by bare name made a consumer's own
+ * section an `error`-level tiered home.
+ *
+ * `SettingsSection` is here for its `actions` header slot (`CtlSlot`-wrapped); `SettingsRow` is
+ * NOT — its `control` is the form-row home and keeps Mantine's `md` tier. See {@link SLOT_ATTRS}.
+ */
+const SLOT_OWNER_TAGS = new Set([
+  'PageBar',
+  'Section',
+  'WidgetHeader',
+  'ChartCard',
+  'StatCard',
+  'BasaltDataTable',
+  'SettingsSection',
+  'FilterSet',
+])
+
+/**
+ * Raw Mantine selection controls — the shape a store-bound basalt filter replaces. Membership is
+ * checked against the file's `@mantine/*` IMPORTS, not the bare tag name: a consumer's own
+ * `<Select>` (a wrapper, a re-export, a different component entirely) is not the Mantine one, and
+ * these rules ship to consumers.
+ */
+const RAW_FILTER_TAGS = new Set([
+  'SegmentedControl',
+  'Select',
+  'MultiSelect',
+  'NativeSelect',
+  'DatePickerInput',
+  'DateInput',
+  'TagsInput',
+  'Chip.Group',
+])
+
+/** The bound controls a home is SUPPOSED to hold — `basalt-ui/controls`, each over a FieldHandle. */
+const BOUND_TAGS = new Set([
+  'RangeFilter',
+  'CompareFilter',
+  'SelectFilter',
+  'MultiSelectFilter',
+  'NumberFilter',
+  'SearchFilter',
+  'ToggleFilter',
+  'ViewTabs',
+])
+
+/**
+ * The names whose DECLARATION means this file defines a basalt control rather than consuming one —
+ * the owner exemption, the same shape as `hand-rolled-plot`'s `notesOwnerDefinition`: a rule that
+ * says "use a bound control" cannot fire inside the module that IS the bound control.
+ */
+const CONTROL_OWNER_NAMES = new Set([
+  ...BOUND_TAGS,
+  'FilterSet',
+  'FilterPill',
+  'SyncButton',
+  'ActionGroup',
+  'OverflowMenu',
+  'CtlSlot',
+])
+
+/**
+ * Where a raw selection control legitimately lives outside a TIERED home: a settings row, an
+ * overlay, a composer. Every one of these is a place the tier does not apply, so the advice ("move
+ * it into a home slot") would be wrong rather than merely unwelcome.
+ *
+ * `SettingsRow` is the form row — law C1's third home, not an exception to C1 — so
+ * `control-outside-home` treating it as a home is the whole of the enforcement a settings page
+ * gets, and the two tier rules deliberately do not reach inside it (see {@link SLOT_ATTRS}).
+ *
+ * Declared with the shared slot walk rather than beside `control-outside-home` because three rules
+ * read it: that rule's ancestry exemption, and {@link hostedInsideSlot} for the two tier rules.
+ */
+const CONTROL_HOST_TAGS = new Set([
+  'SettingsRow',
+  'Modal',
+  'Drawer',
+  'Popover.Dropdown',
+  'Menu.Dropdown',
+  'Composer',
+])
+
+/**
+ * A file whose NAME declares it is an overlay's or a form's own body — the cross-file half of
+ * {@link CONTROL_HOST_TAGS}, and the one exemption here that is a CONVENTION rather than a fact
+ * about the AST.
+ *
+ * It exists because law C1's cross-file case is explicitly advisory (`docs/CONTROLS-SPEC.md` §6,
+ * "Honest coverage") and `control-outside-home` was paying for it in false positives: argo's
+ * wave-7 run left 9 warns, all of them a `Select`/`SegmentedControl` inside a `*-modal.tsx` or
+ * `*-form.tsx` whose `<Modal>` is rendered by the PARENT route. Nothing in the flagged file can see
+ * the overlay, so no ancestry walk — however deep — will ever reach it, and the alternative is 9
+ * `theme-allow-file` comments that say what the filename already says.
+ *
+ * The trade is stated plainly: this exempts a whole file on a naming convention, so a `Select` that
+ * genuinely belongs in a page bar goes unreported if it is written in `filters-panel.tsx`. That is
+ * the same bargain `@mantine/form` already buys and a strictly smaller one than promoting the rule
+ * with 9 known false positives. `-panel.tsx` is the loosest member and the one to reconsider first
+ * if the set ever needs narrowing.
+ *
+ * Basename only — a `modal/` DIRECTORY is not the convention, because a directory of modals holds
+ * the page pieces around them too.
+ */
+const OVERLAY_CONVENTION_FILE = /(?:^|\/)[^/]*-(?:modal|drawer|popover|panel|form)\.[jt]sx$/
+
+/** How far an ancestry walk climbs before giving up — a JSX tree this deep is not a slot value. */
+const ANCESTRY_MAX_DEPTH = 60
+
+/** A JSX tag name as written: `Select`, or `Chip.Group` for a member tag. */
+function jsxTagName(nameNode) {
+  if (nameNode === null || nameNode === undefined) return undefined
+  if (typeof nameNode.name === 'string') return nameNode.name
+  const object = jsxTagName(nameNode.object)
+  const property = nameNode.property?.name
+  if (typeof object !== 'string' || typeof property !== 'string') return undefined
+  return `${object}.${property}`
+}
+
+/** The BINDING a JSX tag resolves through — `Chip` for `<Chip.Group>`, `Select` for `<Select>`. */
+function jsxRootName(nameNode) {
+  if (nameNode === null || nameNode === undefined) return undefined
+  if (typeof nameNode.name === 'string') return nameNode.name
+  return jsxRootName(nameNode.object)
+}
+
+/** The value a namespace import (`import * as M from '@mantine/core'`) records for its local name. */
+const MANTINE_NAMESPACE = Symbol('mantine-namespace')
+
+/**
+ * Local name → the `@mantine/*` name it was imported UNDER — the provenance test the tag rules
+ * apply, and a MAP rather than a set because the two are not the same string. `Select as
+ * MantineSelect` is the canonical way a consumer wraps a Mantine component, and keying membership
+ * on the local name meant `<MantineSelect value onChange/>` in a slot — the exact C1/C3 violation
+ * `hand-rolled-filter` exists for — was invisible. A namespace import records
+ * {@link MANTINE_NAMESPACE} so `<M.SegmentedControl>` resolves through the member path instead.
+ */
+function collectMantineImports(node, into) {
+  const source = node.source?.value
+  if (typeof source !== 'string' || !source.startsWith('@mantine/')) return
+  for (const spec of node.specifiers ?? []) {
+    const local = spec.local?.name
+    if (typeof local !== 'string') continue
+    if (spec.type === 'ImportNamespaceSpecifier') into.set(local, MANTINE_NAMESPACE)
+    else into.set(local, spec.imported?.name ?? spec.imported?.value ?? local)
+  }
+}
+
+/**
+ * The `@mantine/*` name a JSX tag resolves to, or undefined when the tag is not a Mantine binding.
+ *
+ * `<Select>` → `Select`; `import { Select as MantineSelect }` + `<MantineSelect>` → `Select`;
+ * `import { Chip as C }` + `<C.Group>` → `Chip.Group`; `import * as M` + `<M.SegmentedControl>` →
+ * `SegmentedControl`. Resolution already implies provenance, so a caller tests the RESULT against
+ * `RAW_FILTER_TAGS` and needs no separate import-membership check.
+ */
+function resolveMantineTag(nameNode, mantineImports) {
+  const tag = jsxTagName(nameNode)
+  const root = jsxRootName(nameNode)
+  if (tag === undefined || root === undefined) return undefined
+  const imported = mantineImports.get(root)
+  if (imported === undefined) return undefined
+  const member = tag.slice(root.length)
+  if (imported !== MANTINE_NAMESPACE) return `${imported}${member}`
+  return member === '' ? undefined : member.slice(1)
+}
+
+/** The package's own `src/` — where a RELATIVE import of `WidgetHeader` is still basalt's own. */
+const BASALT_OWN_SRC = `${resolvePath(PACKAGE_ROOT, 'src')}/`
+
+/** `basalt-ui` and every published subpath — the sources a home component is imported FROM. */
+const BASALT_IMPORT_SOURCE = /^basalt-ui(?:\/|$)/
+
+/** A relative specifier — `./section`, `../widget-header`. */
+const RELATIVE_IMPORT_SOURCE = /^\.\.?\//
+
+/** Is the linted file part of basalt's OWN source tree — the dogfood side of the owner test? */
+function isBasaltOwnSource(filename) {
+  return filename.startsWith(BASALT_OWN_SRC)
+}
+
+/**
+ * Local names that resolve to a basalt HOME component — the owner-tag counterpart of
+ * {@link collectMantineImports}, and for the same reason: `Section` is one of the most common local
+ * component names there is (a marketing page, a docs layout), and reading a consumer's own
+ * `<Section actions={…}>` as a tiered home made two `error`-level rules fire on code basalt has no
+ * claim over.
+ *
+ * A relative import counts only inside basalt's own `src/` (`ownTree`), where `section.tsx` and
+ * `data-table.tsx` render `<WidgetHeader actions={…}>`/`<FilterSet>` through `../widget-header`
+ * rather than through the package name — without that half the dogfood surface goes silent, which
+ * is the blind spot that let the 1.4.0 regression reach consumers.
+ *
+ * Known accepted false negative: a consumer re-exporting basalt's `Section` through their own
+ * barrel (`from '@/ui'`) — the same gap the Mantine provenance test already accepts.
+ */
+function collectBasaltImports(node, into, ownTree) {
+  const source = node.source?.value
+  if (typeof source !== 'string') return
+  if (!BASALT_IMPORT_SOURCE.test(source) && !(ownTree && RELATIVE_IMPORT_SOURCE.test(source))) {
+    return
+  }
+  for (const spec of node.specifiers ?? []) {
+    if (spec.local?.name !== undefined) into.add(spec.local.name)
+  }
+}
+
+/**
+ * {@link collectBasaltImports} as a local→EXPORTED map — the same provenance test, keyed so a caller
+ * can ask WHICH home it found rather than only whether it found one.
+ *
+ * `control-size-literal` needs the distinction: `ChartCard` is the one slot owner whose slot cannot
+ * mount the tier theme, and `import { ChartCard as Card }` is a normal thing to write, so a
+ * membership Set (which answers `Card`) could not express the exemption at all.
+ */
+function collectBasaltImportMap(node, into, ownTree) {
+  const source = node.source?.value
+  if (typeof source !== 'string') return
+  if (!BASALT_IMPORT_SOURCE.test(source) && !(ownTree && RELATIVE_IMPORT_SOURCE.test(source))) {
+    return
+  }
+  for (const spec of node.specifiers ?? []) {
+    const local = spec.local?.name
+    if (typeof local !== 'string') continue
+    into.set(local, spec.imported?.name ?? spec.imported?.value ?? local)
+  }
+}
+
+/**
+ * The BINDING a home's slot prop hangs off — `PageBar` for `<PageBar filters={…}>` — or undefined
+ * when `attr` is not a slot-shaped prop on a home-shaped tag.
+ *
+ * Provenance (is that `Section` basalt's?) is deliberately NOT tested here: the answer needs the
+ * file's import list, which is only complete at `Program:exit`, while the ancestry a caller walks to
+ * reach this attribute is only walkable during the visit. So the walk captures the NAME and the
+ * caller resolves it against {@link collectBasaltImports}'s set afterwards.
+ */
+function slotOwnerBinding(attr) {
+  if (attr === null || attr === undefined || attr.type !== 'JSXAttribute') return undefined
+  const name = attr.name?.name
+  if (typeof name !== 'string' || !SLOT_ATTRS.has(name)) return undefined
+  const owner = attr.parent
+  if (owner === null || owner === undefined || owner.type !== 'JSXOpeningElement') return undefined
+  if (!SLOT_OWNER_TAGS.has(jsxTagName(owner.name) ?? '')) return undefined
+  return jsxRootName(owner.name)
+}
+
+/** The home slot attribute that ENCLOSES `node`, or undefined. Stops at the attribute, never the element. */
+function enclosingSlotAttribute(node) {
+  let current = node.parent
+  for (let depth = 0; current !== null && current !== undefined; depth++) {
+    if (depth > ANCESTRY_MAX_DEPTH || current.type === 'Program') return undefined
+    if (slotOwnerBinding(current) !== undefined) return current
+    current = current.parent
+  }
+  return undefined
+}
+
+/**
+ * Does an OVERLAY (or a settings row) sit between `node` and the home slot it is written in?
+ *
+ * Colocating a trigger with its overlay in a slot — a `New` button beside the `<Modal>` it opens, a
+ * `Custom range` button beside its `<Popover.Dropdown>` — is the ordinary way to write both, and
+ * the overlay's own contents are NOT in the bar: they portal out of it, they are not tiered by the
+ * slot's `MantineThemeProvider`, and `control-outside-home` already declares every one of these a
+ * non-home ({@link CONTROL_HOST_TAGS}). Before this test the same overlay was exempt outside a slot
+ * and an `error` inside one.
+ *
+ * The walk stops at the slot attribute so an overlay ABOVE the home (a whole `PageBar` rendered
+ * inside a `Modal`) does not exempt the bar's own controls.
+ */
+function hostedInsideSlot(node) {
+  let current = node.parent
+  for (let depth = 0; current !== null && current !== undefined; depth++) {
+    if (depth > ANCESTRY_MAX_DEPTH || current.type === 'Program') return false
+    if (
+      current.type === 'JSXElement' &&
+      CONTROL_HOST_TAGS.has(jsxTagName(current.openingElement?.name) ?? '')
+    ) {
+      return true
+    }
+    if (current.type === 'JSXAttribute' && SLOT_ATTRS.has(current.name?.name ?? '')) return false
+    current = current.parent
+  }
+  return false
+}
+
+/** The name of the nearest enclosing `const x = …` binding — the hoisted-slot-value lookup. */
+function enclosingDeclaratorName(node) {
+  let current = node.parent
+  for (let depth = 0; current !== null && current !== undefined; depth++) {
+    if (depth > ANCESTRY_MAX_DEPTH || current.type === 'Program') return undefined
+    if (current.type === 'VariableDeclarator') {
+      return typeof current.id?.name === 'string' ? current.id.name : undefined
+    }
+    current = current.parent
+  }
+  return undefined
+}
+
+/** True when any JSX ELEMENT ancestor of `node` opens with one of `tags`. */
+function hasAncestorTag(node, tags) {
+  let current = node.parent
+  for (let depth = 0; current !== null && current !== undefined; depth++) {
+    if (depth > ANCESTRY_MAX_DEPTH || current.type === 'Program') return false
+    if (current.type === 'JSXElement' && tags.has(jsxTagName(current.openingElement?.name) ?? '')) {
+      return true
+    }
+    current = current.parent
+  }
+  return false
+}
+
+/** Identifiers a slot attribute's value resolves through — `filters={pills}`, `actions={[a, b]}`. */
+function collectSlotValueIdentifiers(node, into, depth = 0) {
+  if (node === null || node === undefined || depth > 8) return
+  if (node.type === 'Identifier') {
+    into.add(node.name)
+    return
+  }
+  if (node.type === 'ArrayExpression') {
+    for (const el of node.elements) collectSlotValueIdentifiers(el, into, depth + 1)
+    return
+  }
+  if (node.type === 'ConditionalExpression') {
+    collectSlotValueIdentifiers(node.consequent, into, depth + 1)
+    collectSlotValueIdentifiers(node.alternate, into, depth + 1)
+    return
+  }
+  if (node.type === 'LogicalExpression') {
+    collectSlotValueIdentifiers(node.left, into, depth + 1)
+    collectSlotValueIdentifiers(node.right, into, depth + 1)
+  }
+}
+
+/**
+ * The shared "am I inside a home slot" resolver, and the one piece of state every control rule
+ * needs the WHOLE file to answer: a hoisted `const pills = <Select …/>` handed to `filters={pills}`
+ * further down is inside that slot (argo's hoisted `headerExtra`, `cost-over-time.tsx:54-68`), and
+ * the binding is only known to be slot-bound once the attribute has been seen.
+ *
+ * So the ancestry facts are CAPTURED during the visit — while `node.parent` is walkable — and
+ * resolved at `Program:exit`, when the slot-bound identifier set is complete. `capture()` returns a
+ * descriptor, `resolve()` turns it into a verdict; nothing re-walks the tree after traversal ends.
+ *
+ * The descriptor holds the owner BINDING NAME rather than a boolean for the same reason: whether
+ * that `Section` is basalt's is answered by the import list (`noteImport`), which is also only
+ * complete at exit.
+ */
+function createSlotContext(context) {
+  /** Local binding → the basalt export it was imported under. Membership IS the home test. */
+  const homes = new Map()
+  const ownTree = isBasaltOwnSource(getFilename(context))
+  /**
+   * Hoisted identifier → EVERY owner BINDING whose slot it was handed to.
+   *
+   * A Set, not one binding: `const acts = <Button size="xs"/>` handed to both `<Section actions>` and
+   * `<ChartCard actions>` is inside two slots at once, and a last-writer-wins map made the verdict
+   * depend on which attribute came later in the file — the same code went silent or reported
+   * depending on JSX order.
+   */
+  const slotBoundIdentifiers = new Map()
+  return {
+    /** Feed every ImportDeclaration here — this is where the owner provenance comes from. */
+    noteImport(node) {
+      collectBasaltImportMap(node, homes, ownTree)
+    },
+    /** Feed every JSXAttribute here — a slot attribute contributes its value's identifiers. */
+    note(attr) {
+      const owner = slotOwnerBinding(attr)
+      if (owner === undefined) return
+      const identifiers = new Set()
+      collectSlotValueIdentifiers(unwrapExpressionContainer(attr.value), identifiers)
+      for (const id of identifiers) {
+        const owners = slotBoundIdentifiers.get(id)
+        if (owners === undefined) slotBoundIdentifiers.set(id, new Set([owner]))
+        else owners.add(owner)
+      }
+    },
+    /** Snapshot `node`'s ancestry while it is walkable — the owner NAME, resolved later. */
+    capture(node) {
+      const attr = enclosingSlotAttribute(node)
+      return {
+        directOwner: attr === undefined ? undefined : slotOwnerBinding(attr),
+        declaratorName: enclosingDeclaratorName(node),
+      }
+    },
+    /** Is a captured node inside a BASALT home slot — directly, or via a hoisted binding? */
+    resolve(captured) {
+      if (captured.directOwner !== undefined) return homes.has(captured.directOwner)
+      if (captured.declaratorName === undefined) return false
+      const hoistedOwners = slotBoundIdentifiers.get(captured.declaratorName)
+      if (hoistedOwners === undefined) return false
+      // ANY basalt owner puts the binding in a home: a node handed to one basalt slot and one
+      // consumer component still renders inside the basalt slot.
+      for (const owner of hoistedOwners) {
+        if (homes.has(owner)) return true
+      }
+      return false
+    },
+    /** Does `name` resolve to a basalt home component in this file? */
+    isHome(name) {
+      return name !== undefined && homes.has(name)
+    },
+    /**
+     * EVERY basalt EXPORT whose slot a captured node sits in — `['ChartCard']` for
+     * `<ChartCard actions={…}>` and for `<Card actions={…}>` under an alias, `[]` when the node is in
+     * no basalt slot. Resolves through the same hoisted-binding hop `resolve` does.
+     *
+     * A LIST, because one hoisted binding can be handed to several slots, and an exemption keyed on
+     * the owner is only sound when it holds for all of them — a `size="xs"` shared between
+     * `<ChartCard actions>` and `<Section actions>` really does render inside the Section's tiered
+     * slot. Non-basalt owners are dropped: they are not homes, so they carry no tier either way.
+     */
+    ownerExports(captured) {
+      const bindings =
+        captured.directOwner !== undefined
+          ? [captured.directOwner]
+          : captured.declaratorName === undefined
+            ? []
+            : [...(slotBoundIdentifiers.get(captured.declaratorName) ?? [])]
+      return bindings.filter((binding) => homes.has(binding)).map((binding) => homes.get(binding))
+    },
+  }
+}
+
+/** Collects an owner-definition flag for the control layer — see {@link CONTROL_OWNER_NAMES}. */
+function createControlOwnerProbe() {
+  const state = { definesControl: false }
+  const note = (name) => {
+    if (typeof name === 'string' && CONTROL_OWNER_NAMES.has(name)) state.definesControl = true
+  }
+  return {
+    state,
+    visitors: {
+      FunctionDeclaration(node) {
+        note(node.id?.name)
+      },
+      VariableDeclarator(node) {
+        note(node.id?.name)
+      },
+    },
+  }
+}
+
+// ── Rule 16 — hand-rolled-filter ────────────────────────────────────────────────────────────────
+
+const HAND_ROLLED_FILTER_MESSAGE =
+  'Raw Mantine selection control inside a home slot — a filter or tab in a PageBar / Section / ' +
+  'WidgetHeader slot takes a `field` (a FieldHandle) and owns both the URL write and the ' +
+  'localStorage mirror, so it cannot carry value/onChange at all (laws C1–C3). Use ' +
+  'RangeFilter / SelectFilter / MultiSelectFilter / SearchFilter / ToggleFilter / ViewTabs from ' +
+  "basalt-ui/controls. Two shapes are NOT this rule: a control in a home's CHILDREN (a Section " +
+  "body form), and a SettingsRow's `control` — the form-row home, where a raw input at Mantine's " +
+  'md tier is the right answer. (basalt/hand-rolled-filter)'
+
+/**
+ * A raw Mantine selection control handed to a home slot (laws C1/C3).
+ *
+ * Ships `error` from the start, unlike its sibling `control-outside-home`: "this element is inside
+ * a slot" is a structural fact with no heuristic in it, and the wave-1..4 migrations left no
+ * incumbents. Two shapes are deliberately outside the rule: the body form (the ancestry walk stops
+ * at the slot ATTRIBUTE, so a `<Select>` in a `Section`'s children never reaches it) and
+ * `SettingsRow.control`, the form-row home — see {@link SLOT_ATTRS} for why a raw input is right
+ * there.
+ */
+const handRolledFilter = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Disallow a raw Mantine selection control inside a basalt home slot.' },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+    const slots = createSlotContext(context)
+    const mantineImports = new Map()
+    const candidates = []
+
+    return {
+      ImportDeclaration(node) {
+        collectMantineImports(node, mantineImports)
+        slots.noteImport(node)
+      },
+      JSXAttribute(node) {
+        slots.note(node)
+      },
+      JSXOpeningElement(node) {
+        // Cheap pre-filter: the tag as WRITTEN, or any Mantine binding (an alias resolves at exit).
+        const root = jsxRootName(node.name)
+        if (!RAW_FILTER_TAGS.has(jsxTagName(node.name) ?? '') && !mantineImports.has(root)) return
+        candidates.push({
+          node,
+          name: node.name,
+          captured: slots.capture(node),
+          hosted: hostedInsideSlot(node),
+        })
+      },
+      'Program:exit'() {
+        for (const { node, name, captured, hosted } of candidates) {
+          const tag = resolveMantineTag(name, mantineImports)
+          if (tag === undefined || !RAW_FILTER_TAGS.has(tag)) continue
+          if (hosted || !slots.resolve(captured)) continue
+          if (hasThemeAllow(context, node, 'hand-rolled-filter')) continue
+          context.report({ node, message: HAND_ROLLED_FILTER_MESSAGE })
+        }
+      },
+    }
+  },
+}
+
+// ── Rule 17 — control-outside-home ──────────────────────────────────────────────────────────────
+
+const CONTROL_OUTSIDE_HOME_MESSAGE =
+  'Raw Mantine selection control with no home — a filter, tab or action belongs in exactly one of ' +
+  'the three homes (a PageBar / Section / WidgetHeader slot, or a form row), and a home is entered ' +
+  'through a slot prop (law C1). A settings row, an overlay (Modal/Drawer/Popover/Menu) and a ' +
+  'form (@mantine/form) are the declared non-homes and never report. ' +
+  '(basalt/control-outside-home)'
+
+/**
+ * The cross-file half of C1, and the one rule here that is openly a HEURISTIC: "this control has
+ * no home" is a claim about layout intent, which no AST can see. It ships `warn` for that reason
+ * and stays warn until the playground and the five consumer repos run it with ≤3 waivers
+ * (docs/CONTROLS-SPEC.md §9 wave 7).
+ *
+ * Four exemptions carry the false-positive load: an overlay/settings-row ancestor, an
+ * {@link OVERLAY_CONVENTION_FILE} basename (the CROSS-FILE case — the `<Modal>` lives in the
+ * parent), a file that imports `@mantine/form` (a form is the third home and its inputs are not
+ * filters), and the owner exemption — a file DEFINING a basalt control cannot be told to use one.
+ */
+const controlOutsideHome = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Warn on a raw Mantine selection control that is in no basalt home.' },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+    if (OVERLAY_CONVENTION_FILE.test(getFilename(context))) return {}
+    const slots = createSlotContext(context)
+    const owner = createControlOwnerProbe()
+    const mantineImports = new Map()
+    const candidates = []
+    let importsMantineForm = false
+
+    return {
+      ...owner.visitors,
+      ImportDeclaration(node) {
+        collectMantineImports(node, mantineImports)
+        slots.noteImport(node)
+        if ((node.source?.value ?? '') === '@mantine/form') importsMantineForm = true
+      },
+      JSXAttribute(node) {
+        slots.note(node)
+      },
+      JSXOpeningElement(node) {
+        // Cheap pre-filter: the tag as WRITTEN, or any Mantine binding (an alias resolves at exit).
+        const root = jsxRootName(node.name)
+        if (!RAW_FILTER_TAGS.has(jsxTagName(node.name) ?? '') && !mantineImports.has(root)) return
+        candidates.push({
+          node,
+          name: node.name,
+          captured: slots.capture(node),
+          hosted: hasAncestorTag(node, CONTROL_HOST_TAGS),
+        })
+      },
+      'Program:exit'() {
+        if (importsMantineForm || owner.state.definesControl) return
+        for (const { node, name, captured, hosted } of candidates) {
+          const tag = resolveMantineTag(name, mantineImports)
+          if (tag === undefined || !RAW_FILTER_TAGS.has(tag)) continue
+          if (hosted || slots.resolve(captured)) continue
+          if (hasThemeAllow(context, node, 'control-outside-home')) continue
+          context.report({ node, message: CONTROL_OUTSIDE_HOME_MESSAGE })
+        }
+      },
+    }
+  },
+}
+
+// ── Rule 18 — control-size-literal ──────────────────────────────────────────────────────────────
+
+/** The props a home already owns — the tier, the width, and the responsive swap (laws C5/C9). */
+const CONTROL_SIZE_ATTRS = new Set(['size', 'w', 'fullWidth', 'visibleFrom', 'hiddenFrom'])
+
+const CONTROL_SIZE_LITERAL_MESSAGE =
+  'Size/width/breakpoint prop inside a tiered home slot — the HOME sets the tier (`size="ctl"` = 30px, ' +
+  "mounted by the slot's own MantineThemeProvider), the control owns its own responsive swap, and " +
+  'the overflow fold is computed by basalt from typed data. A `size`/`w`/`fullWidth`/`visibleFrom`/' +
+  '`hiddenFrom` written here fights all three (laws C5/C7/C9) — drop the prop. ' +
+  '(basalt/control-size-literal)'
+
+/**
+ * The elements the slot's own `MantineThemeProvider` actually re-tiers, beyond the raw filters: a
+ * `Button size="xs"` dropped into `PageBar.actions` is the same defect as a `Select size="xs"` there
+ * — one control in the bar that is not 30px.
+ *
+ * This file is plain JS shipped to consumers and `src/theme/ctl-theme.tsx` is Mantine-coupled
+ * TypeScript it may not import, so the list is written out here — and PINNED to
+ * `CTL_THEME.components` by `oxlint-plugin.test.ts`, which can import both. Drift fails that test
+ * rather than silently re-tiering a component the rule still polices (or the reverse).
+ *
+ * The scope IS the rule: an `<IconDownload size={14}/>`, a count `<Badge size="sm">`, a
+ * `<Loader size={14}/>` or a `<Modal size="lg">` colocated in a slot is NOT sized by the slot theme,
+ * so "drop the prop" produced a 24px icon and a message whose promise ("the HOME sets the tier") was
+ * false for every one of them.
+ *
+ * `Switch` USED to be on that not-sized list and is now on this one, together with `Radio`,
+ * `Checkbox` and the three `*Group`s: the tier gained their `-ctl` vars in the same minor this rule
+ * ships in (`theme/ctl-theme.tsx`, `theme/index.ts`'s `ctlSizeVars`), because a 20px indicator beside
+ * the tier's 13.5px option label was what every filter popover and the mobile sheet rendered. The
+ * grace runway in {@link PLUGIN_RULE_GRACE} is unchanged — the rule has never shipped at any level,
+ * so widening it before its first release restarts nothing.
+ */
+export const CTL_THEME_TAGS = new Set([
+  'Button',
+  'ActionIcon',
+  'Input',
+  'TextInput',
+  'Select',
+  'MultiSelect',
+  'SegmentedControl',
+  'NativeSelect',
+  'Radio',
+  'RadioGroup',
+  'Checkbox',
+  'CheckboxGroup',
+  'Switch',
+  'SwitchGroup',
+])
+
+/**
+ * A size/width/breakpoint prop on a control the slot theme tiers. The slot's hoisted
+ * `MantineThemeProvider` already resolves the tier with no prop. A `SettingsRow`'s `control` is NOT
+ * a tiered slot (see {@link SLOT_ATTRS}): a form row keeps Mantine's `md`, so the `size` written
+ * there is load-bearing rather than redundant.
+ *
+ * Scoped to `RAW_FILTER_TAGS` ∪ `BOUND_TAGS` (basalt's own controls, by name) ∪ a Mantine-imported
+ * {@link CTL_THEME_TAGS} member, and skipped under an overlay ({@link hostedInsideSlot}) — see
+ * `CTL_THEME_TAGS` for what firing on everything in the slot cost.
+ */
+/**
+ * The home whose slot cannot mount the tier theme, so the CONTROL there has to state its own size.
+ *
+ * `ChartCard` lives inside the Mantine-free chart layer (`src/charts/primitives/`), which means it
+ * cannot render a `MantineThemeProvider` at all — it writes `data-basalt-tier="widget"` by hand and
+ * nothing else (`../CLAUDE.md`, "A home sizes its own SLOT"; `docs/CONTROLS-SPEC.md` §5). So this
+ * rule's whole message — "the HOME sets the tier, drop the prop" — is FALSE in exactly one slot: a
+ * `Switch` in `ChartCard.actions` with no `size` renders at Mantine's default, not at `ctl`.
+ *
+ * It has to be an exemption rather than a waiver because the rule fires on the `size` ATTRIBUTE and
+ * cannot tell a correct `size="ctl"` from the `size="xs"` it exists to catch. The playground carried
+ * exactly one waiver for this and it was the honest kind — the rule was wrong, not the code.
+ *
+ * `hand-rolled-filter` is deliberately NOT exempted here: a raw `Select` in `ChartCard.actions` is
+ * still a filter that should take a `field`, and the tier is not what makes that true.
+ */
+const TIERLESS_SLOT_OWNERS = new Set(['ChartCard'])
+
+const controlSizeLiteral = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Warn on a size/width/breakpoint prop written inside a home slot.' },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+    const slots = createSlotContext(context)
+    const mantineImports = new Map()
+    const candidates = []
+
+    return {
+      ImportDeclaration(node) {
+        collectMantineImports(node, mantineImports)
+        slots.noteImport(node)
+      },
+      JSXAttribute(node) {
+        slots.note(node)
+        const name = node.name?.name
+        if (typeof name !== 'string' || !CONTROL_SIZE_ATTRS.has(name)) return
+        const owner = node.parent
+        if (owner === null || owner === undefined || owner.type !== 'JSXOpeningElement') return
+        candidates.push({
+          node,
+          name: owner.name,
+          captured: slots.capture(node),
+          hosted: hostedInsideSlot(node),
+        })
+      },
+      'Program:exit'() {
+        for (const { node, name, captured, hosted } of candidates) {
+          const written = jsxTagName(name) ?? ''
+          const tiered =
+            RAW_FILTER_TAGS.has(written) ||
+            BOUND_TAGS.has(written) ||
+            CTL_THEME_TAGS.has(resolveMantineTag(name, mantineImports) ?? '')
+          if (!tiered || hosted) continue
+          if (!slots.resolve(captured)) continue
+          // EVERY home the node was handed to has to be tierless. One hoisted `const acts =
+          // <Button size="xs"/>` given to both `<ChartCard actions>` and `<Section actions>` renders
+          // in a tiered slot too, and the prop is redundant there — so the exemption does not apply.
+          const owners = slots.ownerExports(captured)
+          if (owners.length > 0 && owners.every((owner) => TIERLESS_SLOT_OWNERS.has(owner)))
+            continue
+          if (hasThemeAllow(context, node, 'control-size-literal')) continue
+          context.report({ node, message: CONTROL_SIZE_LITERAL_MESSAGE })
+        }
+      },
+    }
+  },
+}
+
+// ── Rule 19 — page-bar-budget ───────────────────────────────────────────────────────────────────
+
+/** `PageBar.actions.secondary` — 4, because the one `primary` makes 5 (law C6). */
+const PAGE_BAR_SECONDARY_BUDGET = 4
+/** A `Section`'s `actions` — 3 (law C6). */
+const SECTION_ACTION_BUDGET = 3
+
+const PAGE_BAR_BUDGET_MESSAGES = {
+  duplicate:
+    'Second PageBar in the same returned tree — a page has exactly one page bar, and row 1 portals ' +
+    'into the app shell header, so two bars mounted TOGETHER race for the same node (law C6). An ' +
+    'early-return loading state and two page components in one file each get their own tree and ' +
+    'never report. (basalt/page-bar-budget)',
+  secondary:
+    `More than ${PAGE_BAR_SECONDARY_BUDGET} secondary PageBar actions — the bar holds ≤5 entries ` +
+    'including the one `primary`, and everything past that folds into the `More` menu basalt ' +
+    'computes from the typed BarAction[] (laws C6/C7). Move the rest into a `kind: "menu"` entry. ' +
+    '(basalt/page-bar-budget)',
+  section:
+    `More than ${SECTION_ACTION_BUDGET} Section actions — a section header holds ≤3 (law C6). ` +
+    '(basalt/page-bar-budget)',
+  filled:
+    'Second filled Button/ActionIcon inside one slot — a home has exactly one primary action, and ' +
+    'two filled buttons side by side name neither (law C6). A filled Badge/ThemeIcon (a count) and ' +
+    "an overlay's own submit button are not actions in the bar and never report. " +
+    '(basalt/page-bar-budget)',
+}
+
+/** The two tags a `variant="filled"` makes a PRIMARY ACTION — a Badge is a count, not an action. */
+const PRIMARY_ACTION_TAGS = new Set(['Button', 'ActionIcon'])
+
+/**
+ * The JSX TREE `node` is returned in — the nearest `ReturnStatement`, concise arrow body, or
+ * `const` binding, whichever the walk reaches first.
+ *
+ * This is what "two PageBars race for the same node" actually requires: they must MOUNT together.
+ * Counting per FILE made an `if (!data) return <PageBar title="Jobs"/>` loading state, and two page
+ * components exported from one file, an `error` on code that never renders two bars — with a
+ * `theme-allow` on correct code as the only escape.
+ */
+function enclosingReturnedTree(node) {
+  let current = node.parent
+  for (let depth = 0; current !== null && current !== undefined; depth++) {
+    if (depth > ANCESTRY_MAX_DEPTH || current.type === 'Program') return undefined
+    if (current.type === 'ReturnStatement' || current.type === 'VariableDeclarator') return current
+    if (current.type === 'ArrowFunctionExpression' && current.body?.type !== 'BlockStatement') {
+      return current
+    }
+    current = current.parent
+  }
+  return undefined
+}
+
+/** The `actions` attribute of a JSXOpeningElement, unwrapped, or undefined. */
+function actionsAttributeValue(node) {
+  for (const attr of node.attributes ?? []) {
+    if (attr.type !== 'JSXAttribute' || attr.name?.name !== 'actions') continue
+    return { attr, value: unwrapExpressionContainer(attr.value) }
+  }
+  return undefined
+}
+
+/**
+ * The four countable halves of C6. `error` from the start: every one of them is arithmetic over a
+ * literal the file wrote down, with no heuristic and no layout intent to guess at.
+ */
+const pageBarBudget = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Enforce the PageBar / Section action budgets and the single primary.' },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+    const slots = createSlotContext(context)
+    const mantineImports = new Map()
+    const pageBars = []
+    const findings = []
+    /** Slot attribute node → its owner binding + the `variant="filled"` attributes inside it. */
+    const filledPerSlot = new Map()
+
+    return {
+      ImportDeclaration(node) {
+        collectMantineImports(node, mantineImports)
+        slots.noteImport(node)
+      },
+      JSXOpeningElement(node) {
+        const tag = jsxTagName(node.name)
+        const owner = jsxRootName(node.name)
+        if (tag === 'PageBar') {
+          pageBars.push({ node, owner, tree: enclosingReturnedTree(node) })
+          const actions = actionsAttributeValue(node)
+          if (actions?.value?.type === 'ObjectExpression') {
+            for (const prop of actions.value.properties) {
+              if (prop.type !== 'Property' || propertyKeyName(prop) !== 'secondary') continue
+              if (prop.value?.type !== 'ArrayExpression') continue
+              if (prop.value.elements.length <= PAGE_BAR_SECONDARY_BUDGET) continue
+              findings.push({ node: prop, owner, message: PAGE_BAR_BUDGET_MESSAGES.secondary })
+            }
+          }
+          return
+        }
+        if (tag !== 'Section') return
+        const actions = actionsAttributeValue(node)
+        if (actions?.value?.type !== 'ArrayExpression') return
+        if (actions.value.elements.length <= SECTION_ACTION_BUDGET) return
+        findings.push({ node: actions.attr, owner, message: PAGE_BAR_BUDGET_MESSAGES.section })
+      },
+      JSXAttribute(node) {
+        slots.note(node)
+        if (node.name?.name !== 'variant') return
+        const value = unwrapExpressionContainer(node.value)
+        if (!isStringLiteral(value) || value.value !== 'filled') return
+        // An overlay's own submit button is not an action in the bar — see hostedInsideSlot.
+        if (hostedInsideSlot(node)) return
+        const element = node.parent
+        if (element === null || element === undefined || element.type !== 'JSXOpeningElement')
+          return
+        const slot = enclosingSlotAttribute(node)
+        if (slot === undefined) return
+        const entry = filledPerSlot.get(slot) ?? { owner: slotOwnerBinding(slot), written: [] }
+        entry.written.push({ node, name: element.name })
+        filledPerSlot.set(slot, entry)
+      },
+      'Program:exit'() {
+        /** Returned tree → the PageBars mounted in it. Two in one tree mount together; see C6. */
+        const barsPerTree = new Map()
+        for (const bar of pageBars) {
+          if (!slots.isHome(bar.owner)) continue
+          barsPerTree.set(bar.tree, [...(barsPerTree.get(bar.tree) ?? []), bar])
+        }
+        for (const bars of barsPerTree.values()) {
+          for (const { node, owner } of bars.slice(1)) {
+            findings.push({ node, owner, message: PAGE_BAR_BUDGET_MESSAGES.duplicate })
+          }
+        }
+        for (const { owner, written } of filledPerSlot.values()) {
+          const actions = written.filter(({ name }) =>
+            PRIMARY_ACTION_TAGS.has(resolveMantineTag(name, mantineImports) ?? ''),
+          )
+          for (const { node } of actions.slice(1)) {
+            findings.push({ node, owner, message: PAGE_BAR_BUDGET_MESSAGES.filled })
+          }
+        }
+        for (const { node, owner, message } of findings) {
+          if (!slots.isHome(owner)) continue
+          if (hasThemeAllow(context, node, 'page-bar-budget')) continue
+          context.report({ node, message })
+        }
+      },
+    }
+  },
+}
+
+// ── Rule 20 — in-body-page-title ────────────────────────────────────────────────────────────────
+
+/** Where an `order={1|2}` Title is a DOCUMENT heading rather than a page title. */
+const PAGE_TITLE_HOST_TAGS = new Set(['Prose', 'ArticleLayout', 'Modal', 'Drawer'])
+
+const IN_BODY_PAGE_TITLE_MESSAGE =
+  'In-body page title — the page is named ONCE, by the breadcrumb (`staticData.title`) or by ' +
+  '`PageBar.title` in a shell-less app, and every section/card/table title is a `WidgetHeader` ' +
+  '(law C8). An `<Title order={1|2}>` in the body is a second, drifting name for the same page. ' +
+  'Prose / ArticleLayout / an overlay and anything under a `content/` path are document headings ' +
+  'and never report. (basalt/in-body-page-title)'
+
+/** The `order` prop as a number literal, or undefined. */
+function titleOrderOf(node) {
+  for (const attr of node.attributes ?? []) {
+    if (attr.type !== 'JSXAttribute' || attr.name?.name !== 'order') continue
+    const value = unwrapExpressionContainer(attr.value)
+    return isNumericLiteral(value) ? value.value : undefined
+  }
+  return undefined
+}
+
+/**
+ * The AST half of C8. Its text-level twin is the `in-body-page-title` GUARD KIND — same id in both
+ * lanes on purpose, so one `theme-allow in-body-page-title — <why>` waives both rather than
+ * needing a different word per enforcement surface.
+ */
+const inBodyPageTitle = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Warn on an in-body <Title order={1|2}> outside prose/overlay context.' },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context) || hasPathSegment(getFilename(context), 'content')) return {}
+
+    return {
+      JSXOpeningElement(node) {
+        if (jsxTagName(node.name) !== 'Title') return
+        const order = titleOrderOf(node)
+        if (order !== 1 && order !== 2) return
+        if (hasAncestorTag(node, PAGE_TITLE_HOST_TAGS)) return
+        if (hasThemeAllow(context, node, 'in-body-page-title')) return
+        context.report({ node, message: IN_BODY_PAGE_TITLE_MESSAGE })
+      },
+    }
+  },
+}
+
+// ── Rule 21 — responsive-twin ───────────────────────────────────────────────────────────────────
+
+const RESPONSIVE_TWIN_MESSAGE =
+  'The same control mounted twice under visibleFrom/hiddenFrom — a responsive swap belongs to the ' +
+  'CONTROL, which owns one mount and switches its own presentation in CSS (law C9). Two mounts are ' +
+  'two states: the hidden half keeps its own value, its own focus and its own store writes. ' +
+  'Render it once. (basalt/responsive-twin)'
+
+/** The breakpoint a `visibleFrom` / `hiddenFrom` prop names, as a string literal. */
+function breakpointAttr(element, attrName) {
+  for (const attr of element.openingElement?.attributes ?? []) {
+    if (attr.type !== 'JSXAttribute' || attr.name?.name !== attrName) continue
+    const value = unwrapExpressionContainer(attr.value)
+    return isStringLiteral(value) ? value.value : undefined
+  }
+  return undefined
+}
+
+/** Every control tag rendered anywhere in `node`'s subtree, itself included. */
+function subtreeControlTags(node, into = new Set(), depth = 0) {
+  if (node === null || node === undefined || depth > 16) return into
+  if (node.type === 'JSXElement') {
+    const tag = jsxTagName(node.openingElement?.name)
+    if (tag !== undefined && (RAW_FILTER_TAGS.has(tag) || BOUND_TAGS.has(tag))) into.add(tag)
+    for (const child of node.children ?? []) subtreeControlTags(child, into, depth + 1)
+    return into
+  }
+  if (node.type === 'JSXFragment') {
+    for (const child of node.children ?? []) subtreeControlTags(child, into, depth + 1)
+    return into
+  }
+  if (node.type === 'JSXExpressionContainer')
+    return subtreeControlTags(node.expression, into, depth + 1)
+  if (node.type === 'ConditionalExpression') {
+    subtreeControlTags(node.consequent, into, depth + 1)
+    return subtreeControlTags(node.alternate, into, depth + 1)
+  }
+  if (node.type === 'LogicalExpression') {
+    subtreeControlTags(node.left, into, depth + 1)
+    return subtreeControlTags(node.right, into, depth + 1)
+  }
+  return into
+}
+
+/**
+ * Law C9 — linewatch shipped three doubled controls this way. The pair test is deliberately narrow:
+ * two SIBLING elements, one `visibleFrom="X"` and one `hiddenFrom="X"` on the SAME breakpoint, whose
+ * subtrees both render the same control tag. A file that DEFINES a basalt control is exempt — the
+ * one legitimate double mount is the CSS swap inside the control itself.
+ */
+const responsiveTwin = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Warn on one control mounted twice under visibleFrom/hiddenFrom.' },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+    const owner = createControlOwnerProbe()
+    const twins = []
+
+    const inspectChildren = (node) => {
+      const children = (node.children ?? []).filter((child) => child.type === 'JSXElement')
+      for (let i = 0; i < children.length; i++) {
+        for (let j = i + 1; j < children.length; j++) {
+          const a = children[i]
+          const b = children[j]
+          const visibleA = breakpointAttr(a, 'visibleFrom')
+          const hiddenA = breakpointAttr(a, 'hiddenFrom')
+          const visibleB = breakpointAttr(b, 'visibleFrom')
+          const hiddenB = breakpointAttr(b, 'hiddenFrom')
+          const paired =
+            (visibleA !== undefined && visibleA === hiddenB) ||
+            (hiddenA !== undefined && hiddenA === visibleB)
+          if (!paired) continue
+          const tagsA = subtreeControlTags(a)
+          if (tagsA.size === 0) continue
+          const shared = [...subtreeControlTags(b)].some((tag) => tagsA.has(tag))
+          if (!shared) continue
+          twins.push(b)
+        }
+      }
+    }
+
+    return {
+      ...owner.visitors,
+      JSXElement: inspectChildren,
+      JSXFragment: inspectChildren,
+      'Program:exit'() {
+        if (owner.state.definesControl) return
+        for (const node of twins) {
+          if (hasThemeAllow(context, node, 'responsive-twin')) continue
+          context.report({ node, message: RESPONSIVE_TWIN_MESSAGE })
+        }
+      },
+    }
+  },
+}
+
+// ── Rule 22 — search-literal-link ───────────────────────────────────────────────────────────────
+
+/** The two calls that build a typed nav definition — `search:` inside one is a nav link's search. */
+const NAV_DEFINITION_CALLEES = new Set(['defineNav', 'navGroup'])
+
+const SEARCH_LITERAL_LINK_MESSAGE =
+  "Object literal as a nav link's `search` — it PINS those values on every click, so a nav link " +
+  'always navigates back to the fallback and the persisted selection is silently discarded (law ' +
+  "C10; argo's reader had zero call sites because of exactly this). Pass `store.linkSearch` BY " +
+  'REFERENCE instead — never a literal, never `search: true`, never a global link callback. ' +
+  '(basalt/search-literal-link)'
+
+/** True when `node` sits inside a `defineNav()` / `navGroup()` argument. */
+function insideNavDefinition(node) {
+  let current = node.parent
+  for (let depth = 0; current !== null && current !== undefined; depth++) {
+    if (depth > ANCESTRY_MAX_DEPTH || current.type === 'Program') return false
+    if (
+      current.type === 'CallExpression' &&
+      current.callee?.type === 'Identifier' &&
+      NAV_DEFINITION_CALLEES.has(current.callee.name)
+    ) {
+      return true
+    }
+    current = current.parent
+  }
+  return false
+}
+
+const searchLiteralLink = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Warn on a `search:` object literal inside defineNav/navGroup.' },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee?.type !== 'Identifier' || node.callee.name !== 'linkOptions') return
+        const arg0 = node.arguments?.[0]
+        if (arg0 === undefined || arg0.type !== 'ObjectExpression') return
+        for (const prop of arg0.properties) {
+          if (prop.type !== 'Property' || propertyKeyName(prop) !== 'search') continue
+          if (prop.value?.type !== 'ObjectExpression') continue
+          if (!insideNavDefinition(node)) continue
+          if (hasThemeAllow(context, prop, 'search-literal-link')) continue
+          context.report({ node: prop, message: SEARCH_LITERAL_LINK_MESSAGE })
+        }
+      },
+    }
+  },
+}
+
+// ── Rule 23 — use-search-from-literal ───────────────────────────────────────────────────────────
+
+const USE_SEARCH_FROM_LITERAL_MESSAGE =
+  "useSearch({ from: '<route>' }) — a `from` literal pins the reader to ONE route id, so the same " +
+  'component throws the moment it renders on a sibling or child route. A store field reads ' +
+  '`useSearch({ strict: false })` internally, which sees the merged search of every matched route ' +
+  '(law C10) — take the value as a prop, or read it through the store field. ' +
+  '(basalt/use-search-from-literal)'
+
+const useSearchFromLiteral = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: "Warn on useSearch({ from: '<literal>' })." },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        const name =
+          callee?.type === 'MemberExpression' ? callee.property?.name : (callee?.name ?? undefined)
+        if (name !== 'useSearch') return
+        const arg0 = node.arguments?.[0]
+        if (arg0 === undefined || arg0.type !== 'ObjectExpression') return
+        for (const prop of arg0.properties) {
+          if (prop.type !== 'Property' || propertyKeyName(prop) !== 'from') continue
+          if (!isStringLiteral(prop.value)) continue
+          if (hasThemeAllow(context, prop, 'use-search-from-literal')) continue
+          context.report({ node: prop, message: USE_SEARCH_FROM_LITERAL_MESSAGE })
+        }
+      },
+    }
+  },
+}
+
 // ── Grace ledger ────────────────────────────────────────────────────────────────────────────────
 
+/**
+ * @typedef {{ since: string; promote: string; why: string }} GraceEntry
+ * @typedef {{ since: string; why: string }} AdvisoryEntry
+ */
+
 /**
  * Plugin rules still inside their grace minor — `warn` in the shipped consumer preset, `error`
- * repo-locally, with the promotion note as the value. This is the plugin's counterpart to
- * `src/guard`'s `GRACE_PERIOD_KINDS`, and it exists because its ABSENCE is what let three rules sit
- * at `warn` for up to twelve minors with nothing tracking them: `configs/oxlint.json` is generated
- * and its top-level keys are fixed by oxlint's own parser, so the ledger cannot live there.
- *
- * `oxlint-plugin.test.ts` asserts the two agree in both directions — a rule listed here must be
- * `warn` in the shipped preset, and one absent from here must be `error`. Deleting an entry IS the
- * promotion, and the test makes the config change mandatory in the same commit.
+ * repo-locally. This is the plugin's counterpart to `src/guard`'s `GRACE_PERIOD_KINDS`, and it
+ * exists because its ABSENCE is what let three rules sit at `warn` for up to twelve minors with
+ * nothing tracking them: `configs/oxlint.json` is generated and its top-level keys are fixed by
+ * oxlint's own parser, so the ledger cannot live there.
+ *
+ * `oxlint-plugin.test.ts` asserts the two agree in both directions — a rule listed here or in
+ * {@link PLUGIN_RULE_ADVISORY} must be `warn` in the shipped preset, and one absent from both must
+ * be `error`. Deleting a `PLUGIN_RULE_GRACE` entry IS the promotion, and the test makes the config
+ * change mandatory in the same commit.
+ *
+ * Each entry is `{ since, promote, why }` (semver strings, C16 — `docs/CONTROLS-SPEC.md` §1): a
+ * version-gated test fails the build once `package.json`'s version reaches `promote` while the
+ * entry is still here — the four entries that used to live here (D4) sat at `warn` for up to five
+ * minors because a bare promotion-note string carried no expiry a test could check. The test gate
+ * fires on the version already published; `scripts/check-grace.ts` is the other end of it, run by
+ * `scripts/release.sh` against the version the dry run COMPUTED, so a release that would ship a
+ * due entry still at `warn` is refused before it is cut (the release commit is `[skip ci]` and
+ * runs no tests, so the test alone would only notice on the next unrelated push).
+ *
+ * @type {Record<string, GraceEntry>}
  */
 export const PLUGIN_RULE_GRACE = {
-  'hand-rolled-plot':
-    'widened AGAIN in the round-5 guard minor (file scope must now be spelled `theme-allow-file`, ' +
-    'so the named-with-a-reason shape every consumer wrote at 1.20.0 is a NODE waiver and the ' +
-    'remaining assembly nodes report) — grace restarts with the widening, per the "a rule the ' +
-    'current minor widens does not promote in that minor" doctrine. Promote one minor after ' +
-    'consumers have moved their file declarations to `theme-allow-file`.',
-  'chart-legend-literal':
-    'widened in the round-4 guard minor (a `.map()` over a non-series array now counts) — promote ' +
-    'to error one minor later, for the same reason as hand-rolled-plot above.',
-  'shadow-basalt-export':
-    'new in the round-4 guard minor, widened in round-5 (reads every published barrel, not just ' +
-    'the root one, so a chart-layer fork is visible) — promote to error one minor later, if ever. ' +
-    'A name collision is strong evidence and not proof, and renaming defeats it outright, so this ' +
-    'may be a permanent warn.',
-  'hand-rolled-shell': 'new in the round-4 guard minor — promote to error one minor later.',
+  'control-outside-home': {
+    since: '1.26.0',
+    promote: '1.28.0',
+    why:
+      'the wave-6 control guards (docs/CONTROLS-SPEC.md §6). The one openly HEURISTIC rule of the ' +
+      'set — "this control has no home" is a claim about layout intent, so its false-positive load ' +
+      'is carried by four exemptions (overlay/settings-row ancestor, the overlay FILENAME ' +
+      'convention below, @mantine/form, owner definition) rather than by certainty. The other five ' +
+      'wave-6 rules promoted at 1.27.0; this one did not, and the reason is measured rather than ' +
+      'cautious: the wave-7 run found 9 remaining warns in argo, every one of them a control in a ' +
+      'modal/form module whose `<Modal>` is rendered by the PARENT — the cross-file case law C1 is ' +
+      'explicitly advisory about, which no ancestry walk inside one file can ever see. ' +
+      '{@link OVERLAY_CONVENTION_FILE} now exempts the declared naming convention for exactly ' +
+      'that shape; 1.28.0 is when the remainder is re-measured. A file outside the convention ' +
+      "that is still an overlay's own body declares it with " +
+      '`theme-allow-file control-outside-home — overlay`.',
+  },
+}
+
+/**
+ * Plugin rules that stay `warn` in the shipped preset PERMANENTLY — outside the C16 version gate,
+ * and not expected to ever promote. `oxlint-plugin.test.ts` still requires `warn` in the shipped
+ * preset and a `why` long enough to justify it, but skips these when checking `promote`.
+ *
+ * `shadow-basalt-export` is the one entry: a name collision is strong evidence a component was
+ * forked rather than imported, but not proof, and renaming the fork defeats the check outright — so
+ * there is no version at which flipping it to `error` is safe to promise in advance.
+ *
+ * @type {Record<string, AdvisoryEntry>}
+ */
+export const PLUGIN_RULE_ADVISORY = {
+  'shadow-basalt-export': {
+    since: '1.20.0',
+    why:
+      'new in the round-4 guard minor (1.20.0), widened in round-5 (1.21.0 — reads every ' +
+      'published barrel, not just the root one, so a chart-layer fork is visible), narrowed at ' +
+      '1.22.0 (`isBasaltScopedFile` plus a component-shaped declaration). A name collision is ' +
+      'strong evidence and not proof, and renaming defeats it outright, so this stays a permanent ' +
+      'warn rather than a grace entry with no honest promote date.',
+  },
 }
 
 // ── Plugin export ───────────────────────────────────────────────────────────────────────────────
@@ -1645,6 +3066,14 @@ export default {
     'shadow-basalt-export': shadowBasaltExport,
     'hand-rolled-shell': handRolledShell,
     'raw-scroll-container': rawScrollContainer,
+    'hand-rolled-filter': handRolledFilter,
+    'control-outside-home': controlOutsideHome,
+    'control-size-literal': controlSizeLiteral,
+    'page-bar-budget': pageBarBudget,
+    'in-body-page-title': inBodyPageTitle,
+    'responsive-twin': responsiveTwin,
+    'search-literal-link': searchLiteralLink,
+    'use-search-from-literal': useSearchFromLiteral,
     'visx-boundary': visxBoundary,
     'visx-tooltip': visxTooltip,
     'token-layer-boundary': tokenLayerBoundary,