basalt-ui 1.27.0 → 1.29.0

package/configs/oxlint-plugin.js

@@ -80,16 +80,30 @@ import { fileURLToPath } from 'node:url'
 
 // ── Shared helpers ──────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Guard kinds and plugin rules RETIRED — kept recognized by `KNOWN_RULE_IDS` (below) and the
+ * guard's own `PLUGIN_RULE_IDS` copy so an existing `theme-allow <id>` reads as a dead waiver via
+ * `check-theme --audit-allows`, never as a typo.
+ *
+ * - `unframed-chart` (regex: a `<ChartLegend items={[...]}>` array literal) →
+ *   `basalt/chart-legend-literal`, which also catches the `.map()`-over-a-non-series form the
+ *   regex never could reach.
+ * - `duplicate-notifications-mount` — its only case, `<BasaltNotifications />` mounted beside
+ *   `<BasaltOverlays notifications>`, is unreachable now that `BasaltNotifications` no longer
+ *   exists as a standalone export; the rule had nothing left to fire on.
+ */
+export const RETIRED_RULE_IDS = new Set(['unframed-chart', 'duplicate-notifications-mount'])
+
 /**
  * Rule ids a `theme-allow` may name — this plugin's own rules plus `src/guard`'s kinds. Duplicated
  * by hand for the same reason `majorOf` is: this file loads standalone out of a consumer's
  * node_modules and must not import from the package.
  *
  * Exported, and `oxlint-plugin.test.ts` asserts it is EXACTLY the plugin's own rule ids plus
- * `GUARD_RULES`'s keys. Forgetting an entry here is not a cosmetic omission — an id this set does
- * not know is treated as a typo, so the annotation naming it waives nothing (see
- * {@link parseThemeAllow}); before the fail-closed change it was worse still, silently widening to
- * a blanket waiver.
+ * `GUARD_RULES`'s keys plus `RETIRED_RULE_IDS`. Forgetting an entry here is not a cosmetic
+ * omission — an id this set does not know is treated as a typo, so the annotation naming it waives
+ * nothing (see {@link parseThemeAllow}); before the fail-closed change it was worse still, silently
+ * widening to a blanket waiver.
  */
 export const KNOWN_RULE_IDS = new Set([
   // this plugin
@@ -104,16 +118,23 @@ export const KNOWN_RULE_IDS = new Set([
   'raw-scroll-container',
   'hand-rolled-filter',
   'control-outside-home',
+  'bound-control-outside-home',
   'control-size-literal',
   'page-bar-budget',
   'responsive-twin',
   'search-literal-link',
   'use-search-from-literal',
+  'provider-above-router',
+  'query-dual-import',
+  'query-fn-unwrap',
+  'deprecated-export',
+  'forms-field-key',
   // `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',
+  'no-import-meta-env',
   // These three honour `basalt-agent-allow`, never `theme-allow` — but they are real ids, so an
   // annotation naming one must parse as a (useless) scoped annotation rather than as prose.
   'agent-resume-guard',
@@ -135,7 +156,6 @@ export const KNOWN_RULE_IDS = new Set([
   'inline-display',
   'raw-visx-axis',
   'raw-motion-value',
-  'unframed-chart',
   'chart-missing-aria-label',
   'raw-form-control',
   'sub-16-input-font',
@@ -147,6 +167,9 @@ export const KNOWN_RULE_IDS = new Set([
   'hidden-inline-style',
   'in-body-page-title',
   'raw-selection-control',
+  // Retired guard kinds — no longer in GUARD_RULES, but a `theme-allow` naming one must still
+  // parse as a real (dead) waiver rather than an unknown-id typo. See RETIRED_RULE_IDS above.
+  ...RETIRED_RULE_IDS,
 ])
 
 const ALLOW_RULE_TOKEN = /^(?:basalt\/)?([a-z][a-z0-9-]*)(?=$|[\s,:—–])/
@@ -443,6 +466,16 @@ function isInStyleContext(context, node) {
   return false
 }
 
+/**
+ * No `/src/tokens/` exemption, and none is needed: both rules below only ever visit `JSXAttribute`/
+ * `Property` nodes, and `src/tokens/**` is pure data — `.ts`, never `.tsx`, zero React — so the
+ * visitor structurally cannot fire there. A path-based exemption used to sit here gated on
+ * `isBasaltScopedFile`, which tests "does the nearest package.json depend on basalt-ui", not
+ * "is this file basalt's own" — a consumer package that merely depends on basalt-ui could put raw
+ * literals under its own `src/tokens/` and silence both rules. Deleting the exemption is simpler
+ * than re-gating it on package identity: the simplest gate is no gate.
+ */
+// Ships: error
 const noRawFontSize = {
   meta: {
     type: 'suggestion',
@@ -452,7 +485,7 @@ const noRawFontSize = {
     schema: [],
   },
   create(context) {
-    if (getFilename(context).includes('/src/tokens/') || isTestFile(context)) return {}
+    if (isTestFile(context)) return {}
 
     return {
       JSXAttribute(node) {
@@ -496,16 +529,19 @@ const SIZE_ATTRS = new Set(['size', 'fz', 'fontSize'])
  * which is not always a font size — on `Text` it is, on `ThemeIcon`/`ActionIcon` it is a box
  * dimension — so one shared id would mean a consumer silencing the icon case also silences every
  * off-scale font size, the bundled-rule mistake the three boundary rules were split apart to avoid.
- * And a separate id can carry its own severity: this rule ships `warn` in the consumer preset for
- * one minor (the grace-minor doctrine in the package CLAUDE.md — it rejects code that previously
- * passed, and majors are banned here, so a consumer has no semver channel warning them). Widening
- * `no-raw-font-size` in place would have promoted it to `error` on upgrade with no such runway.
+ * And a separate id can carry its own severity: this rule ships `error` in the consumer preset —
+ * it is a NEW form the sibling rule never caught (a numeric-only check let every string form walk
+ * straight past it), not a narrowing of code that previously passed, so the grace-minor doctrine in
+ * the package CLAUDE.md does not apply to it. Widening `no-raw-font-size` in place would have meant
+ * the widened check inherited whatever level the sibling id already carried, with no way to give
+ * this specific form its own severity.
  *
  * Numeric `size={32}` is deliberately NOT flagged. It is the documented Mantine idiom for icon
  * dimensions and flagging it would fire on nearly every icon in an app for no design-system gain —
  * the token system has an opinion about type scale and spacing, not about how many pixels wide one
  * glyph box is.
  */
+// Ships: error
 const rawSizeLiteral = {
   meta: {
     type: 'suggestion',
@@ -515,7 +551,7 @@ const rawSizeLiteral = {
     schema: [],
   },
   create(context) {
-    if (getFilename(context).includes('/src/tokens/')) return {}
+    if (isTestFile(context)) return {}
 
     return {
       JSXAttribute(node) {
@@ -546,6 +582,7 @@ function attrValue(attr) {
   return unwrapExpressionContainer(attr.value)
 }
 
+// Ships: error
 const cardInset = {
   meta: {
     type: 'suggestion',
@@ -635,6 +672,7 @@ function subtreeHasChart(node) {
   return false
 }
 
+// Ships: error
 const chartInRawSurface = {
   meta: {
     type: 'suggestion',
@@ -720,6 +758,7 @@ function enclosingHomeOwner(node) {
  * code is small enough to fix rather than schedule. A consumer who disagrees turns the whole rule
  * down in their own config.
  */
+// Ships: error
 const rawScrollContainer = {
   meta: {
     type: 'suggestion',
@@ -854,6 +893,7 @@ function boundaryVisitor(reportFor) {
 // segment named `charts` is deliberately permissive, not restrictive — it only ever widens where
 // visx is allowed, never narrows where it's flagged elsewhere. "Your visx lives in a charts/ dir"
 // is the intended convention.
+// Ships: error
 const visxBoundary = {
   meta: {
     type: 'suggestion',
@@ -885,6 +925,7 @@ const visxBoundary = {
 // Rule 6 — visx-tooltip: @visx/tooltip banned everywhere, including inside charts. Fires ahead of
 // (and instead of) basalt/visx-boundary for that one specifier — basalt's own src/ never imports
 // @visx/tooltip, so no theme-allow-style exemption is needed here either.
+// Ships: error
 const visxTooltip = {
   meta: {
     type: 'suggestion',
@@ -908,6 +949,7 @@ const visxTooltip = {
 // @mantine/* installed (see the file-header comment for the cycle/fork + packaging rationale).
 // Repo-local only — never registered in the shipped consumer preset, since this governs basalt's
 // own internal layering/packaging, not a consumer contract.
+// Ships: repo-local only
 const tokenLayerBoundary = {
   meta: {
     type: 'suggestion',
@@ -969,6 +1011,7 @@ function propertyKeyName(node) {
 
 // Deliberately NO `hasThemeAllow` escape — see basalt/visx-boundary's comment for why these
 // guards use their own token (`basalt-agent-allow`, see the file-header comment) instead.
+// Ships: error
 const agentResumeGuard = {
   meta: {
     type: 'problem',
@@ -1015,6 +1058,7 @@ const RAW_USE_CHAT_SOURCES = new Set(['@ai-sdk/react', 'ai/react'])
 const RAW_USE_CHAT_NAMES = new Set(['useChat', 'useCompletion'])
 
 // Deliberately NO `hasThemeAllow` escape — see the file-header comment.
+// Ships: error
 const agentNoRawUseChat = {
   meta: {
     type: 'problem',
@@ -1210,6 +1254,7 @@ function aiSdkMajorMessage(consumerMajor) {
 // version skew is still a fact about two package.json files, but a written, intentional
 // producer/consumer pair (see `doctor`'s `aiMajorSkewReason`) needs a way to say so at the import
 // site too, not just be permanently blocked.
+// Ships: error
 const aiSdkMajor = {
   meta: {
     type: 'problem',
@@ -1302,6 +1347,7 @@ const HAND_ROLLED_PLOT_MESSAGE =
   'the file. To waive just THIS node and stay policed on the rest, write `theme-allow ' +
   'hand-rolled-plot — <why>` on its own line above it. (basalt/hand-rolled-plot)'
 
+// Ships: error
 const handRolledPlot = {
   meta: {
     type: 'suggestion',
@@ -1412,6 +1458,7 @@ function isMapCall(node) {
   )
 }
 
+// Ships: error
 const chartLegendLiteral = {
   meta: {
     type: 'suggestion',
@@ -1678,6 +1725,7 @@ function shadowBasaltExportMessage(name) {
  * tokens does not. `warn`, not `error`: a name collision is evidence, not proof, and a consumer
  * with a genuinely different `Composer` should be told once, not blocked.
  */
+// Ships: warn (advisory)
 const shadowBasaltExport = {
   meta: {
     type: 'suggestion',
@@ -1806,6 +1854,7 @@ const HAND_ROLLED_SHELL_MESSAGE =
  * it. The module that DEFINES `BasaltShell` is exempt by declaration, not by path — a rule saying
  * "compose X" cannot fire inside X.
  */
+// Ships: error
 const handRolledShell = {
   meta: {
     type: 'suggestion',
@@ -1928,11 +1977,26 @@ const BOUND_TAGS = new Set([
  * 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.
+ *
+ * **The declaration alone is not enough, and the second half is what makes the set safe to widen.**
+ * `PanelRow`, `EnumFilter` and `SliderControl` are ordinary names a consumer writes for their own
+ * helpers, and a bare-name match let one local `function PanelRow(…)` switch `control-outside-home`,
+ * `bound-control-outside-home` and `responsive-twin` off for that WHOLE file. So the exemption also
+ * requires the file to import NOTHING from `basalt-ui*`: basalt's own control sources import each
+ * other RELATIVELY, while a consumer of basalt always names the package. A file that consumes
+ * basalt is not the module that defines its controls, whatever it calls its helpers.
  */
 const CONTROL_OWNER_NAMES = new Set([
   ...BOUND_TAGS,
   'FilterSet',
   'FilterPill',
+  // The INTERNAL control modules, listed for the same reason the public names are: `EnumFilter` is
+  // the shared body behind SelectFilter/CompareFilter/NumberFilter, and `PanelRow`/`SliderControl`
+  // are the aside's row primitives (`docs/ASIDE-SPEC.md` §3). A module that IS a bound control
+  // cannot be told to use one. This is a RELAXATION, so it needs no grace entry (C16).
+  'EnumFilter',
+  'PanelRow',
+  'SliderControl',
   'SyncButton',
   'ActionGroup',
   'OverflowMenu',
@@ -1940,19 +2004,25 @@ const CONTROL_OWNER_NAMES = new Set([
 ])
 
 /**
- * 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.
+ * Where a raw selection control legitimately lives outside a TIERED home: a settings row, a form
+ * 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}).
+ * `FormRow`/`FormGroup` (`basalt-ui/forms`, `src/forms/form-layout.tsx`) are the SAME home written
+ * for a `<form>` rather than a settings page — a `TextInput` bound to a field is read and typed
+ * into at Mantine's own tier, not a 30px chrome affordance — so they are added here rather than
+ * given a second walk.
  *
  * 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',
+  'FormRow',
+  'FormGroup',
   'Modal',
   'Drawer',
   'Popover.Dropdown',
@@ -1960,6 +2030,24 @@ const CONTROL_HOST_TAGS = new Set([
   'Composer',
 ])
 
+/**
+ * The basalt elements whose CHILDREN are a home — the SUBTREE homes, where the body IS the surface
+ * (`docs/ASIDE-SPEC.md` §3). `FilterSet` mounts the pill surface, `PageAside` the panel surface,
+ * `PanelRow` the row itself (its `end` prop resolves here too: the attribute hangs off `PanelRow`'s
+ * own opening element, so the ancestry walk reaches the element).
+ *
+ * Read by BOTH C1 rules, because the two must not disagree about what a home IS — before this set
+ * existed `bound-control-outside-home` treated all three as homes and `control-outside-home` knew
+ * none of them, so a raw `<Select>` inside a `<PageAside><PanelRow>` reported while the bound
+ * control beside it did not.
+ *
+ * Unlike {@link CONTROL_HOST_TAGS} these are PROVENANCE-gated, the same test
+ * {@link SLOT_OWNER_TAGS} applies and for the same reason: `PanelRow` is an ordinary name for a
+ * consumer's own layout helper, and reading one as a basalt home would exempt a genuinely homeless
+ * control. The overlay hosts stay name-matched because `Modal`/`Drawer` are Mantine's, not basalt's.
+ */
+const BASALT_HOST_TAGS = new Set(['FilterSet', 'PageAside', 'PanelRow'])
+
 /**
  * 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
@@ -1978,10 +2066,32 @@ const CONTROL_HOST_TAGS = new Set([
  * with 9 known false positives. `-panel.tsx` is the loosest member and the one to reconsider first
  * if the set ever needs narrowing.
  *
+ * TWO dialects, because a repo picks one file-naming law and the convention has to survive either:
+ * `edit-session-modal.tsx` (kebab) and `CbbiPanel.tsx` (PascalCase — what a repo mandating
+ * `PascalCase.tsx` for component files writes, basalt's own root `CLAUDE.md` included). The kebab
+ * form alone could never match a component file in such a repo, which is exactly how the CBBI panel
+ * — a `PageAside` child whose `<PageAside>` is in the PARENT page — collected four warns that no
+ * ancestry walk in that file could ever have avoided.
+ *
+ * Both dialects require the leading SUBJECT: `Panel.tsx` and `modal.tsx` are page modules in every
+ * consumer that has one, and a bare-noun exemption would switch the rules off wholesale.
+ *
  * 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$/
+const OVERLAY_CONVENTION_KEBAB = /^[^/]*-(?:modal|drawer|popover|panel|form)\.[jt]sx$/
+const OVERLAY_CONVENTION_PASCAL = /^[A-Z]\w*(?:Modal|Drawer|Popover|Panel|Form)\.[jt]sx$/
+
+/**
+ * The single predicate both `control-outside-home` and `bound-control-outside-home` ask — see
+ * {@link OVERLAY_CONVENTION_KEBAB} for the whole trade. One function, so the two rules can never
+ * disagree about what the convention IS; `src/guard/index.ts` carries the text-lane copy of the
+ * same two dialects (`raw-selection-control`), pinned by both test files.
+ */
+function isOverlayConventionFile(filename) {
+  const basename = filename.slice(filename.lastIndexOf('/') + 1)
+  return OVERLAY_CONVENTION_KEBAB.test(basename) || OVERLAY_CONVENTION_PASCAL.test(basename)
+}
 
 /** How far an ancestry walk climbs before giving up — a JSX tree this deep is not a slot value. */
 const ANCESTRY_MAX_DEPTH = 60
@@ -2190,6 +2300,34 @@ function hasAncestorTag(node, tags) {
   return false
 }
 
+/**
+ * The BINDINGS of every JSX ancestor of `node`, nearest first — {@link hasAncestorTag} for a
+ * PROVENANCE-gated set. It returns names rather than a boolean for the same reason
+ * {@link slotOwnerBinding} does: whether that `PanelRow` is basalt's is answered by the import list,
+ * which is only complete at `Program:exit`, while the ancestry is only walkable during the visit.
+ *
+ * `tags` is OPTIONAL, and omitting it is the second real use rather than a convenience: a rule
+ * whose ancestor set is not known until the import list is complete cannot filter by tag NAME at
+ * all (`RouterProvider as Router` is an ordinary thing to write), so it takes every binding and
+ * resolves them at exit. `provider-above-router` is that caller.
+ */
+function ancestorTagBindings(node, tags) {
+  const found = []
+  let current = node.parent
+  for (let depth = 0; current !== null && current !== undefined; depth++) {
+    if (depth > ANCESTRY_MAX_DEPTH || current.type === 'Program') break
+    if (
+      current.type === 'JSXElement' &&
+      (tags === undefined || tags.has(jsxTagName(current.openingElement?.name) ?? ''))
+    ) {
+      const root = jsxRootName(current.openingElement?.name)
+      if (root !== undefined) found.push(root)
+    }
+    current = current.parent
+  }
+  return found
+}
+
 /** 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
@@ -2239,6 +2377,14 @@ function createSlotContext(context) {
    * depending on JSX order.
    */
   const slotBoundIdentifiers = new Map()
+  /**
+   * Hoisted identifier → every SUBTREE-home BINDING whose children it was rendered as.
+   *
+   * The same hop `slotBoundIdentifiers` makes, one home shape over: `const rows = <SelectFilter/>`
+   * handed to `<PageAside>{rows}</PageAside>` is inside that aside, and the ancestry walk cannot
+   * see it because at the `const` there is no `PageAside` above the node at all.
+   */
+  const subtreeHostedIdentifiers = new Map()
   return {
     /** Feed every ImportDeclaration here — this is where the owner provenance comes from. */
     noteImport(node) {
@@ -2256,12 +2402,32 @@ function createSlotContext(context) {
         else owners.add(owner)
       }
     },
+    /**
+     * Feed every JSXExpressionContainer here — a `{expr}` CHILD of a subtree home
+     * ({@link BASALT_HOST_TAGS}) hosts the identifiers that expression resolves through.
+     */
+    noteChild(node) {
+      const parent = node.parent
+      if (parent === null || parent === undefined || parent.type !== 'JSXElement') return
+      const name = parent.openingElement?.name
+      if (!BASALT_HOST_TAGS.has(jsxTagName(name) ?? '')) return
+      const owner = jsxRootName(name)
+      if (owner === undefined) return
+      const identifiers = new Set()
+      collectSlotValueIdentifiers(node.expression, identifiers)
+      for (const id of identifiers) {
+        const owners = subtreeHostedIdentifiers.get(id)
+        if (owners === undefined) subtreeHostedIdentifiers.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),
+        subtreeHosts: ancestorTagBindings(node, BASALT_HOST_TAGS),
       }
     },
     /** Is a captured node inside a BASALT home slot — directly, or via a hoisted binding? */
@@ -2281,6 +2447,21 @@ function createSlotContext(context) {
     isHome(name) {
       return name !== undefined && homes.has(name)
     },
+    /**
+     * Is a captured node inside a basalt SUBTREE home — directly by ancestry, or via a hoisted
+     * binding rendered as one's `{expr}` child? Both halves resolve the binding through `homes`,
+     * so a consumer's own `PanelRow` is not one.
+     */
+    inSubtreeHome(captured) {
+      for (const binding of captured.subtreeHosts) {
+        if (homes.has(binding)) return true
+      }
+      if (captured.declaratorName === undefined) return false
+      for (const owner of subtreeHostedIdentifiers.get(captured.declaratorName) ?? []) {
+        if (homes.has(owner)) return true
+      }
+      return false
+    },
     /**
      * 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
@@ -2303,14 +2484,24 @@ function createSlotContext(context) {
   }
 }
 
-/** Collects an owner-definition flag for the control layer — see {@link CONTROL_OWNER_NAMES}. */
+/** Collects the owner-definition verdict for the control layer — see {@link CONTROL_OWNER_NAMES}. */
 function createControlOwnerProbe() {
-  const state = { definesControl: false }
+  const state = { definesControl: false, importsBasalt: false }
   const note = (name) => {
     if (typeof name === 'string' && CONTROL_OWNER_NAMES.has(name)) state.definesControl = true
   }
   return {
-    state,
+    /** Feed every ImportDeclaration here — a `basalt-ui*` import disqualifies the exemption. */
+    noteImport(node) {
+      const source = node.source?.value
+      if (typeof source === 'string' && BASALT_IMPORT_SOURCE.test(source)) {
+        state.importsBasalt = true
+      }
+    },
+    /** Does this file DEFINE a basalt control rather than consume one? Both halves are required. */
+    isOwner() {
+      return state.definesControl && !state.importsBasalt
+    },
     visitors: {
       FunctionDeclaration(node) {
         note(node.id?.name)
@@ -2343,6 +2534,7 @@ const HAND_ROLLED_FILTER_MESSAGE =
  * `SettingsRow.control`, the form-row home — see {@link SLOT_ATTRS} for why a raw input is right
  * there.
  */
+// Ships: error
 const handRolledFilter = {
   meta: {
     type: 'problem',
@@ -2392,9 +2584,9 @@ const handRolledFilter = {
 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)'
+  'through a slot prop (law C1). A settings row, a form row (FormRow/FormGroup), 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
@@ -2402,11 +2594,13 @@ const CONTROL_OUTSIDE_HOME_MESSAGE =
  * 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.
+ * Four exemptions carry the false-positive load: an overlay/settings-row/form-row ancestor
+ * ({@link CONTROL_HOST_TAGS}, `FormRow`/`FormGroup` included), an {@link isOverlayConventionFile}
+ * 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.
  */
+// Ships: warn (grace → 1.30.0)
 const controlOutsideHome = {
   meta: {
     type: 'suggestion',
@@ -2415,7 +2609,7 @@ const controlOutsideHome = {
   },
   create(context) {
     if (isTestFile(context)) return {}
-    if (OVERLAY_CONVENTION_FILE.test(getFilename(context))) return {}
+    if (isOverlayConventionFile(getFilename(context))) return {}
     const slots = createSlotContext(context)
     const owner = createControlOwnerProbe()
     const mantineImports = new Map()
@@ -2427,11 +2621,15 @@ const controlOutsideHome = {
       ImportDeclaration(node) {
         collectMantineImports(node, mantineImports)
         slots.noteImport(node)
+        owner.noteImport(node)
         if ((node.source?.value ?? '') === '@mantine/form') importsMantineForm = true
       },
       JSXAttribute(node) {
         slots.note(node)
       },
+      JSXExpressionContainer(node) {
+        slots.noteChild(node)
+      },
       JSXOpeningElement(node) {
         // Cheap pre-filter: the tag as WRITTEN, or any Mantine binding (an alias resolves at exit).
         const root = jsxRootName(node.name)
@@ -2444,11 +2642,11 @@ const controlOutsideHome = {
         })
       },
       'Program:exit'() {
-        if (importsMantineForm || owner.state.definesControl) return
+        if (importsMantineForm || owner.isOwner()) 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 (hosted || slots.resolve(captured) || slots.inSubtreeHome(captured)) continue
           if (hasThemeAllow(context, node, 'control-outside-home')) continue
           context.report({ node, message: CONTROL_OUTSIDE_HOME_MESSAGE })
         }
@@ -2536,6 +2734,7 @@ export const CTL_THEME_TAGS = new Set([
  */
 const TIERLESS_SLOT_OWNERS = new Set(['ChartCard'])
 
+// Ships: error
 const controlSizeLiteral = {
   meta: {
     type: 'suggestion',
@@ -2655,6 +2854,7 @@ function actionsAttributeValue(node) {
  * 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.
  */
+// Ships: error
 const pageBarBudget = {
   meta: {
     type: 'problem',
@@ -2770,6 +2970,7 @@ function titleOrderOf(node) {
  * lanes on purpose, so one `theme-allow in-body-page-title — <why>` waives both rather than
  * needing a different word per enforcement surface.
  */
+// Ships: error
 const inBodyPageTitle = {
   meta: {
     type: 'suggestion',
@@ -2842,6 +3043,7 @@ function subtreeControlTags(node, into = new Set(), depth = 0) {
  * 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.
  */
+// Ships: error
 const responsiveTwin = {
   meta: {
     type: 'suggestion',
@@ -2878,10 +3080,13 @@ const responsiveTwin = {
 
     return {
       ...owner.visitors,
+      ImportDeclaration(node) {
+        owner.noteImport(node)
+      },
       JSXElement: inspectChildren,
       JSXFragment: inspectChildren,
       'Program:exit'() {
-        if (owner.state.definesControl) return
+        if (owner.isOwner()) return
         for (const node of twins) {
           if (hasThemeAllow(context, node, 'responsive-twin')) continue
           context.report({ node, message: RESPONSIVE_TWIN_MESSAGE })
@@ -2920,6 +3125,7 @@ function insideNavDefinition(node) {
   return false
 }
 
+// Ships: error
 const searchLiteralLink = {
   meta: {
     type: 'suggestion',
@@ -2953,6 +3159,7 @@ const USE_SEARCH_FROM_LITERAL_MESSAGE =
   '(law C10) — take the value as a prop, or read it through the store field. ' +
   '(basalt/use-search-from-literal)'
 
+// Ships: error
 const useSearchFromLiteral = {
   meta: {
     type: 'suggestion',
@@ -2979,6 +3186,648 @@ const useSearchFromLiteral = {
   },
 }
 
+// ── Rule 24 — bound-control-outside-home ────────────────────────────────────────────────────────
+
+/**
+ * A bound basalt control with no home — the pill-shaped controls, and `SliderControl` is
+ * deliberately NOT among them: it has no pill form at all. It always renders a `PanelRow`
+ * (`docs/ASIDE-SPEC.md` §3), so a `<Section>` body or a plain page stack is a legitimate place to
+ * write one and "this renders as a stray pill" would be false there. {@link BOUND_TAGS} is the
+ * whole set; every member is a `FieldHandle`-bound `basalt-ui/controls` export, so unlike
+ * {@link RAW_FILTER_TAGS} there is no question of what it is FOR — only of where it was written.
+ */
+const BOUND_CONTROL_OUTSIDE_HOME_MESSAGE =
+  'Bound basalt control with no home — a SelectFilter / ToggleFilter / RangeFilter / ' +
+  'MultiSelectFilter / NumberFilter / SearchFilter / ViewTabs renders as a stray pill when it is ' +
+  'written into a Section body or a page stack. It belongs in a home slot (`filters` / `tabs` / ' +
+  '`filtersEnd` / `actions` / `sync` / `control`), inside a <FilterSet>, or inside a <PageAside> ' +
+  '— where the panel surface renders it as a row instead (law C1, docs/ASIDE-SPEC.md §3). ' +
+  'SliderControl is not policed: it renders its own PanelRow and has no pill form. An overlay ' +
+  '(Modal/Drawer/Popover/Menu), a settings row and a form row (FormRow/FormGroup) are the ' +
+  'declared non-homes and never report. (basalt/bound-control-outside-home)'
+
+/**
+ * A BOUND basalt control that is in no home at all — ledger G5 (`docs/ASIDE-SPEC.md` §2), the half
+ * of law C1 that had no guard: `control-outside-home` matches raw Mantine tags only, so a
+ * `<SelectFilter field={…}/>` dropped into a `Section` body passed silently and shipped as a stray
+ * pill.
+ *
+ * A NEW id rather than a widening of `control-outside-home`, per C16: a level is per-id, so
+ * widening that rule would have landed this form at whatever level it holds, with no grace of its
+ * own — and widening it in a minor would restart its grace besides.
+ *
+ * Provenance is the tag's basalt IMPORT ({@link collectBasaltImportMap}), never its bare name: a
+ * consumer's own `SelectFilter` is not this one. The exemptions are the sibling rule's minus the
+ * `@mantine/form` one — a form input is a raw input, and a `FieldHandle`-bound filter in a form
+ * module is homeless there exactly as it is anywhere else.
+ *
+ * **There is deliberately NO text-lane twin in `src/guard`.** `raw-selection-control` can key on a
+ * bare Mantine tag name because that name is Mantine's whatever the file does with it; a bound
+ * control's name says nothing without the import graph and the ancestry, and a regex over a
+ * 12-line window has neither. A text heuristic here would report a consumer's own `SelectFilter` in
+ * its own `filters` slot — signal the plugin already has, noise the guard would add.
+ */
+// Ships: warn (grace → 1.30.0)
+const boundControlOutsideHome = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Warn on a bound basalt control that is in no basalt home.' },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+    if (isOverlayConventionFile(getFilename(context))) return {}
+    const slots = createSlotContext(context)
+    const owner = createControlOwnerProbe()
+    const controls = new Map()
+    const ownTree = isBasaltOwnSource(getFilename(context))
+    const candidates = []
+
+    return {
+      ...owner.visitors,
+      ImportDeclaration(node) {
+        collectBasaltImportMap(node, controls, ownTree)
+        slots.noteImport(node)
+        owner.noteImport(node)
+      },
+      JSXAttribute(node) {
+        slots.note(node)
+      },
+      JSXExpressionContainer(node) {
+        slots.noteChild(node)
+      },
+      JSXOpeningElement(node) {
+        // Cheap pre-filter on the tag as WRITTEN; an alias resolves through `controls` at exit.
+        const root = jsxRootName(node.name)
+        if (root === undefined) return
+        if (!BOUND_TAGS.has(jsxTagName(node.name) ?? '') && !controls.has(root)) return
+        candidates.push({
+          node,
+          root,
+          captured: slots.capture(node),
+          hosted: hasAncestorTag(node, CONTROL_HOST_TAGS),
+        })
+      },
+      'Program:exit'() {
+        if (owner.isOwner()) return
+        for (const { node, root, captured, hosted } of candidates) {
+          const exported = controls.get(root)
+          if (exported === undefined || !BOUND_TAGS.has(exported)) continue
+          if (hosted || slots.resolve(captured) || slots.inSubtreeHome(captured)) continue
+          if (hasThemeAllow(context, node, 'bound-control-outside-home')) continue
+          context.report({ node, message: BOUND_CONTROL_OUTSIDE_HOME_MESSAGE })
+        }
+      },
+    }
+  },
+}
+
+// ── Rule 25 — provider-above-router ─────────────────────────────────────────────────────────────
+
+/** `@tanstack/react-router` and its subpaths — never `@tanstack/react-router-devtools`. */
+const TANSTACK_ROUTER_SOURCE = /^@tanstack\/react-router(?:\/|$)/
+
+const PROVIDER_ABOVE_ROUTER_MESSAGE =
+  '<BasaltProvider> is rendered INSIDE <RouterProvider> — invert them. Mantine context has to ' +
+  'exist before any route renders, so the mount order is BasaltProvider → the data layer → ' +
+  'RouterProvider (agent/rules/basalt-mantine.md). A route that renders a themed component ' +
+  'before the provider mounts reads Mantine defaults, not the basalt theme. ' +
+  '(basalt/provider-above-router)'
+
+/**
+ * `BasaltProvider` mounted BELOW a TanStack `RouterProvider` — F5, the first of the three
+ * `basalt-mantine.md` laws that shipped under a `not guarded: —` banner.
+ *
+ * Both tags are provenance-gated: `BasaltProvider` through {@link collectBasaltImportMap} (so a
+ * consumer's own component of that name is not this one) and `RouterProvider` through an
+ * `@tanstack/react-router` import, by its LOCAL binding rather than its written name. The inverse
+ * nesting — the correct one — is not a finding, and neither is either tag alone.
+ *
+ * **STATIC JSX ancestry only, and that is the whole heuristic.** The two providers have to be
+ * written in one JSX tree in one file for this to see anything. The common real shape (`main.tsx`
+ * renders `<BasaltProvider><App/></BasaltProvider>` and `App` renders `<RouterProvider/>`) is
+ * INVERTED cross-file and correct; the inverted-and-wrong cross-file shape is equally invisible.
+ * A rule that followed the composition would need the module graph, which an oxlint rule does not
+ * have — so this catches the one-file case and the law stays advisory for the rest. That is why it
+ * lands at `warn`.
+ */
+// Ships: warn (grace → 1.30.0)
+const providerAboveRouter = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Warn on a BasaltProvider rendered inside a TanStack RouterProvider.' },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+    const ownTree = isBasaltOwnSource(getFilename(context))
+    const basalt = new Map()
+    const routers = new Set()
+    const candidates = []
+
+    return {
+      ImportDeclaration(node) {
+        collectBasaltImportMap(node, basalt, ownTree)
+        const source = node.source?.value
+        if (typeof source !== 'string' || !TANSTACK_ROUTER_SOURCE.test(source)) return
+        for (const spec of node.specifiers ?? []) {
+          const imported = spec.imported?.name ?? spec.imported?.value
+          if (imported === 'RouterProvider' && typeof spec.local?.name === 'string') {
+            routers.add(spec.local.name)
+          }
+        }
+      },
+      JSXOpeningElement(node) {
+        const root = jsxRootName(node.name)
+        if (root === undefined || !basalt.has(root)) return
+        candidates.push({ node, root, ancestors: ancestorTagBindings(node) })
+      },
+      'Program:exit'() {
+        for (const { node, root, ancestors } of candidates) {
+          if (basalt.get(root) !== 'BasaltProvider') continue
+          if (!ancestors.some((name) => routers.has(name))) continue
+          if (hasThemeAllow(context, node, 'provider-above-router')) continue
+          context.report({ node, message: PROVIDER_ABOVE_ROUTER_MESSAGE })
+        }
+      },
+    }
+  },
+}
+
+// ── Rule 27 — query-dual-import ─────────────────────────────────────────────────────────────────
+
+/** `@tanstack/react-query` and its subpaths — never `@tanstack/react-query-devtools`. */
+const TANSTACK_QUERY_SOURCE = /^@tanstack\/react-query(?:\/|$)/
+
+/** The `basalt-ui/query` subpath, exactly — the seam the hooks are supposed to arrive through. */
+const BASALT_QUERY_SOURCE = 'basalt-ui/query'
+
+/** The root barrel — where `QueryState` and the dashboard composites live. */
+const BASALT_ROOT_SOURCE = 'basalt-ui'
+
+const QUERY_DUAL_IMPORT_MESSAGE =
+  'Dual query import — this file imports from @tanstack/react-query AND from basalt-ui/query. ' +
+  'Take the hooks, the client factory and `unwrap` from basalt-ui/query only: two entry points to ' +
+  'one library is how a second QueryClient, a second devtools bundle and a duplicated ' +
+  '`toErrorMessage` reach an app (agent/rules/basalt-batteries.md). ' +
+  '(basalt/query-dual-import)'
+
+const QUERY_ROOT_IMPORT_MESSAGE =
+  'Raw @tanstack/react-query import in a basalt file — the hooks come through basalt-ui/query, ' +
+  'which re-exports them beside `createBasaltQueryClient`, `unwrap`, `toErrorMessage` and the lazy ' +
+  'devtools (agent/rules/basalt-batteries.md). Import from basalt-ui/query instead. ' +
+  '(basalt/query-dual-import)'
+
+/**
+ * The `basalt-batteries.md` law "import query hooks from `basalt-ui/query`, never dual-import
+ * `@tanstack/react-query`" — F5, and one of the two `./query` surfaces that shipped advisory.
+ *
+ * TWO forms, one id, because they are one law read at two strengths. The DUAL form (both
+ * specifiers present) is the law verbatim. The softer form — a raw `@tanstack/react-query` import
+ * in a file that also imports the basalt root barrel — is a heuristic: it says "this file is
+ * already a basalt file, so the query seam is right there", and it is the form that actually
+ * catches the drift, since a file that has never heard of `basalt-ui/query` cannot dual-import.
+ * The softer form is why the whole rule lands at `warn` rather than `error`.
+ *
+ * Gated on the LITERAL specifier, never on `ownTree` relative resolution: basalt's own
+ * `src/query/**` and `src/dashboard/query-state.tsx` import `@tanstack/react-query` because they
+ * ARE the seam, and they reach their siblings relatively. A file that writes `basalt-ui/query` is
+ * by definition a consumer of the published surface.
+ */
+// Ships: warn (grace → 1.30.0)
+const queryDualImport = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Warn on a raw @tanstack/react-query import beside a basalt import.' },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+    const raw = []
+    let basaltQuery = false
+    let basaltRoot = false
+
+    return {
+      ImportDeclaration(node) {
+        const source = node.source?.value
+        if (typeof source !== 'string') return
+        if (source === BASALT_QUERY_SOURCE) basaltQuery = true
+        else if (source === BASALT_ROOT_SOURCE) basaltRoot = true
+        // `import type { UseQueryResult } from '@tanstack/react-query'` is erased at compile time
+        // — there is no runtime import to route through the seam, and typing against the library's
+        // own result type is exactly what `QueryStateLike` documents as legitimate. Same skip
+        // `agent-no-raw-usechat` and `ai-sdk-major` take.
+        else if (TANSTACK_QUERY_SOURCE.test(source) && node.importKind !== 'type') raw.push(node)
+      },
+      'Program:exit'() {
+        if (!basaltQuery && !basaltRoot) return
+        const message = basaltQuery ? QUERY_DUAL_IMPORT_MESSAGE : QUERY_ROOT_IMPORT_MESSAGE
+        for (const node of raw) {
+          if (hasThemeAllow(context, node, 'query-dual-import')) continue
+          context.report({ node, message })
+        }
+      },
+    }
+  },
+}
+
+// ── Rule 28 — query-fn-unwrap ───────────────────────────────────────────────────────────────────
+
+const QUERY_FN_UNWRAP_MESSAGE =
+  'queryFn fetches without unwrap() — `unwrap` throws on the error branch AND on a null data with ' +
+  'no error (a 204, a silent transport failure), and both are caller bugs that have to surface as ' +
+  'a rejected query rather than as `data: null` rendered through the success branch ' +
+  '(agent/rules/basalt-batteries.md). Wrap the call: `queryFn: () => unwrap(client.thing.get())`. ' +
+  '(basalt/query-fn-unwrap)'
+
+/** A bare `fetch(` / `unwrap(` call, as written — the two halves of this rule's text heuristic. */
+const FETCH_CALL = /\bfetch\s*\(/
+const UNWRAP_CALL = /\bunwrap\s*\(/
+
+/**
+ * A `queryFn` that fetches and never `unwrap`s it — F5, the second unguarded `./query` law.
+ *
+ * **The heuristic is deliberately one sentence long, and it is a TEXT test inside a SYNTACTIC
+ * range**: the rule takes the source span of the `queryFn` property's own function value and fires
+ * only when `fetch(` appears in it and `unwrap(` does not. Nothing resolves, nothing follows a
+ * helper out of the span.
+ *
+ * What that buys and what it costs, both stated so neither is a surprise. It sees the two shapes
+ * the doctrine is actually written against — `queryFn: () => fetch(url)` and
+ * `queryFn: async () => (await fetch(url)).json()`. It does NOT see a `queryFn: fetchThing`
+ * reference, an Eden/Treaty call (`client.thing.get()` contains no `fetch(`), or an `unwrap`
+ * applied one frame out; and it counts an `unwrap(` anywhere in the span, including one applied to
+ * something else. A stricter version would need the call graph. The narrow version fires on the
+ * form a consumer writes by reflex on day one, which is the one the law exists for.
+ *
+ * Scoped to files importing `basalt-ui/query` literally, for the reason {@link queryDualImport}
+ * gives: without that gate it is an opinion about `fetch`, which basalt does not have.
+ */
+// Ships: warn (grace → 1.30.0)
+const queryFnUnwrap = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Warn on a queryFn that fetches without wrapping the call in unwrap().' },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+    const candidates = []
+    let basaltQuery = false
+
+    return {
+      ImportDeclaration(node) {
+        if (node.source?.value === BASALT_QUERY_SOURCE) basaltQuery = true
+      },
+      Property(node) {
+        if (propertyKeyName(node) !== 'queryFn') return
+        const value = node.value
+        if (value?.type !== 'ArrowFunctionExpression' && value?.type !== 'FunctionExpression') {
+          return
+        }
+        candidates.push({ node, value })
+      },
+      'Program:exit'() {
+        if (!basaltQuery) return
+        const text = context.sourceCode?.text ?? ''
+        for (const { node, value } of candidates) {
+          const [start, end] = value.range ?? []
+          if (typeof start !== 'number' || typeof end !== 'number') continue
+          const body = text.slice(start, end)
+          if (!FETCH_CALL.test(body) || UNWRAP_CALL.test(body)) continue
+          if (hasThemeAllow(context, node, 'query-fn-unwrap')) continue
+          context.report({ node, message: QUERY_FN_UNWRAP_MESSAGE })
+        }
+      },
+    }
+  },
+}
+
+// ── Rule 29 — deprecated-export ─────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {{
+ *   subpath: string
+ *   name: string
+ *   prop?: string
+ *   replacement: string
+ *   removeIn: string
+ *   fix?: false
+ * }} DeprecatedExport
+ */
+
+/**
+ * The deprecation ledger — every export that is `@deprecated` but still SHIPPED, with what to
+ * write instead and the minor it goes away in. B4: majors are banned here, so a rename cannot be
+ * signalled by a version number; the lifecycle is instead "ship the alias, lint the old name, write
+ * the MIGRATING row, remove it a minor later" (`../CLAUDE.md`, "Deprecation lifecycle").
+ *
+ * A row without `prop` is a NAMED IMPORT from `subpath` — reported on the specifier, with an
+ * autofix that rewrites it to `{ <replacement> as <local> }` so no call site has to move in the
+ * same edit. **That autofix is the row's contract**: only a DROP-IN rename belongs here. A
+ * deprecation whose replacement takes a different shape (`createSearchParamStore` →
+ * `createSearchStore` + a `fields` object) would need the fix suppressed before it could be a row,
+ * and until then it lives in `MIGRATING.md` alone. A row WITH `prop` is a JSX ATTRIBUTE on the component `name`, imported from `subpath`
+ * — no autofix, because the three connectivity props collapse into ONE object prop and a
+ * per-attribute rewrite would produce three `connectivity=` attributes on one tag.
+ *
+ * **Adding a row is the whole job.** Deprecate the export in its JSDoc, add the row here with a
+ * `removeIn` at least one minor out, add the `MIGRATING.md` row, and this rule starts nudging.
+ * `oxlint-plugin.test.ts` scans every `src/**\/index.ts(x)` barrel for a JSDoc `@deprecated` and
+ * fails when one has no row here, so the barrel half cannot be forgotten. Removing the export is a
+ * separate commit that deletes the row in the same change.
+ *
+ * @type {readonly DeprecatedExport[]}
+ */
+export const DEPRECATED_EXPORTS = [
+  // Empty since 1.29.0: every 1.28.x deprecation was removed on schedule. The next
+  // deprecation adds a row here in the same commit as its @deprecated JSDoc and MIGRATING entry.
+]
+
+function deprecatedExportMessage(row) {
+  const what =
+    row.prop === undefined
+      ? `\`${row.name}\` from ${row.subpath}`
+      : `\`${row.prop}\` on <${row.name}>`
+  return (
+    `Deprecated basalt export — ${what} is superseded by \`${row.replacement}\` and is removed in ` +
+    `${row.removeIn}. It still resolves today, so nothing is broken yet; migrate before that minor ` +
+    '(packages/basalt-ui/MIGRATING.md carries the row). ' +
+    '(basalt/deprecated-export)'
+  )
+}
+
+/**
+ * A shipped-but-`@deprecated` export still being imported or written — B4, the sunset half of the
+ * lifecycle whose absence the blueprint audit found (§8): the grace mechanism covers a rule getting
+ * STRICTER, and nothing covered an export going away.
+ *
+ * Permanently `warn` ({@link PLUGIN_RULE_ADVISORY}), for the same reason `shadow-basalt-export` is:
+ * a deprecation is a schedule, not a defect. The code compiles and runs; promoting this to `error`
+ * would break a consumer's build for something that still works, which is the one thing the
+ * no-majors doctrine exists to avoid. The `removeIn` minor is where it becomes an error — by the
+ * export ceasing to exist.
+ */
+// Ships: warn (advisory)
+const deprecatedExport = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Warn on an import or prop that basalt has deprecated but still ships.' },
+    schema: [],
+    fixable: 'code',
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+    if (isBasaltOwnSource(getFilename(context))) return {}
+    const importRows = DEPRECATED_EXPORTS.filter((row) => row.prop === undefined)
+    const propRows = DEPRECATED_EXPORTS.filter((row) => row.prop !== undefined)
+    const components = new Map()
+    const candidates = []
+
+    return {
+      ImportDeclaration(node) {
+        const source = node.source?.value
+        if (typeof source !== 'string') return
+        for (const spec of node.specifiers ?? []) {
+          const imported = spec.imported?.name ?? spec.imported?.value
+          const local = spec.local?.name
+          if (typeof imported !== 'string' || typeof local !== 'string') continue
+          for (const row of propRows) {
+            if (source === row.subpath && imported === row.name) components.set(local, row.name)
+          }
+          const row = importRows.find((r) => r.subpath === source && r.name === imported)
+          if (row === undefined) continue
+          if (hasThemeAllow(context, spec, 'deprecated-export')) continue
+          context.report({
+            node: spec,
+            message: deprecatedExportMessage(row),
+            ...(row.fix === false
+              ? {}
+              : { fix: (fixer) => fixer.replaceText(spec, `${row.replacement} as ${local}`) }),
+          })
+        }
+      },
+      JSXAttribute(node) {
+        const name = node.name?.name
+        if (typeof name !== 'string') return
+        const owner = node.parent
+        if (owner === null || owner === undefined || owner.type !== 'JSXOpeningElement') return
+        const root = jsxRootName(owner.name)
+        if (root === undefined) return
+        candidates.push({ node, root, name })
+      },
+      'Program:exit'() {
+        for (const { node, root, name } of candidates) {
+          const component = components.get(root)
+          if (component === undefined) continue
+          const row = propRows.find((r) => r.name === component && r.prop === name)
+          if (row === undefined) continue
+          if (hasThemeAllow(context, node, 'deprecated-export')) continue
+          context.report({ node, message: deprecatedExportMessage(row) })
+        }
+      },
+    }
+  },
+}
+
+// ── Rule 30 — forms-field-key ───────────────────────────────────────────────────────────────────
+
+/** The subpath the forms idiom is imported from — the only provenance this rule accepts. */
+const FORMS_IMPORT_SOURCE = 'basalt-ui/forms'
+
+/** The three names this rule resolves through the local→imported map. */
+const FORMS_SPREAD_NAMES = new Set(['inputProps', 'field'])
+
+const FORMS_FIELD_KEY_MESSAGES = {
+  missing:
+    'A spread `inputProps(…)` with no sibling `key`. The field loses its reconciler key, so an ' +
+    'uncontrolled input keeps its old text through `form.reset()`, `form.setValues()` and a ' +
+    'removed list row — nothing throws and nothing type-checks differently. Write ' +
+    '`key={fieldKey(form, path)} {...inputProps(form, path)}`: `inputProps` stopped returning ' +
+    '`key` because a spread `key` is a React 19 warning, and a call site that merely kept the ' +
+    'spread compiles unchanged and silently stops resetting. ' +
+    '(basalt/forms-field-key)',
+  deprecatedAlias:
+    'A spread `field(…)`. That is the @deprecated 1.27 alias and it still bundles `key` INTO the ' +
+    'returned object, so it still logs React 19\'s `A props object containing a "key" prop is ' +
+    'being spread into JSX` on every render — kept byte-identical on purpose, because a ' +
+    'deprecation is a schedule and not a silent behaviour change. Migrate to ' +
+    '`key={fieldKey(form, path)} {...inputProps(form, path)}` (packages/basalt-ui/MIGRATING.md ' +
+    'carries the row); the alias itself is removed in 1.29.0. ' +
+    '(basalt/forms-field-key)',
+}
+
+/** The `key` attribute among a JSXOpeningElement's attributes, if it has one written literally. */
+function hasKeyAttribute(opening) {
+  for (const attr of opening?.attributes ?? []) {
+    if (attr?.type === 'JSXAttribute' && attr.name?.name === 'key') return true
+  }
+  return false
+}
+
+/**
+ * A field spread that lost its reconciler key — the guard for the one change in the 1.28.0 forms
+ * minor that a consumer's compiler cannot see.
+ *
+ * `inputProps` used to return `getInputProps(path)` AND `key` in one object, so
+ * `<TextInput {...inputProps(form, 'x')} />` covered both. It no longer returns `key` (a spread
+ * `key` is a React 19 warning), and that exact call site still type-checks, still renders and still
+ * validates — it just stops resetting. There is no compile error, no throw and no console line to
+ * find it by, which is precisely the profile a lint rule exists for.
+ *
+ * TWO forms under this one id, because they are one law read from either end:
+ *
+ * - `{...inputProps(…)}` with no sibling `key` — the post-migration mistake. Autofixed: the `key`
+ *   attribute is inserted with the SAME arguments, and `fieldKey` is added to the existing
+ *   `basalt-ui/forms` import when it is not already there, so `--fix` produces working code rather
+ *   than an unresolved identifier.
+ * - `{...field(…)}` — the pre-migration call site. Reported ALWAYS, key or no key, and deliberately
+ *   NOT autofixed: `field` still returns the bundle, so inserting a second `key` would be wrong,
+ *   and the honest remedy is the rename `basalt/deprecated-export` already nudges. This arm is a
+ *   pointer at the migration, one lane over from that rule's import-level nudge.
+ *
+ * Provenance is the `basalt-ui/forms` specifier (plus a relative import inside basalt's own `src/`,
+ * or the dogfood surface goes silent — the same gate `collectBasaltImports` uses), read through the
+ * local→imported map so `import { inputProps as f }` is covered. `inputProps` is an ordinary enough
+ * name that firing on an unimported one would be an opinion about a consumer's own helper.
+ */
+// Ships: warn (grace → 1.30.0)
+const formsFieldKey = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Warn on a spread field object that lost (or still bundles) its key.' },
+    schema: [],
+    fixable: 'code',
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+    const ownTree = isBasaltOwnSource(getFilename(context))
+    /** local name → the name it was imported as, for the three forms names. */
+    const imported = new Map()
+    /** The forms ImportDeclaration the `fieldKey` specifier is added to, if one exists. */
+    let formsImport
+    const candidates = []
+
+    return {
+      ImportDeclaration(node) {
+        const source = node.source?.value
+        if (typeof source !== 'string') return
+        if (source !== FORMS_IMPORT_SOURCE && !(ownTree && RELATIVE_IMPORT_SOURCE.test(source))) {
+          return
+        }
+        for (const spec of node.specifiers ?? []) {
+          const local = spec.local?.name
+          const name = spec.imported?.name ?? spec.imported?.value
+          if (typeof local !== 'string' || typeof name !== 'string') continue
+          if (name === 'fieldKey' || FORMS_SPREAD_NAMES.has(name)) {
+            imported.set(local, name)
+            if (source === FORMS_IMPORT_SOURCE) formsImport = node
+          }
+        }
+      },
+      JSXSpreadAttribute(node) {
+        const call = node.argument
+        if (call?.type !== 'CallExpression' || call.callee?.type !== 'Identifier') return
+        const opening = node.parent
+        if (opening === null || opening === undefined || opening.type !== 'JSXOpeningElement')
+          return
+        candidates.push({ node, call, local: call.callee.name, opening })
+      },
+      'Program:exit'() {
+        const text = context.sourceCode?.text ?? ''
+        const hasFieldKey = [...imported.values()].includes('fieldKey')
+        let importFixed = false
+
+        for (const { node, call, local, opening } of candidates) {
+          const name = imported.get(local)
+          if (name === undefined) continue
+          if (hasThemeAllow(context, node, 'forms-field-key')) continue
+
+          if (name === 'field') {
+            context.report({ node, message: FORMS_FIELD_KEY_MESSAGES.deprecatedAlias })
+            continue
+          }
+          if (hasKeyAttribute(opening)) continue
+
+          const args = call.arguments ?? []
+          const first = args[0]?.range
+          const last = args[args.length - 1]?.range
+          // No arguments to copy means no honest `fieldKey(…)` to write — report without a fix
+          // rather than emit one that does not compile.
+          if (first === undefined || last === undefined) {
+            context.report({ node, message: FORMS_FIELD_KEY_MESSAGES.missing })
+            continue
+          }
+          const argsText = text.slice(first[0], last[1])
+          // The import specifier is added by the FIRST fixed occurrence only: three fields in one
+          // file would otherwise emit three overlapping edits to one import, and an overlapping
+          // fix is dropped rather than merged.
+          const needsImport = !hasFieldKey && !importFixed && formsImport !== undefined
+          const lastSpec = needsImport
+            ? formsImport.specifiers?.[(formsImport.specifiers?.length ?? 0) - 1]
+            : undefined
+          if (needsImport && lastSpec !== undefined) importFixed = true
+
+          context.report({
+            node,
+            message: FORMS_FIELD_KEY_MESSAGES.missing,
+            fix: (fixer) => {
+              const fixes = [fixer.insertTextBefore(node, `key={fieldKey(${argsText})} `)]
+              if (lastSpec !== undefined) fixes.push(fixer.insertTextAfter(lastSpec, ', fieldKey'))
+              return fixes
+            },
+          })
+        }
+      },
+    }
+  },
+}
+
+// ── Rule 31 — no-import-meta-env ────────────────────────────────────────────────────────────────
+
+const NO_IMPORT_META_ENV_MESSAGE =
+  'import.meta.env is banned in shipped basalt-ui source — this package is consumed both as a ' +
+  'Vite-bundled dep AND resolved directly by a consumer whose own bundler may define no ' +
+  'import.meta.env at all (basaltViteConfig defines process.env.NODE_ENV precisely so basalt ' +
+  'code never needs it). Use process.env.NODE_ENV instead. (basalt/no-import-meta-env)'
+
+/**
+ * `import.meta.env` — a MemberExpression whose object is the `import.meta` MetaProperty and whose
+ * property is `env`. Repo-local only: a CONSUMER's own app code legitimately uses
+ * `import.meta.env.VITE_*` for its own config, so this must never reach the shipped preset — only
+ * `/.oxlintrc.json` wires it, scoped to `packages/basalt-ui/src/**` the same way the Mantine-free
+ * boundaries above are scoped, rather than through path logic in the rule itself (unlike
+ * `token-layer-boundary`, which every package resolves the plugin from and so has to self-scope).
+ */
+// Ships: repo-local only
+const noImportMetaEnv = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow import.meta.env — basalt-ui source must use process.env.NODE_ENV.',
+    },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+
+    return {
+      MemberExpression(node) {
+        const object = node.object
+        if (
+          object?.type !== 'MetaProperty' ||
+          object.meta?.name !== 'import' ||
+          object.property?.name !== 'meta'
+        )
+          return
+        if (node.computed || node.property?.name !== 'env') return
+        if (hasThemeAllow(context, node, 'no-import-meta-env')) return
+        context.report({ node, message: NO_IMPORT_META_ENV_MESSAGE })
+      },
+    }
+  },
+}
+
 // ── Grace ledger ────────────────────────────────────────────────────────────────────────────────
 
 /**
@@ -3012,7 +3861,7 @@ const useSearchFromLiteral = {
 export const PLUGIN_RULE_GRACE = {
   'control-outside-home': {
     since: '1.26.0',
-    promote: '1.28.0',
+    promote: '1.30.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 ' +
@@ -3022,11 +3871,76 @@ export const PLUGIN_RULE_GRACE = {
       '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 " +
+      '{@link isOverlayConventionFile} exempts that declared naming convention, in BOTH the kebab ' +
+      '(`edit-session-modal.tsx`) and the PascalCase (`CbbiPanel.tsx`) dialect. Re-dated ' +
+      '2026-08-28 — the argo wave-7 migration has not run; the PascalCase overlay convention (this ' +
+      'change) is expected to clear most of the 9. 1.30.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`.',
   },
+  'bound-control-outside-home': {
+    since: '1.28.0',
+    promote: '1.30.0',
+    why:
+      'ASIDE-SPEC G5 — a bound control in a section body rendered as a stray pill and nothing saw ' +
+      'it. `control-outside-home` matches raw Mantine tags only, so the whole basalt half of law ' +
+      'C1 was unguarded: `<SelectFilter field={…}/>` written into a `Section` body or a bare page ' +
+      'stack passed every lane. A NEW id rather than a widening (C16 — a level is per-id), landing ' +
+      'warn because it inherits the sibling rule\'s heuristic: "this control has no home" is a ' +
+      'claim about layout intent, and the ancestry it reads now spans four subtree homes ' +
+      '(FilterSet / PageAside / PanelRow / the overlay hosts) that only shipped in 1.27.0. 1.30.0 ' +
+      'is when the incumbent count across argo, linewatch, image-share, rb, image-gen and the ' +
+      'playground is re-measured.',
+  },
+  'provider-above-router': {
+    since: '1.28.0',
+    promote: '1.30.0',
+    why:
+      'F5 — one of the three basalt-mantine.md laws that shipped under a `not guarded: —` banner. ' +
+      'It reads STATIC JSX ancestry inside one file, which is a genuine fraction of the law: the ' +
+      'usual real shape composes the two providers across modules, where no oxlint rule can see ' +
+      'the nesting at all. Landing it at `error` would state a certainty the implementation does ' +
+      'not have. 1.30.0 is when the incumbent count across argo, linewatch, image-share, rb, ' +
+      'image-gen and the playground is measured — every one of them mounts a router, so the ' +
+      'false-positive question has a real sample.',
+  },
+  'query-dual-import': {
+    since: '1.28.0',
+    promote: '1.30.0',
+    why:
+      'F5 — the basalt-batteries.md law with no guard. TWO forms under one id: the dual import ' +
+      '(both `@tanstack/react-query` and `basalt-ui/query` in one file) is the law verbatim, and ' +
+      'the softer form — a raw `@tanstack/react-query` import in a file that also imports the ' +
+      'basalt root barrel — is the heuristic that actually catches the drift, since a file that ' +
+      'never names `basalt-ui/query` cannot dual-import. The soft form is what holds the whole ' +
+      'rule at `warn`: "this file is already a basalt file" is a claim about intent. 1.30.0 is ' +
+      'when the consumer count is measured and the soft form is either kept or split off.',
+  },
+  'forms-field-key': {
+    since: '1.28.0',
+    promote: '1.30.0',
+    why:
+      "the 1.28.0 forms minor took `key` out of `inputProps`' return, and the OLD call site " +
+      "(`<TextInput {...inputProps(form, 'x')} />`) survives that change with no compile error, " +
+      'no throw and no console line — it just stops resetting. This rule is the only thing that ' +
+      'reports it, which is an argument for `error`, not `warn`; it lands at `warn` anyway ' +
+      'because it fires on code every consumer is CURRENTLY shipping, and the grace minor is what ' +
+      'turns "your build is broken by the upgrade" into "your editor lists the eleven lines". ' +
+      'The `field(` arm is the same law read from the pre-migration end, and that alias is removed ' +
+      'in 1.29.0 anyway. 1.30.0 is when argo, linewatch, image-share, rb, image-gen and the ' +
+      'playground have all been through the autofix and the remainder is measured.',
+  },
+  'query-fn-unwrap': {
+    since: '1.28.0',
+    promote: '1.30.0',
+    why:
+      'F5 — the second unguarded ./query law. Openly a TEXT heuristic inside a syntactic range: ' +
+      '`fetch(` present in the queryFn span and `unwrap(` absent. It cannot see a `queryFn: ' +
+      'fetchThing` reference, an Eden/Treaty call, or an unwrap one frame out, and it counts an ' +
+      '`unwrap(` applied to anything. That is a deliberate floor rather than a first draft, and a ' +
+      'rule whose stated reach is this narrow has no business failing a build. 1.30.0 is when the ' +
+      'measured false-positive load decides whether it promotes or stays advisory.',
+  },
 }
 
 /**
@@ -3050,6 +3964,16 @@ export const PLUGIN_RULE_ADVISORY = {
       '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.',
   },
+  'deprecated-export': {
+    since: '1.28.0',
+    why:
+      'B4, the sunset half of the deprecation lifecycle (`../CLAUDE.md`). A deprecation is a ' +
+      'SCHEDULE, not a defect: the code compiles, runs and is correct until the `removeIn` minor, ' +
+      'so promoting this to `error` would fail a consumer build over something that still works — ' +
+      'the one outcome the no-majors doctrine exists to avoid. There is no version at which that ' +
+      'stops being true, which is what makes it advisory rather than a grace entry: enforcement ' +
+      'arrives by the export ceasing to exist, not by this rule changing level.',
+  },
 }
 
 // ── Plugin export ───────────────────────────────────────────────────────────────────────────────
@@ -3068,17 +3992,24 @@ export default {
     'raw-scroll-container': rawScrollContainer,
     'hand-rolled-filter': handRolledFilter,
     'control-outside-home': controlOutsideHome,
+    'bound-control-outside-home': boundControlOutsideHome,
     '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,
+    'provider-above-router': providerAboveRouter,
+    'query-dual-import': queryDualImport,
+    'query-fn-unwrap': queryFnUnwrap,
+    'deprecated-export': deprecatedExport,
+    'forms-field-key': formsFieldKey,
     'visx-boundary': visxBoundary,
     'visx-tooltip': visxTooltip,
     'token-layer-boundary': tokenLayerBoundary,
     'agent-resume-guard': agentResumeGuard,
     'agent-no-raw-usechat': agentNoRawUseChat,
     'ai-sdk-major': aiSdkMajor,
+    'no-import-meta-env': noImportMetaEnv,
   },
 }