@unoverse-platform/studio 0.1.90 → 0.1.92

package/vendor/base/src/lint/design/file.mjs

@@ -0,0 +1,737 @@
+/**
+ * The per-FILE rules: what a definition must declare about itself.
+ *
+ * Manifests (discovery meta, whenToUse shape), faces (a Switch on defaultState reaching
+ * layouts/<state>), state ordering, microapp discipline (props are inputs, state is scalar
+ * view-state). Everything that is about the file as a whole rather than a node within it.
+ *
+
+ * These rules close over the run: the design-system location, the token scale, which refs
+ * resolve, which app sizes exist. Rather than thread ten parameters through a recursive
+ * walk, each module exports a MAKER that takes the context once and returns the function.
+ *
+ * The context is created per run by index.mjs, so nothing survives between runs.
+ */
+import { existsSync, statSync, readdirSync, readFileSync } from "node:fs";
+import { join, dirname, basename, relative, sep } from "node:path";
+import { RAW_VALUE, PARTIAL_DIRS, PROP_KEYS, INTERFACE_FIELDS, AUTHORED_CONTROLS } from "./vocabulary.mjs";
+import { isDefFile, defName, defPath, readDef, parseDef } from "./defs.mjs";
+
+/**
+ * THE PROPS MAP IS THE CONTRACT (UNOVERSE_AUTHORING §3b, ruled 2026-08-30). Every field's
+ * description, limits, mock and hydration live here now, so this is where they are held
+ * to a shape — and where a prop wearing an INTERFACE FIELD's name is told what happens
+ * when a delivery carries that field.
+ */
+function checkProps(props, file, report, path) {
+  if (!props || typeof props !== "object" || Array.isArray(props)) return;
+  for (const [name, spec] of Object.entries(props)) {
+    if (name.startsWith("_comment")) continue; // a JSON comment, not a prop
+    if (!spec || typeof spec !== "object" || Array.isArray(spec)) continue;
+    const where = path ? `${path}${name}` : name;
+    for (const k of Object.keys(spec))
+      if (!PROP_KEYS.includes(k))
+        report("error", file, `prop "${where}" has no "${k}". A prop reads ${PROP_KEYS.map((x) => `"${x}"`).join(", ")} — everything it needs to be understood and written (UNOVERSE_AUTHORING §3b)`);
+    // THE DELIVERY WINS. A row fills a component by name with no mapping layer
+    // (docs.unoverse.ai/design/interface-data), so `title` on a content-attached card is
+    // the row's title. Using the name is right and expected; writing a brief for a field
+    // the delivery supplies is the part that quietly never applies.
+    if (!path && INTERFACE_FIELDS.has(name)) {
+      const controls = AUTHORED_CONTROLS.filter((k) => spec[k] !== undefined);
+      if (controls.length)
+        report("warn", file, `prop "${name}" is an INTERFACE FIELD, so a delivery fills it by name — and a row's value is not measured against the ${controls.map((c) => `"${c}"`).join(", ")} written here. Keep the name (binding is by name, never mapped); the limit applies only to a value an Agent writes (docs.unoverse.ai/design/interface-data)`);
+    }
+    if (spec.items && typeof spec.items === "object") checkProps(spec.items, file, report, `${where}.items.`);
+  }
+}
+
+/**
+ * THE DISCOVERY META CONTRACT (docs.unoverse.ai/nodes/node-discoverability).
+ * Four fields, one job each, and the SAME rules for a component, a template and an app:
+ * all three are ranked against what a PERSON said, so an app gets these errors rather
+ * than the warnings it used to get.
+ *
+ * The embedded text is "<title>. <whenToUse> <description>" (runtime/bootstrap.ts), so a
+ * missing title means the def name, or the folder slug, is the first token the ranker
+ * sees. That is a warning rather than an error: the fallback is fine when the name
+ * already reads as the thing.
+ */
+const SELECTOR_SHAPED = /\b(pick when|pick whenever|pick for|use (this|when)|when the (user|customer|learner|caller) (asks|wants|says|needs|expresses)|select (this|when))\b/i;
+const MECHANISM_WORDS = /(two-column|\blayout\b|componentslot|\bstreamed\b|\bskeleton\b|\bfull-height\b|\bshell\b)/i;
+
+function checkDiscoveryMeta(report, file, json, kind, docs) {
+  const desc = typeof json.description === "string" ? json.description.trim() : "";
+  if (desc.length < 20)
+    report("error", file, `discovery manifest.description missing/too short. One line (\u226520 chars) saying what the ${kind} IS (${docs})`);
+  else if (desc.length > 120)
+    report("error", file, `discovery manifest.description is ${desc.length} chars: it's the listing subtitle (\u2264120); move detail into whenToUse (${docs})`);
+  if (/\buse when\b/i.test(desc))
+    report("error", file, `discovery manifest.description smuggles "use when\u2026". Description says what it IS; routing text belongs in whenToUse (${docs})`);
+
+  const wtu = typeof json.whenToUse === "string" ? json.whenToUse.trim() : "";
+  if (wtu.length < 20)
+    report("error", file, `discovery manifest.whenToUse missing/too short. The utterance-shaped selection text findIntent ranks on (${docs})`);
+  else {
+    if (SELECTOR_SHAPED.test(wtu))
+      report("error", file, `discovery manifest.whenToUse is selector-shaped. Write the words the USER would say, not instructions about the user (${docs})`);
+    const mech = wtu.match(MECHANISM_WORDS);
+    if (mech)
+      report("error", file, `discovery manifest.whenToUse leads with mechanism ("${mech[0]}"), so it ranks near layout vocabulary instead of the job. Outcome first (${docs})`);
+  }
+
+  if (!(typeof json.title === "string" && json.title.trim()))
+    report("warn", file, `discovery manifest has no "title". The embedding is "<title>. <whenToUse> <description>", so the name or the folder slug leads it instead (${docs})`);
+  if (!(typeof json.category === "string" && json.category.trim()))
+    report("warn", file, `discovery manifest has no "category". Name the domain of the job, never the implementation (${docs})`);
+}
+
+export function makeLintFile(ctx) {
+  const { report, walkNode, isFixture, isHook, isPropsExtract, isManifest, isAppPath, isTemplatePart, defRoot, componentNamesForFile, DS, orgDirs, RX, readText } = ctx;
+
+function checkStateOrder(order, rootFolder, file, includeLayouts = false) {
+  if (!Array.isArray(order)) return;
+  const dirNames = (sub) => {
+    const d = join(rootFolder, sub);
+    return existsSync(d)
+      ? readdirSync(d).filter(isDefFile).map(defName)
+      : [];
+  };
+  // TEMPLATES: stateOrder lists LOCAL states + LAYOUTS in picker order (docs.unoverse.ai/design/apps) —
+  // a layout name (the view a component enters) is a valid entry. COMPONENTS: states only.
+  const stateNames = dirNames("states");
+  const onDisk = new Set([...stateNames, ...(includeLayouts ? dirNames("layouts") : [])]);
+  for (const name of order)
+    if (typeof name === "string" && !onDisk.has(name))
+      report("error", file, `stateOrder lists "${name}" but no states/${name}${includeLayouts ? ` or layouts/${name}` : ""} definition exists (docs.unoverse.ai/design/${includeLayouts ? "apps" : "components"})`);
+  // Only STATES must appear in stateOrder to lock the picker order; the default layout is
+  // legitimately omitted, so never warn on layouts.
+  for (const name of stateNames)
+    if (!order.includes(name))
+      report("warn", file, `states/${name}.json is not in stateOrder. It falls to the end of the picker; add it to lock the order (docs.unoverse.ai/design/studio)`);
+}
+
+
+// THE APP TREE CHECK (extracted 2026-08-29: the tree's home is the ENVELOPE —
+// one folder grammar — while a manifest-held tree remains the legacy read, so
+// both call sites validate identically).
+function checkAppTree(json, root, file) {
+      if (json.states !== undefined) {
+        if (!json.states || typeof json.states !== "object" || Array.isArray(json.states)) {
+          report("error", file, `manifest "states" must be an object — the template tree: { <base>: { states: {…} }, <reaction>: {}, … } (STATE_MODEL §5)`);
+        } else {
+          const names = Object.keys(json.states);
+          const base = json.layout ?? Object.keys(json.states)[0] ?? "main";
+          if (!names.includes(base))
+            report("error", file, `the template tree must include the BASE state "${base}" (named for the default layout) — the ladder derives as the top level minus it (STATE_MODEL §5)`);
+          const subs = [];
+          for (const [n, s] of Object.entries(json.states)) {
+            if (s !== null && (typeof s !== "object" || Array.isArray(s)))
+              report("error", file, `tree state "${n}" must be an object declaring its layout path (STATE_MODEL §5)`);
+            // EXPLICIT PATHS (owner ruling 2026-08-29): every state DECLARES the
+            // layout it draws as a root-relative path (layout: layouts/<file>);
+            // nothing is assumed from the state's name and no folder is magic.
+            const declared = s && typeof s === "object" && typeof s.layout === "string" ? s.layout : undefined;
+            if (!declared)
+              report("error", file, `tree state "${n}" declares no layout. Every state names its drawing as a path — layout: layouts/${n} (2026-08-29 ruling; the same-name default is retired) (STATE_MODEL §5)`);
+            else if (!defPath(root, declared))
+              report("error", file, `tree state "${n}" declares layout "${declared}" but no such file exists (STATE_MODEL §5)`);
+            const nested = s && typeof s === "object" ? s.states : undefined;
+            if (nested && typeof nested === "object" && !Array.isArray(nested))
+              for (const [sub, sv] of Object.entries(nested)) {
+                subs.push(sub);
+                const subDeclared = sv && typeof sv === "object" && typeof sv.layout === "string" ? sv.layout : undefined;
+                if (!subDeclared)
+                  report("error", file, `substate "${sub}" (under "${n}") declares no layout. Every state names its drawing as a path — layout: layouts/${n}-${sub} (the owner-prefix naming convention survives as readability) (2026-08-29 ruling) (LAYERS §3)`);
+                else if (!defPath(root, subDeclared))
+                  report("error", file, `substate "${sub}" (under "${n}") declares layout "${subDeclared}" but no such file exists (LAYERS §3)`);
+              }
+          }
+          for (const sub of subs)
+            if (names.includes(sub))
+              report("error", file, `"${sub}" is declared both as a top-level state and a substate — nesting IS containment; a name lives at exactly one level (STATE_MODEL §5)`);
+          // THE FOLDER CANNOT LIE (owner ruling 2026-08-22): every layouts/ file is
+          // either a SCREEN (a bare name declaring a top-level state) or a substate
+          // drawing (<owner>-<sub>, both declared). Anything else is an error — a
+          // shared part belongs in components/.
+          {
+            const ldir = join(root, "layouts");
+            if (existsSync(ldir)) {
+              const declaredSubs = new Map();
+              for (const [n2, s2] of Object.entries(json.states)) {
+                const nested2 = s2 && typeof s2 === "object" ? s2.states : undefined;
+                if (nested2 && typeof nested2 === "object" && !Array.isArray(nested2))
+                  for (const sub2 of Object.keys(nested2)) declaredSubs.set(`${n2}-${sub2}`, n2);
+              }
+              // A file NAMED by any state's/substate's declared path is accounted
+              // for wherever it sits (2026-08-29: declarations, not names, link).
+              const declaredPaths = new Set();
+              for (const s3 of Object.values(json.states)) {
+                if (s3 && typeof s3 === "object" && typeof s3.layout === "string") declaredPaths.add(s3.layout);
+                const nested3 = s3 && typeof s3 === "object" ? s3.states : undefined;
+                if (nested3 && typeof nested3 === "object" && !Array.isArray(nested3))
+                  for (const sv3 of Object.values(nested3))
+                    if (sv3 && typeof sv3 === "object" && typeof sv3.layout === "string") declaredPaths.add(sv3.layout);
+              }
+              for (const f of readdirSync(ldir).filter(isDefFile)) {
+                const nm = defName(f);
+                if (declaredPaths.has(`layouts/${nm}`)) continue;
+                if (names.includes(nm) || declaredSubs.has(nm)) continue;
+                const owner = names.find((n2) => nm.startsWith(`${n2}-`));
+                if (owner)
+                  report("error", file, `layouts/${nm} is prefixed for state "${owner}" but "${nm.slice(owner.length + 1)}" is not declared as its substate — declare it in the tree, or move the file to components/ if it is a shared part (LAYERS §3)`);
+                else
+                  report("error", file, `layouts/${nm} is neither a declared state nor an <owner>-<sub> substate drawing — bare names are the app's screens; declare it, prefix it with its owner, or move it to components/ (LAYERS §3)`);
+              }
+            }
+          }
+          if (json.stateOrder !== undefined)
+            report("warn", file, `"stateOrder" is superseded by the "states" tree (the ladder derives from the top level minus the base) — delete it (STATE_MODEL §5)`);
+        }
+      } else checkStateOrder(json.stateOrder, root, file, /* includeLayouts */ true);
+}
+
+// ── lint one file ──
+function lintFile(file) {
+  // `readText` is disk unless the caller supplied an overlay for this path (index.mjs).
+  // Studio's editor lints unsaved text through exactly these rules that way.
+  const src = readText(file);
+
+  // LAW 1 — tokens only (skip manifest + fixture; styles/ is never in a def home).
+  // Exempt: `appWidth` — the HOST-facing outer width (state-owned sizing, docs.unoverse.ai/design/apps).
+  // It is raw CSS the embed host applies to the app panel ("min(50vw, 760px)", "360px"),
+  // never a style the SDK resolves — token law governs the inside, not the envelope.
+  if (!isFixture(file) && !isHook(file) && !isManifest(file))
+    src.split("\n").forEach((line, i) => {
+      /**
+       * THE RULE JUDGES CODE, NEVER COMMENTARY. A comment explaining a contrast
+       * decision legitimately names the hex it rejected ("#E9F1FF dropped it to
+       * 1.14:1"), and scanning the raw line flagged exactly the best-documented
+       * files (observed live 2026-08-21: two comment hexes blocked a deploy).
+       * YAML comments start at an unquoted #, at line start or after whitespace;
+       * everything from there is prose. A quoted "#fff" VALUE stays visible to the
+       * rule, which is the whole point of the law.
+       */
+      let code = line, inS = false, inD = false;
+      for (let j = 0; j < line.length; j++) {
+        const ch = line[j];
+        if (ch === "'" && !inD) inS = !inS;
+        else if (ch === '"' && !inS) inD = !inD;
+        else if (ch === "#" && !inS && !inD && (j === 0 || /\s/.test(line[j - 1]))) {
+          code = line.slice(0, j);
+          break;
+        }
+      }
+      if (RAW_VALUE.test(code) && !/^\s*"?appWidth"?\s*:/.test(code))
+        report("error", file, `raw value. Token names only; add/scale a token in the org styles instead (LAW 1, docs.unoverse.ai/design/styles-and-tokens): ${code.trim()}`, i + 1);
+    });
+
+  let json;
+  try {
+    json = parseDef(src, file);
+  } catch (e) {
+    report("error", file, `invalid ${file.endsWith(".yaml") ? "YAML" : "JSON"}: ${e.message}`);
+    return;
+  }
+
+  if (isFixture(file)) return; // legacy fixture, unused: don't choke
+  if (isHook(file)) return;    // a lifecycle hook: calls + a projection, not a UI tree
+  if (isPropsExtract(file)) return; // the envelope's props map, composed there — not a UI tree
+
+  if (isManifest(file)) {
+    const root = dirname(file);
+    if (isAppPath(file)) {
+      // TEMPLATE manifest = the envelope. Requires binding + a resolvable root.
+      if (!json.name) report("warn", file, `app manifest missing "name": the display name (docs.unoverse.ai/design/apps)`);
+      checkDiscoveryMeta(report, file, json, "app", "docs.unoverse.ai/design/apps");
+      if (!(json.binding && json.binding.workflow))
+        report("warn", file, `template manifest has no binding.workflow. The app owns its workflow binding (docs.unoverse.ai/design/apps)`);
+      // Two valid roots (definitions.ts:229): the STANDARD manifest-only form (root =
+      // layouts/<layout>), OR a `<name>` envelope OVERRIDE (its own root). Only the
+      // manifest-only form must resolve a layout; an envelope-form template supplies its own.
+      const hasEnvelope = !!defPath(root, basename(root));
+      if (!hasEnvelope) {
+        // The base defaults to the FIRST DECLARED STATE (states own layouts and
+        // declaration order ranks them); "main" only when no states block exists.
+        const firstState = json.states && typeof json.states === "object" && !Array.isArray(json.states)
+          ? Object.keys(json.states)[0]
+          : undefined;
+        // The base state's DECLARED path wins (2026-08-29 ruling: layout is a
+        // root-relative path, nothing assumed); the name fallback survives only
+        // for the unswept installed tier.
+        const firstEntry = firstState ? json.states[firstState] : undefined;
+        const declaredBase = firstEntry && typeof firstEntry === "object" && typeof firstEntry.layout === "string" ? firstEntry.layout : undefined;
+        if (declaredBase) {
+          if (!defPath(root, declaredBase))
+            report("error", file, `base state "${firstState}" declares layout "${declaredBase}" but no such file exists (docs.unoverse.ai/design/apps)`);
+        } else {
+          const layoutName = json.layout ?? firstState ?? "main";
+          if (!defPath(join(root, "layouts"), layoutName))
+            report("error", file, `manifest.layout "${layoutName}" → layouts/${layoutName} does not exist (and no <name> envelope) (docs.unoverse.ai/design/apps)`);
+        }
+      }
+      // THE TEMPLATE TREE (STATE_MODEL v2, checkpoint 2026-08-08): a manifest
+      // `states:` block declares the whole machine — validate the DECLARATION:
+      //   top-level order is the ladder (base first by convention, named for the
+      //   default layout); every non-base top-level state needs its arrangement
+      //   (layouts/<name>); every base substate needs its state file
+      //   (states/<name>); a name cannot be both; an authored stateOrder is
+      //   superseded and should be deleted.
+      // ONE DRAWINGS FOLDER (owner ruling 2026-08-22): templates work like
+      // components — every drawing lives in layouts/, the tree decides which state
+      // owns which. A states/ folder is the pre-unification anatomy: move its files
+      // into layouts/ and update $include paths.
+      if (existsSync(join(root, "states")))
+        report("error", file, `template carries a states/ folder — templates have ONE drawings folder. Move states/* into layouts/ and update every "$include: states/<name>" to "layouts/<name>" (anatomy unified with components, LAYERS §3)`);
+      checkAppTree(json, root, file);
+      // ONE STATE AT A TIME (docs.unoverse.ai/design/state): the active state is derived from the
+      // latest surfaced VIEW, so no two surfaces in one template may claim the same
+      // view — the active surface would be ambiguous.
+      {
+        const claims = new Map(); // view -> first file
+        const collectClaims = (n, from) => {
+          if (Array.isArray(n)) return n.forEach((c) => collectClaims(c, from));
+          if (!n || typeof n !== "object") return;
+          const w = n.type === "ComponentSlot" ? n.select?.where : null;
+          if ((w?.field === "state" || w?.field === "view" || w?.field === "defaultState") && typeof w.eq === "string") {
+            if (claims.has(w.eq))
+              report("error", file, `two reaction surfaces claim the view "${w.eq}" (${claims.get(w.eq)} and ${from}). A template is in ONE state at a time; each view has exactly one surface (docs.unoverse.ai/design/state)`);
+            else claims.set(w.eq, from);
+          }
+          for (const v of Object.values(n)) if (v && typeof v === "object") collectClaims(v, from);
+        };
+        for (const sub of ["layouts", "states", "components"]) {
+          const d = join(root, sub);
+          if (!existsSync(d)) continue;
+          for (const f of readdirSync(d).filter(isDefFile)) {
+            try {
+              collectClaims(readDef(join(d, f)), `${sub}/${f}`);
+            } catch {
+              /* that file lints separately */
+            }
+          }
+        }
+      }
+      if (json.mode !== undefined && json.defaultState === undefined)
+        report("warn", file, `"mode" was renamed to "defaultState". Still read as a fallback, but rename it (docs.unoverse.ai/design/state)`);
+      // `preview` — the per-state MOCK map ({ "<state>": ["course-card", …] }): each key
+      // must be a states/ file, each name a real component. A repeated name seeds
+      // several instances (a card rail).
+      if (json.preview !== undefined) {
+        if (!json.preview || typeof json.preview !== "object" || Array.isArray(json.preview))
+          report("error", file, `"preview" must be an object mapping state names to component-name arrays (docs.unoverse.ai/design/studio)`);
+        else {
+          // preview keys are per-LAYOUT (the component view Studio mocks) or a local state
+          // (docs.unoverse.ai/design/apps) — resolve against states/ ∪ layouts/, same as stateOrder.
+          const viewsIn = (sub) => {
+            const d = join(root, sub);
+            return existsSync(d)
+              ? readdirSync(d).filter(isDefFile).map(defName)
+              : [];
+          };
+          const states = new Set([...viewsIn("states"), ...viewsIn("layouts")]);
+          // ANATOMY UNIFIED (2026-08-22): a substate's drawing lives in layouts/ under
+          // `<arrangement>-<substate>`, so the STATE's own name is no longer a filename.
+          // The resolver already looks both ways (definitions.ts, template tree); without
+          // the same lookup here a correctly-migrated template lints as though every one
+          // of its substates had vanished.
+          // The tree's home is the ENVELOPE (one folder grammar, 2026-08-29); a
+          // manifest-held tree is the legacy read.
+          const envPath = defPath(root, basename(root));
+          const envStates = envPath ? readDef(envPath)?.states : undefined;
+          const treeStates = (json.states && typeof json.states === "object" && !Array.isArray(json.states) ? json.states : undefined)
+            ?? (envStates && typeof envStates === "object" && !Array.isArray(envStates) ? envStates : {});
+          for (const [parent, node] of Object.entries(treeStates)) {
+            states.add(parent);
+            for (const sub of Object.keys(node?.states ?? {})) if (states.has(`${parent}-${sub}`)) states.add(sub);
+          }
+          const comps = componentNamesForFile(file);
+          for (const [state, list] of Object.entries(json.preview)) {
+            if (!states.has(state))
+              report("error", file, `preview."${state}". No states/${state}.json or layouts/${state}.json in this template (docs.unoverse.ai/design/studio)`);
+            // An OBJECT entry is authored TEMPLATE-STATE mock data (what the workflow
+            // would have echoed — comments, a discriminant, an anchor), merged verbatim
+            // when the state's pill is picked. Only the two shapes; anything else errors.
+            if (list && typeof list === "object" && !Array.isArray(list)) continue;
+            if (!Array.isArray(list) || list.some((c) => typeof c !== "string")) {
+              report("error", file, `preview."${state}" must be an array of component names, or an object of template-state mock data`);
+              continue;
+            }
+            for (const c of list)
+              if (comps && !comps.has(String(c).toLowerCase()))
+                report("error", file, `preview."${state}" names unknown component "${c}". No match in design/marketplace/components/ or this org's components/ (org-privacy: another org's components are out of reach; lookup is case-insensitive)`);
+          }
+        }
+      }
+      // Sizing is STATE-OWNED (docs.unoverse.ai/design/apps): the layout root's `appWidth` is the core
+      // surface's constant width; a panel slot's `appWidth` slides out on top. Manifest
+      // width/focusWidth are DEAD — nothing reads them; there is no fallback.
+      for (const dep of ["width", "focusWidth"])
+        if (json[dep] !== undefined)
+          report("error", file, `manifest "${dep}" is dead. Nothing reads it. Sizing is state-owned: \`appWidth\` on the layout root (constant core width) or on a panel (slide-out width) (docs.unoverse.ai/design/apps)`);
+    } else {
+      // COMPONENT manifest = OPTIONAL spatial discovery. No binding. Mirrors the
+      // discovery-meta assertions in server/src/runtime/microapp-structure.test.ts.
+      const isTpl = /[\\/]templates[\\/]/.test(file);
+      checkDiscoveryMeta(report, file, json, isTpl ? "template" : "component",
+        isTpl ? "docs.unoverse.ai/design/templates" : "docs.unoverse.ai/design/components");
+      if (json.binding)
+        report("warn", file, `a component discovery manifest has no workflow. Drop "binding" (a component is streamed or node-hydrated) (docs.unoverse.ai/design/components)`);
+      // `lifetime` — OPTIONAL render lifetime (docs.unoverse.ai/design/state §Two lifetimes). Closed set:
+      // "turn" (default — the universal new-turn reset) | "conversation" (durable
+      // conversation-scoped surface: conversation-keyed instance, exempt from the
+      // new-turn reset, retired only by replacement, self-close, or a template swap).
+      if (json.lifetime !== undefined && json.lifetime !== "turn" && json.lifetime !== "conversation")
+        report("error", file, `manifest "lifetime" must be "turn" (default) or "conversation". Got ${JSON.stringify(json.lifetime)} (docs.unoverse.ai/design/state §Two lifetimes)`);
+    }
+    return;
+  }
+
+  const isEnvelope = typeof json.unoverse === "string";
+  const root = defRoot(file);
+
+  if (isEnvelope) {
+    // The declaration word is `type:`; `kind:` is the legacy spelling, still read.
+    // ONE FOLDER GRAMMAR (owner ruling 2026-08-29): every kind has an envelope
+    // saying what it IS. component/atom = root; template = parts+shapes; app =
+    // the states tree (its manifest stays the MCP face).
+    const declared = json.type ?? json.kind;
+    // Template grammar §9b (2026-08-29): states like every kind; parts/shapes = legacy.
+    // ONE REQUIREMENT SHAPE (2026-08-29): a kind declares its tree (`states:`) OR
+    // its drawing (`root` — flat components/atoms). A tree component's root is
+    // SYNTHESIZED by the compiler, never required.
+    // A BLOCK is a template that declares a DRAWING instead of a tree (2026-08-31): a flat
+    // file, no manifest, one `root:` — `pair`, `feature`, `single`, `rail`, `stack`. It has
+    // no states because it is not a screen: it is a shape a page imports by `Ref`, inlined
+    // before the page's sections compile. Requiring `states:` of it would be demanding a
+    // state machine from a fragment, which is the same mistake as demanding a manifest:
+    // both are what a PAGE has, and a block is not a page.
+    const isBlock = declared === "template" && json.states === undefined && json.root !== undefined;
+    const envelopeRequired =
+      isBlock ? ["name", "root"]
+      : declared === "app" || declared === "template" ? ["name", "states"]
+      : declared === "component" ? ["name", ...(json.states !== undefined || json.state?.view !== undefined ? [] : ["root"])]
+      : ["name", "root"];
+    if (declared === "template" && json.states === undefined && (json.parts !== undefined || json.shapes !== undefined)) envelopeRequired.pop();
+    for (const req of envelopeRequired)
+      if (json[req] === undefined) report("error", file, `envelope missing "${req}" (docs.unoverse.ai/design/sdui-and-mcp-apps)`);
+    if (declared === undefined) report("error", file, `envelope missing "type" (docs.unoverse.ai/design/sdui-and-mcp-apps)`);
+    if (json.kind !== undefined && json.type === undefined)
+      report("warn", file, `"kind" is the legacy spelling of the declaration — write "type: ${json.kind}"`);
+    if (declared && !["component", "template", "atom", "app"].includes(declared))
+      report("error", file, `unknown type "${declared}"`);
+    if (declared === "component" && !json.category)
+      report("warn", file, `component has no "category". Used to group it in the palette (docs.unoverse.ai/design/sdui-and-mcp-apps)`);
+    // APP envelope: the states tree lives HERE (one folder grammar) — validate it
+    // exactly as the legacy manifest-held tree was.
+    if (declared === "app") checkAppTree(json, root, file);
+    if (json.root) walkNode(json.root, file, root);
+
+    // ── the contained-microapp discipline (mirrors microapp-structure.test.ts) ──
+    if (declared === "component") {
+      // A TEMPLATE'S OWN PART IS A FLAT COMPONENT (TEMPLATE_MODEL §9b rule 7): one file,
+      // no manifest, no state tree — the face IS the filename. Its `root` here is the
+      // TEMPLATE's folder, which does carry `layouts/`, so without this the whole faced-
+      // component discipline fires on every part and demands a Switch it must not have.
+      const hasLayouts = !isTemplatePart(file) && existsSync(join(root, "layouts"));
+      const statesDir = join(root, "states");
+      const stateFiles = existsSync(statesDir)
+        ? readdirSync(statesDir).filter(isDefFile).map(defName).sort()
+        : [];
+      const hasStateBlock = json.state && typeof json.state === "object";
+
+      // THE DISCOVERY MANIFEST IS THE SINGLE HOME for the meta — but the envelope's own
+      // `description` is now COMPOSITION CONTEXT (UNOVERSE_AUTHORING §3b, 2026-08-30):
+      // what an Agent filling the WHOLE of this must know, which used to ride an unbound
+      // `brief` on the layout root. Two files, two audiences. Only a COPY of the
+      // manifest's text is the duplication this rule exists to stop.
+      {
+        const mPath = defPath(root, "manifest");
+        let m = null;
+        if (mPath) { try { m = readDef(mPath); } catch { m = null; } }
+        if (m) {
+          if (json.whenToUse !== undefined)
+            report("error", file, `envelope duplicates manifest meta "whenToUse". The discovery manifest is the single home (docs.unoverse.ai/design/components)`);
+          if (typeof json.description === "string" && json.description.trim() === String(m.description ?? "").trim())
+            report("error", file, `the envelope's "description" is a copy of the manifest's. The manifest is the single home for the DISCOVERY line; the envelope's own description is composition context — what an Agent filling the whole of this must know (UNOVERSE_AUTHORING §3b)`);
+        }
+      }
+
+      // deprecated bridge: a top-level `defaultState` triggers the component node APP_DATA emit
+      if (json.defaultState !== undefined)
+        report("warn", file, `top-level "defaultState" is the deprecated bridge (component-node APP_DATA emit). The master state lives in the \`state\` block; templates react via ComponentSlot.select.where (STATE_MODEL §5b)`);
+
+      // THE PROP IS THE BRIEF (UNOVERSE_AUTHORING §3b, 2026-08-30): a prop declares
+      // everything about itself, so the props map is the whole contract and is held to a
+      // closed shape. The props extract composes first (`props: { $include: props }` —
+      // the loader does the same before any reader sees the map).
+      let judgedProps = json.props ?? {};
+      if (typeof judgedProps.$include === "string") {
+        const incPath = defPath(root, judgedProps.$include);
+        if (!incPath) {
+          report("error", file, `props $include "${judgedProps.$include}" resolves to no file in the definition folder (docs.unoverse.ai/design/components)`);
+          judgedProps = {};
+        } else {
+          try { judgedProps = readDef(incPath) ?? {}; } catch { judgedProps = {}; }
+        }
+      }
+      checkProps(judgedProps, file, report, "");
+
+      // EVERY PROP CARRIES A DESCRIPTION (UNOVERSE_AUTHORING §3b, RULED 2026-08-30).
+      //
+      // It reads BOTH ways, which is why it is compulsory rather than encouraged. A
+      // description is not only what a copywriter fills against: it is what lets an agent
+      // UNDERSTAND the screen it is looking at. `read` reports where the person is; the
+      // descriptions say what is actually in front of them. A screen of unnamed fields is
+      // one no agent can reason about, in either direction.
+      //
+      // AND IT SAYS NOTHING ABOUT PERMISSION. That is the layout's word — `static` /
+      // `copywriter` / `director` (TEMPLATE_MODEL §9b) — never a prop's. The rule this
+      // replaces was "a described prop is a writable prop", which made silence the safety
+      // mechanism: a field was protected because nobody had explained it, and explaining it
+      // was what exposed it. Describing a field is now free of consequence, so there is no
+      // longer any reason to leave one blank.
+      const undescribed = Object.entries(judgedProps)
+        .filter(([, v]) => !(v && typeof v === "object" && typeof v.description === "string" && v.description.trim()))
+        .map(([k]) => k);
+      if (undescribed.length)
+        report("error", file, `props [${undescribed.join(", ")}] carry no "description". Every prop says what it IS, so an agent can read the screen as well as fill it. A description grants nothing: permission is the layout's word (static / copywriter / director), never a prop's (UNOVERSE_AUTHORING §3b)`);
+
+      // only components that ADOPTED the structure are held to the full discipline
+      if (hasLayouts || stateFiles.length || hasStateBlock) {
+        // Every prop declares what fills it. Was "must be input:true", from when props
+        // only held workflow data; shared components added props nothing streams in (the
+        // preview axis, literals passed via `Ref with`) — input:true there is false AND
+        // load-bearing, since configSchema derives from it. Silence is the error:
+        // unflagged props default to INPUTS.
+        // The props extract composes first (`props: { $include: props }` — the loader
+        // does the same before any reader sees the map).
+        const undeclared = Object.entries(judgedProps)
+          .filter(([, v]) => !(v && typeof v === "object" && typeof v.input === "boolean"))
+          .map(([k]) => k);
+        if (undeclared.length)
+          report("error", file, `microapp props [${undeclared.join(", ")}] do not declare "input". Every prop says what fills it: input:true = a workflow streams it (it joins the node's configSchema); input:false = nothing does (a preview axis, or a literal the host passes via Ref with). Unflagged props default to INPUTS (docs.unoverse.ai/design/components)`);
+
+
+        // STATE MODEL v2 (UNOVERSE_STATE_MODEL §5): an authored `state.view` TREE is
+        // the component's state machine — the ONE object the scalar rule admits.
+        // Well-formed = { initial?: string, states: { <name>: { layout?/layouts?/on?/
+        // initial?/states? } } }. A malformed tree is still an error.
+        const isViewTree = (v) => {
+          if (!v || typeof v !== "object" || Array.isArray(v)) return false;
+          if (v.initial !== undefined && typeof v.initial !== "string") return false;
+          if (!v.states || typeof v.states !== "object" || Array.isArray(v.states)) return false;
+          return Object.values(v.states).every(
+            (s) => s && typeof s === "object" && !Array.isArray(s) &&
+              (s.on === undefined || typeof s.on === "string") &&
+              (s.initial === undefined || typeof s.initial === "string") &&
+              (s.layout === undefined || typeof s.layout === "string"),
+          );
+        };
+        // THE RULED FORM (2026-08-29): the tree lives at TOP-LEVEL `states:` like
+        // every kind; `state.view` is the legacy wrapper, still read.
+        const topTree = json.states && typeof json.states === "object" && !Array.isArray(json.states) && isViewTree({ states: json.states }) ? { states: json.states } : null;
+        const viewTree = topTree ?? (hasStateBlock && isViewTree(json.state.view) ? json.state.view : null);
+
+        // the state block holds SCALAR internal view-state ONLY — an array/object (a
+        // finder's result rows) or a URL is content/data slop: hardcode it in the layout,
+        // or move workflow-fed data to props (input:true) (AUTHORING §3). The one
+        // exception: a well-formed v2 `state.view` tree (STATE_MODEL §5 rule 1).
+        const scalarHomes = [];
+        if (hasStateBlock) scalarHomes.push(["state", json.state]);
+        if (json.values && typeof json.values === "object" && !Array.isArray(json.values)) scalarHomes.push(["values", json.values]);
+        for (const [home, blk] of scalarHomes)
+          for (const [k, v] of Object.entries(blk)) {
+            if (home === "state" && k === "view" && viewTree && !topTree) continue; // legacy wrapper only
+            if (Array.isArray(v) || (v && typeof v === "object"))
+              report("error", file, `${home}.${k} is an ${Array.isArray(v) ? "array" : "object"}. The values block is SCALAR starting values only (the one object allowed is a well-formed v2 \`state.view\` tree); workflow-fed data → props (input:true), static content → hardcode in the layout (docs.unoverse.ai/design/components)`);
+            else if (typeof v === "string" && /^https?:\/\//.test(v))
+              report("error", file, `${home}.${k} is a URL. Content, not a starting value; hardcode it in the layout (or props input:true if workflow-fed) (docs.unoverse.ai/design/components)`);
+          }
+
+        if (hasLayouts) {
+          const raw = JSON.stringify(json.root ?? {}).replace(/\s/g, "");
+          if (viewTree && json.root == null) {
+            // THE TREE IS THE MACHINE (2026-08-29 late): no authored root — the
+            // compiler synthesizes the Switch from the tree. Nothing to check.
+          } else if (viewTree) {
+            // An AUTHORED root is a real shell (beyond the plain Switch) — it must
+            // still switch the public axis. A root that merely restates the tree is
+            // redundant: delete it and let the compiler synthesize.
+            if ((!raw.includes('"on":"state"') && !raw.includes('"on":"view"')) || !/"\$include":"layouts\//.test(raw))
+              report("error", file, `a tree component's authored root must Switch on "state" (the ruled public-axis word; "view" is the legacy spelling) → $include layouts/<layout> (STATE_MODEL §5)`);
+            const rootObj = json.root ?? {};
+            const kids = Array.isArray(rootObj.children) ? rootObj.children : [];
+            if (rootObj.type === "Box" && kids.length === 1 && kids[0]?.type === "Switch")
+              report("warn", file, `the root is only the tree's Switch restated — delete it; the compiler synthesizes the root from \`states:\` (2026-08-29 ruling)`);
+          } else if (!raw.includes('"on":"defaultState"') || !/"\$include":"layouts\//.test(raw))
+            report("error", file, `a faced component's root must Switch on defaultState → $include layouts/<state> (legacy; or declare a v2 state.view tree and Switch on "view") (docs.unoverse.ai/design/components)`);
+
+          // ── face set ⇄ layouts/ cross-check (OPEN name set — inline/focused/<any>) ──
+          // The FACES are the root Switch's cases; Studio's face toggle and the render
+          // path both derive from them, so cases and layout files must agree exactly.
+          const axes = viewTree ? ["state", "view"] : ["defaultState"];
+          const findFaceSwitch = (n) => {
+            if (!n || typeof n !== "object") return null;
+            if (Array.isArray(n)) { for (const c of n) { const r = findFaceSwitch(c); if (r) return r; } return null; }
+            if (n.type === "Switch" && axes.includes(n.on) && n.cases && typeof n.cases === "object") return n;
+            for (const v of Object.values(n)) { const r = findFaceSwitch(v); if (r) return r; }
+            return null;
+          };
+          const faceSwitch = findFaceSwitch(json.root);
+          if (faceSwitch) {
+            const cases = faceSwitch.cases;
+            const caseNames = Object.keys(cases).filter((k) => k !== "default");
+            // inline is the UNIVERSAL default face: an unknown/absent defaultState must
+            // render SOMETHING — require an `inline` case or an explicit `default`.
+            // EXCEPTION — a SURFACE-ONLY component (docs.unoverse.ai/design/components): its manifest
+            // declares a SURFACED arrival (defaultState naming one of its cases, not
+            // inline), and it deliberately renders NOTHING while unsurfaced (e.g. a
+            // rail card retired by a new turn). Then omitting inline/default is the
+            // point, not a mistake.
+            if (!caseNames.includes("inline") && cases.default === undefined) {
+              // v2: the tree's `initial` IS the declared base — the component always
+              // has somewhere to rest, so no inline/default case is required as long
+              // as the initial names a real case.
+              const treeInitial = viewTree ? (viewTree.initial ?? Object.keys(viewTree.states)[0]) : undefined;
+              let arrival;
+              try {
+                const mp = defPath(root, "manifest");
+                if (mp) arrival = readDef(mp).defaultState;
+              } catch { /* linted separately */ }
+              const surfaceOnly = typeof arrival === "string" && arrival !== "inline" && caseNames.includes(arrival);
+              const v2Based = typeof treeInitial === "string" && caseNames.includes(treeInitial);
+              if (!surfaceOnly && !v2Based)
+                report("error", file, `faced component's Switch has no "inline" case and no "default". Inline is the universal default face; a component with neither disappears for unknown states. (v2: the state.view tree's \`initial\` naming a case also satisfies this; legacy surface-only: manifest.defaultState naming one of its cases.) (STATE_MODEL §5)`);
+            }
+            // Each named case's layout include must MATCH the case name — the layout
+            // filename IS the state name (Studio writes defaultState=<case>).
+            const usedLayouts = new Set();
+            for (const [name, body] of Object.entries(cases)) {
+              const inc = body && typeof body === "object" ? body.$include : undefined;
+              if (typeof inc !== "string" || !inc.startsWith("layouts/")) continue;
+              const layoutName = inc.slice("layouts/".length);
+              usedLayouts.add(layoutName);
+              // v2: the STATE owns its layout — the tree's declaration decides which
+              // file draws it. Declarations are root-relative PATHS (2026-08-29
+              // ruling); a bare name still reads as layouts/<name> for the unswept
+              // installed tier.
+              const declaredLayout = viewTree?.states?.[name]?.layout;
+              const expected = declaredLayout
+                ? (declaredLayout.includes("/") ? declaredLayout : `layouts/${declaredLayout}`).replace(/^layouts\//, "")
+                : name;
+              if (name !== "default" && layoutName !== expected)
+                report("error", file, viewTree
+                  ? `state "${name}" declares layout "${expected}" but its case includes layouts/${layoutName} — the tree's declaration and the case must agree (STATE_MODEL §5 rule 1)`
+                  : `face case "${name}" includes layouts/${layoutName}. The layout FILENAME is the state name; rename one so they match (docs.unoverse.ai/design/components)`);
+            }
+            // v2: tree-declared layouts (including nested substates' and variants') are
+            // reachable by declaration — seed them so the orphan check knows them.
+            if (viewTree) {
+              // Declared values are PATHS (2026-08-29); the orphan set is keyed by
+              // layouts/-relative names, so strip the prefix (bare legacy names
+              // pass through unchanged).
+              const asName = (l) => l.replace(/^layouts\//, "");
+              const seed = (states) => {
+                for (const s of Object.values(states ?? {})) {
+                  if (!s || typeof s !== "object") continue;
+                  if (typeof s.layout === "string") usedLayouts.add(asName(s.layout));
+                  if (s.layouts && typeof s.layouts === "object")
+                    for (const l of Object.values(s.layouts)) if (typeof l === "string") usedLayouts.add(asName(l));
+                  if (s.states) seed(s.states);
+                }
+              };
+              seed(viewTree.states);
+            }
+            // Orphan faces: a layouts/*.json no case references is invisible — Studio's
+            // face toggle and the renderer only know the Switch's cases.
+            //
+            // REACHABILITY IS TRANSITIVE. A face may itself be a Switch on some other key
+            // (a `course` face switching on `step` into `course-detail` and `course-apply`),
+            // and those layouts are reached only from inside it. Counting the outer cases
+            // alone called them orphans and told the developer to delete two live files.
+            //
+            // So follow every include from the faces outward, to a fixed point. Anything
+            // still unreached is genuinely unreachable.
+            const layoutsDir = join(root, "layouts");
+            const includesIn = (node, into) => {
+              if (!node || typeof node !== "object") return into;
+              if (Array.isArray(node)) { for (const v of node) includesIn(v, into); return into; }
+              if (typeof node.$include === "string" && node.$include.startsWith("layouts/"))
+                into.add(node.$include.slice("layouts/".length));
+              for (const v of Object.values(node)) includesIn(v, into);
+              return into;
+            };
+            for (const queue = [...usedLayouts]; queue.length; ) {
+              const lp = defPath(layoutsDir, queue.pop());
+              if (!lp) continue;
+              let body;
+              try { body = readDef(lp); } catch { continue; /* linted as its own file */ }
+              for (const next of includesIn(body, new Set()))
+                if (!usedLayouts.has(next)) { usedLayouts.add(next); queue.push(next); }
+            }
+
+            if (existsSync(layoutsDir))
+              for (const lf of readdirSync(layoutsDir).filter(isDefFile)) {
+                const lname = defName(lf);
+                if (!usedLayouts.has(lname))
+                  report("warn", file, `layouts/${lf} is not referenced by any Switch case. An orphan face is unreachable (add a case "${lname}" or delete the file) (docs.unoverse.ai/design/components)`);
+              }
+          }
+          // v2 STRAGGLER NUDGE: inside a component that declares a tree, every
+          // public-axis write must use `view` — a leftover setValue on
+          // "defaultState" still works through the alias but dies with it.
+          if (viewTree) {
+            for (const sub of ["layouts", "components"]) {
+              const d = join(root, sub);
+              if (!existsSync(d)) continue;
+              for (const lf of readdirSync(d).filter(isDefFile)) {
+                try {
+                  if (/"key":"defaultState"/.test(JSON.stringify(readDef(join(d, lf)))))
+                    report("warn", file, `${sub}/${lf} writes setValue "defaultState" but this component declares a tree — write "state" (the ruled word; "view"/"defaultState" are legacy) (STATE_MODEL §2)`);
+                } catch { /* that file lints separately */ }
+              }
+            }
+          }
+          // arrival state: the manifest is the render-contract home (default "inline"); the
+          // state block is the legacy fallback.
+          let mDefault;
+          try {
+            const mp = defPath(root, "manifest");
+            if (mp) mDefault = readDef(mp).defaultState;
+          } catch { /* linted separately */ }
+          const arrival = viewTree
+            ? (viewTree.initial ?? Object.keys(viewTree.states)[0])
+            : (mDefault ?? (hasStateBlock ? json.state.defaultState : undefined));
+          if (typeof arrival !== "string")
+            report("error", file, `a faced component must declare its base state — a v2 state.view tree \`initial\`, or (legacy) manifest.defaultState / state.defaultState (docs.unoverse.ai/design/components)`);
+        }
+        // A tree DECLARES its order, so an authored stateOrder beside one is a second source
+        // of truth that can silently disagree with it. Five docs call this form legacy and
+        // nothing enforced it, so a component kept running on one and never heard a word.
+        // The old check only fired when a states/ FOLDER existed, which a fragment-based
+        // component does not have (docs/doc-control §Guards: enforce rules as tests).
+        if (viewTree && json.stateOrder !== undefined)
+          report("error", file, `authored "stateOrder" beside a "state.view" tree. The tree declares the order: nest these as substates and delete the list (docs.unoverse.ai/design/state)`);
+
+        if (stateFiles.length) {
+          const order = Array.isArray(json.stateOrder) ? [...json.stateOrder].sort() : null;
+          if (!order || !order.length)
+            report("error", file, `has states/ but no stateOrder in the envelope (docs.unoverse.ai/design/components)`);
+          else if (JSON.stringify(order) !== JSON.stringify(stateFiles))
+            report("error", file, `stateOrder and states/*.json must name the same set (docs.unoverse.ai/design/components)`);
+        }
+      }
+    } else {
+      checkStateOrder(json.stateOrder, root, file); // non-component envelopes (rare)
+    }
+  } else {
+    // bare partial (layouts/ states/ components/ blocks/, or an atom). A template
+    // layout's TOP-LEVEL node is the app's layout root — the one non-slot home for
+    // `appWidth` (state-owned sizing, docs.unoverse.ai/design/apps).
+    walkNode(json, file, root, null, /[\\/]layouts[\\/][^\\/]+\.(json|yaml)$/.test(file) && isAppPath(file));
+  }
+}
+
+
+  return lintFile;
+}