Add self-describing evidence exports

README.md

@@ -104,7 +104,7 @@ Candidate comparisons to run:
 
 For model comparisons, choose the candidate model before **Load models**, run **Run benchmark suite**, add at least three real microphone rows with **Run 3 real-mic series**, then click **Unload models** and choose the next candidate. The benchmark table is preserved across unloads, so **Copy JSON** can export the summary and all rows after the comparison set. For TTS voice/step comparisons, change the voice or step slider after loading and rerun **Run TTS benchmark** plus the text/loopback benchmarks; those values are captured per row.
 
-Use **Download JSON** after benchmark or real-mic runs on the hosted Space to save a timestamped evidence file with the same payload as **Copy JSON** and `window.browserSpeakBench.exportResults()`. The export includes `generatedAt`, `hostMetadata` with the hosted Space commit when the static host exposes it, the current `runtime`, an `evidence` summary for real-mic/hardware-WebGPU/hosted-build readiness, aggregate `summary`, and raw `results`. The **Run evidence capture** button starts a timestamped `browser-speak-evidence-*.json` download when the capture sequence finishes; if the browser blocks the automatic download, **Download JSON** saves the same payload manually. Benchmark rows are also autosaved in browser storage for the current host and Space commit, so a reload during manual evidence capture can restore rows from the same deployed build; **Clear** removes both the visible rows and the saved copy.
+Use **Download JSON** after benchmark or real-mic runs on the hosted Space to save a timestamped evidence file with the same payload as **Copy JSON** and `window.browserSpeakBench.exportResults()`. The export includes `schemaVersion`, a unique `exportId`, `generatedAt`, `hostMetadata` with the hosted Space commit when the static host exposes it, the current `runtime`, an `evidence` summary for real-mic/hardware-WebGPU/hosted-build readiness, an embedded `evidenceGuide` with the audit command and row requirements, aggregate `summary`, and raw `results`. The **Run evidence capture** button starts a timestamped `browser-speak-evidence-*.json` download when the capture sequence finishes; if the browser blocks the automatic download, **Download JSON** saves the same payload manually. Benchmark rows are also autosaved in browser storage for the current host and Space commit, so a reload during manual evidence capture can restore rows from the same deployed build; **Clear** removes both the visible rows and the saved copy.
 
 Use `node tools/audit-browser-evidence.mjs path/to/browser-speak-benchmarks.json` to audit a JSON file downloaded from the hosted browser UI. This checks that the export came from the static Space revision, reports the page-generated `evidence` summary, verifies that at least three real-mic rows meet the WER/identity/latency gates from raw rows, and verifies that at least one completed row reports hardware WebGPU rather than a software adapter. Browser-downloaded JSON cannot prove no-server network behavior or Chrome launch flags by itself, so pair it with `node tools/run-hosted-smoke.mjs` for network evidence or `node tools/run-real-mic-series.mjs` for harness-collected real-mic provenance.
 

app.js

@@ -133,6 +133,7 @@ const DEFAULT_LOOPBACK_PREROLL_MS = 180;
 const DEFAULT_LOOPBACK_PROMPT = "Identify this browser demo.";
 const REAL_MIC_TARGET_RUNS = 3;
 const REAL_MIC_MAX_WER = 0.25;
+const BENCHMARK_EXPORT_SCHEMA_VERSION = "browser-speak-benchmarks/v2";
 const BENCHMARK_STORAGE_KEY = "browser-speak:benchmark-results:v1";
 const BENCHMARK_STORAGE_VERSION = 1;
 const BENCHMARK_STORAGE_MAX_ROWS = 80;
@@ -1869,16 +1870,86 @@ function exportBenchmarkSummary() {
 }
 
 function benchmarkExportPayload() {
+  const generatedAt = new Date().toISOString();
+  const evidence = evidenceSummaryForRows(state.benchmarkResults);
   return {
-    generatedAt: new Date().toISOString(),
+    schemaVersion: BENCHMARK_EXPORT_SCHEMA_VERSION,
+    exportId: createExportId(),
+    generatedAt,
     hostMetadata: { ...state.hostMetadata },
     runtime: runtimeEnvironment(),
-    evidence: evidenceSummaryForRows(state.benchmarkResults),
+    evidence,
+    evidenceGuide: browserEvidenceGuide(evidence),
     summary: exportBenchmarkSummary(),
     results: [...state.benchmarkResults],
   };
 }
 
+function createExportId() {
+  const random = globalThis.crypto?.randomUUID?.();
+  return random ? `browser-speak-${random}` : `browser-speak-${Date.now().toString(36)}`;
+}
+
+function browserEvidenceGuide(evidence) {
+  return {
+    auditCommand: "node tools/audit-browser-evidence.mjs <downloaded-json>",
+    pairedNetworkCheck: "node tools/run-hosted-smoke.mjs",
+    requirements: {
+      hostedSpaceMetadata: {
+        hostSuffix: ".hf.space",
+        commitHeader: "x-repo-commit",
+      },
+      realMic: {
+        prompt: APP_IDENTITY_PROMPT,
+        requiredRows: REAL_MIC_TARGET_RUNS,
+        maxMedianWer: REAL_MIC_MAX_WER,
+        requiredSignals: [
+          "completed mic rows",
+          "mic input stats",
+          "identity answer pass",
+          "finite speech-end-to-first-audio latency",
+        ],
+      },
+      hardwareWebgpu: {
+        requiredRows: 1,
+        requiredSignals: [
+          "row stack device is webgpu",
+          "browser reports WebGPU available",
+          "adapter is not classified as software",
+        ],
+      },
+    },
+    current: {
+      realMicPassed: evidence.realMic.passed,
+      realMicRows: evidence.realMic.rows,
+      hardwareWebgpuPassed: evidence.hardwareWebgpu.passed,
+      hardwareWebgpuRows: evidence.hardwareWebgpu.hardwareRows,
+      hostedPassed: evidence.hosted.passed,
+    },
+    nextActions: browserEvidenceNextActions(evidence),
+    limitations: [
+      "Downloaded browser JSON proves page-reported rows and adapter metadata.",
+      "Pair with hosted smoke for no-server network evidence.",
+      "Use the real-mic harness for Chrome launch provenance when fake-capture flags must be ruled out.",
+    ],
+  };
+}
+
+function browserEvidenceNextActions(evidence) {
+  const actions = [];
+  if (!evidence.hosted.passed) {
+    actions.push("Run and download evidence from the hosted static HF Space.");
+  }
+  if (!evidence.realMic.passed) {
+    actions.push(`Run evidence capture or Run 3 real-mic series, saying "${APP_IDENTITY_PROMPT}" each time.`);
+  }
+  if (!evidence.hardwareWebgpu.passed) {
+    actions.push("Run evidence capture in a browser exposing a hardware WebGPU adapter.");
+  }
+  if (actions.length === 0) actions.push("Audit this JSON with tools/audit-browser-evidence.mjs.");
+  return actions;
+}
+
 function downloadBenchmarkJson({
   prefix = "browser-speak-benchmarks",
   message = "Benchmark JSON download started.",