The Register

/**
 * Build a complete case from a code. Deterministic: same code + difficulty +
 * mode + engine version (+ config) → identical setting, names, clues and solution.
 */
export function generateCase(code, difficulty = 'classic', mode = 'cold', onProgress = () => {}) {
  if (typeof mode === 'function') { onProgress = mode; mode = 'cold'; }
  const t0 = Date.now();
  const diff = DIFFICULTIES[difficulty];
  if (!diff) throw new Error(`Unknown difficulty ${difficulty}`);
  if (!MODES[mode]) throw new Error(`Unknown mode ${mode}`);
  const root = caseRng(code, difficulty, mode);

  // The setting decides who these people are and how they're listed; the
  // difficulty decides how many of them there are.
  const setting = root.fork('setting').pick(SETTINGS);
  const total = namesFor(difficulty);
  const label = `Entering ${total.toLocaleString('en-US')} ${setting.people} into the ${setting.registerWord}`;
  onProgress({ phase: 'names', label, p: 0 });
  const names = generatePeople(root.fork('people'), setting, total);
  onProgress({ phase: 'names', label, p: 1 });
  const chapterPages = planChapters(root.fork('chapters'), names.length);
  const book = layoutNovel(names, chapterPages, { fullNames: true });

  onProgress({ phase: 'clues', label: mode === 'inquiry' ? 'Lining up the witnesses' : 'Gathering the evidence', p: 0 });
  const rng = root.fork('clues');
  const plan = casePlan(root.fork('plan'));
  const build = mode === 'inquiry' ? tryBuildInquiry : tryBuildCase;
  let solved = null, attempts = 0;
  while (!solved && attempts < SEARCH.attempts) {
    attempts++;
    // If this case's mix of clue types keeps failing, let it draw on all of them.
    solved = build(rng, book, difficulty, plan, attempts > SEARCH.attempts / 2);
    onProgress({ phase: 'clues', label: mode === 'inquiry' ? 'Lining up the witnesses' : 'Gathering the evidence', p: Math.min(0.95, attempts / 12) });
  }
  if (!solved) throw new Error(`Could not construct a balanced case in ${SEARCH.attempts} attempts — loosen BALANCE or raise SEARCH in config.js`);

  const { killer, victim, rules } = solved;
  const story = generateStory(root.fork('story'), book.entries[victim], setting);
  const ctx = { entries: book.entries, book, victim: book.entries[victim], registerWord: setting.registerWord };
  const finalRules = rules.map(r => ({ ...r, ...describeRule(r, ctx) }));

  onProgress({ phase: 'verify', label: 'Checking every alibi', p: 0.5 });
  const caseData = {
    engine: ENGINE_VERSION,
    code,
    difficulty,
    mode,
    setting: setting.id,
    style: plan.style,
    title: caseTitle(story),
    story,
    layout: 'novel',
    fullNames: true,
    names,
    chapterPages,
    victim,
    rules: finalRules,
    solution: seal(killer, code),
    stats: { pageCount: book.pageCount, attempts, iterations: solved.iterations, ms: 0, sectionSurvivors: solved.sectionSurvivors },
  };
  const v = validateCase(caseData);
  caseData.validation = { ok: v.ok, checks: v.checks };
  caseData.metrics = v.metrics;
  caseData.stats.ms = Date.now() - t0;
  if (!caseData.validation.ok) throw new Error('Case failed validation: ' + caseData.validation.checks.filter(c => !c.ok).map(c => c.label).join('; '));
  onProgress({ phase: 'done', label: 'The case is ready', p: 1 });
  return caseData;
}

/**
 * Novel layout: names in the given (shuffled) reading order, three columns,
 * chapters of `chapterPages[c]` pages each. Every chapter but the last fills
 * its pages exactly; the book's final page splits its names evenly.
 */
export function layoutNovel(names, chapterPages, { fullNames = false } = {}) {
  const entries = [], pages = [], chapterInfo = [];
  let k = 0, pageNo = 0;
  chapterPages.forEach((count, ci) => {
    const firstPage = pageNo + 1, start = k;
    for (let pg = 0; pg < count && k < names.length; pg++) {
      const opener = pg === 0;
      const rows = opener ? ROWS_OPENER : ROWS_FULL;
      const onPage = Math.min(names.length - k, rows * NOVEL_COLS);
      const perCol = onPage === rows * NOVEL_COLS ? [rows, rows, rows] : balance(onPage, NOVEL_COLS);
      pageNo++;
      const page = { page: pageNo, ci, opener, rows, cols: perCol.map(() => []) };
      let s = 0;
      perCol.forEach((n, c) => {
        for (let line = 1; line <= n; line++, s++) {
          const i = entries.length;
          entries.push({ i, name: names[k + s], ci, page: pageNo, col: c + 1, line });
          page.cols[c].push(i);
        }
      });
      pages.push(page);
      k += onPage;
    }
    chapterInfo.push({ ci, label: String(ci + 1), title: `Chapter ${numberWord(ci + 1)}`, word: numberWord(ci + 1), firstPage, lastPage: pageNo, count: k - start });
  });
  for (const e of entries) decorate(e);
  return { entries, pages, chapters: chapterInfo, pageCount: pageNo, cols: NOVEL_COLS, style: 'novel', fullNames };
}

/** Split the register's names into chapters of 10–30 pages (mostly 12–26), novel-style. */
export function planChapters(rng, total) {
  const full = ROWS_FULL * NOVEL_COLS, open = ROWS_OPENER * NOVEL_COLS;
  const cap = p => open + (p - 1) * full;
  const pagesFor = n => 1 + Math.ceil(Math.max(0, n - open) / full);
  const plan = [];
  let left = total;
  while (left > 0) {
    const p = rng.range(12, 26);
    if (left <= cap(p)) {
      const need = pagesFor(left);
      if (need >= CHAPTER_PAGES[0] || !plan.length) plan.push(need);
      else {
        // Too short for a chapter: fold it into the previous one, or split the two evenly.
        const merged = plan.pop();
        const namesInBoth = cap(merged) + left;
        const both = pagesFor(namesInBoth) + 1; // two openers instead of one
        if (pagesFor(namesInBoth) <= CHAPTER_PAGES[1]) plan.push(pagesFor(namesInBoth));
        else { const a = Math.ceil(both / 2); plan.push(a, pagesFor(namesInBoth - cap(a))); }
      }
      left = 0;
    } else { plan.push(p); left -= cap(p); }
  }
  return plan;
}

function stats(part) {
  const n = letters(part);
  let vowels = 0, mask = 0, repeat = false, dbl = false;
  for (let j = 0; j < n.length; j++) {
    const c = n[j];
    if (VOWEL(c)) vowels++;
    const bit = 1 << (c.charCodeAt(0) - 97);
    if (mask & bit) repeat = true;
    mask |= bit;
    if (j && n[j - 1] === c) dbl = true;
  }
  return { name: part, lower: n, len: n.length, vowels, consonants: n.length - vowels, mask, repeat, double: dbl };
}

// ── clue types: at most one clue of each type per case ───────────────────
// `broad` types are always present; they set the difficulty. Families listed
// under a type are interchangeable ways of saying something about one subject.
export const TYPES = [
  // Engine 7 sections: stretches of the register, anchored to people in it.
  { id: 'span',         tier: 'record',     label: 'Between Two Names',       families: ['span'] },
  { id: 'landmark',     tier: 'record',     label: 'A Landmark Name',         families: ['landmark'] },
  { id: 'nearVictim',   tier: 'record',     label: 'Near the Victim',         families: ['victimSpan'] },
  { id: 'chapterCompany', tier: 'record',   label: 'The Chapter’s Company',   families: ['chapterCompany'] },
  { id: 'nearPerson',   tier: 'record',     label: 'Near a Named Person',     families: ['nearPerson'] },
  { id: 'chapterRelative', tier: 'record',  label: 'A Named Person’s Chapter', families: ['chapterRelative'] },
  // Before engine 7: simple structural gates, struck a page or column at a time. No longer dealt.
  { id: 'chapter',      tier: 'registry',   legacy: true, label: 'The Chapter',            families: ['chapterParity', 'chapterPrime', 'chapterMultiple', 'chapterRange', 'chapterSpelled', 'pageInChapter'] },
  { id: 'page',         tier: 'ledger',     legacy: true, label: 'The Page Number',        families: ['pagePrime', 'pageParity', 'pageMultiple', 'pageDigitSum', 'pageLastDigit', 'pageHasDigit', 'pageReversed'] },
  { id: 'column',       tier: 'placement',  legacy: true, label: 'The Column',             families: ['column'] },
  { id: 'line',         tier: 'placement',  legacy: true, label: 'The Line Number',        families: ['lineParity', 'lineHalf', 'lineMultiple', 'linePrime'] },
  { id: 'initial',      tier: 'name',       label: 'The Initial',             families: ['word', 'half', 'straight', 'window', 'victimInitial'] },
  { id: 'length',       tier: 'name',       label: 'Length',                  families: ['lengthEq', 'lengthCmp', 'lengthParity'] },
  { id: 'presence',     tier: 'name',       label: 'Letters Present',         families: ['contains', 'containsAny'] },
  { id: 'position',     tier: 'name',       label: 'Letter Positions',        families: ['secondVowel', 'thirdVowel', 'secondHalf'] },
  { id: 'ending',       tier: 'name',       label: 'The Last Letter',         families: ['endsVowel', 'lastHalf', 'endsIn'] },
  { id: 'vowels',       tier: 'name',       label: 'Vowels',                  families: ['vowelCount', 'balance'] },
  { id: 'repetition',   tier: 'name',       label: 'Repeated Letters',        families: ['repeat', 'double'] },
  { id: 'pairs',        tier: 'name',       label: 'Letter Pairs',            families: ['pair'] },
  { id: 'order',        tier: 'name',       label: 'Alphabetical Order',      families: ['firstVsLast', 'secondVsFirst'] },
  { id: 'runs',         tier: 'name',       label: 'Vowel & Consonant Runs',  families: ['vowelRun', 'consonantRun'] },
  { id: 'before',       tier: 'connection', label: 'The Name Before',         families: ['prevLength', 'prevLast'] },
  { id: 'after',        tier: 'connection', label: 'The Name After',          families: ['nextLast', 'nextLength'] },
  { id: 'lineMates',    tier: 'connection', label: 'The Same Line',           families: ['lineLength', 'lineLast', 'lineInitial'] },
  { id: 'neighbours',   tier: 'connection', label: 'Both Neighbors',         families: ['neighbourEnds', 'neighbourLength'] },
  { id: 'victimLetters', tier: 'connection', label: 'The Victim’s Letters',   families: ['victimShare'] },
  { id: 'victimLength', tier: 'connection', label: 'The Victim’s Length',     families: ['victimLength'] },
  { id: 'pageCompany',  tier: 'connection', label: 'The Top of the Page',     families: ['pageFirstSecond', 'pageFirstLength'] },
  { id: 'household',    tier: 'connection', label: 'The Family',              families: ['familyNeighbour', 'familyPosition'] },
  { id: 'namesakes',    tier: 'connection', label: 'Namesakes',               families: ['pageNamesake', 'columnNamesake'] },
  // Engine 7: more ways to read a name, its family, and reasoning puzzles.
  { id: 'initials',     tier: 'name',       label: 'The Initials',            families: ['initialsOrder', 'initialsKind', 'initialsWord'] },
  { id: 'mirror',       tier: 'name',       label: 'First Name & Surname',    families: ['mirrorLength', 'mirrorShared', 'mirrorOrder', 'mirrorLink'] },
  { id: 'familySize',   tier: 'connection', label: 'The Size of the Family',  families: ['familySize'] },
  { id: 'numbers',      tier: 'reasoning',  label: 'Names & Numbers',         families: ['lineVsLength', 'parityMatch'] },
  { id: 'ifThen',       tier: 'reasoning',  label: 'If… Then…',               families: ['compound_implies'] },
  { id: 'eitherOr',     tier: 'reasoning',  label: 'Either… Or…',             families: ['compound_xor', 'compound_or'] },
  { id: 'bothOrNeither', tier: 'reasoning', label: 'Both or Neither',         families: ['compound_iff'] },
];

/** Indices of people whose full name appears exactly once, in register order. */
function uniqueAnchors(book) {
  let a = anchorCache.get(book);
  if (!a) { a = []; for (const [, ids] of bookIndex(book).byFull) if (ids.length === 1) a.push(ids[0]); a.sort((x, y) => x - y); anchorCache.set(book, a); }
  return a;
}

const chapterRel = (e, a, rel) => rel === 'later' ? e.ci > a.ci : rel === 'earlier' ? e.ci < a.ci : (Math.abs(e.ci - a.ci) <= 1) === (rel === 'near');

const ATOMS = [
  { id: 'start', name: true, kind: 'start', make: r => ({ part: r.pick(['first', 'last']), vowel: r.chance(0.5) }), test: (e, p) => isVowel(e[p.part].lower[0]) === p.vowel, say: p => `the killer’s ${PW[p.part]} begins with a ${p.vowel ? 'vowel' : 'consonant'}` },
  { id: 'end', name: true, kind: 'end', make: r => ({ part: r.pick(['first', 'last']), vowel: r.chance(0.5) }), test: (e, p) => isVowel(e[p.part].lower[e[p.part].len - 1]) === p.vowel, say: p => `the killer’s ${PW[p.part]} ends in a ${p.vowel ? 'vowel' : 'consonant'}` },
  { id: 'len', name: true, kind: 'len', make: r => { const part = r.pick(['first', 'last']); return { part, k: part === 'first' ? r.range(5, 7) : r.range(6, 8) }; }, test: (e, p) => e[p.part].len >= p.k, say: p => `the killer’s ${PW[p.part]} has ${NUM[p.k]} or more letters` },
  { id: 'has', name: true, kind: 'has', make: r => ({ part: r.pick(['first', 'last']), c: r.pick('aeinorlst'.split('')) }), test: (e, p) => e[p.part].lower.includes(p.c), say: p => `the killer’s ${PW[p.part]} contains the letter ${p.c.toUpperCase()}` },
  { id: 'dbl', name: true, kind: 'dbl', make: r => ({ part: r.pick(['first', 'last']) }), test: (e, p) => e[p.part].double, say: p => `the killer’s ${PW[p.part]} has a double letter (the same letter twice in a row)` },
  { id: 'half', name: true, kind: 'half', make: r => ({ part: r.pick(['first', 'last']) }), test: (e, p) => e[p.part].lower[0] < 'n', say: p => `the killer’s ${PW[p.part]} begins with a letter from A to M` },
  { id: 'longer', name: true, kind: 'longer', make: () => ({}), test: e => e.first.len > e.last.len, say: () => 'the killer’s first name is longer than their surname' },
  { id: 'odd', kind: 'odd', make: () => ({}), test: e => e.line % 2 === 1, say: () => 'the killer is on an odd-numbered line' },
  { id: 'top', kind: 'top', make: () => ({}), test: e => e.line <= 12, say: () => 'the killer is on one of lines 1 to 12' },
  { id: 'evenPage', kind: 'evenPage', make: () => ({}), test: e => e.page % 2 === 0, say: () => 'the killer’s page number is even' },
  { id: 'left', kind: 'left', make: () => ({}), test: e => e.col === 1, say: () => 'the killer is in the left-hand column of their page' },
];

const COMPOUND = { implies: (a, b) => !a || b, xor: (a, b) => a !== b, or: (a, b) => a || b, iff: (a, b) => a === b };

export function caseRng(code, difficulty, mode = 'cold') { return new Rng(`${code}|${difficulty}|${mode}|v${ENGINE_VERSION}`); }

export function newCaseCode(entropy = Math.random) {
  let s = '';
  for (let i = 0; i < 8; i++) s += CODE_ALPHABET[Math.floor(entropy() * CODE_ALPHABET.length)];
  return `${s.slice(0, 4)}-${s.slice(4)}`;
}

/** Popularity-weighted picker over a most-common-first list (Zipf by rank). */
function zipfPicker(list, s) {
  const cum = [];
  let t = 0;
  list.forEach((_, r) => { t += 1 / Math.pow(r + 1, s); cum.push(t); });
  return rng => {
    const x = rng.next() * t;
    let lo = 0, hi = cum.length - 1;
    while (lo < hi) { const mid = (lo + hi) >> 1; if (cum[mid] < x) lo = mid + 1; else hi = mid; }
    return list[lo];
  };
}

// Name banks hold ~100–250 names each, far fewer than a real population, so
// their popularity skew is softened: otherwise one surname would cover 15–30%
// of a town. Lewis still ends up dominated by MacLeods — as it really was.
const SURNAME_SKEW = 0.6, FIRST_SKEW = 0.9;

/** Returns `total` full names ("First Surname") in register order. */
export function generatePeople(rng, setting, total = 26000) {
  const cultureOf = () => rng.weighted(setting.cultures, ([, w]) => w)[0];
  const sizeOf = () => rng.weighted(setting.grouping.sizes, ([, w]) => w)[0];
  const out = [];
  while (out.length < total) {
    const size = Math.min(sizeOf(), total - out.length);
    if (setting.grouping.kind === 'households') {
      // A household: one surname, one culture.
      const c = culture(cultureOf());
      let surname, members = [];
      for (let t = 0; t < 10 && members.length < size; t++) {
        surname = c.surname(rng);
        members = [];
        const taken = new Set();
        for (let m = 0; m < size; m++) { const f = firstName(rng, c, surname, taken); if (f) { taken.add(f); members.push(`${f} ${surname}`); } }
      }
      out.push(...members);
    } else {
      // A party of friends: mixed backgrounds; couples and siblings sometimes share a surname.
      let shared = null;
      for (let m = 0; m < size; m++) {
        const c = culture(cultureOf());
        const surname = shared && rng.chance(setting.grouping.sharedSurname) ? shared : c.surname(rng);
        const f = firstName(rng, c, surname);
        if (!f) continue;
        out.push(`${f} ${surname}`);
        shared = surname;
      }
    }
  }
  return out.slice(0, total);
}

/**
 * Difficulty sets three things:
 *   names — how many people are in the register (26,000 for Cozy, rising to
 *           52,000 for Noir, whose id is still 'hardboiled');
 *   band  — how many suspects survive the "section" clues (the ones about
 *           stretches of the register, struck in runs), i.e. how much
 *           name-by-name checking the reader does;
 *   clues — the [min, max] clue count.
 * There is at most one clue per type (see TYPES in rules.js), and in Cold Case
 * every clue must still be necessary.
 */
export const DIFFICULTIES = {
  cozy:       { label: 'Cozy',        blurb: 'A Sunday-afternoon mystery. A smaller register, and few suspects left once the sections are struck.', names: 26000, band: [300, 600],   clues: [9, 10] },
  classic:    { label: 'Classic',     blurb: 'The intended experience: a few evenings with the Register.',                                         names: 39000, band: [700, 1400],  clues: [10, 12] },
  hardboiled: { label: 'Noir',        blurb: 'Fifty-two thousand names, and thousands still standing after the sections. Bring coffee.',          names: 52000, band: [1500, 3000], clues: [12, 15] },
};

/**
 * Case styles: every case leans a different way, so no two feel alike. Each
 * style sets the tier quotas for the fine clues — name (the name itself),
 * connection (neighbours, family, the victim) and reasoning (clues built from
 * two conditions, or that cross a name with its position) — and how many fine
 * types it may draw from at all. The reader sees the style in the case report.
 */
export const STYLES = {
  wordsmith:   { label: 'The Wordsmith',   blurb: 'Most of the evidence is about the names themselves.',           quota: { name: [4, 9], connection: [1, 3], reasoning: [0, 2] } },
  gossip:      { label: 'The Gossip',      blurb: 'Most of the evidence is about who sits near whom, and family.', quota: { name: [2, 5], connection: [3, 6], reasoning: [0, 2] } },
  logician:    { label: 'The Logician',    blurb: 'Expect evidence that hangs on “if”, “either” and “both”.',     quota: { name: [2, 5], connection: [1, 3], reasoning: [2, 4] } },
  generalist:  { label: 'The Generalist',  blurb: 'A little of everything.',                                     quota: { name: [2, 6], connection: [2, 4], reasoning: [1, 3] } },
};

/**
 * A case's style (which tiers its fine clues lean on) and the fine clue types
 * it sets aside, so no two cases draw on quite the same mix.
 */
function casePlan(rng) {
  const style = rng.pick(Object.keys(STYLES));
  const dropped = new Set();
  for (const tier of FINE_TIERS) {
    const types = DEALT_TYPES.filter(t => t.tier === tier).map(t => t.id);
    // Keep enough of each tier to meet the style's quota, with room to spare.
    const keep = Math.min(types.length, STYLES[style].quota[tier][1] + 2);
    let left = types.length;
    for (const t of rng.shuffle(types)) if (left > keep && rng.chance(TYPE_DROPOUT)) { dropped.add(t); left--; }
  }
  return { style, dropped };
}

/**
 * Balance thresholds. "Suspects" means everyone except the killer and the
 * victim (25,998 names). A clue "clears" a name when the name breaks it.
 */
export const BALANCE = {
  // (2) No single clue may clear more than this share of suspects — no clue
  // does the whole job. Also a floor, so no clue is a near no-op.
  maxClearShare: 0.80,
  minClearShare: 0.12,
  // Tighter caps for clue types that are applied in bulk with a few clicks.
  // A chapter clue struck with "Strike chapter" shouldn't wipe out half the
  // town — it should trim the book, leaving the real work to the other clues.
  // (Engine 7 has no chapter clues; chapterCompany is the nearest relative.)
  maxClearShareByType: { chapter: 0.35, chapterCompany: 0.6 },

  // (1) Overlap: at most `maxShare` of suspects may be cleared by `clues` or
  // more clues.
  //
  // Measured on typical cases, the share of suspects cleared by at least k clues:
  //     k:   2      4      6      8      10     12
  //        99.7%  95.5%  78%    46%    14%    1.7%
  // "Cleared by 2+" is pinned near 99.7% by arithmetic: every suspect must be
  // cleared, and the only names cleared by exactly one clue are the near-misses
  // that make each clue necessary — with one solution allowed there can only be
  // a few dozen. So the literal { clues: 2 } can only be set to ~0.999 and
  // barely bites. The default caps pile-ups instead: no more than 22% of the
  // town may be struck by 10 or more clues.
  overlap: { clues: 10, maxShare: 0.22 },

  // Every clue must be the *only* clue clearing at least this many names.
  // 1 = every clue is strictly necessary. Higher = each clue does more
  // unique work (and the case is more forgiving of a misread clue elsewhere).
  minSoloClears: 1,

  // Read in Casebook order, every clue must newly clear at least this share
  // of the suspects still standing when the reader reaches it. Keeps late
  // clues from feeling like busywork.
  minMarginalShare: 0.08,

  // No two clues may clear nearly the same names: if the smaller of two clues'
  // cleared sets lies this much inside the other's, they read as a repeat.
  maxPairOverlap: 0.85,
};

/** Search effort. Raise if cases start failing to generate; lower for speed. */
export const SEARCH = {
  attempts: 300,       // fresh killer/victim picks before giving up (a failed
                       // attempt is cheap; most fail fast on an awkward killer)
  iterations: 1500,    // local-search steps per attempt (more rarely helps:
                       // a stuck attempt is usually a hard killer — re-pick)
  candidates: 32,      // moves scored per step
  uphill: 0.04,        // chance of accepting a worse move (escapes dead ends)
  perType: 6,          // candidate moves per clue type per step, so a type with
                       // hundreds of forms is no likelier to be tried than one with two
  sample: 40,          // clues drawn per attempt for each sampled family (the
                       // section clues and compound clues have too many
                       // possible forms to enumerate, so each attempt draws
                       // fresh ones that fit its killer)
};

/** Largest overlap between two clues' cleared sets, as a share of the smaller set. */
function pairOverlap(bitsList, killer, victim, N) {
  const cleared = bitsList.map(b => { const out = []; for (let i = 0; i < N; i++) if (!b[i] && i !== killer && i !== victim) out.push(i); return out; });
  let max = 0, pair = null;
  for (let a = 0; a < cleared.length; a++) for (let b = a + 1; b < cleared.length; b++) {
    const [small, bigBits] = cleared[a].length <= cleared[b].length ? [cleared[a], bitsList[b]] : [cleared[b], bitsList[a]];
    let both = 0;
    for (const i of small) if (!bigBits[i]) both++;
    const share = small.length ? both / small.length : 0;
    if (share > max) { max = share; pair = [a, b]; }
  }
  return { max, pair };
}

/** Independent re-check of a stored case: names, layout, uniqueness, balance. */
export function validateCase(caseData) {
  const checks = [];
  const add = (label, ok, detail = '') => checks.push({ label, ok: !!ok, detail });
  const inquiry = caseData.mode === 'inquiry';
  const engine = caseData.engine || 0, legacy = engine < 7;
  const expected = namesFor(caseData.difficulty, engine), many = expected.toLocaleString('en-US');
  if (caseData.layout === 'novel') {
    const nv = validateNameList(caseData.names, caseData.fullNames, expected);
    add(caseData.fullNames ? `${many} well-formed full names` : `${many} names, all unique and well formed`, nv.ok, nv.ok ? `${nv.unique.toLocaleString('en-US')} distinct ${caseData.fullNames ? 'full names (repeats are realistic)' : 'names'}` : nv.problems.join('; '));
  } else {
    const nv = validateNames(caseData.chapters);
    add('26,000 names, all unique, correctly filed and sorted', nv.ok, nv.ok ? `${nv.unique.toLocaleString('en-US')} unique names` : nv.problems.join('; '));
  }

  const book = layoutCase(caseData);
  const pagesOk = book.pages.every((p, i) => p.page === i + 1) && book.entries.length === expected;
  add('Every name has exactly one page, column and line', pagesOk, `${book.pageCount} pages · ${book.cols} columns`);
  if (book.style === 'novel') {
    const lens = book.chapters.map(c => c.lastPage - c.firstPage + 1);
    add(`Every chapter is ${CHAPTER_PAGES[0]}–${CHAPTER_PAGES[1]} pages long`, lens.every(n => n >= CHAPTER_PAGES[0] && n <= CHAPTER_PAGES[1]), `${book.chapters.length} chapters of ${Math.min(...lens)}–${Math.max(...lens)} pages`);
  }

  const rules = caseData.rules;
  const killer = unseal(caseData.solution);
  const m = caseMetrics(book, rules, caseData.victim, killer);
  add('Exactly one name satisfies every clue', m.survivors.length === 1, `${m.survivors.length} survivor(s)`);
  add('That name is the sealed solution', m.survivors.length === 1 && m.survivors[0] === killer);
  add('The victim is not the solution', caseData.victim !== killer);

  const [lo, hi] = clueRange(caseData.difficulty);
  add(`Between ${lo} and ${hi} clues`, rules.length >= lo && rules.length <= hi, `${rules.length} clues`);
  const types = rules.map(r => FAMILY[r.family].type);
  const dupes = types.filter((t, k) => t && types.indexOf(t) !== k);
  add('No two clues of the same type', !dupes.length, dupes.length ? `repeated: ${[...new Set(dupes)].map(t => TYPE[t]?.label || t).join(', ')}` : `${new Set(types).size} distinct types`);
  const tierCount = tier => types.filter(t => TYPE[t]?.tier === tier).length;
  if (legacy && !inquiry) {
    const missingBroad = LEGACY_BROAD.filter(t => !types.includes(t));
    add('Chapter, page number, column and line are all covered', !missingBroad.length, missingBroad.map(t => TYPE[t].label).join(', '));
    const quotaOk = Object.entries(TIER_QUOTA).every(([tier, [a, b]]) => tierCount(tier) >= a && tierCount(tier) <= b);
    add('Name and connection clues within their quotas', quotaOk, `${tierCount('name')} about the name · ${tierCount('connection')} about connections`);
  }
  if (!legacy) {
    const retired = rules.filter(r => FAMILY[r.family].retired || FAMILY[r.family].legacy);
    add('No simple page, column, line or chapter gates', !retired.length, retired.length ? `retired: ${retired.map(r => r.typeLabel).join(', ')}` : '');
    if (!inquiry) {
      // Engine 7 read its 2–3 section clues first; from engine 8 the Casebook is shuffled.
      const [sLo, sHi] = engine < 8 ? [2, 3] : SECTION_CLUES;
      const sec = types.filter(t => TYPE[t]?.tier === 'record').length;
      const secFirst = engine >= 8 || types.slice(0, sec).every(t => TYPE[t]?.tier === 'record');
      add(`${sLo}–${sHi} clues about sections of the register${engine < 8 ? ', listed first' : ''}`, sec >= sLo && sec <= sHi && secFirst, `${sec} section clues`);
      const st = STYLES[caseData.style];
      const quotaOk = !!st && FINE_TIERS.every(tier => tierCount(tier) >= st.quota[tier][0] && tierCount(tier) <= st.quota[tier][1]);
      add(`Clue mix fits the case’s style${st ? ` (${st.label})` : ''}`, quotaOk, `${tierCount('name')} about the name · ${tierCount('connection')} about connections · ${tierCount('reasoning')} reasoning`);
    }
  }

  const tooBig = m.perClue.map((c, k) => c.clearShare > maxClearFor(FAMILY[rules[k].family]?.type) + 1e-9 ? k + 1 : 0).filter(Boolean);
  const tooSmall = m.perClue.map((c, k) => c.clearShare < BALANCE.minClearShare - 1e-9 ? k + 1 : 0).filter(Boolean);
  const shares = m.perClue.map(c => c.clearShare);
  const typeCaps = Object.entries(BALANCE.maxClearShareByType || {}).map(([t, v]) => `${TYPE[t]?.label.replace(/^The /, '').toLowerCase() || t} clues ${pct(v)}`).join(', ');
  add(`No clue clears more than ${pct(BALANCE.maxClearShare)}${typeCaps ? ` (${typeCaps})` : ''} or less than ${pct(BALANCE.minClearShare)} of suspects`, !tooBig.length && !tooSmall.length,
    tooBig.length || tooSmall.length ? `out of range: clue ${[...tooBig, ...tooSmall].join(', ')}` : `range ${pct(Math.min(...shares))} – ${pct(Math.max(...shares))}`);
  if (!inquiry) {
    add(`At most ${pct(BALANCE.overlap.maxShare)} of suspects cleared by ${BALANCE.overlap.clues}+ clues`, m.overlapShare <= BALANCE.overlap.maxShare + 1e-9,
      `${pct(m.overlapShare)} · on average each suspect is cleared by ${m.meanClears.toFixed(1)} clues`);
    const minSolo = Math.min(...m.perClue.map(c => c.solo));
    add(`Every clue is the only clue clearing at least ${BALANCE.minSoloClears} name${BALANCE.minSoloClears > 1 ? 's' : ''} (so every clue is necessary)`, minSolo >= BALANCE.minSoloClears, `fewest: ${minSolo}`);
  }
  const minMarg = Math.min(...m.perClue.map(c => c.marginalShare));
  const minCleared = Math.min(...m.perClue.map(c => c.marginal));
  add(inquiry ? `Every witness, in turn, clears at least ${pct(BALANCE.minMarginalShare)} of those still standing` : `Read in order, every clue clears at least ${pct(BALANCE.minMarginalShare)} of those still standing`,
    minMarg >= BALANCE.minMarginalShare - 1e-9 && minCleared >= 1, `weakest: ${pct(minMarg)}`);
  add(`No two clues clear nearly the same names (at most ${pct(BALANCE.maxPairOverlap)} overlap)`, m.pairOverlap <= BALANCE.maxPairOverlap + 1e-9,
    `closest pair: clues ${m.pairOverlapClues ? m.pairOverlapClues.join(' & ') : '—'} at ${pct(m.pairOverlap)}`);
  add('Clue statements are present and distinct', new Set(rules.map(r => r.text)).size === rules.length);
  return { ok: checks.every(c => c.ok), checks, metrics: { ...m, survivors: undefined } };
}