@starci/eslint-grammar-core 0.15.33 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.16.0 - 2026-10-30
+
+- Changed: the peer moves to eslint-canon-fe 9.6.0; the bundled runtime copies are now generated from the hfs build (TypeScript emitted as .mjs) per runtime/bundle.json, with a drift check in CI; the copies the package keeps as its own are listed there and stay hand-maintained; the bundled canon pins name hfs 4.12.0, eslint-canon-be 3.9.0, eslint-canon-fe 9.6.0, the Grammar family 0.16.0, jest-preset 2.5.3 and test-world 1.3.3. No rule of this package changed.
+- Added: starci-grammar/generated-art-in-mascot-or-media-frame (R338, FE_GENERATED_ART_OUTSIDE_FRAME): a static /images/**.webp or .png src outside Mascot or MediaFrame is a finding; starci-grammar/mascot-asset-slot-required (R339, FE_MASCOT_ASSET_SLOT_MISSING): a Mascot names its assetSlot. Specs: src/mascot.spec.ts.
+
+## 0.15.34 - 2026-10-30
+
+- Changed: the peer moves to eslint-canon-fe 9.5.23; the bundled canon pins name hfs 4.11.22 (app check and lint pass under 20 findings), eslint-canon-be 3.8.21, eslint-canon-fe 9.5.23 and the Grammar family 0.15.34. No rule of this package changed.
+
 ## 0.15.33 - 2026-10-30
 
 - Changed: the peer moves to eslint-canon-fe 9.5.22; the bundled canon pins name hfs 4.11.21 (the one-command urgent release), eslint-canon-be 3.8.20, eslint-canon-fe 9.5.22 and the Grammar family 0.15.33. No rule of this package changed.

package/README.md

@@ -19,7 +19,7 @@ Family helpers and the generated runtime closure belong to this package.
 
 The rule IDs remain stable when their namespace moves. Laws cover the fixed app shell and navbar,
 Grammar-owned structural elements, glyphs and icon sizes, destructive menu entries, status inks,
-chip labels that start uppercase, the page head composed by `PageHeader`, the route page as one `Page` with its tabs in the header, heading and token scales, vendor ownership and slot-status composition. Each rule's metadata cites
+chip labels that start uppercase, generated art rendered through `Mascot` or `MediaFrame` with every `Mascot` naming its asset slot, the page head composed by `PageHeader`, the route page as one `Page` with its tabs in the header, heading and token scales, vendor ownership and slot-status composition. Each rule's metadata cites
 its behavioral knowledge source and the governing ownership test. The R318 surface composition
 rules (nested control variants, panel-list alignment, layout-only CSS) stay in the universal canon.
 

package/dist/index.js

@@ -5,6 +5,7 @@ import { rules as chipLabelRules } from "./chip-label.js";
 import { rules as drawingRules } from "./drawing.js";
 import { rules as grammarBoundaryRules } from "./grammar-boundary.js";
 import { rules as iconRules } from "./icon.js";
+import { rules as mascotRules } from "./mascot.js";
 import { rules as menuEntriesRules } from "./menu-entries.js";
 import { rules as pageRules } from "./page.js";
 import { rules as pageHeaderRules } from "./page-header.js";
@@ -19,6 +20,7 @@ const CONTRIBUTIONS = [
     { law: "drawing", rules: drawingRules },
     { law: "grammar-boundary", rules: grammarBoundaryRules },
     { law: "icon", rules: iconRules },
+    { law: "mascot", rules: mascotRules },
     { law: "menu-entries", rules: menuEntriesRules },
     { law: "page", rules: pageRules },
     { law: "page-header", rules: pageHeaderRules },

package/dist/lib/why.js

@@ -9,6 +9,16 @@ export const why = {
         en: "A StatusDot or Badge label in `<file>` starts with a lowercase letter.",
         fix: "Start the label with an uppercase letter (`Running`, not `running`); the rule fixes a literal label in place.",
     },
+    "generated-art-in-mascot-or-media-frame": {
+        code: "FE_GENERATED_ART_OUTSIDE_FRAME",
+        en: "Generated art (a `.webp` or `.png` under `/images/`) in `<file>` is drawn outside Grammar's `Mascot` and `MediaFrame`, so it takes whatever box the page gives it.",
+        fix: "Render a character with `<Mascot src size assetSlot />` (sm, md, lg or hero), or frame a scene or illustration in `<MediaFrame assetSlot>`.",
+    },
+    "mascot-asset-slot-required": {
+        code: "FE_MASCOT_ASSET_SLOT_MISSING",
+        en: "A `Mascot` in `<file>` names no `assetSlot`, so nothing ties the art it draws to the asset workflow's request.",
+        fix: "Pass `assetSlot` (the slot id of the request) and `assetSha256` once the file is delivered.",
+    },
     "navbar-cluster": {
         code: "FE_NAVBAR_CLUSTER",
         en: "Navbar action component kinds or order differ from the app-shell canon.",

package/dist/mascot.d.ts

@@ -0,0 +1,28 @@
+import type { Rule } from "eslint";
+/**
+ * The mascot law (HFS R338 `FE_GENERATED_ART_OUTSIDE_FRAME`, R339 `FE_MASCOT_ASSET_SLOT_MISSING`): generated art renders
+ * at the Grammar's size scale and stays tied to the asset workflow's request.
+ *
+ * Generated art is a raster the asset workflow delivers under the public `/images/` tree, as `.webp` or `.png`. Drawn
+ * through a bare `Image` or `<img>` it takes whatever box its page gives it, so one mascot comes out at a different size on
+ * every screen and nothing ties the bytes to the slot that requested them. Grammar's `Mascot` owns the character scale
+ * (sm, md, lg, hero), and `MediaFrame` frames a scene or illustration; those two are its renderers.
+ *
+ * WHAT IT READS. A JSX `src` attribute whose value is statically a string (a literal, an expression container holding one,
+ * a template literal without expressions, or a `const` of the file initialised with one). A source computed at run time is
+ * not judged: the rule never guesses. `assetSlot` is read on every `Mascot` element (`Mascot` or `<ns>.Mascot`); a spread
+ * attribute may carry it, so an element with a spread is not judged.
+ *
+ * WHERE IT APPLIES. Product source (`isProductSource`: the route, feature, component, hook, foundation, module and transport
+ * tiers and the workspace packages). A script or a file no slot owns is not judged.
+ */
+/** A generated raster under the public `/images/` tree: `.webp` or `.png`, any case, an optional query or fragment. */
+export declare const GENERATED_ART: RegExp;
+/** Generated art under `/images/` renders only through `Mascot` or inside a `MediaFrame`. */
+export declare const generatedArtInMascotOrMediaFrame: Rule.RuleModule;
+/** Every `Mascot` names the asset slot its art was requested under. */
+export declare const mascotAssetSlotRequired: Rule.RuleModule;
+/** The rules this law contributes to the plugin. */
+export declare const rules: Record<string, Rule.RuleModule>;
+/** Every rule of this law is an error. */
+export declare const recommended: Record<string, "error">;

package/dist/mascot.js

@@ -0,0 +1,166 @@
+import { isProductSource } from "@starci/eslint-canon-fe/lib/scope.mjs";
+import { defineFamilyRules, defineRule } from "./lib/rule-contract.js";
+/**
+ * The mascot law (HFS R338 `FE_GENERATED_ART_OUTSIDE_FRAME`, R339 `FE_MASCOT_ASSET_SLOT_MISSING`): generated art renders
+ * at the Grammar's size scale and stays tied to the asset workflow's request.
+ *
+ * Generated art is a raster the asset workflow delivers under the public `/images/` tree, as `.webp` or `.png`. Drawn
+ * through a bare `Image` or `<img>` it takes whatever box its page gives it, so one mascot comes out at a different size on
+ * every screen and nothing ties the bytes to the slot that requested them. Grammar's `Mascot` owns the character scale
+ * (sm, md, lg, hero), and `MediaFrame` frames a scene or illustration; those two are its renderers.
+ *
+ * WHAT IT READS. A JSX `src` attribute whose value is statically a string (a literal, an expression container holding one,
+ * a template literal without expressions, or a `const` of the file initialised with one). A source computed at run time is
+ * not judged: the rule never guesses. `assetSlot` is read on every `Mascot` element (`Mascot` or `<ns>.Mascot`); a spread
+ * attribute may carry it, so an element with a spread is not judged.
+ *
+ * WHERE IT APPLIES. Product source (`isProductSource`: the route, feature, component, hook, foundation, module and transport
+ * tiers and the workspace packages). A script or a file no slot owns is not judged.
+ */
+/** A generated raster under the public `/images/` tree: `.webp` or `.png`, any case, an optional query or fragment. */
+export const GENERATED_ART = /^\/images\/.+\.(?:webp|png)(?:[?#].*)?$/i;
+/** The components that render generated art: the element itself, or an ancestor that frames it. */
+const RENDERER = "Mascot";
+const FRAME = "MediaFrame";
+/** The element name of a JSX name: `Mascot`, or `G.Mascot` as `Mascot`. */
+const nameOf = (name) => {
+    if (name.type === "JSXIdentifier")
+        return name.name;
+    if (name.type === "JSXMemberExpression")
+        return name.property.name;
+    return null;
+};
+/** The variable a name resolves to, walking the scope chain outwards. */
+const variableOf = (scope, name) => {
+    for (let current = scope; current !== null; current = current.upper) {
+        const found = current.set.get(name);
+        if (found !== undefined)
+            return found;
+    }
+    return null;
+};
+/** The string an expression statically is, or null. */
+const staticString = (expression, scopeOf) => {
+    if (expression.type === "Literal")
+        return typeof expression.value === "string" ? expression.value : null;
+    if (expression.type === "TemplateLiteral")
+        return expression.expressions.length === 0 ? expression.quasis.map((quasi) => quasi.value.cooked ?? "").join("") : null;
+    if (expression.type === "Identifier") {
+        const variable = variableOf(scopeOf(expression), expression.name);
+        const definition = variable?.defs.length === 1 ? variable.defs[0] : undefined;
+        if (definition?.type !== "Variable")
+            return null;
+        const declarator = definition.node;
+        const declaration = definition.parent;
+        if (declaration?.kind !== "const" || declarator.init === null || declarator.init.type === "Identifier")
+            return null;
+        return staticString(declarator.init, scopeOf);
+    }
+    return null;
+};
+/** The string a JSX attribute value statically is, or null. */
+const attributeString = (value, scopeOf) => {
+    if (value === null)
+        return null;
+    if (value.type === "Literal")
+        return typeof value.value === "string" ? value.value : null;
+    if (value.type === "JSXExpressionContainer" && value.expression.type !== "JSXEmptyExpression")
+        return staticString(value.expression, scopeOf);
+    return null;
+};
+/** True when a `MediaFrame` element encloses the node. */
+const insideFrame = (node) => {
+    // The Program's parent is null at run time though the tree's types say a node always has one.
+    for (let current = node.parent; current !== undefined && current !== null; current = current.parent) {
+        if (current.type === "JSXElement" && nameOf(current.openingElement.name) === FRAME)
+            return true;
+    }
+    return false;
+};
+/** Generated art under `/images/` renders only through `Mascot` or inside a `MediaFrame`. */
+export const generatedArtInMascotOrMediaFrame = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "R338: generated art (a .webp or .png under /images/) renders only through Grammar's Mascot or inside a MediaFrame." },
+        schema: [],
+        messages: {
+            outside: "`{{src}}` is generated art drawn by `<{{element}}>`, outside Grammar's `Mascot` and `MediaFrame`: it takes whatever box this page gives it, so the same art comes out at a different size on every screen. Render a character with `<Mascot src size assetSlot />` (sm, md, lg or hero) or frame a scene or illustration in `<MediaFrame assetSlot>`.",
+        },
+    },
+    create(context) {
+        if (!isProductSource(context))
+            return {};
+        const scopeOf = (node) => context.sourceCode.getScope(node);
+        return {
+            JSXAttribute(attribute) {
+                if (attribute.name.type !== "JSXIdentifier" || attribute.name.name !== "src")
+                    return;
+                const src = attributeString(attribute.value, scopeOf);
+                if (src === null || !GENERATED_ART.test(src))
+                    return;
+                const opening = attribute.parent;
+                if (opening.type !== "JSXOpeningElement")
+                    return;
+                const element = nameOf(opening.name);
+                if (element === RENDERER || insideFrame(opening))
+                    return;
+                context.report({ node: attribute, messageId: "outside", data: { src, element: element ?? "element" } });
+            },
+        };
+    },
+});
+/** True when an attribute names nothing: no value, an empty string, or `undefined`. */
+const namesNothing = (attribute) => {
+    const value = attribute.value;
+    if (value === null)
+        return true;
+    if (value.type === "Literal")
+        return value.value === "";
+    if (value.type !== "JSXExpressionContainer")
+        return false;
+    const expression = value.expression;
+    if (expression.type === "JSXEmptyExpression")
+        return true;
+    if (expression.type === "Identifier")
+        return expression.name === "undefined";
+    if (expression.type === "Literal")
+        return expression.value === "" || expression.value === null;
+    if (expression.type === "TemplateLiteral")
+        return expression.expressions.length === 0 && expression.quasis.every((quasi) => quasi.value.cooked === "");
+    return false;
+};
+/** Every `Mascot` names the asset slot its art was requested under. */
+export const mascotAssetSlotRequired = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "R339: every Grammar Mascot names its asset slot (assetSlot), tying the rendered art to the asset workflow's request." },
+        schema: [],
+        messages: {
+            missing: "This `Mascot` names no `assetSlot`: nothing ties the art it draws to the asset workflow's request, so a drawing, a test or an audit cannot tell which slot it fills. Pass `assetSlot` (and `assetSha256` once the file is delivered).",
+        },
+    },
+    create(context) {
+        if (!isProductSource(context))
+            return {};
+        return {
+            JSXOpeningElement(opening) {
+                if (nameOf(opening.name) !== RENDERER)
+                    return;
+                if (opening.attributes.some((attribute) => attribute.type === "JSXSpreadAttribute"))
+                    return;
+                const slot = opening.attributes.find((attribute) => attribute.type === "JSXAttribute" && attribute.name.type === "JSXIdentifier" && attribute.name.name === "assetSlot");
+                if (slot === undefined || namesNothing(slot))
+                    context.report({ node: opening, messageId: "missing" });
+            },
+        };
+    },
+});
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "generated-art-in-mascot-or-media-frame": generatedArtInMascotOrMediaFrame,
+    "mascot-asset-slot-required": mascotAssetSlotRequired,
+};
+defineFamilyRules({ "generated-art-in-mascot-or-media-frame": generatedArtInMascotOrMediaFrame }, "knowledge/hfs/rules.yaml#R338");
+defineFamilyRules({ "mascot-asset-slot-required": mascotAssetSlotRequired }, "knowledge/hfs/rules.yaml#R339");
+/** Every rule of this law is an error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-grammar/${name}`, "error"]));

package/docs/mascot.md

@@ -0,0 +1,60 @@
+# Generated art renders through Mascot
+
+Law module: `mascot.ts`. Catalogue: R338 FE_GENERATED_ART_OUTSIDE_FRAME, R339 FE_MASCOT_ASSET_SLOT_MISSING.
+
+Generated art is a raster the asset workflow delivers under the public `/images/` tree, as `.webp` or `.png`. Grammar's
+`Mascot` renders a character at one size scale (`sm` 96px, `md` 160px, `lg` 240px square, `hero` filling its host's
+height up to its cap), always contained on a transparent ground; `MediaFrame` frames a scene or illustration. Both carry
+the asset-slot props (`assetSlot`, `assetSha256`, `assetPrompt`) that tie the render to the request. Drawn through a bare
+`Image` or `<img>`, the same art takes whatever box each page gives it.
+
+Every rule below is an error in `coreGrammarConfig`; none can be switched off or suppressed inline. Both apply to
+product source (the route, feature, component, hook, foundation, module and transport tiers and the workspace packages);
+a script or a file no slot owns is not judged.
+
+## `starci-grammar/generated-art-in-mascot-or-media-frame`
+
+A JSX `src` attribute whose value is statically a path under `/images/` ending in `.webp` or `.png` (any case, an
+optional query or fragment) is a finding unless its element is a `Mascot` (`Mascot` or `<ns>.Mascot`) or a `MediaFrame`
+element encloses it. The value is read from a string literal, an expression container holding one, a template literal
+without expressions, or a `const` of the file initialised with one; a source computed at run time is not judged.
+`.svg`, `.jpg` and paths outside `/images/` are not generated art here.
+
+**Invalid** (`src/components/blocks/Onboarding/component.tsx`)
+
+```tsx
+<Image src="/images/mascot/welcome.webp" alt="" />
+```
+
+**Valid** (`src/components/blocks/Onboarding/component.tsx`)
+
+```tsx
+<Mascot src="/images/mascot/welcome.webp" size="lg" assetSlot="onboarding.welcome" />
+
+<MediaFrame assetSlot="landing.scene">
+  <Image src="/images/scene/landing.webp" alt="" />
+</MediaFrame>
+```
+
+**Finding code:** `FE_GENERATED_ART_OUTSIDE_FRAME`
+
+## `starci-grammar/mascot-asset-slot-required`
+
+A `Mascot` element with no `assetSlot`, or with one that names nothing (`""`, `{undefined}`), is a finding, reported on
+the element. An element with a spread attribute is not judged: the spread may carry the slot.
+
+**Invalid**
+
+```tsx
+<Mascot src="/images/mascot/welcome.webp" size="hero" />
+```
+
+**Valid**
+
+```tsx
+<Mascot src="/images/mascot/welcome.webp" size="hero" assetSlot="auth.sign-in" assetSha256={sha} />
+```
+
+**Finding code:** `FE_MASCOT_ASSET_SLOT_MISSING`
+
+Rule ownership: [FE-RULE-OWNERSHIP](../../../contexts/code/fe/README.md#the-placement-test-fe-rule-ownership).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-grammar-core",
-  "version": "0.15.33",
+  "version": "0.16.0",
   "description": "ESLint rules for the core Grammar's component, token and composition contracts.",
   "keywords": [
     "eslint",
@@ -41,7 +41,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@starci/eslint-canon-fe": "9.5.22",
+    "@starci/eslint-canon-fe": "9.6.0",
     "eslint": ">=9",
     "typescript": ">=5.9"
   },

package/runtime/bundle.json

@@ -0,0 +1,74 @@
+{
+  "generated": [
+    "engine/by-code-unit.mjs",
+    "engine/model-config.mjs",
+    "engine/orca-config.mjs",
+    "engine/plain-object.mjs",
+    "engine/release-config.mjs",
+    "engine/removed-vocabulary.mjs",
+    "engine/resources-config.mjs",
+    "engine/runtime-root.mjs",
+    "engine/secrets.mjs",
+    "engine/sonar-config.mjs",
+    "engine/yaml.mjs",
+    "knowledge/grammars/core/playbook.yaml",
+    "knowledge/grammars/index.yaml",
+    "knowledge/hfs/canon-pins.yaml",
+    "knowledge/ui/presentation/font.yaml",
+    "knowledge/ui/presentation/padding.yaml",
+    "modules/kernel/removed-vocabulary.yaml",
+    "modules/models/registry.yaml",
+    "modules/models/runtimes.yaml",
+    "modules/models/tiers.yaml",
+    "scripts/hfs/allows.mjs",
+    "scripts/hfs/architecture/config.mjs",
+    "scripts/hfs/architecture/side-boundary.mjs",
+    "scripts/hfs/architecture/type-context.mjs",
+    "scripts/hfs/architecture/typescript.mjs",
+    "scripts/hfs/declaration-shape.mjs",
+    "scripts/hfs/declaration-slots.mjs",
+    "scripts/hfs/edition-slots.mjs",
+    "scripts/hfs/param-names.mjs",
+    "scripts/hfs/rule-catalog.mjs",
+    "scripts/hfs/rule-params-shape.mjs",
+    "scripts/hfs/slot-app-view.mjs",
+    "scripts/hfs/slot-classify.mjs",
+    "scripts/hfs/slot-errors.mjs",
+    "scripts/hfs/slot-imports.mjs",
+    "scripts/hfs/slot-manifest-shape.mjs",
+    "scripts/hfs/slot-match.mjs",
+    "scripts/hfs/slot-path.mjs",
+    "scripts/hfs/slot-required.mjs",
+    "scripts/hfs/slot-semantic-problems.mjs",
+    "scripts/hfs/slot-side-problems.mjs",
+    "scripts/hfs/slots.mjs",
+    "scripts/hfs/typescript-programs.mjs",
+    "scripts/hfs/view.mjs",
+    "scripts/lib/glob.mjs",
+    "scripts/lib/grammar-lint.mjs",
+    "scripts/lib/i18n.mjs",
+    "scripts/lib/json-clone.mjs",
+    "scripts/lib/json.mjs",
+    "scripts/lib/list.mjs",
+    "scripts/lib/path-key.mjs",
+    "scripts/lib/read-text.mjs",
+    "scripts/lib/regex.mjs",
+    "scripts/lib/source-phrases.mjs",
+    "scripts/lib/ts-analysis.mjs",
+    "scripts/lib/ts-ast.mjs",
+    "scripts/lib/walk.mjs",
+    "scripts/lib/yaml-cached.mjs"
+  ],
+  "own": [
+    "engine/config.mjs",
+    "engine/invalid-config.mjs",
+    "knowledge/hfs/rules.yaml",
+    "knowledge/hfs/slots.yaml",
+    "knowledge/patterns/fe/index.yaml",
+    "knowledge/patterns/fe/ui.yaml",
+    "knowledge/ui/composition/app-shell.yaml",
+    "knowledge/ui/proof/anatomy-source.yaml",
+    "modules/goal/source-phrases.yaml",
+    "scripts/hfs/manifest-shape.mjs"
+  ]
+}

package/runtime/engine/by-code-unit.mjs

@@ -1,12 +1,12 @@
-// by-code-unit.mjs - the comparator of a bare `Array.prototype.sort()`, owned beside the engine files that digest and canonicalize (scripts/lib/list.mjs re-exports it).
-
+// by-code-unit.mjs -the comparator of a bare `Array.prototype.sort()`, owned beside the engine files that digest and canonicalize (scripts/lib/list.mjs re-exports it).
 /**
  * The comparator of a bare `Array.prototype.sort()`: values compared as strings by UTF-16 code unit. Pass it to `sort` and
  * `toSorted` so the order is stated, and stays byte-identical to the default order that digests and canonical output depend on.
  */
 export const byCodeUnit = (a, b) => {
-  const left = String(a);
-  const right = String(b);
-  if (left < right) return -1;
-  return left > right ? 1 : 0;
+    const left = String(a);
+    const right = String(b);
+    if (left < right)
+        return -1;
+    return left > right ? 1 : 0;
 };

package/runtime/engine/model-config.mjs

@@ -1,90 +1,112 @@
 import fs from 'node:fs';
-import {fileURLToPath} from 'node:url';
-import {parseYaml} from './yaml.mjs';
-import {isPlainObject as plain} from './plain-object.mjs';
-import {invalid} from './invalid-config.mjs';
-import {byCodeUnit} from './by-code-unit.mjs';
-import {removedOfKind} from './removed-vocabulary.mjs';
-
+import { fileURLToPath } from 'node:url';
+import { parseYaml } from './yaml.mjs';
+import { isPlainObject as plain } from './plain-object.mjs';
+import { invalid } from './invalid-config.mjs';
+import { byCodeUnit } from './by-code-unit.mjs';
+import { removedOfKind } from './removed-vocabulary.mjs';
 /** The effort vocabulary, ordered weakest to strongest — the only list of it. */
-export const EFFORT_LEVELS=new Set(['none','minimal','low','medium','high','xhigh','max','ultra']);
-const DIFFICULTIES=['easy','medium','hard','insane'];
-export const MODELS_KEYS=['tiers','seats','balance','usage'];
-const known=names=>[...names].sort(byCodeUnit).join(', ');
-
-const hasPath=(root,dotted)=>dotted.split('.').reduce((node,key)=>(plain(node)&&Object.hasOwn(node,key)?node[key]:undefined),root)!==undefined;
-
+export const EFFORT_LEVELS = new Set(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra']);
+const DIFFICULTIES = ['easy', 'medium', 'hard', 'insane'];
+export const MODELS_KEYS = ['tiers', 'seats', 'balance', 'usage'];
+const known = (names) => [...names].sort(byCodeUnit).join(', ');
+const hasPath = (root, dotted) => dotted.split('.').reduce((node, key) => (plain(node) && Object.hasOwn(node, key) ? node[key] : undefined), root) !== undefined;
 /** Refuse an old-shape config (the removed keys of modules/kernel/removed-vocabulary.yaml), naming every removed key and where its meaning lives now. */
-export function refuseRemovedKeys(config){
-  const found=removedOfKind('config-key').filter(({name})=>hasPath(config,name));
-  if(!found.length)return;
-  const removed=found.map(({name,use})=>`${name} is removed (${use})`).join('; ');
-  throw new Error(`Invalid config.yaml: ${removed}.`);
+export function refuseRemovedKeys(config) {
+    const found = removedOfKind('config-key').filter(({ name }) => hasPath(config, name));
+    if (!found.length)
+        return;
+    const removed = found.map(({ name, use }) => `${name} is removed (${use})`).join('; ');
+    throw new Error(`Invalid config.yaml: ${removed}.`);
 }
-
-let shippedCache=null;
+let shippedCache = null;
 /** modules/models/tiers.yaml as shipped, parsed once per file version. */
-export function shippedTiers(){
-  const file=fileURLToPath(new URL('../modules/models/tiers.yaml',import.meta.url));
-  let stat;try{stat=fs.statSync(file);}catch{throw new Error('Missing modules/models/tiers.yaml');}
-  const version=`${stat.mtimeMs}:${stat.size}`;
-  if(shippedCache?.version!==version)shippedCache={version,doc:parseYaml(fs.readFileSync(file,'utf8'))};
-  return structuredClone(shippedCache.doc);
+export function shippedTiers() {
+    const file = fileURLToPath(new URL('../modules/models/tiers.yaml', import.meta.url));
+    let stat;
+    try {
+        stat = fs.statSync(file);
+    }
+    catch {
+        throw new Error('Missing modules/models/tiers.yaml');
+    }
+    const version = `${stat.mtimeMs}:${stat.size}`;
+    if (shippedCache?.version !== version)
+        shippedCache = { version, doc: parseYaml(fs.readFileSync(file, 'utf8')) };
+    return structuredClone(shippedCache.doc);
 }
-
-function validateMember(bad,where,member,profile){
-  if(!plain(member)||Object.keys(member).some(key=>!['agent','model','effort'].includes(key))||typeof member.agent!=='string'||typeof member.model!=='string')
-    bad(`${where} must be {agent, model, effort?}.`);
-  if(profile.models?.[member.model]?.provider!==member.agent)bad(`${where}: model ${member.model} is not declared by agent ${member.agent} in modules/models/registry.yaml models.`);
-  if(member.effort!==undefined&&!EFFORT_LEVELS.has(member.effort))bad(`${where}.effort must use the effort vocabulary.`);
+function validateMember(bad, where, member, profile) {
+    if (!plain(member) || Object.keys(member).some(key => !['agent', 'model', 'effort'].includes(key)) || typeof member.agent !== 'string' || typeof member.model !== 'string')
+        return bad(`${where} must be {agent, model, effort?}.`);
+    if (profile.models?.[member.model]?.provider !== member.agent)
+        bad(`${where}: model ${member.model} is not declared by agent ${member.agent} in modules/models/registry.yaml models.`);
+    if (member.effort !== undefined && !(typeof member.effort === 'string' && EFFORT_LEVELS.has(member.effort)))
+        bad(`${where}.effort must use the effort vocabulary.`);
 }
-
-function validateChains(bad,tiers,profile){
-  for(const [name,chain] of Object.entries(tiers)){
-    if(!Array.isArray(chain)||!chain.length)bad(`.${name} must be a non-empty ordered list of {agent, model, effort?}.`);
-    chain.forEach((member,index)=>validateMember(bad,`.${name}[${index}]`,member,profile));
-    if(new Set(chain.map(member=>`${member.agent}/${member.model}`)).size!==chain.length)bad(`.${name} names each member once.`);
-  }
+function validateChains(bad, tiers, profile) {
+    for (const [name, chain] of Object.entries(tiers)) {
+        if (!Array.isArray(chain) || !chain.length)
+            return bad(`.${name} must be a non-empty ordered list of {agent, model, effort?}.`);
+        chain.forEach((member, index) => validateMember(bad, `.${name}[${index}]`, member, profile));
+        // validateMember refused every member that is not a {agent, model, effort?} record above.
+        const members = chain;
+        if (new Set(members.map(member => `${member.agent}/${member.model}`)).size !== chain.length)
+            bad(`.${name} names each member once.`);
+    }
 }
-
 /** A call tier is taken by a headless call only: no seat, difficulty, kind, order or caller reference may name it, and every call names one. */
-function validateUse(bad,{doc,names,refs}){
-  const callTiers=new Set(Object.entries(doc.tierUse).filter(([,use])=>use==='call').map(([tier])=>tier));
-  for(const tier of Object.keys(doc.tierUse))if(!names.has(tier))bad(`: tierUse names tier ${tier} (known: ${known(names)}).`);
-  for(const [where,tier] of refs)if(callTiers.has(tier))bad(`: ${where} names tier ${tier}, a call tier (tierUse): a headless call is made on it, no seat or op is seated on it.`);
-  for(const [call,spec] of Object.entries(doc.calls))if(!callTiers.has(spec.tier))bad(`: calls.${call}.tier ${spec.tier} must be a tier whose tierUse is call.`);
+function validateUse(bad, { doc, names, refs }) {
+    const callTiers = new Set(Object.entries(doc.tierUse).filter(([, use]) => use === 'call').map(([tier]) => tier));
+    for (const tier of Object.keys(doc.tierUse))
+        if (!names.has(tier))
+            bad(`: tierUse names tier ${tier} (known: ${known(names)}).`);
+    for (const [where, tier] of refs)
+        if (callTiers.has(tier))
+            bad(`: ${where} names tier ${tier}, a call tier (tierUse): a headless call is made on it, no seat or op is seated on it.`);
+    for (const [call, spec] of Object.entries(doc.calls))
+        if (!callTiers.has(spec.tier))
+            bad(`: calls.${call}.tier ${spec.tier} must be a tier whose tierUse is call.`);
 }
-
 /** The tier document the picker reads: the shipped tiers.yaml with config.yaml `models` laid over it. Validated. */
-export function effectiveTiers(config,profile){
-  const doc=shippedTiers(),models=plain(config?.models)?config.models:{};
-  const bad=invalid('models');
-  const tiers={...doc.tiers,...models.tiers};
-  validateChains(bad,tiers,profile);
-  const seats={...doc.seats,...models.seats};
-  const balance={...doc.balance,...models.balance};
-  const usage={...doc.usage,...models.usage};
-  const names=new Set(Object.keys(tiers));
-  const refs=[...Object.entries(seats).map(([seat,tier])=>[`.seats.${seat}`,tier]),...DIFFICULTIES.map(level=>[`difficulty.${level}`,doc.difficulty[level]]),
-    ...Object.entries(doc.kindTiers).map(([kind,tier])=>[`kindTiers.${kind}`,tier]),...doc.tierOrder.map(tier=>['tierOrder',tier])];
-  for(const [where,tier] of refs)if(!names.has(tier))bad(`: ${where} names tier ${tier} (known: ${known(names)}).`);
-  validateUse(bad,{doc,names,refs});
-  if(!(Number.isInteger(balance.maxStreak)&&balance.maxStreak>=1))bad('.balance.maxStreak must be an integer >= 1.');
-  if(!(typeof balance.maxSharePercent==='number'&&balance.maxSharePercent>0&&balance.maxSharePercent<=100))bad('.balance.maxSharePercent must be a number in (0, 100].');
-  const {reservePercent,biasPercent,exhaustedPercent}=usage;
-  if(![reservePercent,biasPercent,exhaustedPercent].every(value=>typeof value==='number'&&value>=0&&value<=100)||!(reservePercent<=biasPercent&&biasPercent<exhaustedPercent))
-    bad('.usage must hold numbers with reservePercent <= biasPercent < exhaustedPercent, each within 0..100.');
-  return {...doc,tiers,seats,balance,usage};
+export function effectiveTiers(config, profile) {
+    const doc = shippedTiers(), models = plain(config?.models) ? config.models : {};
+    const bad = invalid('models');
+    const merged = { ...doc.tiers, ...models.tiers };
+    validateChains(bad, merged, profile);
+    // validateChains refused every chain that is not a non-empty list of {agent, model, effort?} members.
+    const tiers = merged;
+    const seats = { ...doc.seats, ...models.seats };
+    const balance = { ...doc.balance, ...models.balance };
+    const usage = { ...doc.usage, ...models.usage };
+    const names = new Set(Object.keys(tiers));
+    const refs = [...Object.entries(seats).map(([seat, tier]) => [`.seats.${seat}`, tier]), ...DIFFICULTIES.map(level => [`difficulty.${level}`, doc.difficulty[level]]),
+        ...Object.entries(doc.kindTiers).map(([kind, tier]) => [`kindTiers.${kind}`, tier]), ...doc.tierOrder.map(tier => ['tierOrder', tier])];
+    for (const [where, tier] of refs)
+        if (!names.has(tier))
+            bad(`: ${where} names tier ${tier} (known: ${known(names)}).`);
+    validateUse(bad, { doc, names, refs });
+    if (!(Number.isInteger(balance.maxStreak) && balance.maxStreak >= 1))
+        bad('.balance.maxStreak must be an integer >= 1.');
+    if (!(typeof balance.maxSharePercent === 'number' && balance.maxSharePercent > 0 && balance.maxSharePercent <= 100))
+        bad('.balance.maxSharePercent must be a number in (0, 100].');
+    const { reservePercent, biasPercent, exhaustedPercent } = usage;
+    if (![reservePercent, biasPercent, exhaustedPercent].every(value => typeof value === 'number' && value >= 0 && value <= 100) || !(reservePercent <= biasPercent && biasPercent < exhaustedPercent))
+        bad('.usage must hold numbers with reservePercent <= biasPercent < exhaustedPercent, each within 0..100.');
+    return { ...doc, tiers, seats, balance, usage };
 }
-
 /** config.yaml `models` — {tiers?, seats?, balance?, usage?}; the shipped defaults make every key optional. */
-export function validateModelsBlock(config,profile){
-  refuseRemovedKeys(config);
-  const models=config?.models;
-  if(models===undefined||models===null)return;
-  const bad=invalid('models');
-  if(!plain(models)||Object.keys(models).some(key=>!MODELS_KEYS.includes(key)))bad(` must be {${MODELS_KEYS.map(key=>key+'?').join(', ')}} or null (unknown keys are refused).`);
-  if(models.tiers!==undefined&&!plain(models.tiers))bad('.tiers must map tier names to ordered member lists.');
-  for(const key of ['seats','balance','usage'])if(models[key]!==undefined&&!plain(models[key]))bad(`.${key} must be a mapping.`);
-  effectiveTiers(config,profile);
+export function validateModelsBlock(config, profile) {
+    refuseRemovedKeys(config);
+    const models = config?.models;
+    if (models === undefined || models === null)
+        return;
+    const bad = invalid('models');
+    if (!plain(models) || Object.keys(models).some(key => !MODELS_KEYS.includes(key)))
+        return bad(` must be {${MODELS_KEYS.map(key => key + '?').join(', ')}} or null (unknown keys are refused).`);
+    if (models.tiers !== undefined && !plain(models.tiers))
+        bad('.tiers must map tier names to ordered member lists.');
+    for (const key of ['seats', 'balance', 'usage'])
+        if (models[key] !== undefined && !plain(models[key]))
+            bad(`.${key} must be a mapping.`);
+    effectiveTiers(config, profile);
 }