Refactor to align on benchmark hierarchy

app/evals/page.tsx

@@ -1,9 +1,10 @@
 "use client"
 
 import { useCallback, useDeferredValue, useEffect, useMemo, useState } from "react"
+import { useRouter, useSearchParams } from "next/navigation"
 import { ChevronDown, ChevronUp, Search, Tag } from "lucide-react"
 
-import { FamilyTable } from "@/components/family-table"
+import { FamilyTable, getFamilyNavId } from "@/components/family-table"
 import { InfiniteScrollSentinel } from "@/components/infinite-scroll"
 import { Navigation } from "@/components/navigation"
 import type { EvalHierarchy, HierarchyFamily } from "@/lib/backend-artifacts"
@@ -18,42 +19,35 @@ type FamilySort = "results" | "benchmarks" | "name" | "category"
 function familyEvalsCount(fam: HierarchyFamily): number {
   if (fam.evals_count != null) return fam.evals_count
 
-  const composites = fam.composites ?? []
-  const standalone = fam.standalone_benchmarks ?? []
-  const benchmarks = fam.benchmarks ?? []
-  const leaves = fam.leaves ?? []
-
+  // v3 fallback: sum metric counts across the family's benchmarks (one
+  // of the three layout fields is present per family per spec §5.1).
   const allBenchmarks = [
-    ...standalone,
-    ...benchmarks,
-    ...composites.flatMap((c) => c.benchmarks ?? []),
+    ...(fam.standalone_benchmarks ?? []),
+    ...(fam.benchmarks ?? []),
+    ...((fam.composites ?? []).flatMap((c) => c.benchmarks ?? [])),
   ]
-
-  return (
-    (fam.metrics?.length ?? 0) +
-    allBenchmarks.reduce(
-      (sum, b) => sum + ((b as { metrics?: unknown[] }).metrics?.length ?? 0),
-      0,
-    ) +
-    leaves.reduce((sum, l) => sum + (l.evals_count ?? 0), 0)
+  return allBenchmarks.reduce(
+    (sum, b) => sum + (b.metrics?.length ?? 0),
+    0,
   )
 }
 
 function familyBenchmarkCount(fam: HierarchyFamily): number {
-  const composites = fam.composites ?? []
-  const standalone = fam.standalone_benchmarks ?? []
-  const benchmarks = fam.benchmarks ?? []
-  const leaves = fam.leaves ?? []
-
-  const all = [
-    ...standalone,
-    ...benchmarks,
-    ...composites.flatMap((c) => c.benchmarks ?? []),
-  ]
-  return all.length > 0 ? all.length : leaves.length
+  return (
+    (fam.standalone_benchmarks?.length ?? 0) +
+    (fam.benchmarks?.length ?? 0) +
+    ((fam.composites ?? []).reduce(
+      (sum, c) => sum + (c.benchmarks?.length ?? 0),
+      0,
+    ))
+  )
 }
 
 export default function EvalsPage() {
+  const router = useRouter()
+  const searchParams = useSearchParams()
+  const familyParam = searchParams.get("family")
+
   const [hierarchy, setHierarchy] = useState<EvalHierarchy | null>(null)
   const [totalModels, setTotalModels] = useState<number>(0)
   const [evalItems, setEvalItems] = useState<Map<string, BenchmarkEvalListItem>>(new Map())
@@ -81,6 +75,23 @@ export default function EvalsPage() {
       .finally(() => setLoading(false))
   }, [])
 
+  // Resolve the `?family=<key>` deep link from the home page family cards.
+  // For families with a clean family-level summary we redirect to the
+  // detail page; for aggregator families (no nav target) we seed the
+  // search box so the listing narrows to that family and the user can
+  // expand it. Runs once per `family` param value, after data loads.
+  useEffect(() => {
+    if (!familyParam || !hierarchy) return
+    const fam = hierarchy.families.find((f) => f.key === familyParam)
+    if (!fam) return
+    const navId = getFamilyNavId(fam, benchmarkCards)
+    if (navId) {
+      router.replace(`/evals/${encodeURIComponent(navId)}`)
+      return
+    }
+    setSearchQuery(fam.display_name || fam.key)
+  }, [familyParam, hierarchy, benchmarkCards, router])
+
   const families = hierarchy?.families ?? []
 
   // Build a domain → family-count map. The lite eval list doesn't carry
@@ -116,13 +127,7 @@ export default function EvalsPage() {
         }
       }
 
-      // Legacy fallback: per-leaf tags + cards keyed by leaf slug.
-      for (const leaf of fam.leaves ?? []) {
-        for (const d of leaf.tags?.domains ?? []) seen.add(d.trim().toLowerCase())
-        for (const d of lookupDomains(leaf.key)) seen.add(d.trim().toLowerCase())
-      }
-
-      // Family-level eval_summary_ids cover both shapes.
+      // Family-level eval_summary_ids cover the v3 shape.
       for (const id of fam.eval_summary_ids ?? []) {
         for (const d of lookupDomains(id)) seen.add(d.trim().toLowerCase())
       }
@@ -154,9 +159,6 @@ export default function EvalsPage() {
       for (const benchmark of nestedBenchmarks) {
         for (const d of benchmark.tags?.domains ?? []) recordLabel(d)
       }
-      for (const leaf of fam.leaves ?? []) {
-        for (const d of leaf.tags?.domains ?? []) recordLabel(d)
-      }
     }
     for (const set of familyDomains.values()) {
       for (const key of set) counts.set(key, (counts.get(key) ?? 0) + 1)
@@ -280,11 +282,7 @@ export default function EvalsPage() {
             <div className="ec-page-meta-item">
               <span className="ec-page-meta-item-l">Single benchmarks</span>
               <span className="ec-page-meta-item-v">
-                {(
-                  stats.benchmark_count ??
-                  (stats.single_benchmark_count ?? 0) +
-                    (stats.standalone_benchmark_count ?? 0)
-                ).toLocaleString()}
+                {(stats.benchmark_count ?? 0).toLocaleString()}
               </span>
             </div>
             <div className="ec-page-meta-item">

app/page.tsx

@@ -53,14 +53,11 @@ export default async function HomePage() {
   const stats = hierarchy.stats
   const familyCount = stats?.family_count ?? hierarchy.families.length
   const compositeCount = stats?.composite_count ?? 0
-  // Single benchmarks: prefer the new `benchmark_count` (total distinct
-  // benchmarks across all composites in the v2 dim), fall back to the
-  // legacy single + standalone split when the adapter synthesised them
-  // from an older snapshot shape.
-  const singleBenchmarkCount = stats?.single_benchmark_count ?? 0
-  const standaloneBenchmarkCount = stats?.standalone_benchmark_count ?? 0
-  const benchmarkLeafCount =
-    stats?.benchmark_count ?? singleBenchmarkCount + standaloneBenchmarkCount
+  // v3 hierarchy ships `benchmark_count` directly. The legacy
+  // `single_benchmark_count` / `standalone_benchmark_count` synthesis
+  // is gone with the adapter (Step 4b); v3's `benchmark_count` is the
+  // distinct (composite, benchmark) row count from the dim.
+  const benchmarkLeafCount = stats?.benchmark_count ?? 0
   const sliceCount = stats?.slice_count ?? 0
   const metricCount = stats?.metric_count ?? 0
   const tripleCount = stats?.metric_rows_scanned ?? 0
@@ -77,9 +74,19 @@ export default async function HomePage() {
   const generatedAt = formatGeneratedAt(manifest?.generated_at)
 
   // Featured family cards — pick the first six families with summaries.
+  // Curated multi-benchmark families (BFCL, MMLU, JudgeBench, …) put
+  // their benchmarks under composites[].benchmarks[] after the adapter;
+  // singletons land in standalone_benchmarks[] or benchmarks[]. Pull
+  // from all four shapes so the count reflects the union (matches
+  // family-table.tsx:313's logic).
   const featuredFamilies = hierarchy.families.slice(0, 6).map((family) => {
-    const benches: unknown[] =
-      family.benchmarks ?? family.standalone_benchmarks ?? family.leaves ?? []
+    // v3 family layouts: exactly one of standalone_benchmarks / benchmarks /
+    // composites is present per family. Walk all three to count benchmarks.
+    const benches: unknown[] = [
+      ...(family.standalone_benchmarks ?? []),
+      ...(family.benchmarks ?? []),
+      ...((family.composites ?? []).flatMap((c) => c.benchmarks ?? [])),
+    ]
     let slices = 0
     for (const b of benches) {
       const benchSlices = (b as { slices?: unknown[] }).slices

components/benchmark-detail.tsx

@@ -105,38 +105,15 @@ interface CompositeGroup {
 
 const INSTANCE_PREVIEW_LIMIT = 5
 
-const SUITE_DISPLAY_NAMES: Record<string, string> = {
-  hfopenllm_v2: "HF Open LLM v2",
-  helm_lite: "HELM Lite",
-  helm_capabilities: "HELM Capabilities",
-  helm_classic: "HELM Classic",
-  helm_instruct: "HELM Instruct",
-  helm_mmlu: "HELM MMLU",
-  reward_bench: "RewardBench",
-  reward_bench_2: "RewardBench 2",
-  bfcl: "BFCL",
-  global_mmlu_lite: "Global MMLU Lite",
-  swe_bench: "SWE-bench",
-  arc_agi: "ARC-AGI",
-  tau_bench_2: "TAU-Bench 2",
-  ace: "ACE",
-  apex_agents: "APEX Agents",
-  apex_v1: "APEX v1",
-  appworld: "AppWorld",
-  browsecompplus: "BrowseComp+",
-  livecodebenchpro: "LiveCodeBench Pro",
-  sciarena: "SciArena",
-  terminal_bench_2_0: "Terminal Bench 2.0",
-  la_leaderboard: "LA Leaderboard",
-  theory_of_mind: "Theory of Mind",
-  fibble_arena: "Fibble Arena",
-  fibble1_arena: "Fibble Arena v1",
-  fibble2_arena: "Fibble Arena v2",
-  fibble3_arena: "Fibble Arena v3",
-  fibble4_arena: "Fibble Arena v4",
-  fibble5_arena: "Fibble Arena v5",
-  wordle_arena: "Wordle Arena",
-}
+// SUITE_DISPLAY_NAMES (38-entry hardcoded slug→display map) was deleted
+// in Step 4c of the hierarchy-alignment work
+// (notes/hierarchy-alignment.md §6 / §7 Step 4). The producer now ships
+// curated display names for every family / composite / benchmark via
+// prettify_display + the registry's display_overrides.yaml. This
+// component reads the shipped name; the DISPLAY_TOKEN_OVERRIDES /
+// DISPLAY_NAME_OVERRIDES below remain as a per-token polish layer
+// (mostly for raw model identifier rendering, where the producer's
+// metadata doesn't carry a curated display).
 
 const DISPLAY_TOKEN_OVERRIDES: Record<string, string> = {
   ace: "ACE",
@@ -169,7 +146,6 @@ const DISPLAY_TOKEN_OVERRIDES: Record<string, string> = {
 }
 
 const DISPLAY_NAME_OVERRIDES: Record<string, string> = {
-  ...SUITE_DISPLAY_NAMES,
   apex: "APEX",
   apex_agents: "APEX Agents",
   apex_v1: "APEX v1",
@@ -294,17 +270,17 @@ function doesLabelMatchSuiteKey(label: string | null | undefined, compositeKey:
 
 function getCompositeKey(group: BenchmarkGroup): string {
   const evaluation = group.variants[0]?.evaluation
-  const backendSuiteKey =
-    evaluation?.benchmark_parent_key ||
-    evaluation?.benchmark_family_key ||
-    evaluation?.benchmark
+  const backendSuiteKey = evaluation?.family_id
 
   return normalizeCompositeKey(backendSuiteKey ?? group.key)
 }
 
 function getCompositeDisplayName(key: string): string {
-  const normalizedKey = normalizeCompositeKey(key)
-  return SUITE_DISPLAY_NAMES[normalizedKey] ?? normalizeDisplayLabel(key)
+  // Display names come from the shipped hierarchy.json. This helper
+  // is used in fallback paths where only a raw key is in scope; it
+  // applies the same per-token polish (DISPLAY_TOKEN_OVERRIDES) the
+  // rest of the renderer uses.
+  return normalizeDisplayLabel(key)
 }
 
 function getCompositeName(group: BenchmarkGroup, compositeKey: string): string {
@@ -1426,11 +1402,12 @@ function buildBenchmarkGroups(
       (entry.evaluation.slice_name && (entry.evaluation.benchmark_parent_name || entry.evaluation.benchmark)
         ? `${entry.evaluation.benchmark_parent_name || entry.evaluation.benchmark} / ${entry.evaluation.slice_name}`
         : title)
+    // eval_summary_id is producer-shipped on every v3 entry; the
+    // remaining ?? tiers are for legacy snapshots without that field.
     const groupKey =
       entry.evaluation.eval_summary_id ??
-      entry.evaluation.benchmark_parent_key ??
-      entry.evaluation.benchmark_leaf_key ??
-      entry.evaluation.benchmark ??
+      entry.evaluation.parent_benchmark_id ??
+      entry.evaluation.family_id ??
       "benchmark"
     const card = benchmarkCards
       ? lookupBenchmarkCard(benchmarkCards, rawBenchmarkName)
@@ -1988,7 +1965,7 @@ export function BenchmarkDetail({
 
   // Family-bucketed groups for the list view, mirroring plotboxUnits logic.
   // When comparisonIndex is available we use the backend-authoritative
-  // benchmark_family_key; otherwise we fall back to the group's own key so each
+  // family_id; otherwise we fall back to the group's own key so each
   // BenchmarkGroup forms its own family.
   type ListFamily = {
     familyKey: string
@@ -2008,9 +1985,9 @@ export function BenchmarkDetail({
         ?.evaluation.eval_summary_id
       const evalEntry =
         evalId && comparisonIndex ? comparisonIndex.evals[evalId] : null
-      const famKey = evalEntry?.benchmark_family_key ?? group.key
+      const famKey = evalEntry?.family_id ?? group.key
       const famName =
-        evalEntry?.benchmark_family_name ||
+        evalEntry?.family_display_name ||
         evalEntry?.display_name ||
         group.title
 
@@ -2338,7 +2315,12 @@ export function BenchmarkDetail({
           .filter((p) => selectedIds.has(p.model_route_id))
           .map((p) => ({
             modelId: p.model_route_id,
-            modelName: getModelDisplayName(p.model_family_name),
+            // Fall back to model_family_id when the registry has no display
+            // name for this model. ~86% of score entries today land here;
+            // root cause (registry coverage) is Step 2 work. The id is
+            // already human-readable in this codebase ("anthropic/Sonnet 4.5"),
+            // so the fallback is more useful than "Unknown Model".
+            modelName: getModelDisplayName(p.model_family_name || p.model_family_id),
             score: p.score,
             isCurrent: false,
             isDefault: defaults.has(p.model_route_id),
@@ -2406,7 +2388,7 @@ export function BenchmarkDetail({
   // A plotbox can expose a top-level "view" selector (slices, child
   // benchmarks, components) and an optional metric tab rail beneath the chart.
   // Plotbox grouping is driven entirely by comparison-index's own
-  // benchmark_family_key so it stays in sync with the backend.
+  // family_id so it stays in sync with the backend.
   type PlotboxMetricTab = {
     tabKey: string
     label: string
@@ -2474,9 +2456,9 @@ export function BenchmarkDetail({
       const evalEntry = comparisonIndex.evals[evalId]
       if (!evalEntry) continue
 
-      const famKey = evalEntry.benchmark_family_key ?? evalId
+      const famKey = evalEntry.family_id ?? evalId
       const famName =
-        evalEntry.benchmark_family_name || evalEntry.display_name || famKey
+        evalEntry.family_display_name || evalEntry.display_name || famKey
       const bucket = familyBuckets.get(famKey) ?? {
         familyName: famName,
         category: group.category,
@@ -2509,8 +2491,7 @@ export function BenchmarkDetail({
       histKey: histKeyFor(evalEntry.eval_summary_id, metric.metric_summary_id),
       evalSummaryId: evalEntry.eval_summary_id,
       metricSummaryId: metric.metric_summary_id,
-      evalDisplayName:
-        evalEntry.display_name || evalEntry.benchmark_leaf_name || group.title,
+      evalDisplayName: evalEntry.display_name || group.title,
       evalEntry,
       metricEntry: metric,
       isRollup,
@@ -2526,8 +2507,7 @@ export function BenchmarkDetail({
         // One eval in scope — slices/splits become the view selector while
         // metrics move to a compact tab rail beneath the chart.
         const { group, evalEntry } = resolved[0]
-        const evalDisplay =
-          evalEntry.display_name || evalEntry.benchmark_leaf_name || group.title
+        const evalDisplay = evalEntry.display_name || group.title
         const singleEvalViewBuckets = new Map<
           string,
           { viewKey: string; label: string; variants: BenchmarkVariant[] }
@@ -2598,21 +2578,22 @@ export function BenchmarkDetail({
 
       // Multi-eval family — the view selector chooses among child evals and
       // each view exposes that eval's metrics in the bottom tab rail.
+      // Rollup row = this eval IS the family root, i.e. its benchmark id
+      // matches the family id. For multi-benchmark families like HELM,
+      // there is no such eval (HELM has no "helm" benchmark), so rollup
+      // stays null and the children render as siblings.
       const rollup =
         resolved.find(
           (r) =>
-            r.evalEntry.benchmark_leaf_key != null &&
-            r.evalEntry.benchmark_leaf_key === r.evalEntry.benchmark_family_key
+            r.evalEntry.benchmark_id != null &&
+            r.evalEntry.benchmark_id === r.evalEntry.family_id,
         ) ?? null
       const children = rollup ? resolved.filter((r) => r !== rollup) : resolved
       const ordered: ResolvedGroup[] = rollup ? [rollup, ...children] : children
 
       const views: PlotboxView[] = ordered
         .map((r) => {
-          const rawLabel =
-            r.evalEntry.benchmark_leaf_name ||
-            r.evalEntry.display_name ||
-            r.group.title
+          const rawLabel = r.evalEntry.display_name || r.group.title
           const label =
             r === rollup ? "Overall" : stripFamilyPrefix(rawLabel, familyName)
           const tabs = r.evalEntry.metrics
@@ -2648,8 +2629,20 @@ export function BenchmarkDetail({
       let hasSlice = false
       let hasDistinctLeaves = false
       for (const r of children) {
-        const leafKey = r.evalEntry.benchmark_leaf_key
-        if (leafKey && leafKey !== r.evalEntry.benchmark_family_key) {
+        // "Distinct leaf" = this child has an identity distinct from the
+        // family root. Two cases:
+        //   1. Non-slice child (e.g. HELM/MMLU under HELM family).
+        //   2. Slice whose parent benchmark is not the family itself
+        //      (e.g. HELM/MMLU/anatomy — slice of MMLU under HELM, where
+        //      parent="mmlu" ≠ family="helm"). In a singleton family the
+        //      slice's parent equals the family and this case collapses
+        //      back to "slice", as expected.
+        const evalEntry = r.evalEntry
+        const isDistinctLeaf =
+          evalEntry.is_slice === false ||
+          (evalEntry.parent_benchmark_id != null &&
+            evalEntry.parent_benchmark_id !== evalEntry.family_id)
+        if (isDistinctLeaf) {
           hasDistinctLeaves = true
         }
         if (r.group.variants[0]?.evaluation.benchmark_component_key ?? null) {

components/eval-detail.tsx

@@ -373,7 +373,8 @@ function splitFlagNote(raw: string): { tag: string | null; body: string } {
   return { tag: match[1].trim(), body: match[2].trim() }
 }
 
-function formatRawScore(score: number, unit?: string) {
+function formatRawScore(score: number | null | undefined, unit?: string) {
+  if (score == null || !Number.isFinite(score)) return "—"
   const suffix = unit ? ` ${unit}` : ""
   return `${score.toFixed(2)}${suffix}`
 }
@@ -644,8 +645,8 @@ export function EvalDetail({ summary }: EvalDetailProps) {
             summary.evaluation_name,
             summary.composite_benchmark_name,
             summary.composite_benchmark_key,
-            summary.benchmark_family_key,
-            summary.benchmark_leaf_key,
+            summary.family_id,
+            summary.benchmark_id,
             summary.benchmark_card.benchmark_details?.name,
           )}
         />
@@ -1317,7 +1318,7 @@ export function EvalDetail({ summary }: EvalDetailProps) {
                                 <div className="space-y-3">
                                   <ResearcherReproducibilityCard
                                     modelResult={modelResult}
-                                    benchmarkKey={summary.benchmark_id ?? summary.benchmark_leaf_key ?? summary.composite_benchmark_key}
+                                    benchmarkKey={summary.benchmark_id ?? summary.composite_benchmark_key}
                                     evalName={summary.evaluation_name}
                                   />
                                   <div className="flex justify-end">
@@ -2039,7 +2040,7 @@ function MultiMetricLeaderboard({
                       <div className="space-y-3">
                         <ResearcherReproducibilityCard
                           modelResult={matchingResult}
-                          benchmarkKey={summary.benchmark_id ?? summary.benchmark_leaf_key ?? summary.composite_benchmark_key}
+                          benchmarkKey={summary.benchmark_id ?? summary.composite_benchmark_key}
                           evalName={summary.evaluation_name}
                         />
                         <div className="flex justify-end">

components/family-table.tsx

@@ -4,7 +4,7 @@ import { Fragment, useMemo, useState } from "react"
 import { useRouter } from "next/navigation"
 import { ArrowUpRight, ChevronDown, ChevronRight } from "lucide-react"
 
-import type { HierarchyBenchmark, HierarchyFamily, HierarchyLeaf } from "@/lib/backend-artifacts"
+import type { HierarchyBenchmark, HierarchyFamily } from "@/lib/backend-artifacts"
 import type { BenchmarkCard, CategoryType } from "@/lib/benchmark-schema"
 import type { BenchmarkEvalListItem } from "@/lib/eval-processing"
 import { humanizeEvaluationId } from "@/lib/utils"
@@ -118,38 +118,22 @@ function collectLeafEntries(
     })
   }
 
-  if (out.length > 0) return out
-
-  // ── Fallback: legacy `leaves` shape ────────────────────────────────
-  for (const leaf of fam.leaves ?? []) {
-    const explicit = leaf.eval_summary_ids ?? []
-    const ids =
-      explicit.length > 0
-        ? explicit
-        : leaf.key
-        ? [`${fam.key}_${leaf.key}`, leaf.key]
-        : []
-    if (ids.length === 0) continue
-    const collected = new Set<string>()
-    for (const d of leaf.tags?.domains ?? []) collected.add(d.toLowerCase())
-    const cardByLeaf = benchmarkCards?.[leaf.key]
-    for (const d of cardByLeaf?.benchmark_details?.domains ?? []) collected.add(d.toLowerCase())
-    for (const id of ids) {
-      const cardById = benchmarkCards?.[id]
-      for (const d of cardById?.benchmark_details?.domains ?? []) collected.add(d.toLowerCase())
-    }
-    out.push({
-      id: ids[0],
-      leafKey: leaf.key,
-      leafName: leaf.display_name || leaf.key,
-      evalsCount: leaf.evals_count ?? ids.length,
-      domains: Array.from(collected),
-    })
-  }
-
   return out
 }
 
+/**
+ * Resolve the family-level navigation target without exposing the
+ * internal `LeafEntry` shape. Returns the eval_summary_id to open when
+ * the user clicks the family card / row, or `null` for aggregator
+ * families that should expand inline instead of navigating.
+ */
+export function getFamilyNavId(
+  fam: HierarchyFamily,
+  benchmarkCards?: Record<string, BenchmarkCard>,
+): string | null {
+  return pickFamilyNavId(fam, collectLeafEntries(fam, benchmarkCards))
+}
+
 /**
  * Pick the eval_summary_id to navigate to when the user clicks the family
  * row. Returns null when the family has no genuine family-level summary —
@@ -308,21 +292,17 @@ export function FamilyTable({
       const composites = fam.composites ?? []
       const standalone = fam.standalone_benchmarks ?? []
       const benchmarks = fam.benchmarks ?? []
-      const leaves: HierarchyLeaf[] = fam.leaves ?? []
 
       const allBenchmarks = [
         ...standalone,
         ...benchmarks,
         ...composites.flatMap((c) => c.benchmarks ?? []),
       ]
-      const metricCount =
-        (fam.metrics?.length ?? 0) +
-        allBenchmarks.reduce(
-          (sum, b) => sum + ((b as { metrics?: unknown[] }).metrics?.length ?? 0),
-          0,
-        )
-      const benchmarkCount =
-        allBenchmarks.length > 0 ? allBenchmarks.length : leaves.length
+      const metricCount = allBenchmarks.reduce(
+        (sum, b) => sum + (b.metrics?.length ?? 0),
+        0,
+      )
+      const benchmarkCount = allBenchmarks.length
 
       const leafEntries = collectLeafEntries(fam, benchmarkCards)
       const navId = pickFamilyNavId(fam, leafEntries)

components/policy-overview.tsx

@@ -59,7 +59,7 @@ export function PolicyOverview({ summary }: PolicyOverviewProps) {
   const cardNameNorm = normalizeId(cardName)
   const evalIdentifiers = [
     summary.evaluation_name,
-    summary.benchmark_leaf_key,
+    summary.benchmark_id,
     summary.composite_benchmark_key,
     summary.composite_benchmark_name,
     summary.canonical_display_name,
@@ -180,16 +180,16 @@ export function PolicyOverview({ summary }: PolicyOverviewProps) {
         summary.evaluation_name,
         summary.composite_benchmark_name,
         summary.composite_benchmark_key,
-        summary.benchmark_family_key,
-        summary.benchmark_leaf_key,
+        summary.family_id,
+        summary.benchmark_id,
         card?.benchmark_details?.name,
       ),
     [
       summary.evaluation_name,
       summary.composite_benchmark_name,
       summary.composite_benchmark_key,
-      summary.benchmark_family_key,
-      summary.benchmark_leaf_key,
+      summary.family_id,
+      summary.benchmark_id,
       card?.benchmark_details?.name,
     ],
   )

components/signals/corpus-signals-strip.tsx

@@ -87,7 +87,7 @@ export function CorpusSignalsStrip({
         statValue={pctNum(multiSourceRate)}
         statUnit="%"
         headline="of reported score triples have reports from more than one party."
-        detail={`${formatPct(tpShare)} third-party, ${formatPct(fpShare)} first-party of ${totalReports.toLocaleString()} triples.`}
+        detail={`${formatPct(tpShare)} third-party, ${formatPct(fpShare)} first-party of ${totalReports.toLocaleString()} unique triples.`}
         asks="Who reported this score, and have others reproduced it?"
       />
       <SignalTile

lib/backend-artifacts.ts

@@ -241,6 +241,24 @@ export interface ComparabilityCorpusBlock {
   groups_with_cross_party_check: number
 }
 
+// ---------------------------------------------------------------------------
+// Hierarchy types (v3 — family-rooted tree).
+//
+// The producer emits this shape via eval_card_backend's
+// `write_hierarchy()` after the Step 3 reshape. See
+// /Users/jchim/projects/evaleval/notes/hierarchy-alignment.md §5.1
+// for the canonical spec.
+//
+// Top level: `families[]` is the rich entity. Composites nest under
+// families[].composites[]. `benchmark_index[]` cross-links a canonical
+// benchmark that appears in multiple families.
+//
+// Each family chooses ONE of three layouts:
+//   - standalone_benchmarks: single-benchmark family.
+//   - benchmarks (flat): multiple benchmarks, no composite layer.
+//   - composites: multi-composite family (HELM has 7).
+// ---------------------------------------------------------------------------
+
 export interface HierarchyTags {
   domains: string[]
   languages: string[]
@@ -250,109 +268,108 @@ export interface HierarchyTags {
 export interface HierarchyMetric {
   key: string
   display_name: string
+  /** Producer-supplied list of organisations whose results back this
+   *  metric. Empty when source attribution wasn't recoverable. */
   sources?: string[]
+  /** Per spec §5.1 — true when this is the benchmark's primary metric
+   *  (matches `primary_metric_key`). */
+  is_primary?: boolean
+  /** Distinct model count contributing to this metric — drives
+   *  primary-metric tie-break. */
+  models_count?: number
 }
 
 export interface HierarchySlice {
   key: string
   display_name: string
   metrics: HierarchyMetric[]
-  /** New: marks the bare-stem "Overall" slice (e.g. `gaia` inside
-   *  the `gaia` benchmark). Frontend can label such a row "Overall". */
+  /** Marks the bare-stem "Overall" slice (e.g. `gaia` inside the
+   *  `gaia` benchmark). Frontend labels such a row "Overall". */
   is_bare_stem?: boolean
 }
 
 export interface HierarchyBenchmark extends SignalSummaries {
   key: string
   display_name: string
+  family_id: string
+  is_slice: boolean
+  /** True when this row IS the family/composite root (canonical_id
+   *  matches the family or composite key). For a singleton family,
+   *  the sole benchmark is overall. For multi-bench families with
+   *  no head benchmark of the same name (HAL, BFCL with no `bfcl`
+   *  benchmark), all are False. */
+  is_overall: boolean
+  /** True for the benchmark within its family that's the headline
+   *  reading. Selected via FAMILY_PRIMARY_OVERRIDE → is_overall →
+   *  alphabetical (see _mark_family_primary_benchmark in producer). */
+  is_primary?: boolean
+  /** Metric key whose primary metric should be displayed as the
+   *  benchmark's headline number. Null when the benchmark has no
+   *  metrics. */
+  primary_metric_key?: string | null
   has_card: boolean
   tags: HierarchyTags
   slices: HierarchySlice[]
   metrics: HierarchyMetric[]
   summary_eval_ids?: string[]
-  /** New post-cutover: family slug (defaults to benchmark key for singletons). */
-  family_id?: string
-  /** New post-cutover: TRUE when this row is a slice of a root benchmark. */
-  is_slice?: boolean
 }
 
 export interface HierarchyComposite extends SignalSummaries {
   key: string
   display_name: string
-  has_card?: boolean
   category: string
   tags: HierarchyTags
   benchmarks: HierarchyBenchmark[]
-  summary_eval_ids?: string[]
-  /** New top-level shape: total triples in the composite. */
   evals_count?: number
+  summary_eval_ids?: string[]
+  /** True for the headline composite within a multi-composite family. */
+  is_primary?: boolean
 }
 
-export interface HierarchyLeaf extends SignalSummaries {
+export interface HierarchyFamily extends SignalSummaries {
   key: string
   display_name: string
   category: string
-  evals_count?: number
-  eval_summary_ids?: string[]
-  tags?: Partial<HierarchyTags>
-  has_card?: boolean
+  tags: HierarchyTags
+  evals_count: number
+  eval_summary_ids: string[]
+  /** Exactly ONE of the three layout fields below is present. */
+  standalone_benchmarks?: HierarchyBenchmark[]
+  benchmarks?: HierarchyBenchmark[]
+  composites?: HierarchyComposite[]
 }
 
-export interface HierarchyFamily extends SignalSummaries {
+export interface BenchmarkIndexAppearance {
+  family_key: string
+  benchmark_key: string
+  eval_summary_ids: string[]
+  /** True when the family this appearance is under is the benchmark's
+   *  natural "home" family (family_key === benchmark_key). */
+  is_canonical_home: boolean
+}
+
+export interface BenchmarkIndexEntry {
   key: string
   display_name: string
-  has_card?: boolean
-  category: string
-  tags?: Partial<HierarchyTags>
-  evals_count?: number
-  eval_summary_ids?: string[]
-  // Legacy nested shape (composites + standalone benchmarks)
-  standalone_benchmarks?: HierarchyBenchmark[]
-  composites?: HierarchyComposite[]
-  benchmarks?: HierarchyBenchmark[]
-  slices?: HierarchySlice[]
-  metrics?: HierarchyMetric[]
-  // Newer 2-level shape (family → leaf)
-  leaves?: HierarchyLeaf[]
+  appearances: BenchmarkIndexAppearance[]
 }
 
 export interface EvalHierarchyStats {
   family_count: number
   composite_count: number
-  /** Legacy benchmark-stem grouping count. Removed in the composite/
-   *  family/slice taxonomy refactor — kept optional so the adapter
-   *  can synthesise it for the existing homepage stats strip. */
-  standalone_benchmark_count?: number
-  /** Same as above. */
-  single_benchmark_count?: number
-  /** New post-cutover field: total distinct (composite, benchmark) rows
-   *  in the benchmarks dim. */
-  benchmark_count?: number
+  benchmark_count: number
   slice_count: number
   metric_count: number
   metric_rows_scanned: number
 }
 
-/** Lightweight family-lookup index entry from the new top-level
- *  `families[]` array (composite/family/slice taxonomy). One per
- *  family_id with the list of member benchmark keys — no nested
- *  composites, no slice payload. The legacy `HierarchyFamily` shape
- *  (with nested `composites[]` / `standalone_benchmarks[]`) is
- *  synthesised by the adapter for backward compat. */
-export interface HierarchyFamilyIndex {
-  key: string
-  display_name: string
-  member_benchmark_keys: string[]
-}
-
 export interface EvalHierarchy {
+  /** Schema marker: "v3.hierarchy.1". Older snapshots lack this. */
+  schema_version?: string
+  generated_at?: string
   stats?: EvalHierarchyStats
   families: HierarchyFamily[]
-  /** New post-cutover top-level array — one per leaderboard slug. */
-  composites?: HierarchyComposite[]
-  /** New post-cutover flat lookup. The adapter promotes this onto
-   *  per-family records as it builds the legacy shape. */
-  family_index?: HierarchyFamilyIndex[]
+  benchmark_index?: BenchmarkIndexEntry[]
 }
 
 // ---------------------------------------------------------------------------
@@ -407,14 +424,15 @@ export interface ComparisonMetricEntry {
 
 export interface ComparisonEvalEntry {
   eval_summary_id: string
-  benchmark_family_key: string | null
-  benchmark_family_name: string | null
-  benchmark_parent_key: string | null
-  benchmark_parent_name: string | null
-  benchmark_leaf_key: string | null
-  benchmark_leaf_name: string | null
+  benchmark_id: string | null
+  family_id: string | null
+  family_display_name: string | null
+  composite_slug: string | null
+  composite_display_name: string | null
+  parent_benchmark_id: string | null
   display_name: string | null
   category: string
+  is_slice: boolean
   is_summary_score: boolean
   summary_score_for: string | null
   summary_eval_ids: string[]

lib/benchmark-schema.ts

@@ -10,16 +10,22 @@ export interface BenchmarkEvaluation {
   eval_summary_id?: string
   evaluation_id: string
   retrieved_timestamp: string
+  /** Legacy benchmark-name-or-slug field. The view-data layer
+   *  (lib/view-data.ts) populates this from eval_evaluation_name with a
+   *  benchmark_id fallback, so it works as a stable name source for
+   *  badges and grouping when nothing better is on-hand. New callers
+   *  should prefer `display_name` / `canonical_display_name`; this
+   *  field is kept for the surfaces that aren't yet migrated. */
   benchmark?: string
   display_name?: string
   canonical_display_name?: string
   category?: CategoryType
-  benchmark_family_key?: string
+  family_id?: string
   benchmark_family_name?: string
-  benchmark_parent_key?: string
+  parent_benchmark_id?: string
   benchmark_parent_name?: string
-  benchmark_leaf_key?: string
   benchmark_leaf_name?: string
+  is_slice?: boolean
   benchmark_component_key?: string | null
   benchmark_component_name?: string | null
   is_summary_score?: boolean

lib/eval-processing.ts

@@ -176,22 +176,20 @@ export interface BenchmarkEvalSummary extends SignalSummaries {
   /** Canonical benchmark id (the registry-resolved benchmark). Drives
    *  benchmark-card lookups regardless of slice/composite axis. */
   benchmark_id?: string
-  /** Benchmark family grouping key — curated multi-benchmark family
-   *  slug (e.g. "mmlu"), defaults to benchmark id for singletons. */
-  benchmark_family_key?: string
   /** Family display name. */
   benchmark_family_name?: string
-  /** Leaf benchmark key — populated when this row is a slice of a
-   *  parent benchmark; null for non-slice rows. */
-  benchmark_leaf_key?: string
   /** Composite (leaderboard) slug — e.g. "wasp", "helm-classic". */
   composite_slug?: string
   /** Composite display name — e.g. "WASP", "HELM Classic". */
   composite_display_name?: string
-  /** Family slug, post-cutover canonical name (alias of benchmark_family_key). */
+  /** Curated multi-benchmark family slug (e.g. "mmlu"), defaults to
+   *  benchmark id for singletons. */
   family_id?: string
   /** Family display, post-cutover canonical name. */
   family_display_name?: string
+  /** Parent benchmark id — populated when this row is a slice of a
+   *  root benchmark; null for non-slice rows. */
+  parent_benchmark_id?: string
   /** True when this row is a within-benchmark slice cut. */
   is_slice?: boolean
   /** Source dataset metadata from the pipeline */

lib/hf-data.ts

@@ -932,386 +932,35 @@ export async function fetchEvalHierarchy(): Promise<EvalHierarchy> {
  *      back under per-family records, with the composite slug as the
  *      family key when no curated multi-benchmark family applies.
  */
-export function adaptEvalHierarchy(raw: EvalHierarchy): EvalHierarchy {
-  const newShape = Array.isArray(raw.composites) && raw.composites.length > 0
-  if (newShape) {
-    return adaptCompositeShape(raw)
-  }
-
-  const families = (raw.families ?? []).map((family) => {
-    const hasLegacyTree =
-      (family.composites && family.composites.length > 0) ||
-      (family.standalone_benchmarks && family.standalone_benchmarks.length > 0) ||
-      (family.benchmarks && family.benchmarks.length > 0)
-
-    if (hasLegacyTree) {
-      return family
-    }
-
-    const leaves = family.leaves ?? []
-    if (leaves.length === 0) {
-      return family
-    }
-
-    const standalone = leaves.map((leaf) => ({
-      key: leaf.key,
-      display_name: leaf.display_name,
-      has_card: leaf.has_card ?? false,
-      tags: {
-        domains: leaf.tags?.domains ?? [],
-        languages: leaf.tags?.languages ?? [],
-        tasks: leaf.tags?.tasks ?? [],
-      },
-      slices: [],
-      metrics: [],
-      reproducibility_summary: leaf.reproducibility_summary,
-      provenance_summary: leaf.provenance_summary,
-      comparability_summary: leaf.comparability_summary,
-      summary_eval_ids: leaf.eval_summary_ids,
-    }))
-
-    return {
-      ...family,
-      tags: {
-        domains: family.tags?.domains ?? [],
-        languages: family.tags?.languages ?? [],
-        tasks: family.tags?.tasks ?? [],
-      },
-      standalone_benchmarks: standalone,
-    }
-  })
-
-  if (raw.stats) {
-    return { ...raw, families }
-  }
-
-  let composite_count = 0
-  let standalone_benchmark_count = 0
-  let single_benchmark_count = 0
-  let slice_count = 0
-  let metric_count = 0
-
-  for (const family of families) {
-    composite_count += family.composites?.length ?? 0
-    const standalone = family.standalone_benchmarks ?? []
-    standalone_benchmark_count += standalone.length
-    if ((family.composites?.length ?? 0) === 0 && standalone.length === 1) {
-      single_benchmark_count += 1
-    }
-    for (const composite of family.composites ?? []) {
-      for (const benchmark of composite.benchmarks ?? []) {
-        slice_count += benchmark.slices?.length ?? 0
-        metric_count += benchmark.metrics?.length ?? 0
-      }
-    }
-    for (const benchmark of standalone) {
-      slice_count += benchmark.slices?.length ?? 0
-      metric_count += benchmark.metrics?.length ?? 0
-    }
-  }
-
-  return {
-    ...raw,
-    families,
-    stats: {
-      family_count: families.length,
-      composite_count,
-      standalone_benchmark_count,
-      single_benchmark_count,
-      slice_count,
-      metric_count,
-      metric_rows_scanned: 0,
-    },
-  }
-}
-
 /**
- * Translate the new composite/family/slice taxonomy shape (top-level
- * `composites[]` + flat `families[]` lookup index) into the legacy
- * `families[].composites[]` / `families[].standalone_benchmarks[]`
- * tree.
+ * Validate-and-passthrough for the v3 hierarchy shape (per
+ * /Users/jchim/projects/evaleval/notes/hierarchy-alignment.md §5.1).
+ * The producer's `write_hierarchy()` emits family-rooted trees
+ * directly; the adapter no longer synthesises legacy shapes.
  *
- * Bucketing rule: every benchmark in `composites[].benchmarks[]` is
- * grouped by `family_id` (curated multi-benchmark family slug,
- * defaulting to benchmark.key for singletons). A family with ≥2
- * member benchmarks lands under a synthetic legacy `composites[]`
- * entry keyed on the family slug; a singleton family lands under
- * `standalone_benchmarks[]`. Slice rows on the new
- * benchmark.slices[] carry through unchanged.
+ * Behaviour:
+ *   - v3 detection via `schema_version === "v3.hierarchy.1"` —
+ *     pass through unchanged.
+ *   - Older snapshot lacking schema_version: log a warning and
+ *     pass through. Consumers may render empty for missing fields
+ *     but won't crash.
  *
- * Stats are taken straight from raw.stats (which has the new
- * shape's `benchmark_count`) plus synthesised
- * `standalone_benchmark_count` / `single_benchmark_count` for
- * back-compat consumers.
+ * Step 4 deleted the legacy `adaptCompositeShape()` synthesis
+ * (~400 lines of bucketing logic that built families[].composites[]
+ * from the old top-level composites[]). The producer now does that
+ * grouping at write time using `canonical_composites.family_id`.
  */
-function adaptCompositeShape(raw: EvalHierarchy): EvalHierarchy {
-  const familyIndex = new Map<string, { display_name: string; member_keys: string[] }>()
-  for (const fam of raw.families ?? []) {
-    if (!fam || typeof fam !== "object") continue
-    const f = fam as unknown as { key?: string; display_name?: string; member_benchmark_keys?: string[] }
-    if (!f.key) continue
-    familyIndex.set(f.key, {
-      display_name: f.display_name ?? f.key,
-      member_keys: f.member_benchmark_keys ?? [],
-    })
-  }
-
-  type LegacyBenchmark = HierarchyBenchmark & { _composite_slug?: string }
-
-  // Set of benchmark keys claimed by curated multi-benchmark families
-  // (families.yaml), so we don't redundantly bucket them under their
-  // composite below. Crucially this only counts MULTI-member families
-  // (≥2 benchmarks) — every benchmark also gets a synthetic singleton
-  // family from the backend's `_synthesise_singleton_families` pass,
-  // and treating those as curated would short-circuit the
-  // composite-implicit grouping (Pass B) and scatter every leaderboard
-  // benchmark into its own row.
-  const curatedMembers = new Set<string>()
-  for (const fam of familyIndex.values()) {
-    if (fam.member_keys.length < 2) continue
-    for (const k of fam.member_keys) curatedMembers.add(k)
-  }
-
-  // Two grouping passes, in priority order:
-  //
-  // (1) Curated families from families.yaml — bucketed by `family_id`.
-  //     Drives the MMLU family, BFCL family, JudgeBench family rows.
-  //
-  // (2) Composite-implicit groupings — for benchmarks NOT in any
-  //     curated family, group by their composite_slug if the
-  //     composite has ≥2 such benchmarks. This restores the legacy
-  //     "HELM Classic / HELM Lite / HELM Safety" family rows that
-  //     would otherwise scatter across one singleton family per
-  //     leaf benchmark, hiding the leaderboard structure.
-  //
-  // (3) Anything still ungrouped lands as a singleton standalone.
-  type Bucket = {
-    key: string
-    display: string
-    benches: LegacyBenchmark[]
-    /** Curated family vs synthesised-from-composite vs singleton. Drives
-     *  whether the legacy `composites[]` slot or `standalone_benchmarks[]`
-     *  is populated. */
-    kind: "curated" | "composite" | "singleton"
-  }
-  const buckets = new Map<string, Bucket>()
-
-  const toLegacyBenchmark = (
-    bench: HierarchyComposite["benchmarks"][number],
-    composite: HierarchyComposite,
-  ): LegacyBenchmark => ({
-    key: bench.key,
-    display_name: bench.display_name,
-    has_card: bench.has_card ?? false,
-    tags: {
-      domains: bench.tags?.domains ?? [],
-      languages: bench.tags?.languages ?? [],
-      tasks: bench.tags?.tasks ?? [],
-    },
-    slices: bench.slices ?? [],
-    metrics: bench.metrics ?? [],
-    summary_eval_ids: bench.summary_eval_ids,
-    reproducibility_summary: bench.reproducibility_summary,
-    provenance_summary: bench.provenance_summary,
-    comparability_summary: bench.comparability_summary,
-    family_id: bench.family_id ?? bench.key,
-    is_slice: bench.is_slice ?? false,
-    _composite_slug: composite.key,
-  })
-
-  // Pass A: curated families.
-  for (const composite of raw.composites ?? []) {
-    for (const bench of composite.benchmarks ?? []) {
-      const familyId = bench.family_id ?? bench.key
-      if (!curatedMembers.has(bench.key)) continue
-      const entry = familyIndex.get(familyId)
-      if (!entry) continue
-      const bucketKey = `family:${familyId}`
-      if (!buckets.has(bucketKey)) {
-        buckets.set(bucketKey, {
-          key: familyId,
-          display: entry.display_name,
-          benches: [],
-          kind: "curated",
-        })
-      }
-      buckets.get(bucketKey)!.benches.push(toLegacyBenchmark(bench, composite))
-    }
-  }
-
-  // Pass B: composite-implicit groupings. Per composite, count
-  // distinct non-curated benchmark keys; if ≥2, group them under the
-  // composite slug; otherwise fall through to the singleton pass.
-  for (const composite of raw.composites ?? []) {
-    const eligibleBenches = (composite.benchmarks ?? [])
-      .filter((b) => !curatedMembers.has(b.key))
-    const distinctKeys = new Set(eligibleBenches.map((b) => b.key))
-    if (distinctKeys.size < 2) continue
-    const bucketKey = `composite:${composite.key}`
-    if (!buckets.has(bucketKey)) {
-      buckets.set(bucketKey, {
-        key: composite.key,
-        display: composite.display_name,
-        benches: [],
-        kind: "composite",
-      })
-    }
-    for (const bench of eligibleBenches) {
-      buckets.get(bucketKey)!.benches.push(toLegacyBenchmark(bench, composite))
-    }
-  }
-
-  // Pass C: singletons (benchmarks not in a curated family and whose
-  // composite carries only this benchmark). Bucketed by benchmark key.
-  for (const composite of raw.composites ?? []) {
-    const eligibleBenches = (composite.benchmarks ?? [])
-      .filter((b) => !curatedMembers.has(b.key))
-    const distinctKeys = new Set(eligibleBenches.map((b) => b.key))
-    if (distinctKeys.size >= 2) continue
-    for (const bench of eligibleBenches) {
-      const bucketKey = `bench:${bench.key}`
-      if (!buckets.has(bucketKey)) {
-        buckets.set(bucketKey, {
-          key: bench.key,
-          display: bench.display_name,
-          benches: [],
-          kind: "singleton",
-        })
-      }
-      buckets.get(bucketKey)!.benches.push(toLegacyBenchmark(bench, composite))
-    }
-  }
-
-  // Synthesise legacy family records.
-  const families: HierarchyFamily[] = []
-  let standalone_benchmark_count = 0
-  let single_benchmark_count = 0
-  let synthesised_composite_count = 0
-
-  // Sort by display name for stable rendering. Curated families first,
-  // then composite-implicit groupings, then singletons.
-  const sortedBuckets = Array.from(buckets.values()).sort((a, b) => {
-    const kindOrder = { curated: 0, composite: 1, singleton: 2 } as const
-    if (kindOrder[a.kind] !== kindOrder[b.kind]) {
-      return kindOrder[a.kind] - kindOrder[b.kind]
-    }
-    return a.key.localeCompare(b.key)
-  })
-
-  for (const bucket of sortedBuckets) {
-    const benches = bucket.benches
-    if (benches.length === 0) continue
-    const display = bucket.display ?? bucket.key
-    const distinctBenchmarkKeys = new Set(benches.map((b) => b.key))
-
-    const tagDomains = new Set<string>()
-    const tagLanguages = new Set<string>()
-    const tagTasks = new Set<string>()
-    for (const b of benches) {
-      b.tags.domains.forEach((d) => tagDomains.add(d))
-      b.tags.languages.forEach((l) => tagLanguages.add(l))
-      b.tags.tasks.forEach((t) => tagTasks.add(t))
-    }
-    const tags: HierarchyTags = {
-      domains: Array.from(tagDomains).sort(),
-      languages: Array.from(tagLanguages).sort(),
-      tasks: Array.from(tagTasks).sort(),
-    }
-
-    const family: HierarchyFamily = {
-      key: bucket.key,
-      display_name: display,
-      category: "General",
-      tags,
-      has_card: benches.some((b) => b.has_card),
-      eval_summary_ids: Array.from(
-        new Set(benches.flatMap((b) => b.summary_eval_ids ?? [])),
-      ),
-      composites: [],
-      standalone_benchmarks: [],
-    }
-
-    if (bucket.kind === "singleton") {
-      // Singleton family — flatten the (potentially N) per-composite
-      // copies of this benchmark into one standalone row by merging
-      // their slice/metric arrays.
-      const merged: HierarchyBenchmark = mergeSingletonBenchmarks(benches)
-      family.standalone_benchmarks!.push(merged)
-      standalone_benchmark_count += 1
-      single_benchmark_count += 1
-    } else {
-      // Multi-benchmark grouping (curated family or composite-implicit).
-      // Emit one legacy composite under the family. De-dup benchmarks
-      // that appear in multiple upstream composites.
-      const seen = new Set<string>()
-      const dedupedBenches: LegacyBenchmark[] = []
-      for (const b of benches) {
-        if (seen.has(b.key)) continue
-        seen.add(b.key)
-        dedupedBenches.push(b)
-      }
-      family.composites!.push({
-        key: bucket.key,
-        display_name: display,
-        has_card: family.has_card,
-        category: family.category,
-        tags,
-        benchmarks: dedupedBenches,
-      })
-      synthesised_composite_count += 1
-    }
-
-    void distinctBenchmarkKeys
-    families.push(family)
-  }
-
-  const stats = raw.stats
-    ? {
-        ...raw.stats,
-        standalone_benchmark_count:
-          raw.stats.standalone_benchmark_count ?? standalone_benchmark_count,
-        single_benchmark_count:
-          raw.stats.single_benchmark_count ?? single_benchmark_count,
-      }
-    : {
-        family_count: families.length,
-        composite_count: raw.composites?.length ?? synthesised_composite_count,
-        benchmark_count: 0,
-        standalone_benchmark_count,
-        single_benchmark_count,
-        slice_count: 0,
-        metric_count: 0,
-        metric_rows_scanned: 0,
-      }
-
-  return {
-    ...raw,
-    families,
-    stats,
-  }
-}
-
-function mergeSingletonBenchmarks(benches: HierarchyBenchmark[]): HierarchyBenchmark {
-  if (benches.length === 1) return benches[0]
-  const first = benches[0]
-  const sliceMap = new Map<string, HierarchySlice>()
-  const metricMap = new Map<string, HierarchyMetric>()
-  const summaryIds = new Set<string>()
-  for (const b of benches) {
-    for (const s of b.slices ?? []) {
-      if (!sliceMap.has(s.key)) sliceMap.set(s.key, s)
-    }
-    for (const m of b.metrics ?? []) {
-      if (!metricMap.has(m.key)) metricMap.set(m.key, m)
-    }
-    for (const id of b.summary_eval_ids ?? []) summaryIds.add(id)
+export function adaptEvalHierarchy(raw: EvalHierarchy): EvalHierarchy {
+  if (!raw) {
+    return { families: [] }
   }
-  return {
-    ...first,
-    slices: Array.from(sliceMap.values()),
-    metrics: Array.from(metricMap.values()),
-    summary_eval_ids: Array.from(summaryIds),
+  if (raw.schema_version && !raw.schema_version.startsWith("v3.hierarchy.")) {
+    console.warn(
+      `adaptEvalHierarchy: unexpected schema_version=${JSON.stringify(raw.schema_version)}; ` +
+        `expected v3.hierarchy.*. Frontend may render incompletely.`,
+    )
   }
+  return raw
 }
 
 export async function fetchComparisonIndex(): Promise<ComparisonIndex> {
@@ -1805,11 +1454,10 @@ function flattenHierarchyNode(
             ? `${context.benchmark_parent_name ?? context.benchmark} / ${metric.slice_name}`
             : context.canonical_display_name ?? context.benchmark),
         category,
-        benchmark_family_key: context.benchmark_family_key,
+        family_id: context.benchmark_family_key,
         benchmark_family_name: context.benchmark_family_name,
-        benchmark_parent_key: context.benchmark_parent_key,
+        parent_benchmark_id: context.benchmark_parent_key,
         benchmark_parent_name: context.benchmark_parent_name,
-        benchmark_leaf_key: metric.benchmark_leaf_key ?? context.benchmark_leaf_key,
         benchmark_leaf_name: metric.benchmark_leaf_name ?? context.benchmark_leaf_name,
         slice_key: sliceKey,
         slice_name: sliceName,

lib/model-data.ts

@@ -493,8 +493,8 @@ export function hfEvalEntryToListItem(entry: HFEvalListEntry): BenchmarkEvalList
     metrics_count: entry.metrics_count,
     metric_names: entry.metric_names,
     instance_data: entry.instance_data,
-    benchmark_family_key: entry.benchmark_family_key,
-    benchmark_leaf_key: entry.benchmark_leaf_key,
+    family_id: entry.benchmark_family_key,
+    parent_benchmark_id: entry.benchmark_parent_key,
     source_data: entry.source_data,
     top_score: entry.top_score,
     subtasks_count: entry.subtasks_count ?? 0,

lib/sidecars.ts

@@ -57,7 +57,28 @@ export function fetchHierarchy(): Promise<EvalHierarchy> {
 }
 
 export function fetchComparisonIndex(): Promise<ComparisonIndex> {
-  return (cache.comparisonIndex ??= fetchJson<ComparisonIndex>("comparison-index.json"))
+  return (cache.comparisonIndex ??= fetchJson<ComparisonIndex>("comparison-index.json").then(
+    (index) => {
+      assertComparisonIndexShape(index)
+      return index
+    },
+  ))
+}
+
+/**
+ * Fail fast on contract regressions. Comparison-index rows must carry
+ * `family_id`; the model-page graph view collapses without it. See
+ * `notes/hierarchy-alignment.md` §5.2.
+ */
+export function assertComparisonIndexShape(index: ComparisonIndex): void {
+  for (const [evalId, entry] of Object.entries(index.evals ?? {})) {
+    if (!Object.prototype.hasOwnProperty.call(entry, "family_id")) {
+      throw new Error(
+        `comparison-index contract regression: evals[${evalId}] is missing family_id. ` +
+          `See notes/hierarchy-alignment.md §5.2.`,
+      )
+    }
+  }
 }
 
 export function resetSidecarCacheForTests() {

lib/view-data.ts

@@ -44,28 +44,23 @@ const MODEL_CARD_COLUMNS = `
 
 // The composite/family/slice taxonomy refactor (eval_card_backend
 // notes/09-) replaced the legacy `composite_benchmark_key` /
-// `composite_benchmark_name` / `benchmark_family_key` /
-// `benchmark_leaf_key` columns with `composite_slug` /
-// `composite_display_name` / `family_id` / `family_display_name` /
-// `is_slice`. We expose both names so existing consumers keep
-// reading without rewrites. Mapping:
+// `composite_benchmark_name` columns with `composite_slug` /
+// `composite_display_name`. The `family_id` / `family_display_name` /
+// `is_slice` columns are the canonical identity surface; we still
+// alias the composite_* legacy names for backward compat with
+// consumers that haven't migrated yet. Mapping:
 //   composite_benchmark_key/name → composite_slug/display_name
 //     (the leaderboard, e.g. "wasp"/"WASP" — what the eval-detail
 //     "Composite" label shows)
-//   benchmark_family_key/name    → family_id/family_display_name
-//     (curated multi-benchmark family, e.g. "judgebench"/"JudgeBench
-//     family" — drives the family-table grouping in the legacy
-//     hierarchy adapter)
 const EVAL_LIST_COLUMNS = `
   evaluation_id, evaluation_name, canonical_display_name,
   benchmark_id,
   composite_slug, composite_display_name,
   family_id, family_display_name, is_slice,
+  parent_benchmark_id,
   composite_slug AS composite_benchmark_key,
   composite_display_name AS composite_benchmark_name,
-  family_id AS benchmark_family_key,
   family_display_name AS benchmark_family_name,
-  CASE WHEN is_slice THEN benchmark_id ELSE NULL END AS benchmark_leaf_key,
   category,
   metric_config, models_count, evaluator_names, source_types,
   latest_source_name, third_party_ratio,
@@ -89,11 +84,10 @@ const CELL_JOIN_COLUMNS = `
   e.family_id AS eval_family_id,
   e.family_display_name AS eval_family_display_name,
   e.is_slice AS eval_is_slice,
+  e.parent_benchmark_id AS eval_parent_benchmark_id,
   e.composite_slug AS eval_composite_benchmark_key,
   e.composite_display_name AS eval_composite_benchmark_name,
-  e.family_id AS eval_benchmark_family_key,
   e.family_display_name AS eval_benchmark_family_name,
-  CASE WHEN e.is_slice THEN e.benchmark_id ELSE NULL END AS eval_benchmark_leaf_key,
   e.category AS eval_category,
   e.metric_config AS eval_metric_config,
   e.source_data AS eval_source_data,
@@ -350,12 +344,12 @@ function reshapeCellToBenchmarkEvaluation(row: Row): BenchmarkEvaluation {
     display_name: optionalString(row.eval_evaluation_name),
     canonical_display_name: optionalString(row.eval_canonical_display_name),
     category: normalizeCategory(row.eval_category ?? row.category),
-    benchmark_family_key: optionalString(row.eval_benchmark_family_key),
-    benchmark_family_name: optionalString(row.eval_composite_benchmark_name),
-    benchmark_parent_key: optionalString(row.eval_composite_benchmark_key),
+    family_id: optionalString(row.eval_family_id),
+    benchmark_family_name: optionalString(row.eval_family_display_name),
+    parent_benchmark_id: optionalString(row.eval_parent_benchmark_id),
     benchmark_parent_name: optionalString(row.eval_composite_benchmark_name),
-    benchmark_leaf_key: optionalString(row.eval_benchmark_leaf_key),
     benchmark_leaf_name: optionalString(row.eval_evaluation_name),
+    is_slice: Boolean(row.eval_is_slice),
     is_summary_score: Boolean(row.eval_is_summary_score ?? row.is_summary_score),
     source_data: sourceDataFromRow(row),
     source_metadata: sourceMetadataFromRow(row),

tests/adapters.test.ts

@@ -55,7 +55,7 @@ describe("flattenModelEvaluations", () => {
       const evaluations = flattenModelEvaluations(input)
       // Snapshot a digest rather than the full output (which can be 10k+ lines
       // for large models). The digest captures: count, distinct categories,
-      // distinct evaluator_relationships, count of distinct benchmark_family_keys,
+      // distinct evaluator_relationships, count of distinct family_ids,
       // count of unique evaluation_ids, and a hash of the full output. Any change
       // to the full output changes the hash; the structured fields make the diff
       // readable when something changes.
@@ -92,7 +92,7 @@ function digestEvaluations(evaluations: BenchmarkEvaluation[]) {
   let missingSourceMetadata = 0
   for (const e of evaluations) {
     if (e.category) categories.add(e.category)
-    if (e.benchmark_family_key) families.add(e.benchmark_family_key)
+    if (e.family_id) families.add(e.family_id)
     if (e.source_metadata?.evaluator_relationship) evaluators.add(e.source_metadata.evaluator_relationship)
     if (e.evaluation_id) evaluationIds.add(e.evaluation_id)
     if (!e.source_metadata) missingSourceMetadata += 1
@@ -101,7 +101,7 @@ function digestEvaluations(evaluations: BenchmarkEvaluation[]) {
     count: evaluations.length,
     distinct_evaluation_ids: evaluationIds.size,
     distinct_categories: [...categories].sort(),
-    distinct_benchmark_family_keys: families.size,
+    distinct_family_ids: families.size,
     distinct_evaluator_relationships: [...evaluators].sort(),
     missing_source_metadata: missingSourceMetadata,
     full_output_hash: stableHash(evaluations),

tests/comparison-index-loader.test.ts

@@ -0,0 +1,115 @@
+import { mkdir, mkdtemp, rm, writeFile } from "fs/promises"
+import os from "os"
+import path from "path"
+
+import { describe, expect, it } from "vitest"
+
+import type { ComparisonIndex } from "../lib/backend-artifacts"
+import { assertComparisonIndexShape } from "../lib/sidecars"
+
+// Shared fixture: a comparison-index that mirrors the post-migration
+// shape from notes/hierarchy-alignment.md §5.2. Tests mutate copies of
+// this to exercise contract assertions.
+const validFixture: ComparisonIndex = {
+  generated_at: "2026-05-04T00:00:00Z",
+  config_version: 2,
+  metric_group_order: ["capability", "robustness", "efficiency", "cost", "latency", "rank", "other"],
+  evals: {
+    "helm-classic%2Fmmlu": {
+      eval_summary_id: "helm-classic%2Fmmlu",
+      benchmark_id: "mmlu",
+      family_id: "helm",
+      family_display_name: "HELM",
+      composite_slug: "helm-classic",
+      composite_display_name: "HELM Classic",
+      parent_benchmark_id: null,
+      display_name: "MMLU",
+      category: "Knowledge",
+      is_slice: false,
+      is_summary_score: false,
+      summary_score_for: null,
+      summary_eval_ids: [],
+      metrics: [],
+    },
+    "helm-classic%2Fmmlu%2Fanatomy": {
+      eval_summary_id: "helm-classic%2Fmmlu%2Fanatomy",
+      benchmark_id: "mmlu",
+      family_id: "helm",
+      family_display_name: "HELM",
+      composite_slug: "helm-classic",
+      composite_display_name: "HELM Classic",
+      parent_benchmark_id: "mmlu",
+      display_name: "MMLU Anatomy",
+      category: "Knowledge",
+      is_slice: true,
+      is_summary_score: false,
+      summary_score_for: null,
+      summary_eval_ids: [],
+      metrics: [],
+    },
+  },
+  by_model: {},
+}
+
+describe("assertComparisonIndexShape", () => {
+  it("accepts entries with family_id present", () => {
+    expect(() => assertComparisonIndexShape(validFixture)).not.toThrow()
+  })
+
+  it("accepts the new parent_benchmark_id field on slice entries", () => {
+    const sliceEntry = validFixture.evals["helm-classic%2Fmmlu%2Fanatomy"]
+    expect(sliceEntry.parent_benchmark_id).toBe("mmlu")
+    expect(sliceEntry.is_slice).toBe(true)
+  })
+
+  it("rejects entries that are missing family_id", () => {
+    const broken = JSON.parse(JSON.stringify(validFixture)) as ComparisonIndex
+    delete (broken.evals["helm-classic%2Fmmlu"] as unknown as Record<string, unknown>).family_id
+
+    expect(() => assertComparisonIndexShape(broken)).toThrow(
+      /missing family_id/,
+    )
+  })
+})
+
+describe("fetchComparisonIndex (v2 sidecar)", () => {
+  it("validates the loaded sidecar against the contract", async () => {
+    const snapshotDir = await mkdtemp(path.join(os.tmpdir(), "eval-card-cmp-"))
+    const previousBackend = process.env.DATA_BACKEND
+    const previousSnapshotUrl = process.env.SNAPSHOT_URL
+
+    try {
+      await mkdir(snapshotDir, { recursive: true })
+      const broken = JSON.parse(JSON.stringify(validFixture)) as ComparisonIndex
+      delete (broken.evals["helm-classic%2Fmmlu"] as unknown as Record<string, unknown>).family_id
+      await writeFile(
+        path.join(snapshotDir, "comparison-index.json"),
+        JSON.stringify(broken),
+      )
+
+      process.env.DATA_BACKEND = "v2"
+      process.env.SNAPSHOT_URL = `file://${snapshotDir}`
+
+      const sidecars = await import("../lib/sidecars")
+      sidecars.resetSidecarCacheForTests()
+
+      await expect(sidecars.fetchComparisonIndex()).rejects.toThrow(
+        /missing family_id/,
+      )
+    } finally {
+      const sidecars = await import("../lib/sidecars")
+      sidecars.resetSidecarCacheForTests()
+      if (previousBackend == null) {
+        delete process.env.DATA_BACKEND
+      } else {
+        process.env.DATA_BACKEND = previousBackend
+      }
+      if (previousSnapshotUrl == null) {
+        delete process.env.SNAPSHOT_URL
+      } else {
+        process.env.SNAPSHOT_URL = previousSnapshotUrl
+      }
+      await rm(snapshotDir, { recursive: true, force: true })
+    }
+  })
+})

tests/eval-hierarchy-adapter.test.ts

@@ -1,11 +1,19 @@
-import { describe, expect, it } from "vitest"
+import { describe, expect, it, vi } from "vitest"
 
 import type { EvalHierarchy } from "../lib/backend-artifacts"
 import { adaptEvalHierarchy } from "../lib/hf-data"
 
-describe("adaptEvalHierarchy", () => {
-  it("keeps GPQA-Diamond as a benchmark sibling in the curated GPQA family", () => {
-    const raw = {
+// adaptEvalHierarchy is a passthrough validator post-Step-4 — the
+// producer's write_hierarchy() emits the v3 family-rooted tree
+// directly (notes/hierarchy-alignment.md §5.1), so the adapter no
+// longer synthesises legacy shapes. These tests confirm the
+// passthrough preserves data and that the schema_version warning
+// fires for unknown versions.
+
+describe("adaptEvalHierarchy (passthrough)", () => {
+  it("returns the v3 hierarchy unchanged", () => {
+    const raw: EvalHierarchy = {
+      schema_version: "v3.hierarchy.1",
       stats: {
         family_count: 1,
         composite_count: 1,
@@ -18,22 +26,19 @@ describe("adaptEvalHierarchy", () => {
         {
           key: "gpqa",
           display_name: "GPQA family",
-          member_benchmark_keys: ["gpqa", "gpqa-diamond"],
-        },
-      ],
-      composites: [
-        {
-          key: "wasp",
-          display_name: "WASP",
-          category: "Reasoning",
+          category: "knowledge",
           tags: { domains: ["reasoning"], languages: [], tasks: ["qa"] },
+          evals_count: 4,
+          eval_summary_ids: ["wasp%2Fgpqa", "wasp%2Fgpqa-diamond"],
           benchmarks: [
             {
               key: "gpqa",
               display_name: "GPQA",
-              has_card: false,
               family_id: "gpqa",
               is_slice: false,
+              is_overall: true,
+              is_primary: true,
+              has_card: false,
               tags: { domains: ["reasoning"], languages: [], tasks: ["qa"] },
               metrics: [{ key: "accuracy", display_name: "Accuracy" }],
               slices: [],
@@ -42,9 +47,11 @@ describe("adaptEvalHierarchy", () => {
             {
               key: "gpqa-diamond",
               display_name: "GPQA Diamond",
-              has_card: false,
               family_id: "gpqa",
               is_slice: false,
+              is_overall: false,
+              is_primary: false,
+              has_card: false,
               tags: { domains: ["reasoning"], languages: [], tasks: ["qa"] },
               metrics: [{ key: "accuracy", display_name: "Accuracy" }],
               slices: [],
@@ -53,22 +60,44 @@ describe("adaptEvalHierarchy", () => {
           ],
         },
       ],
-    } as unknown as EvalHierarchy
+    }
 
     const adapted = adaptEvalHierarchy(raw)
-    const gpqa = adapted.families.find((family) => family.key === "gpqa")
 
-    expect(gpqa).toBeDefined()
-    expect(gpqa?.standalone_benchmarks).toEqual([])
-    expect(gpqa?.composites).toHaveLength(1)
-    expect(gpqa?.composites?.[0].benchmarks.map((benchmark) => benchmark.key)).toEqual([
+    expect(adapted).toBe(raw) // passthrough: same reference
+    expect(adapted.families).toHaveLength(1)
+    expect(adapted.families[0].benchmarks).toHaveLength(2)
+    expect(adapted.families[0].benchmarks?.map((b) => b.key)).toEqual([
       "gpqa",
       "gpqa-diamond",
     ])
-    expect(
-      gpqa?.composites?.[0].benchmarks.flatMap((benchmark) =>
-        benchmark.slices.map((slice) => slice.key),
-      ),
-    ).not.toContain("gpqa-diamond")
+  })
+
+  it("returns a safe empty shape on null/undefined input", () => {
+    expect(adaptEvalHierarchy(null as unknown as EvalHierarchy)).toEqual({
+      families: [],
+    })
+  })
+
+  it("warns on unknown schema_version but still passes through", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    const raw: EvalHierarchy = {
+      schema_version: "v2.hierarchy.999",
+      families: [],
+    }
+    const adapted = adaptEvalHierarchy(raw)
+    expect(adapted).toBe(raw)
+    expect(warn).toHaveBeenCalledOnce()
+    warn.mockRestore()
+  })
+
+  it("does not warn when schema_version matches v3.hierarchy.*", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    adaptEvalHierarchy({
+      schema_version: "v3.hierarchy.1",
+      families: [],
+    })
+    expect(warn).not.toHaveBeenCalled()
+    warn.mockRestore()
   })
 })

tests/view-data.test.ts

@@ -109,8 +109,12 @@ async function writeSyntheticStageJSnapshot(snapshotDir: string) {
         'MMLU' AS canonical_display_name,
         'mmlu' AS composite_benchmark_key,
         'MMLU' AS composite_benchmark_name,
-        'mmlu' AS benchmark_family_key,
-        'mmlu' AS benchmark_leaf_key,
+        'mmlu' AS composite_slug,
+        'MMLU' AS composite_display_name,
+        'mmlu' AS family_id,
+        'MMLU' AS family_display_name,
+        false AS is_slice,
+        NULL AS parent_benchmark_id,
         'Reasoning' AS category,
         struct_pack(
           evaluation_description := 'Accuracy on MMLU',