Add an opt-in frontend preflight check suite

Pre-deploy correctness checks that go beyond "the page loads": they verify
folded ids resolve, redirects point the right way, encoded developer pages load,
and comparison charts render real peer data — all against a warehouse snapshot.

- tests/redirect-integrity.test.ts (vitest, server-free): redirect-map and
resolver fallback invariants. Self-skips unless SNAPSHOT_URL is set, so it
never runs in the default `pnpm test`. Run with `pnpm test:integrity`.
- tests/e2e/ (@playwright /test): page rendering + chart content against the live
app, which it boots itself. Run with `pnpm test:e2e`.
- tests/PREFLIGHT.md: how to run, what each layer checks, the bug taxonomy, and
known limitations.

Nothing here gates the default test run or deploy — it's opt-in, matching the
existing scripts/verify-*.mjs convention. There is no CI today (this repo is an
HF Space; deploy is a git push that builds the Dockerfile).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitignore

@@ -53,3 +53,7 @@ public/peer-ranks.json
 # private working notes / design specs / migration plans — not for publishing
 notes/
 docs/INTERPRETIVE_SIGNALS.md
+
+# Playwright e2e output (tests/e2e via @playwright/test)
+test-results/
+playwright-report/

package.json

@@ -12,6 +12,8 @@
     "start": "next start",
     "test": "vitest",
     "test:drift": "RUN_DRIFT=1 vitest --run tests/upstream-drift.test.ts",
+    "test:integrity": "vitest --run tests/redirect-integrity.test.ts",
+    "test:e2e": "playwright test",
     "compare-data-backends": "node scripts/compare-data-backends.mjs",
     "refresh-fixtures": "node scripts/refresh-fixtures.mjs",
     "audit-adapters": "tsx scripts/audit-adapters.mjs"
@@ -72,10 +74,12 @@
     "zod": "3.25.67"
   },
   "devDependencies": {
+    "@playwright/test": "^1.60.0",
     "@tailwindcss/postcss": "^4.1.9",
     "@types/node": "^22",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "playwright": "^1.60.0",
     "postcss": "^8.5",
     "puppeteer-core": "^24.42.0",
     "tailwindcss": "^4.1.9",

playwright.config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from "@playwright/test"
+
+// Frontend preflight e2e (opt-in): `SNAPSHOT_URL=<warehouse> pnpm test:e2e`.
+// NOT part of `pnpm test` and nothing gates deploy — it's a correctness check you
+// run before shipping a meaningful frontend change. See tests/PREFLIGHT.md.
+//
+// The webServer block boots `pnpm dev` against the snapshot itself (and reuses an
+// already-running one), so there's no manual server dance. When SNAPSHOT_URL is
+// unset the spec self-skips.
+const SNAPSHOT_URL = process.env.SNAPSHOT_URL
+const PORT = Number(process.env.PORT || 3211)
+
+export default defineConfig({
+  testDir: "tests/e2e",
+  // Each test sweeps many pages; give them room (they parallelize internally).
+  timeout: 300_000,
+  fullyParallel: false,
+  workers: 1,
+  reporter: "list",
+  use: { baseURL: `http://localhost:${PORT}` },
+  webServer: SNAPSHOT_URL
+    ? {
+        command: `pnpm dev -p ${PORT}`,
+        url: `http://localhost:${PORT}`,
+        timeout: 120_000,
+        reuseExistingServer: true,
+        env: { DATA_BACKEND: "v2", SNAPSHOT_URL },
+      }
+    : undefined,
+})

pnpm-lock.yaml

@@ -115,7 +115,7 @@ importers:
         version: 8.5.1(react@19.1.1)
       geist:
         specifier: ^1.3.1
-        version: 1.4.2(next@15.2.8(react-dom@19.1.1(react@19.1.1))(react@19.1.1))
+        version: 1.4.2(next@15.2.8(@playwright/test@1.60.0)(react-dom@19.1.1(react@19.1.1))(react@19.1.1))
       input-otp:
         specifier: 1.4.1
         version: 1.4.1(react-dom@19.1.1(react@19.1.1))(react@19.1.1)
@@ -124,7 +124,7 @@ importers:
         version: 0.454.0(react@19.1.1)
       next:
         specifier: 15.2.8
-        version: 15.2.8(react-dom@19.1.1(react@19.1.1))(react@19.1.1)
+        version: 15.2.8(@playwright/test@1.60.0)(react-dom@19.1.1(react@19.1.1))(react@19.1.1)
       next-themes:
         specifier: latest
         version: 0.4.6(react-dom@19.1.1(react@19.1.1))(react@19.1.1)
@@ -168,6 +168,9 @@ importers:
         specifier: 3.25.67
         version: 3.25.67
     devDependencies:
+      '@playwright/test':
+        specifier: ^1.60.0
+        version: 1.60.0
       '@tailwindcss/postcss':
         specifier: ^4.1.9
         version: 4.1.12
@@ -180,6 +183,9 @@ importers:
       '@types/react-dom':
         specifier: ^19
         version: 19.1.7(@types/react@19.1.10)
+      playwright:
+        specifier: ^1.60.0
+        version: 1.60.0
       postcss:
         specifier: ^8.5
         version: 8.5.6
@@ -754,6 +760,11 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@playwright/test@1.60.0':
+    resolution: {integrity: sha512-O71yZIbAh/PxDMNGns37GHBIfrVkEVyn+AXyIa5dOTfb4/xNvRWV+Vv/NMbNCtODB/pO7vLlF2OTmMVLhmr7Ag==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   '@puppeteer/browsers@2.13.0':
     resolution: {integrity: sha512-46BZJYJjc/WwmKjsvDFykHtXrtomsCIrwYQPOP7VfMJoZY2bsDF9oROBABR3paDjDcmkUye1Pb1BqdcdiipaWA==}
     engines: {node: '>=18'}
@@ -2058,6 +2069,11 @@ packages:
   fraction.js@4.3.7:
     resolution: {integrity: sha512-ZsDfxO51wGAXREY55a7la9LScWpwv9RxIrYABrlvOFBlH/ShPnrtsXeuUIfXKKOVicNxQ+o8JTbJvjS4M89yew==}
 
+  fsevents@2.3.2:
+    resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
   fsevents@2.3.3:
     resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
     engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
@@ -2351,6 +2367,16 @@ packages:
   pkg-types@1.3.1:
     resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==}
 
+  playwright-core@1.60.0:
+    resolution: {integrity: sha512-9bW6zvX/m0lEbgTKJ6YppOKx8H3VOPBMOCFh2irXFOT4BbHgrx5hPjwJYLT40Lu+4qtD36qKc/Hn56StUW57IA==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  playwright@1.60.0:
+    resolution: {integrity: sha512-hheHdokM8cdqCb0lcE3s+zT4t4W+vvjpGxsZlDnikarzx8tSzMebh3UiFtgqwFwnTnjYQcsyMF8ei2mCO/tpeA==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   postcss-value-parser@4.2.0:
     resolution: {integrity: sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==}
 
@@ -3177,6 +3203,10 @@ snapshots:
   '@next/swc-win32-x64-msvc@15.2.5':
     optional: true
 
+  '@playwright/test@1.60.0':
+    dependencies:
+      playwright: 1.60.0
+
   '@puppeteer/browsers@2.13.0':
     dependencies:
       debug: 4.4.3
@@ -4495,12 +4525,15 @@ snapshots:
 
   fraction.js@4.3.7: {}
 
+  fsevents@2.3.2:
+    optional: true
+
   fsevents@2.3.3:
     optional: true
 
-  geist@1.4.2(next@15.2.8(react-dom@19.1.1(react@19.1.1))(react@19.1.1)):
+  geist@1.4.2(next@15.2.8(@playwright/test@1.60.0)(react-dom@19.1.1(react@19.1.1))(react@19.1.1)):
     dependencies:
-      next: 15.2.8(react-dom@19.1.1(react@19.1.1))(react@19.1.1)
+      next: 15.2.8(@playwright/test@1.60.0)(react-dom@19.1.1(react@19.1.1))(react@19.1.1)
 
   get-caller-file@2.0.5: {}
 
@@ -4664,7 +4697,7 @@ snapshots:
       react: 19.1.1
       react-dom: 19.1.1(react@19.1.1)
 
-  next@15.2.8(react-dom@19.1.1(react@19.1.1))(react@19.1.1):
+  next@15.2.8(@playwright/test@1.60.0)(react-dom@19.1.1(react@19.1.1))(react@19.1.1):
     dependencies:
       '@next/env': 15.2.8
       '@swc/counter': 0.1.3
@@ -4684,6 +4717,7 @@ snapshots:
       '@next/swc-linux-x64-musl': 15.2.5
       '@next/swc-win32-arm64-msvc': 15.2.5
       '@next/swc-win32-x64-msvc': 15.2.5
+      '@playwright/test': 1.60.0
       sharp: 0.33.5
     transitivePeerDependencies:
       - '@babel/core'
@@ -4747,6 +4781,14 @@ snapshots:
       mlly: 1.7.4
       pathe: 2.0.3
 
+  playwright-core@1.60.0: {}
+
+  playwright@1.60.0:
+    dependencies:
+      playwright-core: 1.60.0
+    optionalDependencies:
+      fsevents: 2.3.2
+
   postcss-value-parser@4.2.0: {}
 
   postcss@8.4.31:

tests/PREFLIGHT.md

@@ -0,0 +1,76 @@
+# Frontend preflight — correctness checks before a deploy
+
+Run these before pushing a meaningful frontend change to the HF Space. They are
+**opt-in and non-blocking** — nothing here gates `git push` or the default
+`pnpm test`; they're a correctness gate you choose to run.
+
+Guiding principle, learned the hard way: **"the page returns 200 / an SVG exists /
+no console error" ≠ correct.** A model page can render cleanly and still be wrong —
+a folded id 404s its data, a redirect points the wrong way, or a chart silently
+shows only the current model. These checks assert content, not just liveness.
+
+## How to run
+
+```bash
+export SNAPSHOT_URL="https://huggingface.co/datasets/evaleval/card_backend/resolve/main/warehouse/<id>"
+#   (or file:///abs/path/to/warehouse/<id>)
+
+# 1. Server-free data-contract checks (fast). Self-skips if SNAPSHOT_URL is unset.
+pnpm test:integrity        # tests/redirect-integrity.test.ts (vitest)
+
+# 2. Live-server page + chart-content checks (Playwright boots its own dev server).
+pnpm test:e2e              # tests/e2e/frontend-preflight.spec.ts
+```
+
+Both need `SNAPSHOT_URL`. `test:e2e` starts `pnpm dev` against it automatically
+(and reuses an already-running server on the port). Set `PORT` to override 3211.
+
+## What each layer asserts
+
+**`test:integrity` (vitest, server-free)** — against the warehouse snapshot:
+- redirect map has 0 self-redirects, 0 chains/loops, every target is an addressable route;
+- direction is folded→group (no addressable id is a redirect KEY — catches an inverted map);
+- every redirect key is a known folded `raw_model_id`;
+- no `raw_model_id` belongs to >1 group (the resolver's `LIMIT 1` fallback is unambiguous);
+- no `models_view` row has NULL `raw_model_ids`.
+
+**`test:e2e` (Playwright, live server)** — against the running app + `/api/comparison-index` ground truth:
+- model / eval / developer pages render with HTTP <400, no client error text, no console errors —
+  **including the regression sets**: folded model ids (from `raw_model_ids`) and percent-encoded
+  developer names (e.g. `Mistral AI`);
+- **100% of folded model ids resolve** (cheap status sweep — not a sample);
+- comparison charts render real **peer bars** — counted in the DOM via `data-model-bar` /
+  `data-bar-current`, NOT via `#n/m` badges (those come from the peer-*ranks* sidecar) or the
+  "No peer scores" string (which never fires on the silent single-bar failure). Catches the
+  "chart shows only the current model" bug. Also: 0 "Unknown Model" labels; the current model is
+  not rendered as its own peer.
+
+## The bug taxonomy these were built to catch
+
+1. Folded model ids 404 — lookup didn't match `raw_model_ids`.
+2. Inverted redirect map 301'd working group URLs to dead leaves.
+3. Percent-encoded developer names (`Mistral%20AI`) 404'd (decoded-vs-encoded mismatch).
+4. Comparison charts showed only the current model (peer lookup keyed on a non-matching id).
+5. Peer bars showed "Unknown Model" (label read a field that isn't on the score rows).
+
+The chart checks depend on the inert `data-model-bar` / `data-bar-current` attributes in
+`components/benchmark-detail.tsx` — keep them.
+
+## Known limitations (spot-check manually when touching the relevant code)
+
+- The chart check only inspects the DEFAULT-rendered metric tab; a break isolated to a
+  non-default tab isn't exercised.
+- Eval/benchmark detail pages get liveness-only checking — their leaderboard content isn't
+  asserted against the index the way model charts are.
+- Error-marker strings are hardcoded UI copy; update them here if the copy changes.
+- **Redirect preservation** (old/pre-rework URLs that used to redirect): not gated here. The
+  warehouse-derived map only covers ids the producer folds into `raw_model_ids`; old base→variant
+  spellings that aren't folded will 404. That's a stale-bookmark concern with an upstream
+  (registry alias) fix, not a frontend gate.
+
+## Enforcement
+
+There is no CI today (this repo is an HF Space — deploy is `git push`; HF builds the Dockerfile
+and does not run tests). So these are run by hand, by convention, like the `scripts/verify-*.mjs`
+family. If we add hosted CI later (e.g. mirror to GitHub), `test:integrity` is the cheap,
+server-free job to wire in first; `test:e2e` belongs in a separate, explicitly-owned job.

tests/e2e/frontend-preflight.spec.ts

@@ -0,0 +1,169 @@
+import { DuckDBConnection } from "@duckdb/node-api"
+import { expect, test, type Browser } from "@playwright/test"
+
+// Frontend correctness e2e — the layer naive "page returns 200" checks miss.
+// Opt-in via `SNAPSHOT_URL=<warehouse> pnpm test:e2e`; self-skips otherwise.
+// Verifies, against the live server + comparison-index ground truth:
+//  - model/eval/developer pages render (incl. folded-id + encoded-name regressions),
+//  - 100% of folded model ids resolve (the raw_model_ids fallback),
+//  - comparison charts render real PEER bars (not just the current model), 0 "Unknown Model".
+// Full bug taxonomy + known limitations: tests/PREFLIGHT.md.
+
+const BASE = `http://localhost:${process.env.PORT || 3211}`
+const SNAPSHOT = (process.env.SNAPSHOT_URL || "").replace(/\/+$/, "")
+const SAMPLE = 30
+const CHART_MODELS = 16
+
+test.describe.configure({ mode: "serial" })
+test.skip(!SNAPSHOT, "set SNAPSHOT_URL to run the frontend preflight e2e")
+
+const ERROR_MARKERS = [
+  "Model not found", "Failed to load model data", "Eval not found",
+  "Benchmark not found", "Failed to load", "Application error",
+  "Something went wrong", "This page could not be found",
+]
+
+const enc = (s: unknown) => encodeURIComponent(String(s))
+const norm = (s: unknown) => String(s || "").toLowerCase().replace(/[^a-z0-9]/g, "")
+const asArray = (j: any): any[] => Array.isArray(j) ? j
+  : (j && typeof j === "object" && ["models", "evals", "developers", "items", "rows", "cards", "data"].map((k) => j[k]).find(Array.isArray)) || []
+const sample = <T>(a: T[], n: number): T[] => a.length <= n ? a.slice() : Array.from({ length: n }, (_, i) => a[Math.floor(i * (a.length / n))])
+const listItems = (v: any): string[] => Array.isArray(v) ? v.map(String) : Array.isArray(v?.items) ? v.items.map(String) : []
+const getJson = async (p: string) => { const r = await fetch(`${BASE}${p}`); return r.ok ? r.json() : null }
+const getJsonT = async (p: string, ms = 90_000, tries = 2) => {
+  for (let i = 0; i < tries; i++) {
+    try { const r = await fetch(`${BASE}${p}`, { signal: AbortSignal.timeout(ms) }); if (r.ok) return r.json() } catch { /* retry */ }
+  }
+  return null
+}
+async function mapLimit<T, R>(items: T[], limit: number, fn: (x: T) => Promise<R>): Promise<R[]> {
+  const out = new Array<R>(items.length)
+  let i = 0
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (i < items.length) { const idx = i++; out[idx] = await fn(items[idx]) }
+  }))
+  return out
+}
+
+let models: any[] = []
+let evals: any[] = []
+let devs: any[] = []
+let folded: string[] = []
+let expectedPeersFor: (routeId: string) => string[]
+
+test.beforeAll(async () => {
+  models = asArray(await getJson("/api/model-cards-lite"))
+  evals = asArray(await getJson("/api/eval-list-lite"))
+  devs = asArray(await getJson("/api/developers"))
+  expect(models.length, "model-cards-lite empty").toBeGreaterThan(0)
+
+  // Comparison-index is the chart ground truth — unavailable must be a HARD fail,
+  // not a silent skip (else the whole chart layer disables itself).
+  const ci = await getJsonT("/api/comparison-index")
+  expect(ci?.by_model && ci?.evals, "comparison-index unavailable — chart check cannot run").toBeTruthy()
+  expectedPeersFor = (routeId: string) => {
+    const byModel = ci.by_model[routeId]
+    if (!byModel) return []
+    const peers = new Set<string>()
+    for (const evalId of Object.keys(byModel)) {
+      for (const metric of (ci.evals[evalId]?.metrics ?? [])) {
+        for (const s of metric.scores) {
+          if (s.model_route_id === routeId) continue
+          const n = norm(s.model_family_name || s.model_family_id)
+          if (n) peers.add(n)
+        }
+      }
+    }
+    return [...peers]
+  }
+
+  // Discover folded ids exhaustively from the warehouse (not a tiny stride).
+  const con = await DuckDBConnection.create()
+  await con.run("INSTALL httpfs; LOAD httpfs;")
+  const rows = (await con.runAndReadAll(
+    `SELECT model_id, raw_model_ids FROM read_parquet('${SNAPSHOT}/models_view.parquet') WHERE len(raw_model_ids) > 0`,
+  )).getRowObjects()
+  const set = new Set<string>()
+  for (const r of rows) for (const raw of listItems(r.raw_model_ids)) {
+    if (String(raw).toLowerCase() !== String(r.model_id).toLowerCase()) set.add(String(raw))
+  }
+  folded = [...set]
+  expect(folded.length, "folded-id regression set empty — discovery/data path changed").toBeGreaterThan(0)
+})
+
+test("100% of folded model ids resolve (raw_model_ids fallback)", async () => {
+  const statuses = await mapLimit(folded, 12, async (raw) => {
+    const r = await fetch(`${BASE}/api/model-summary?id=${enc(raw)}`, { signal: AbortSignal.timeout(30_000) }).catch(() => null)
+    return { raw, status: r ? r.status : 0 }
+  })
+  const bad = statuses.filter((s) => s.status !== 200).map((s) => s.raw)
+  expect(bad, `${bad.length}/${folded.length} folded ids do not resolve: ${bad.slice(0, 8)}`).toEqual([])
+})
+
+test("model / eval / developer pages render (incl. regression sets)", async ({ browser }) => {
+  const seen = new Set<string>()
+  const targets: { cls: string; url: string }[] = []
+  const add = (cls: string, url: string) => { if (url && !seen.has(url)) { seen.add(url); targets.push({ cls, url }) } }
+
+  for (const m of sample(models, SAMPLE)) add("model", `/models/${enc(m.model_id || m.id || m.model_key)}`)
+  for (const raw of sample(folded, 25)) add("model(folded)", `/models/${enc(raw)}`)
+  for (const e of sample(evals, SAMPLE)) { const id = e.evaluation_id || e.id || e.benchmark_id; if (id) add("eval", `/evals/${String(id).replace(/%2F/g, "/")}`) }
+  const devUrl = (rid: string) => `/developers/${String(rid).replace(/%2F/g, "/")}`
+  const encodedDevs = devs.filter((d) => /[^A-Za-z0-9._/-]/.test(String(d.developer || "")) || /%(?!2F)/i.test(String(d.route_id || "")))
+  expect(encodedDevs.length, "encoded-developer regression set empty — data path changed").toBeGreaterThan(0)
+  for (const d of encodedDevs) if (d.route_id) add("developer(encoded)", devUrl(d.route_id))
+  for (const d of sample(devs, 20)) if (d.route_id) add("developer", devUrl(d.route_id))
+
+  const results = await mapLimit(targets, 6, async (t) => {
+    const page = await browser.newPage()
+    const errs: string[] = []
+    page.on("console", (m) => { if (m.type() === "error") errs.push(m.text().slice(0, 120)) })
+    page.on("pageerror", (e) => errs.push(String(e).slice(0, 120)))
+    let status = 0
+    try { const r = await page.goto(`${BASE}${t.url}`, { waitUntil: "networkidle", timeout: 45_000 }); status = r ? r.status() : 0; await page.waitForTimeout(700) }
+    catch (e) { errs.push(`goto: ${String(e).slice(0, 120)}`) }
+    const text = await page.evaluate(() => document.body?.innerText || "").catch(() => "")
+    const marker = ERROR_MARKERS.find((m) => text.includes(m))
+    await page.close()
+    return (!(status > 0 && status < 400) || marker || errs.length)
+      ? `${t.url} [${status}]${marker ? ` "${marker}"` : ""}${errs.length ? ` ${JSON.stringify(errs.slice(0, 2))}` : ""}`
+      : null
+  })
+  const broken = results.filter(Boolean) as string[]
+  expect(broken, `${broken.length} broken pages:\n  ${broken.slice(0, 15).join("\n  ")}`).toEqual([])
+})
+
+test("comparison charts render real peer bars (not only the current model)", async ({ browser }) => {
+  const candidates = sample(models, CHART_MODELS)
+    .map((m) => enc(m.model_id || m.id || m.model_key))
+    .filter((routeId) => expectedPeersFor(routeId).length > 0)
+  const per = await mapLimit(candidates, 6, async (routeId) => {
+    const expected = expectedPeersFor(routeId)
+    const page = await browser.newPage()
+    const problems: string[] = []
+    let bars: { id: string | null; cur: boolean }[] = []
+    try {
+      await page.goto(`${BASE}/models/${routeId}`, { waitUntil: "networkidle", timeout: 45_000 })
+      await page.waitForTimeout(1000)
+      const unknown = ((await page.evaluate(() => document.body?.innerText || "")).match(/Unknown Model/g) || []).length
+      bars = await page.$$eval("[data-model-bar]", (els) =>
+        els.map((e) => ({ id: e.getAttribute("data-model-bar"), cur: e.getAttribute("data-bar-current") === "1" })))
+      const peerBars = bars.filter((b) => !b.cur)
+      const currentBars = bars.length - peerBars.length
+      // MULTIPLE charts rendered but NONE show a peer bar => the only-current-model bug.
+      if (currentBars >= 2 && peerBars.length === 0) problems.push(`${routeId}: ${expected.length} peers in index but 0 peer bars`)
+      if (peerBars.some((b) => b.id === routeId)) problems.push(`${routeId}: current model rendered as its own peer (double-count)`)
+      if (unknown > 0) problems.push(`${routeId}: ${unknown} "Unknown Model" labels`)
+    } catch (e) { problems.push(`${routeId}: ${String(e).slice(0, 80)}`) }
+    await page.close()
+    return { bars: bars.length, problems }
+  })
+  const charted = candidates.length
+  const totalBars = per.reduce((n, r) => n + r.bars, 0)
+  const broken = per.flatMap((r) => r.problems)
+  expect(charted, "no sampled model had expected peers — chart check was vacuous").toBeGreaterThan(0)
+  // Suite-wide: peers expected but NO bars anywhere => the data-model-bar hook was
+  // dropped or charts don't render — the chart check silently disabled itself.
+  expect(totalBars, "0 chart bars across charted pages — data-model-bar hook missing or charts broken").toBeGreaterThan(0)
+  expect(broken, `chart problems:\n  ${broken.slice(0, 15).join("\n  ")}`).toEqual([])
+})

tests/redirect-integrity.test.ts

@@ -0,0 +1,93 @@
+import { readFileSync } from "fs"
+import { fileURLToPath } from "url"
+
+import { DuckDBConnection } from "@duckdb/node-api"
+import { beforeAll, describe, expect, it } from "vitest"
+
+// Server-FREE data-contract checks for the model URL redirect map + resolver
+// fallback invariants, asserted against a Stage-J warehouse snapshot. Opt-in via
+// `SNAPSHOT_URL=<warehouse> pnpm test:integrity` — self-skips in the default
+// `pnpm test` run (mirrors the RUN_DRIFT pattern in upstream-drift.test.ts) so it
+// never blocks a dev or a deploy. The server-BOUND checks (page rendering, chart
+// content, redirect-preservation) live in the Playwright e2e suite + PREFLIGHT.md.
+//
+// Why this exists: "the page returns 200" != "correct". The redirect map and the
+// raw_model_ids fallback have invariants that, if violated, silently break model
+// pages (folded ids 404, an inverted map 301s working URLs to dead leaves). See
+// tests/PREFLIGHT.md for the full bug taxonomy.
+
+const SNAPSHOT = (process.env.SNAPSHOT_URL || "").replace(/\/+$/, "")
+const shouldRun = !!SNAPSHOT
+const MAP_PATH = fileURLToPath(new URL("../lib/model-url-redirects.ts", import.meta.url))
+
+const dec = (s: string) => { try { return decodeURIComponent(s) } catch { return s } }
+const listItems = (v: unknown): string[] =>
+  Array.isArray(v) ? v.map(String)
+    : v && typeof v === "object" && Array.isArray((v as { items?: unknown[] }).items)
+      ? (v as { items: unknown[] }).items.map(String)
+      : []
+
+describe.skipIf(!shouldRun)("redirect-map + fallback integrity (vs SNAPSHOT_URL)", () => {
+  let map: [string, string][] = []
+  let keys: Set<string>
+  const addressable = new Set<string>() // decoded route forms that resolve to a page
+  const rawOwners = new Map<string, Set<string>>() // raw spelling -> owning group(s)
+  let nullRaw = 0
+  let rowCount = 0
+
+  beforeAll(async () => {
+    map = [...readFileSync(MAP_PATH, "utf8").matchAll(/\["([^"]+)",\s*"([^"]+)"\]/g)].map((m) => [m[1], m[2]])
+    keys = new Set(map.map(([k]) => k))
+    const con = await DuckDBConnection.create()
+    await con.run("INSTALL httpfs; LOAD httpfs;")
+    const rows = (await con.runAndReadAll(
+      `SELECT model_id, route_id, model_route_id, model_group_id, model_key, raw_model_ids
+       FROM read_parquet('${SNAPSHOT}/models_view.parquet')`,
+    )).getRowObjects()
+    rowCount = rows.length
+    for (const r of rows) {
+      for (const v of [r.model_id, r.model_route_id, r.route_id, r.model_group_id, r.model_key]) {
+        if (v) addressable.add(dec(String(v)))
+      }
+      if (r.raw_model_ids == null) nullRaw++
+      for (const raw of listItems(r.raw_model_ids)) {
+        const set = rawOwners.get(String(raw)) ?? rawOwners.set(String(raw), new Set()).get(String(raw))!
+        set.add(String(r.model_id))
+      }
+    }
+  }, 120_000)
+
+  it("redirect map has no self-redirects", () => {
+    expect(map.filter(([k, v]) => k === v)).toEqual([])
+  })
+
+  it("redirect map has no chains/loops (no target is also a key)", () => {
+    expect(map.filter(([, v]) => keys.has(v)).map(([, v]) => v)).toEqual([])
+  })
+
+  it("every redirect target is an addressable route", () => {
+    const dead = [...new Set(map.map(([, v]) => v))].filter((t) => !addressable.has(dec(t)))
+    expect(dead, `dead targets: ${dead.slice(0, 8)}`).toEqual([])
+  })
+
+  it("direction is folded->group (no addressable id is a redirect KEY)", () => {
+    // An addressable key means the map redirects a WORKING page away — the
+    // inverted-map bug.
+    const inverted = map.filter(([k]) => addressable.has(dec(k))).map(([k]) => k)
+    expect(inverted, `addressable ids used as redirect keys: ${inverted.slice(0, 8)}`).toEqual([])
+  })
+
+  it("every redirect key is a known folded raw_model_id", () => {
+    const orphan = map.filter(([k]) => !addressable.has(dec(k)) && !rawOwners.has(dec(k))).map(([k]) => k)
+    expect(orphan, `orphan keys (neither addressable nor a raw id): ${orphan.slice(0, 8)}`).toEqual([])
+  })
+
+  it("no raw_model_id belongs to >1 group (LIMIT 1 fallback is unambiguous)", () => {
+    const multi = [...rawOwners].filter(([, s]) => s.size > 1).map(([k]) => k)
+    expect(multi, `raw ids in >1 group: ${multi.slice(0, 8)}`).toEqual([])
+  })
+
+  it("no models_view row has NULL raw_model_ids (the fallback scans this column)", () => {
+    expect(nullRaw, `${nullRaw}/${rowCount} rows have NULL raw_model_ids`).toBe(0)
+  })
+})

vitest.config.ts

@@ -15,6 +15,8 @@ export default defineConfig({
     // self-skips otherwise. We DON'T exclude the path here because vitest's
     // exclude wins over an explicit path arg, which would silently make
     // `pnpm test:drift` find zero tests.
-    exclude: ["**/node_modules/**", "**/dist/**"],
+    // tests/e2e/ is the Playwright (@playwright/test) suite — a different runner.
+    // Excluded so `pnpm test` (vitest) doesn't try to collect its *.spec.ts.
+    exclude: ["**/node_modules/**", "**/dist/**", "**/tests/e2e/**"],
   },
 })