@usefragments/core 1.10.2 → 2.0.0

package/src/compiled-types/index.ts

@@ -5,7 +5,7 @@
  * by AI agents, MCP servers, and context generators.
  */
 
-import type { ComponentGovernanceRecord } from '../governance.js';
+import type { ComponentGovernanceRecord } from "../governance.js";
 
 /**
  * Component metadata
@@ -14,6 +14,7 @@ export interface FragmentMeta {
   name: string;
   description: string;
   category: string;
+  aliases?: string[];
   tags?: string[];
   status?: "stable" | "beta" | "deprecated" | "experimental";
   since?: string;
@@ -28,10 +29,29 @@ export interface FragmentMeta {
 export interface FragmentUsage {
   when: string[];
   whenNot: string[];
+  choose?: Record<string, string>;
+  /** Serialized v3 anti-pattern guidance; `good` is checked JSX source. */
+  dont?: Array<{
+    reason: string;
+    bad: string;
+    good: string;
+  }>;
   guidelines?: string[];
   accessibility?: string[];
 }
 
+/** Static state-space hints carried from a v3 fragment definition. */
+export interface CompiledFragmentMatrix {
+  axes?: Record<string, "auto" | readonly string[]>;
+  forced?: string[];
+  worstCase?: Record<string, unknown>;
+}
+
+/** Optional design-tool reference carried from a v3 fragment definition. */
+export interface CompiledFragmentDesign {
+  figmaNode?: string;
+}
+
 /**
  * Definition for a single prop
  */
@@ -50,6 +70,8 @@ export interface PropDefinition {
     step?: number;
     presetColors?: string[];
   };
+  /** Visibility annotation carried from a v3 fragment definition. */
+  visibility?: "public" | "internal" | "hidden";
 }
 
 /**
@@ -72,20 +94,38 @@ export interface FragmentContract {
   /** Per-component performance budget override in bytes (gzipped) */
   performanceBudget?: number;
   /** Sub-component slot metadata for compound components */
-  compoundChildren?: Record<string, {
-    required?: boolean;
-    accepts?: string[];
-    description?: string;
-  }>;
+  compoundChildren?: Record<
+    string,
+    {
+      required?: boolean;
+      accepts?: string[];
+      description?: string;
+    }
+  >;
   /** Canonical JSX usage examples showing how to assemble the component */
   canonicalUsage?: string[];
 }
 
+/**
+ * Per-component preview configuration carried from either contract input.
+ * JSON contracts use module/css hints; v3 definitions use provider and
+ * visual-diff-region hints. Both are projections of the same compiled object.
+ */
+export interface CompiledFragmentPreview {
+  setupModule?: string;
+  wrapperModule?: string;
+  wrapperExport?: string;
+  css?: string[];
+  theme?: "light" | "dark";
+  providers?: unknown[];
+  dynamicRegions?: string[];
+}
+
 /**
  * Provenance tracking for generated fragments
  */
 export interface FragmentGenerated {
-  source: "storybook" | "manual" | "ai" | "extracted" | "merged" | "migrated";
+  source: "storybook" | "manual" | "ai" | "scan" | "extracted" | "merged" | "migrated";
   sourceFile?: string;
   /** @deprecated Use provenance.verified instead */
   confidence?: number;
@@ -124,7 +164,7 @@ export interface PerformanceData {
   /** Raw (minified, not gzipped) bundle size in bytes */
   rawSize: number;
   /** Complexity classification */
-  complexity: 'lightweight' | 'moderate' | 'heavy';
+  complexity: "lightweight" | "moderate" | "heavy";
   /** Percentage of budget used (0-100+) */
   budgetPercent: number;
   /** Whether the component exceeds its budget */
@@ -137,7 +177,7 @@ export interface PerformanceData {
 
 export interface ObservedUsageProp {
   name: string;
-  kind: 'static' | 'dynamic' | 'spread' | 'jsx' | 'boolean' | 'null';
+  kind: "static" | "dynamic" | "spread" | "jsx" | "boolean" | "null";
   value?: string | number | boolean | null;
 }
 
@@ -171,9 +211,18 @@ export interface CompiledFragment {
     description: string;
     code?: string;
     figma?: string;
+    canonical?: boolean;
     args?: Record<string, unknown>;
   }>;
   contract?: FragmentContract;
+  /** Per-component preview/runtime hints from the authored contract. */
+  preview?: CompiledFragmentPreview;
+  /** Authored state-space hints for the Workshop matrix. */
+  matrix?: CompiledFragmentMatrix;
+  /** Optional design-tool comparison reference. */
+  design?: CompiledFragmentDesign;
+  /** Design-token references used by this component. */
+  tokens?: string[];
   ai?: AIMetadata;
   /** Framework hint from contract, used by preview adapters and Cloud */
   framework?: string;
@@ -260,7 +309,7 @@ export interface CompiledFragmentsFile {
   blocks?: Record<string, CompiledBlock>;
   tokens?: CompiledTokenData;
   /** Component relationship graph for AI structural queries */
-  graph?: import('../graph/types.js').SerializedComponentGraph;
+  graph?: import("../graph/types.js").SerializedComponentGraph;
   /** Performance measurement summary */
   performanceSummary?: PerformanceSummary;
   /** @deprecated Use blocks instead */
@@ -268,12 +317,15 @@ export interface CompiledFragmentsFile {
 }
 
 export class CompiledFragmentsFileValidationError extends Error {
-  constructor(
-    readonly source: string,
-    readonly issues: string[]
-  ) {
-    super(`Invalid compiled Fragments catalog at ${source}: ${issues.join("; ")}`);
+  readonly source: string;
+  readonly issues: string[];
+
+  constructor(source: string, issues: readonly string[]) {
+    const orderedIssues = [...issues].sort(compareStrings);
+    super(`Invalid compiled Fragments catalog at ${source}: ${orderedIssues.join("; ")}`);
     this.name = "CompiledFragmentsFileValidationError";
+    this.source = source;
+    this.issues = orderedIssues;
   }
 }
 
@@ -285,10 +337,10 @@ export function parseCompiledFragmentsFile(
   if (typeof input === "string") {
     try {
       value = JSON.parse(input);
-    } catch (error) {
-      throw new CompiledFragmentsFileValidationError(source, [
-        `invalid JSON (${error instanceof Error ? error.message : String(error)})`,
-      ]);
+    } catch {
+      // Native JSON.parse messages differ across Node and browsers. The public
+      // contract error must not vary with the runtime that validates it.
+      throw new CompiledFragmentsFileValidationError(source, ["invalid JSON"]);
     }
   }
 
@@ -305,20 +357,34 @@ export function parseCompiledFragmentsFile(
   if (!isRecord(value.fragments)) {
     issues.push("fragments must be an object");
   } else {
-    for (const [key, fragment] of Object.entries(value.fragments)) {
+    const names = new Map<string, string>();
+    for (const [key, fragment] of sortedEntries(value.fragments)) {
       validateCompiledFragment(key, fragment, issues);
+      if (
+        !isRecord(fragment) ||
+        !isRecord(fragment.meta) ||
+        typeof fragment.meta.name !== "string"
+      ) {
+        continue;
+      }
+      const previousKey = names.get(fragment.meta.name);
+      if (previousKey !== undefined) {
+        issues.push(
+          `fragments.${key}.meta.name duplicates fragments.${previousKey}.meta.name (${JSON.stringify(fragment.meta.name)})`
+        );
+      } else {
+        names.set(fragment.meta.name, key);
+      }
     }
   }
-  if (value.graph !== undefined) {
-    if (
-      !isRecord(value.graph) ||
-      !Array.isArray(value.graph.nodes) ||
-      !Array.isArray(value.graph.edges) ||
-      !isRecord(value.graph.health)
-    ) {
-      issues.push("graph must contain nodes[], edges[], and health");
-    }
-  }
+  validateOptionalString(value.generatorVersion, "generatorVersion", issues);
+  validateOptionalString(value.packageName, "packageName", issues);
+  validateOptionalStringArray(value.buildInputs, "buildInputs", issues);
+  validateCompiledBlockMap(value.blocks, "blocks", issues);
+  validateCompiledBlockMap(value.recipes, "recipes", issues);
+  validateCompiledTokens(value.tokens, issues);
+  validateSerializedGraph(value.graph, issues);
+  validatePerformanceSummary(value.performanceSummary, issues);
   if (issues.length > 0) throw new CompiledFragmentsFileValidationError(source, issues);
   return value as unknown as CompiledFragmentsFile;
 }
@@ -329,19 +395,554 @@ function validateCompiledFragment(key: string, value: unknown, issues: string[])
     issues.push(`${path} must be an object`);
     return;
   }
-  if (typeof value.filePath !== "string") issues.push(`${path}.filePath must be a string`);
-  if (!isRecord(value.meta) || typeof value.meta.name !== "string") {
-    issues.push(`${path}.meta.name must be a string`);
+  validateString(value.filePath, `${path}.filePath`, issues);
+  validateFragmentMeta(value.meta, `${path}.meta`, issues);
+  validateFragmentUsage(value.usage, `${path}.usage`, issues);
+  if (value.guidance !== undefined) {
+    validateFragmentUsage(value.guidance, `${path}.guidance`, issues);
+  }
+  validateFragmentProps(value.props, `${path}.props`, issues);
+  validateFragmentVariants(value.variants, `${path}.variants`, issues);
+  validateOptionalRecordArray(value.governance, `${path}.governance`, issues);
+  validateRelations(value.relations, `${path}.relations`, issues);
+  validateFragmentPreview(value.preview, `${path}.preview`, issues);
+  validateFragmentMatrix(value.matrix, `${path}.matrix`, issues);
+  validateFragmentDesign(value.design, `${path}.design`, issues);
+  validateOptionalStringArray(value.tokens, `${path}.tokens`, issues);
+  validateOptionalRecord(value.ai, `${path}.ai`, issues);
+  validateOptionalString(value.framework, `${path}.framework`, issues);
+  validateOptionalStringArray(value.propsSummary, `${path}.propsSummary`, issues);
+  validateOptionalString(value.sourcePath, `${path}.sourcePath`, issues);
+  validateOptionalString(value.exportName, `${path}.exportName`, issues);
+  validateFragmentProvenance(value.provenance, `${path}.provenance`, issues);
+  validateFragmentGenerated(value._generated, `${path}._generated`, issues);
+  validateObservedUsages(value.usages, `${path}.usages`, issues);
+  validatePerformanceData(value.performance, `${path}.performance`, issues);
+}
+
+function validateFragmentMeta(value: unknown, path: string, issues: string[]): void {
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
   }
-  if (!isRecord(value.props)) issues.push(`${path}.props must be an object`);
-  if (!Array.isArray(value.variants)) issues.push(`${path}.variants must be an array`);
+  validateString(value.name, `${path}.name`, issues);
+  validateString(value.description, `${path}.description`, issues);
+  validateString(value.category, `${path}.category`, issues);
+  validateOptionalStringArray(value.aliases, `${path}.aliases`, issues);
+  validateOptionalStringArray(value.tags, `${path}.tags`, issues);
   if (
-    !isRecord(value.usage) ||
-    !Array.isArray(value.usage.when) ||
-    !Array.isArray(value.usage.whenNot)
+    value.status !== undefined &&
+    !["stable", "beta", "deprecated", "experimental"].includes(String(value.status))
   ) {
-    issues.push(`${path}.usage must contain when[] and whenNot[]`);
+    issues.push(`${path}.status must be stable, beta, deprecated, or experimental`);
+  }
+  validateOptionalString(value.since, `${path}.since`, issues);
+  validateOptionalString(value.figma, `${path}.figma`, issues);
+  validateOptionalRecord(value.figmaProps, `${path}.figmaProps`, issues);
+  if (value.dependencies !== undefined) {
+    if (!Array.isArray(value.dependencies)) {
+      issues.push(`${path}.dependencies must be an array`);
+    } else {
+      value.dependencies.forEach((dependency, index) => {
+        const dependencyPath = `${path}.dependencies.${index}`;
+        if (!isRecord(dependency)) {
+          issues.push(`${dependencyPath} must be an object`);
+          return;
+        }
+        validateString(dependency.name, `${dependencyPath}.name`, issues);
+        validateString(dependency.version, `${dependencyPath}.version`, issues);
+        validateOptionalString(dependency.reason, `${dependencyPath}.reason`, issues);
+      });
+    }
+  }
+}
+
+function validateFragmentUsage(value: unknown, path: string, issues: string[]): void {
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validateStringArray(value.when, `${path}.when`, issues);
+  validateStringArray(value.whenNot, `${path}.whenNot`, issues);
+  validateOptionalStringArray(value.guidelines, `${path}.guidelines`, issues);
+  validateOptionalStringArray(value.accessibility, `${path}.accessibility`, issues);
+  if (value.choose !== undefined) {
+    validateStringRecord(value.choose, `${path}.choose`, issues);
+  }
+  if (value.dont !== undefined) {
+    if (!Array.isArray(value.dont)) {
+      issues.push(`${path}.dont must be an array`);
+    } else {
+      value.dont.forEach((entry, index) => {
+        const entryPath = `${path}.dont.${index}`;
+        if (!isRecord(entry)) {
+          issues.push(`${entryPath} must be an object`);
+          return;
+        }
+        validateString(entry.reason, `${entryPath}.reason`, issues);
+        validateString(entry.bad, `${entryPath}.bad`, issues);
+        validateString(entry.good, `${entryPath}.good`, issues);
+      });
+    }
+  }
+}
+
+function validateFragmentProps(value: unknown, path: string, issues: string[]): void {
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  for (const [name, prop] of sortedEntries(value)) {
+    const propPath = `${path}.${name}`;
+    if (!isRecord(prop)) {
+      issues.push(`${propPath} must be an object`);
+      continue;
+    }
+    validateString(prop.type, `${propPath}.type`, issues);
+    validateString(prop.description, `${propPath}.description`, issues);
+    validateOptionalStringArray(prop.values, `${propPath}.values`, issues);
+    validateOptionalBoolean(prop.required, `${propPath}.required`, issues);
+    validateOptionalStringArray(prop.constraints, `${propPath}.constraints`, issues);
+    validateOptionalRecord(prop.typeDetails, `${propPath}.typeDetails`, issues);
+    validateOptionalString(prop.controlType, `${propPath}.controlType`, issues);
+    validateOptionalRecord(prop.controlOptions, `${propPath}.controlOptions`, issues);
+    if (
+      prop.visibility !== undefined &&
+      prop.visibility !== "public" &&
+      prop.visibility !== "internal" &&
+      prop.visibility !== "hidden"
+    ) {
+      issues.push(`${propPath}.visibility must be public, internal, or hidden`);
+    }
+  }
+}
+
+function validateFragmentVariants(value: unknown, path: string, issues: string[]): void {
+  if (!Array.isArray(value)) {
+    issues.push(`${path} must be an array`);
+    return;
+  }
+  const names = new Set<string>();
+  value.forEach((variant, index) => {
+    const variantPath = `${path}.${index}`;
+    if (!isRecord(variant)) {
+      issues.push(`${variantPath} must be an object`);
+      return;
+    }
+    validateString(variant.name, `${variantPath}.name`, issues);
+    validateString(variant.description, `${variantPath}.description`, issues);
+    validateOptionalString(variant.code, `${variantPath}.code`, issues);
+    validateOptionalString(variant.figma, `${variantPath}.figma`, issues);
+    validateOptionalBoolean(variant.canonical, `${variantPath}.canonical`, issues);
+    validateOptionalRecord(variant.args, `${variantPath}.args`, issues);
+    if (typeof variant.name === "string") {
+      if (names.has(variant.name)) {
+        issues.push(
+          `${variantPath}.name duplicates an earlier variant (${JSON.stringify(variant.name)})`
+        );
+      }
+      names.add(variant.name);
+    }
+  });
+}
+
+function validateRelations(value: unknown, path: string, issues: string[]): void {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    issues.push(`${path} must be an array`);
+    return;
+  }
+  value.forEach((relation, index) => {
+    const relationPath = `${path}.${index}`;
+    if (!isRecord(relation)) {
+      issues.push(`${relationPath} must be an object`);
+      return;
+    }
+    validateString(relation.component, `${relationPath}.component`, issues);
+    validateString(relation.relationship, `${relationPath}.relationship`, issues);
+    validateString(relation.note, `${relationPath}.note`, issues);
+  });
+}
+
+function validateFragmentPreview(value: unknown, path: string, issues: string[]): void {
+  if (value === undefined) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validateOptionalString(value.setupModule, `${path}.setupModule`, issues);
+  validateOptionalString(value.wrapperModule, `${path}.wrapperModule`, issues);
+  validateOptionalString(value.wrapperExport, `${path}.wrapperExport`, issues);
+  validateOptionalStringArray(value.css, `${path}.css`, issues);
+  validateOptionalStringArray(value.dynamicRegions, `${path}.dynamicRegions`, issues);
+  if (value.providers !== undefined && !Array.isArray(value.providers)) {
+    issues.push(`${path}.providers must be an array`);
+  }
+  if (value.theme !== undefined && value.theme !== "light" && value.theme !== "dark") {
+    issues.push(`${path}.theme must be light or dark`);
+  }
+}
+
+function validateFragmentMatrix(value: unknown, path: string, issues: string[]): void {
+  if (value === undefined) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  if (value.axes !== undefined) {
+    if (!isRecord(value.axes)) {
+      issues.push(`${path}.axes must be an object`);
+    } else {
+      for (const [axis, values] of sortedEntries(value.axes)) {
+        if (values !== "auto" && !isStringArray(values)) {
+          issues.push(`${path}.axes.${axis} must be auto or an array of strings`);
+        }
+      }
+    }
+  }
+  validateOptionalStringArray(value.forced, `${path}.forced`, issues);
+  validateOptionalRecord(value.worstCase, `${path}.worstCase`, issues);
+}
+
+function validateFragmentDesign(value: unknown, path: string, issues: string[]): void {
+  if (value === undefined) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validateOptionalString(value.figmaNode, `${path}.figmaNode`, issues);
+}
+
+function validateFragmentProvenance(value: unknown, path: string, issues: string[]): void {
+  if (value === undefined) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validateString(value.source, `${path}.source`, issues);
+  validateBoolean(value.verified, `${path}.verified`, issues);
+  validateOptionalString(value.frameworkSupport, `${path}.frameworkSupport`, issues);
+  validateOptionalString(value.sourceHash, `${path}.sourceHash`, issues);
+  validateOptionalString(value.extractedAt, `${path}.extractedAt`, issues);
+}
+
+function validateFragmentGenerated(value: unknown, path: string, issues: string[]): void {
+  if (value === undefined) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
   }
+  const sources = ["storybook", "manual", "ai", "scan", "extracted", "merged", "migrated"];
+  if (typeof value.source !== "string" || !sources.includes(value.source)) {
+    issues.push(`${path}.source must be a supported provenance source`);
+  }
+  validateOptionalString(value.sourceFile, `${path}.sourceFile`, issues);
+  validateOptionalNumber(value.confidence, `${path}.confidence`, issues);
+  validateOptionalBoolean(value.verified, `${path}.verified`, issues);
+  validateOptionalString(value.timestamp, `${path}.timestamp`, issues);
+}
+
+function validateObservedUsages(value: unknown, path: string, issues: string[]): void {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    issues.push(`${path} must be an array`);
+    return;
+  }
+  value.forEach((usage, index) => {
+    const usagePath = `${path}.${index}`;
+    if (!isRecord(usage)) {
+      issues.push(`${usagePath} must be an object`);
+      return;
+    }
+    validateString(usage.file, `${usagePath}.file`, issues);
+    validateNumber(usage.line, `${usagePath}.line`, issues);
+    validateNumber(usage.column, `${usagePath}.column`, issues);
+    validateOptionalString(usage.parentElement, `${usagePath}.parentElement`, issues);
+    validateOptionalBoolean(usage.conditional, `${usagePath}.conditional`, issues);
+    if (!Array.isArray(usage.props)) {
+      issues.push(`${usagePath}.props must be an array`);
+      return;
+    }
+    usage.props.forEach((prop, propIndex) => {
+      const propPath = `${usagePath}.props.${propIndex}`;
+      if (!isRecord(prop)) {
+        issues.push(`${propPath} must be an object`);
+        return;
+      }
+      validateString(prop.name, `${propPath}.name`, issues);
+      if (
+        typeof prop.kind !== "string" ||
+        !["static", "dynamic", "spread", "jsx", "boolean", "null"].includes(prop.kind)
+      ) {
+        issues.push(`${propPath}.kind must be a supported observation kind`);
+      }
+      if (
+        prop.value !== undefined &&
+        prop.value !== null &&
+        typeof prop.value !== "string" &&
+        typeof prop.value !== "number" &&
+        typeof prop.value !== "boolean"
+      ) {
+        issues.push(`${propPath}.value must be a JSON scalar`);
+      }
+    });
+  });
+}
+
+function validatePerformanceData(value: unknown, path: string, issues: string[]): void {
+  if (value === undefined) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  validateNumber(value.bundleSize, `${path}.bundleSize`, issues);
+  validateNumber(value.rawSize, `${path}.rawSize`, issues);
+  validateString(value.complexity, `${path}.complexity`, issues);
+  validateNumber(value.budgetPercent, `${path}.budgetPercent`, issues);
+  validateBoolean(value.overBudget, `${path}.overBudget`, issues);
+  validateString(value.measuredAt, `${path}.measuredAt`, issues);
+  if (value.imports !== undefined) {
+    if (!Array.isArray(value.imports)) {
+      issues.push(`${path}.imports must be an array`);
+    } else {
+      value.imports.forEach((entry, index) => {
+        const entryPath = `${path}.imports.${index}`;
+        if (!isRecord(entry)) {
+          issues.push(`${entryPath} must be an object`);
+          return;
+        }
+        validateString(entry.path, `${entryPath}.path`, issues);
+        validateNumber(entry.bytes, `${entryPath}.bytes`, issues);
+        validateNumber(entry.percent, `${entryPath}.percent`, issues);
+      });
+    }
+  }
+}
+
+function validateCompiledBlockMap(value: unknown, path: string, issues: string[]): void {
+  if (value === undefined) return;
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`);
+    return;
+  }
+  const names = new Set<string>();
+  for (const [key, block] of sortedEntries(value)) {
+    const blockPath = `${path}.${key}`;
+    if (!isRecord(block)) {
+      issues.push(`${blockPath} must be an object`);
+      continue;
+    }
+    validateString(block.filePath, `${blockPath}.filePath`, issues);
+    validateString(block.name, `${blockPath}.name`, issues);
+    validateString(block.description, `${blockPath}.description`, issues);
+    validateString(block.category, `${blockPath}.category`, issues);
+    validateStringArray(block.components, `${blockPath}.components`, issues);
+    validateString(block.code, `${blockPath}.code`, issues);
+    validateOptionalStringArray(block.tags, `${blockPath}.tags`, issues);
+    if (typeof block.name === "string") {
+      if (names.has(block.name)) {
+        issues.push(
+          `${blockPath}.name duplicates an earlier block (${JSON.stringify(block.name)})`
+        );
+      }
+      names.add(block.name);
+    }
+  }
+}
+
+function validateCompiledTokens(value: unknown, issues: string[]): void {
+  if (value === undefined) return;
+  if (!isRecord(value)) {
+    issues.push("tokens must be an object");
+    return;
+  }
+  validateString(value.prefix, "tokens.prefix", issues);
+  validateNumber(value.total, "tokens.total", issues);
+  if (!isRecord(value.categories)) {
+    issues.push("tokens.categories must be an object");
+    return;
+  }
+  for (const [category, entries] of sortedEntries(value.categories)) {
+    const categoryPath = `tokens.categories.${category}`;
+    if (!Array.isArray(entries)) {
+      issues.push(`${categoryPath} must be an array`);
+      continue;
+    }
+    entries.forEach((entry, index) => {
+      const entryPath = `${categoryPath}.${index}`;
+      if (!isRecord(entry)) {
+        issues.push(`${entryPath} must be an object`);
+        return;
+      }
+      validateString(entry.name, `${entryPath}.name`, issues);
+      validateOptionalString(entry.value, `${entryPath}.value`, issues);
+      validateOptionalString(entry.description, `${entryPath}.description`, issues);
+    });
+  }
+}
+
+function validateSerializedGraph(value: unknown, issues: string[]): void {
+  if (value === undefined) return;
+  if (!isRecord(value)) {
+    issues.push("graph must be an object");
+    return;
+  }
+  if (!Array.isArray(value.nodes)) {
+    issues.push("graph.nodes must be an array");
+  } else {
+    const nodeNames = new Set<string>();
+    value.nodes.forEach((node, index) => {
+      const nodePath = `graph.nodes.${index}`;
+      if (!isRecord(node)) {
+        issues.push(`${nodePath} must be an object`);
+        return;
+      }
+      validateString(node.name, `${nodePath}.name`, issues);
+      validateString(node.category, `${nodePath}.category`, issues);
+      validateString(node.status, `${nodePath}.status`, issues);
+      validateOptionalStringArray(node.subComponents, `${nodePath}.subComponents`, issues);
+      if (typeof node.name === "string") {
+        if (nodeNames.has(node.name)) {
+          issues.push(
+            `${nodePath}.name duplicates an earlier graph node (${JSON.stringify(node.name)})`
+          );
+        }
+        nodeNames.add(node.name);
+      }
+    });
+  }
+  if (!Array.isArray(value.edges)) {
+    issues.push("graph.edges must be an array");
+  } else {
+    value.edges.forEach((edge, index) => {
+      const edgePath = `graph.edges.${index}`;
+      if (!isRecord(edge)) {
+        issues.push(`${edgePath} must be an object`);
+        return;
+      }
+      validateString(edge.s, `${edgePath}.s`, issues);
+      validateString(edge.t, `${edgePath}.t`, issues);
+      validateString(edge.ty, `${edgePath}.ty`, issues);
+      validateNumber(edge.w, `${edgePath}.w`, issues);
+      validateOptionalString(edge.no, `${edgePath}.no`, issues);
+      validateString(edge.p, `${edgePath}.p`, issues);
+    });
+  }
+  if (!isRecord(value.health)) {
+    issues.push("graph.health must be an object");
+    return;
+  }
+  validateStringArray(value.health.orphans, "graph.health.orphans", issues);
+  validateNumber(value.health.compositionCoverage, "graph.health.compositionCoverage", issues);
+  validateNumber(value.health.averageDegree, "graph.health.averageDegree", issues);
+  validateNumber(value.health.nodeCount, "graph.health.nodeCount", issues);
+  validateNumber(value.health.edgeCount, "graph.health.edgeCount", issues);
+  if (!Array.isArray(value.health.connectedComponents)) {
+    issues.push("graph.health.connectedComponents must be an array");
+  } else {
+    value.health.connectedComponents.forEach((component, index) =>
+      validateStringArray(component, `graph.health.connectedComponents.${index}`, issues)
+    );
+  }
+  if (!Array.isArray(value.health.hubs)) {
+    issues.push("graph.health.hubs must be an array");
+  } else {
+    value.health.hubs.forEach((hub, index) => {
+      const hubPath = `graph.health.hubs.${index}`;
+      if (!isRecord(hub)) {
+        issues.push(`${hubPath} must be an object`);
+        return;
+      }
+      validateString(hub.name, `${hubPath}.name`, issues);
+      validateNumber(hub.degree, `${hubPath}.degree`, issues);
+    });
+  }
+}
+
+function validatePerformanceSummary(value: unknown, issues: string[]): void {
+  if (value === undefined) return;
+  if (!isRecord(value)) {
+    issues.push("performanceSummary must be an object");
+    return;
+  }
+  validateString(value.preset, "performanceSummary.preset", issues);
+  validateNumber(value.budget, "performanceSummary.budget", issues);
+  validateNumber(value.total, "performanceSummary.total", issues);
+  validateNumber(value.overBudget, "performanceSummary.overBudget", issues);
+  if (!isRecord(value.tiers)) {
+    issues.push("performanceSummary.tiers must be an object");
+  } else {
+    for (const [tier, count] of sortedEntries(value.tiers)) {
+      validateNumber(count, `performanceSummary.tiers.${tier}`, issues);
+    }
+  }
+}
+
+function validateString(value: unknown, path: string, issues: string[]): void {
+  if (typeof value !== "string") issues.push(`${path} must be a string`);
+}
+
+function validateOptionalString(value: unknown, path: string, issues: string[]): void {
+  if (value !== undefined) validateString(value, path, issues);
+}
+
+function validateNumber(value: unknown, path: string, issues: string[]): void {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    issues.push(`${path} must be a finite number`);
+  }
+}
+
+function validateOptionalNumber(value: unknown, path: string, issues: string[]): void {
+  if (value !== undefined) validateNumber(value, path, issues);
+}
+
+function validateBoolean(value: unknown, path: string, issues: string[]): void {
+  if (typeof value !== "boolean") issues.push(`${path} must be a boolean`);
+}
+
+function validateOptionalBoolean(value: unknown, path: string, issues: string[]): void {
+  if (value !== undefined) validateBoolean(value, path, issues);
+}
+
+function validateStringArray(value: unknown, path: string, issues: string[]): void {
+  if (!isStringArray(value)) issues.push(`${path} must be an array of strings`);
+}
+
+function validateOptionalStringArray(value: unknown, path: string, issues: string[]): void {
+  if (value !== undefined) validateStringArray(value, path, issues);
+}
+
+function validateStringRecord(value: unknown, path: string, issues: string[]): void {
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object of strings`);
+    return;
+  }
+  for (const [key, entry] of sortedEntries(value)) {
+    validateString(entry, `${path}.${key}`, issues);
+  }
+}
+
+function validateOptionalRecord(value: unknown, path: string, issues: string[]): void {
+  if (value !== undefined && !isRecord(value)) issues.push(`${path} must be an object`);
+}
+
+function validateOptionalRecordArray(value: unknown, path: string, issues: string[]): void {
+  if (value === undefined) return;
+  if (!Array.isArray(value) || value.some((entry) => !isRecord(entry))) {
+    issues.push(`${path} must be an array of objects`);
+  }
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+function sortedEntries(value: Record<string, unknown>): Array<[string, unknown]> {
+  return Object.entries(value).sort(([left], [right]) => compareStrings(left, right));
+}
+
+function compareStrings(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {