@applesnort/crosscheck 0.2.0

package/lenses/ux.md

@@ -0,0 +1,105 @@
+---
+name: ux
+summary: usability under interruption, error, and extreme states
+when: [**/*.{jsx,tsx,vue,svelte,html}, "**/components/**", "**/views/**", "**/pages/**"]
+owns: situations where a real, hurried user cannot complete or understand a task
+not-owns: assistive technology and WCAG criteria, correctness, architecture, security
+cites: ["Nielsen's ten usability heuristics"]
+---
+
+# Lens: ux — usability under real conditions
+
+You are a product designer using this software as an impatient, busy person who
+did not read any documentation, is interrupted mid-task, and does not care how the
+system works internally. You report where the interface fails that person.
+
+You are not the accessibility lens — assistive technology, contrast ratios, and
+WCAG criteria belong there. You are not a visual-taste critic; "I would style this
+differently" is not a finding.
+
+## Standards this lens cites
+
+- **Nielsen's ten usability heuristics** — cite the heuristic by name where one
+  applies (visibility of system status, match to the real world, user control and
+  freedom, consistency, error prevention, recognition over recall, flexibility,
+  minimalist design, error recovery, help).
+
+The heuristics are a reference frame, not a checklist to recite. A finding that
+maps to none of them still counts if you can describe the user failing.
+
+## What you check
+
+**System status**
+- After an action, does the interface say what happened? A mutation with no
+  confirmation leaves the user unsure whether to retry.
+- Is slow work distinguishable from broken work?
+- Is a disabled control's reason discoverable, or does the user have to guess what
+  unlocks it?
+
+**Destruction and reversibility**
+- Irreversible actions without confirmation, and confirmations so frequent they
+  get clicked through.
+- Destructive and routine actions adjacent enough to mis-tap.
+- Work that can be lost by navigating away, refreshing, or being interrupted.
+- Absence of undo where the action is reversible in principle.
+
+**Error prevention and recovery**
+- Validation that fires while typing, marking a half-entered value wrong.
+- Errors that state what is invalid without stating what would be valid.
+- Errors surfaced away from the field that caused them, or after the user has
+  moved on.
+- A failed submission that discards the entered data.
+
+**Interruption and re-entry**
+- Can a multi-step flow be left and resumed, or does leaving restart it?
+- Is progress through a long flow visible?
+- Does the interface remember what the user already told it, or ask again?
+
+**Recognition over recall**
+- Codes, identifiers, or internal vocabulary shown where a human-readable label
+  belongs.
+- A choice presented without the information needed to make it.
+- Domain terms used inconsistently between screens for the same thing.
+
+**Empty, first-run, and extreme states**
+- Empty state: does it explain what goes here and how to add it, or show a blank
+  panel?
+- Zero, one, and very many items — layouts that only work at the demo count.
+- Long values: names, addresses, and titles that overflow, clip, or truncate the
+  part that distinguishes them.
+- Are `0` and "not entered" visually distinct where the difference matters?
+
+**Density and effort**
+- Steps, clicks, or confirmations that do not earn their cost.
+- Frequent actions buried; rare actions given prime position.
+- Information needed together, split across screens.
+
+## Project specifics
+
+If the project documents interaction rules — a save pattern, a validation
+convention, a toast or empty-state standard, a design system — read them from the
+project's own conventions and enforce them as part of this lens. Deviation from a
+written house pattern is a finding; deviation from your taste is not.
+
+## Output
+
+Findings only. One per line, no preamble, no summary:
+
+```
+file:line — SEVERITY — [HEURISTIC] the user, the situation, what they cannot do — the fix
+```
+
+`SEVERITY` is one of:
+
+- `BLOCK` — the user loses work, cannot complete the task, or is misled about what
+  happened.
+- `FIX` — real friction or a state the interface handles badly.
+- `CONSIDER` — a refinement; say plainly that it is one.
+
+Every finding describes a **person in a situation**, not an abstraction. "Poor
+UX" is not a finding; "a user who mis-taps Delete on the row above loses the
+record with no undo" is.
+
+If nothing in scope is user-facing, return exactly `NO FINDINGS`.
+
+Do not edit any file. This lens reports.

package/lib/baseline.mjs

@@ -0,0 +1,78 @@
+/*!
+ * Copyright (c) 2026 Joel Mangin. MIT License.
+ */
+// Baseline support: the difference between a panel a team keeps running and one
+// they run once.
+//
+// The first run against an existing codebase returns hundreds of findings, and
+// the report gets closed. A baseline records what was already there, so later
+// runs report what the change introduced. Suppressed counts are always
+// returned — a baseline that hides its own size is a way to make a codebase
+// look clean by declaring its problems normal.
+
+import { fingerprint } from './sarif.mjs';
+
+export const BASELINE_VERSION = 1;
+
+export function toBaseline(findings, options = {}) {
+  const { note = null } = options;
+  const entries = (findings ?? []).map(f => ({
+    fingerprint: fingerprint(f),
+    file: f.file,
+    line: f.line,
+    severity: f.severity,
+    // Stored for human review of the baseline file, not used for matching.
+    issue: f.issue,
+    lenses: f.lenses
+  }));
+  entries.sort((a, b) =>
+    a.file.localeCompare(b.file) || a.line - b.line ||
+    a.fingerprint.localeCompare(b.fingerprint));
+  return {
+    version: BASELINE_VERSION,
+    note,
+    count: entries.length,
+    findings: entries
+  };
+}
+
+export function baselineFingerprints(baseline) {
+  if (!baseline) {
+    return new Set();
+  }
+  if (baseline.version !== BASELINE_VERSION) {
+    throw new Error(
+      `Unsupported baseline version ${baseline.version}; expected ` +
+      `${BASELINE_VERSION}. Regenerate the baseline rather than editing it.`);
+  }
+  return new Set((baseline.findings ?? []).map(f => f.fingerprint));
+}
+
+// Returns { findings, suppressed } — findings not present in the baseline, and
+// the ones that were. Both are returned so the caller can report the second
+// number instead of quietly dropping it.
+export function filterAgainstBaseline(findings, baseline) {
+  const known = baselineFingerprints(baseline);
+  if (known.size === 0) {
+    return { findings: findings ?? [], suppressed: [] };
+  }
+  const fresh = [];
+  const suppressed = [];
+  for (const finding of findings ?? []) {
+    if (known.has(fingerprint(finding))) {
+      suppressed.push(finding);
+    } else {
+      fresh.push(finding);
+    }
+  }
+  return { findings: fresh, suppressed };
+}
+
+// Entries in the baseline that no longer appear in a run. Worth surfacing:
+// either they were fixed and the baseline should shrink, or the lens that found
+// them stopped running and coverage silently dropped.
+export function staleBaselineEntries(baseline, findings) {
+  const current = new Set((findings ?? []).map(fingerprint));
+  return (baseline?.findings ?? [])
+    .filter(entry => !current.has(entry.fingerprint));
+}

package/lib/calibrate.mjs

@@ -0,0 +1,169 @@
+/*!
+ * Copyright (c) 2026 Joel Mangin. MIT License.
+ */
+// Score a panel run against planted ground truth.
+//
+// Without this, a persona panel is unfalsifiable: you cannot tell whether it
+// works, whether a new lens helped, or whether a prompt edit made it worse.
+// Given a fixture whose defects are known (fixtures/calibration/expected.json)
+// and the panel's own findings, this measures recall per lens, the false
+// positive rate, and — the claim worth checking — whether consensus findings are
+// actually more likely to be real than single-lens ones.
+//
+// This module scores an existing run. It does not run a panel and never
+// fabricates one: if you have no panel output, you have no score.
+
+import { normalizeSeverity } from './merge.mjs';
+
+// A lens may reasonably anchor a finding on the offending statement, the
+// enclosing function signature, or a line between them.
+export function matchesDefect(finding, defect) {
+  if (finding.file !== defect.file) {
+    return false;
+  }
+  const [lo, hi] = defect.span ?? [defect.line, defect.line];
+  return finding.line >= lo && finding.line <= hi;
+}
+
+export function findDefect(finding, defects) {
+  return (defects ?? []).find(d => matchesDefect(finding, d)) ?? null;
+}
+
+// A lens gets credit for a defect if it is the expected owner or listed in
+// alsoAcceptedBy. Reporting a real defect outside your remit is not scored as a
+// false positive — it is real — but it does not count toward the owner's recall.
+export function lensIsCredited(lens, defect) {
+  return defect.expectedBy === lens ||
+    (defect.alsoAcceptedBy ?? []).includes(lens);
+}
+
+// findings: merged findings ([{file, line, severity, lenses, consensus,
+//   consensusScore, issue}]). expected: the parsed expected.json.
+export function score(findings, expected) {
+  const defects = expected?.defects ?? [];
+  const list = findings ?? [];
+
+  const matchedByDefect = new Map();
+  const truePositives = [];
+  const falsePositives = [];
+
+  for (const finding of list) {
+    const defect = findDefect(finding, defects);
+    if (!defect) {
+      falsePositives.push(finding);
+      continue;
+    }
+    truePositives.push({ finding, defect });
+    if (!matchedByDefect.has(defect.id)) {
+      matchedByDefect.set(defect.id, []);
+    }
+    matchedByDefect.get(defect.id).push(finding);
+  }
+
+  const missed = defects.filter(d => !matchedByDefect.has(d.id));
+
+  // Per-lens recall against the defects that lens is credited for.
+  const lenses = [...new Set(list.flatMap(f => f.lenses ?? []))].sort();
+  const perLens = {};
+  for (const lens of lenses) {
+    const owned = defects.filter(d => lensIsCredited(lens, d));
+    const found = owned.filter(d =>
+      (matchedByDefect.get(d.id) ?? []).some(f => (f.lenses ?? []).includes(lens)));
+    const reported = list.filter(f => (f.lenses ?? []).includes(lens));
+    const spurious = reported.filter(f => !findDefect(f, defects));
+    perLens[lens] = {
+      owned: owned.length,
+      found: found.length,
+      recall: owned.length === 0 ? null : round(found.length / owned.length),
+      reported: reported.length,
+      falsePositives: spurious.length,
+      precision: reported.length === 0
+        ? null : round((reported.length - spurious.length) / reported.length)
+    };
+  }
+
+  // Severity agreement on the defects that were found.
+  const severityMismatches = truePositives
+    .filter(({ finding, defect }) =>
+      normalizeSeverity(finding.severity) !== normalizeSeverity(defect.severity))
+    .map(({ finding, defect }) => ({
+      id: defect.id,
+      expected: normalizeSeverity(defect.severity),
+      reported: normalizeSeverity(finding.severity)
+    }));
+
+  // The load-bearing claim: is a finding several independent lenses agreed on
+  // more likely to be real? If these two precisions come out equal, consensus
+  // ranking is decoration.
+  const consensusFindings = list.filter(f => f.consensus === true);
+  const soloFindings = list.filter(f => f.consensus !== true);
+
+  return {
+    defects: defects.length,
+    found: matchedByDefect.size,
+    recall: defects.length === 0
+      ? null : round(matchedByDefect.size / defects.length),
+    missed: missed.map(d => ({ id: d.id, expectedBy: d.expectedBy })),
+    reported: list.length,
+    falsePositives: falsePositives.length,
+    precision: list.length === 0
+      ? null : round(truePositives.length / list.length),
+    severityMismatches,
+    consensusPrecision: precisionOf(consensusFindings, defects),
+    soloPrecision: precisionOf(soloFindings, defects),
+    consensusCount: consensusFindings.length,
+    soloCount: soloFindings.length,
+    perLens
+  };
+}
+
+function precisionOf(findings, defects) {
+  if (findings.length === 0) {
+    return null;
+  }
+  const real = findings.filter(f => findDefect(f, defects)).length;
+  return round(real / findings.length);
+}
+
+function round(n) {
+  return Number(n.toFixed(4));
+}
+
+export function formatScore(result) {
+  const pct = v => v == null ? 'n/a' : `${(v * 100).toFixed(1)}%`;
+  const lines = [
+    `defects planted:   ${result.defects}`,
+    `defects found:     ${result.found}  (recall ${pct(result.recall)})`,
+    `findings reported: ${result.reported}  (precision ${pct(result.precision)})`,
+    `false positives:   ${result.falsePositives}`,
+    ''
+  ];
+  if (result.missed.length) {
+    lines.push('missed:');
+    for (const m of result.missed) {
+      lines.push(`  - ${m.id} (expected from ${m.expectedBy})`);
+    }
+    lines.push('');
+  }
+  if (result.severityMismatches.length) {
+    lines.push('severity mismatches:');
+    for (const s of result.severityMismatches) {
+      lines.push(`  - ${s.id}: expected ${s.expected}, reported ${s.reported}`);
+    }
+    lines.push('');
+  }
+  lines.push(
+    'consensus vs solo precision — if these are equal, consensus ranking is',
+    'decoration and should be dropped or reweighted:',
+    `  consensus (${result.consensusCount}): ${pct(result.consensusPrecision)}`,
+    `  solo      (${result.soloCount}): ${pct(result.soloPrecision)}`,
+    '',
+    'per lens:');
+  for (const [lens, s] of Object.entries(result.perLens)) {
+    lines.push(
+      `  ${lens.padEnd(16)} recall ${pct(s.recall).padStart(6)} ` +
+      `(${s.found}/${s.owned})   precision ${pct(s.precision).padStart(6)} ` +
+      `(${s.falsePositives} fp of ${s.reported})`);
+  }
+  return lines.join('\n');
+}

package/lib/corpus.mjs

@@ -0,0 +1,340 @@
+/*!
+ * Copyright (c) 2026 Joel Mangin. MIT License.
+ */
+// Adapter for externally authored defect corpora, and file-level scoring.
+//
+// The built-in fixture scores by line span, which works when you planted the
+// defects and know where they are. External corpora label a whole test case
+// instead, and — the reason they matter — they label cases where the code looks
+// vulnerable and is not. Those are the false-positive opportunities a
+// self-authored fixture cannot honestly provide, because the same hand wrote the
+// decoys, the answer key, and the lens prompts.
+//
+// Nothing here vendors a corpus. It reads one that has been fetched locally.
+
+// OWASP Benchmark categories mapped to the CWE they carry and the vocabulary a
+// finding would use. A finding counts as matching a case only if it cites the
+// CWE number or this vocabulary — a lens reporting some unrelated real issue in
+// a safe case is neither credited nor penalised.
+export const OWASP_CATEGORIES = {
+  sqli: { cwe: 89, terms: ['sql injection', 'sqli', 'sql statement', 'prepared statement', 'parameteriz', 'query concatenat'] },
+  weakrand: { cwe: 330, terms: ['weak random', 'insecure random', 'predictable', 'java.util.random', 'securerandom', 'insufficient entropy'] },
+  xss: { cwe: 79, terms: ['cross-site scripting', 'xss', 'html escap', 'output encod', 'unescaped'] },
+  pathtraver: { cwe: 22, terms: ['path traversal', 'directory traversal', 'file path', 'canonicaliz', '../'] },
+  cmdi: { cwe: 78, terms: ['command injection', 'cmdi', 'os command', 'runtime.exec', 'processbuilder', 'shell'] },
+  crypto: { cwe: 327, terms: ['weak cipher', 'broken cipher', 'insecure crypto', 'des', 'ecb', 'weak encryption', 'broken crypto'] },
+  hash: { cwe: 328, terms: ['weak hash', 'broken hash', 'md5', 'sha1', 'sha-1', 'insecure hash'] },
+  trustbound: { cwe: 501, terms: ['trust boundary', 'session attribute', 'untrusted data stored', 'trust violation'] },
+  securecookie: { cwe: 614, terms: ['secure flag', 'secure cookie', 'cookie without secure', 'httponly', 'insecure cookie'] },
+  ldapi: { cwe: 90, terms: ['ldap injection', 'ldapi', 'ldap filter', 'ldap query'] },
+  xpathi: { cwe: 643, terms: ['xpath injection', 'xpathi', 'xpath expression', 'xpath query'] }
+};
+
+// `# comment` header, then: testname,category,realVulnerability,cwe
+export function parseExpectedResults(csv) {
+  const cases = [];
+  for (const line of String(csv ?? '').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+    const [name, category, real, cwe] = trimmed.split(',').map(f => f.trim());
+    if (!name || !category || !real) {
+      continue;
+    }
+    if (real !== 'true' && real !== 'false') {
+      throw new Error(
+        `unexpected label "${real}" for ${name}; expected true or false`);
+    }
+    cases.push({
+      name,
+      category,
+      vulnerable: real === 'true',
+      cwe: Number(cwe)
+    });
+  }
+  if (cases.length === 0) {
+    throw new Error('no cases parsed — is this the expectedresults CSV?');
+  }
+  return cases;
+}
+
+// The pre-registered sampling rule: for each category, the first N `true` and
+// first N `false` cases by ascending test number. Mechanical and reproducible —
+// no hand-picking, and re-running it on the same corpus yields the same sample.
+export function sampleCases(cases, perLabel = 3) {
+  const byCategory = new Map();
+  for (const c of cases ?? []) {
+    if (!byCategory.has(c.category)) {
+      byCategory.set(c.category, []);
+    }
+    byCategory.get(c.category).push(c);
+  }
+  const sample = [];
+  const shortfalls = [];
+  for (const category of [...byCategory.keys()].sort()) {
+    const group = [...byCategory.get(category)]
+      .sort((a, b) => a.name.localeCompare(b.name));
+    for (const vulnerable of [true, false]) {
+      const matching = group.filter(c => c.vulnerable === vulnerable);
+      const taken = matching.slice(0, perLabel);
+      sample.push(...taken);
+      if (taken.length < perLabel) {
+        shortfalls.push({
+          category, vulnerable, wanted: perLabel, available: taken.length
+        });
+      }
+    }
+  }
+  return { sample, shortfalls };
+}
+
+// Does this finding claim the vulnerability the case is about? Citing the CWE
+// number is decisive; otherwise the category vocabulary has to appear.
+export function findingMatchesCase(finding, testCase, categories = OWASP_CATEGORIES) {
+  const meta = (categories ?? OWASP_CATEGORIES)[testCase.category];
+  const text = `${finding.issue ?? ''} ${finding.fix ?? ''}`.toLowerCase();
+  const cwe = meta?.cwe ?? testCase.cwe;
+  if (cwe && new RegExp(`cwe[- ]?0*${cwe}\\b`, 'i').test(text)) {
+    return true;
+  }
+  return (meta?.terms ?? []).some(term => text.includes(term));
+}
+
+// findings must already be merged (so `lenses` and `consensus` are populated).
+// Returns per-case classification plus the aggregate the claim turns on.
+export function scoreCases(results, options = {}) {
+  const { onlyMatching = true } = options;
+  const perCase = [];
+  let truePositives = 0;
+  let falsePositives = 0;
+  let missed = 0;
+  let declined = 0;
+  let unrelated = 0;
+  const matchedFindings = [];
+
+  for (const { testCase, findings } of results ?? []) {
+    const matching = (findings ?? []).filter(f =>
+      findingMatchesCase(f, testCase));
+    const others = (findings ?? []).length - matching.length;
+    unrelated += others;
+    matchedFindings.push(...matching.map(f => ({ finding: f, testCase })));
+
+    let outcome;
+    if (testCase.vulnerable) {
+      outcome = matching.length > 0 ? 'true-positive' : 'missed';
+      if (matching.length > 0) {
+        truePositives += 1;
+      } else {
+        missed += 1;
+      }
+    } else {
+      outcome = matching.length > 0 ? 'false-positive' : 'declined';
+      if (matching.length > 0) {
+        falsePositives += 1;
+      } else {
+        declined += 1;
+      }
+    }
+    perCase.push({
+      name: testCase.name,
+      category: testCase.category,
+      vulnerable: testCase.vulnerable,
+      outcome,
+      matched: matching.length,
+      unrelated: others,
+      lenses: [...new Set(matching.flatMap(f => f.lenses ?? []))]
+    });
+  }
+
+  // The comparison the whole ranking rests on. A matched finding in a
+  // `false`-labeled case is wrong; in a `true`-labeled case it is right. So
+  // precision can be computed separately for consensus and solo findings.
+  const pool = onlyMatching ? matchedFindings : matchedFindings;
+  const consensus = pool.filter(m => m.finding.consensus === true);
+  const solo = pool.filter(m => m.finding.consensus !== true);
+
+  return {
+    cases: perCase.length,
+    truePositives,
+    falsePositives,
+    missed,
+    declined,
+    unrelatedFindings: unrelated,
+    recall: (truePositives + missed) === 0
+      ? null : round(truePositives / (truePositives + missed)),
+    specificity: (falsePositives + declined) === 0
+      ? null : round(declined / (falsePositives + declined)),
+    consensusPrecision: precisionOf(consensus),
+    soloPrecision: precisionOf(solo),
+    consensusCount: consensus.length,
+    soloCount: solo.length,
+    perCase
+  };
+}
+
+function precisionOf(matched) {
+  if (matched.length === 0) {
+    return null;
+  }
+  const correct = matched.filter(m => m.testCase.vulnerable).length;
+  return round(correct / matched.length);
+}
+
+// Case-level agreement.
+//
+// On a corpus labeled per case, the meaningful unit of agreement is "two lenses
+// independently flagged this case", not "their line anchors happened to cluster
+// within three lines". Two lenses can describe the same vulnerability from
+// different anchors in a 70-line servlet — one at the sink, one at the source —
+// and line-proximity clustering would score that as two solo findings.
+//
+// results: [{testCase, findings: [{lens, line, severity, issue, fix}]}]
+export function scoreCaseAgreement(results, options = {}) {
+  const { categories } = options;
+  const detections = [];
+  const perCase = [];
+
+  for (const { testCase, findings } of results ?? []) {
+    const matching = (findings ?? []).filter(f =>
+      findingMatchesCase(f, testCase, categories));
+    const lenses = [...new Set(matching.map(f => f.lens))].sort();
+    const outcome = lenses.length === 0
+      ? (testCase.vulnerable ? 'missed' : 'declined')
+      : (testCase.vulnerable ? 'true-positive' : 'false-positive');
+    perCase.push({
+      name: testCase.name,
+      category: testCase.category,
+      vulnerable: testCase.vulnerable,
+      outcome,
+      lenses,
+      unrelated: (findings ?? []).length - matching.length
+    });
+    if (lenses.length > 0) {
+      detections.push({
+        name: testCase.name,
+        vulnerable: testCase.vulnerable,
+        lenses,
+        consensus: lenses.length > 1
+      });
+    }
+  }
+
+  const consensus = detections.filter(d => d.consensus);
+  const solo = detections.filter(d => !d.consensus);
+  const precision = group => group.length === 0
+    ? null
+    : round(group.filter(d => d.vulnerable).length / group.length);
+
+  const truePositives = perCase.filter(c => c.outcome === 'true-positive').length;
+  const falsePositives = perCase.filter(c => c.outcome === 'false-positive').length;
+  const missed = perCase.filter(c => c.outcome === 'missed').length;
+  const declined = perCase.filter(c => c.outcome === 'declined').length;
+
+  return {
+    cases: perCase.length,
+    truePositives,
+    falsePositives,
+    missed,
+    declined,
+    recall: (truePositives + missed) === 0
+      ? null : round(truePositives / (truePositives + missed)),
+    specificity: (falsePositives + declined) === 0
+      ? null : round(declined / (falsePositives + declined)),
+    detections: detections.length,
+    consensusCount: consensus.length,
+    soloCount: solo.length,
+    consensusPrecision: precision(consensus),
+    soloPrecision: precision(solo),
+    unrelatedFindings: perCase.reduce((n, c) => n + c.unrelated, 0),
+    perCase
+  };
+}
+
+// Measured overlap between two lenses on this corpus: the Jaccard index of the
+// case sets each one flagged. Feeds the independence weighting, and answers
+// whether a second lens in the same domain adds anything.
+export function lensCaseOverlap(results, options = {}) {
+  const { categories } = options;
+  const byLens = new Map();
+  for (const { testCase, findings } of results ?? []) {
+    for (const f of findings ?? []) {
+      if (!findingMatchesCase(f, testCase, categories)) {
+        continue;
+      }
+      if (!byLens.has(f.lens)) {
+        byLens.set(f.lens, new Set());
+      }
+      byLens.get(f.lens).add(testCase.name);
+    }
+  }
+  const lenses = [...byLens.keys()].sort();
+  const overlap = {};
+  for (let i = 0; i < lenses.length; i++) {
+    for (let j = i + 1; j < lenses.length; j++) {
+      const a = byLens.get(lenses[i]);
+      const b = byLens.get(lenses[j]);
+      const union = new Set([...a, ...b]);
+      if (union.size === 0) {
+        continue;
+      }
+      let shared = 0;
+      for (const name of a) {
+        if (b.has(name)) {
+          shared += 1;
+        }
+      }
+      overlap[`${lenses[i]}|${lenses[j]}`] = round(shared / union.size);
+    }
+  }
+  return overlap;
+}
+
+function round(n) {
+  return Number(n.toFixed(4));
+}
+
+export function formatCaseScore(result) {
+  const pct = v => v == null ? 'n/a' : `${(v * 100).toFixed(1)}%`;
+  const lines = [
+    `cases scored:        ${result.cases}`,
+    `vulnerable found:    ${result.truePositives}  (recall ${pct(result.recall)})`,
+    `vulnerable missed:   ${result.missed}`,
+    `safe declined:       ${result.declined}  (specificity ${pct(result.specificity)})`,
+    `FALSE POSITIVES:     ${result.falsePositives}`,
+    `unrelated findings:  ${result.unrelatedFindings}  (neither credited nor penalised)`,
+    '',
+    'consensus vs solo precision — the claim under test:',
+    `  consensus (${result.consensusCount}): ${pct(result.consensusPrecision)}`,
+    `  solo      (${result.soloCount}): ${pct(result.soloPrecision)}`,
+    ''
+  ];
+  if (result.falsePositives < 3) {
+    lines.push(
+      'Fewer than 3 false positives — per the pre-registered criteria this is',
+      'INCONCLUSIVE regardless of which precision is higher.', '');
+  } else if (result.consensusPrecision != null && result.soloPrecision != null) {
+    const delta = result.consensusPrecision - result.soloPrecision;
+    lines.push(
+      `consensus advantage: ${(delta * 100).toFixed(1)} points`,
+      delta >= 0.1 ? 'Criteria met: claim SUPPORTED.'
+        : delta <= 0 ? 'Criteria met: claim REFUTED.'
+          : 'Between thresholds: INCONCLUSIVE.', '');
+  }
+  const byCategory = new Map();
+  for (const c of result.perCase) {
+    if (!byCategory.has(c.category)) {
+      byCategory.set(c.category, { tp: 0, fp: 0, missed: 0, declined: 0 });
+    }
+    const bucket = byCategory.get(c.category);
+    if (c.outcome === 'true-positive') bucket.tp += 1;
+    else if (c.outcome === 'false-positive') bucket.fp += 1;
+    else if (c.outcome === 'missed') bucket.missed += 1;
+    else bucket.declined += 1;
+  }
+  lines.push('per category (tp / missed / fp / declined):');
+  for (const [category, b] of [...byCategory.entries()].sort()) {
+    lines.push(`  ${category.padEnd(14)} ${b.tp} / ${b.missed} / ${b.fp} / ${b.declined}`);
+  }
+  return lines.join('\n');
+}