Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

43.3 KB
Raw Blame
/**
 * MeatSpace POST — Deterministic Cognitive Drills
 *
 * Pure generators + scorers for non-LLM cognitive-training exercises:
 *   - n-back          (working memory)      — signal when the current item matches N steps back
 *   - digit-span      (working memory)      — recall a shown digit sequence forward/backward
 *   - stroop          (attention/inhibition) — name the INK color, not the word
 *   - schulte-table   (visual attention)     — scan a shuffled grid for sequential numbers
 *   - mental-rotation (spatial reasoning)    — pick the rotated (not mirrored) match
 *   - reaction-time   (processing speed)     — simple/choice reaction-time baseline
 *   - task-switching  (rule switching)       — apply a cued classification rule
 *   - go-no-go        (response inhibition)  — respond to go stimuli, withhold to lures
 *   - flanker         (interference control) — report a target direction around distractors
 *
 * These are deterministic: the drill's answer key lives in the generated data
 * and every score is recomputed here on session submit, so a client-supplied
 * `correct`/`score` is never trusted (mirrors the math `scoreDrill` contract).
 * NO AI-provider calls happen anywhere in this module.
 */

import { shuffle } from '../lib/arrayUtils.js';

// Coarse module tag stored on scored cognitive tasks, so stats read as
// `byDrill['cognitive:<type>']` (parallel to `mental-math:<type>`).
export const COGNITIVE_MODULE = 'cognitive';
// Moved to lib so route validation can enumerate the types without importing
// this module — issue #4901.
export { COGNITIVE_DRILL_TYPES } from '../lib/postDrillTypes.js';
import { COGNITIVE_DRILL_TYPES } from '../lib/postDrillTypes.js';
import { COGNITIVE_PAIR_CONSTRAINTS } from '../lib/postCognitiveConfig.js';

const NBACK_LETTERS = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H'];

// Named colors used by the Stroop drill. `hex` is the rendered ink color and
// the swatch on the answer buttons; `name` is the correct answer token.
export const STROOP_COLORS = [
  { name: 'red', hex: '#ef4444' },
  { name: 'blue', hex: '#3b82f6' },
  { name: 'green', hex: '#22c55e' },
  { name: 'yellow', hex: '#eab308' },
];

// =============================================================================
// HELPERS
// =============================================================================

function clampInt(value, min, max, fallback) {
  const n = Math.round(Number(value));
  // Clamp the fallback into [min,max] too — a fallback that sits outside the
  // range (e.g. maxLength's fallback 8 when startLength has clamped up to 9)
  // would otherwise slip through un-clamped and, for digit-span, make
  // maxLength < startLength → an empty drill.
  const v = Number.isFinite(n) ? n : fallback;
  return Math.min(max, Math.max(min, v));
}

function pick(arr) {
  return arr[Math.floor(Math.random() * arr.length)];
}

function seedString(value) {
  if (value != null && String(value).trim()) return String(value).trim().slice(0, 100);
  return `${Date.now().toString(36)}-${Math.floor(Math.random() * 0xffffffff).toString(36)}`;
}

// Mulberry32 seeded from an FNV-1a-style string hash. The generated drill
// stores the normalized seed in config, so the same seed + knobs reconstructs
// the same answer key during server rescoring and in focused regression tests.
function seededRandom(seed) {
  let state = 2166136261;
  for (const char of seed) {
    state ^= char.charCodeAt(0);
    state = Math.imul(state, 16777619);
  }
  return () => {
    state |= 0;
    state = (state + 0x6D2B79F5) | 0;
    let t = state;
    t = Math.imul(t ^ (t >>> 15), t | 1);
    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

function pickWith(arr, random) {
  return arr[Math.floor(random() * arr.length)];
}

function shuffleWith(items, random) {
  const out = [...items];
  for (let i = out.length - 1; i > 0; i -= 1) {
    const j = Math.floor(random() * (i + 1));
    [out[i], out[j]] = [out[j], out[i]];
  }
  return out;
}

function clampMs(ms, refMs) {
  return Math.min(Math.max(Number(ms) || 0, 0), refMs);
}

/**
 * Shared 0-100 score: 80% accuracy + 20% speed. `refMs` is the per-trial
 * response window used for the speed bonus (avg RT over answered trials).
 */
function accuracySpeedScore(recomputed, refMs) {
  if (!recomputed.length) return 0;
  const correctRatio = recomputed.filter(q => q.correct).length / recomputed.length;
  const timed = recomputed.filter(q => q.answered != null && q.responseMs > 0);
  const avgMs = timed.length ? timed.reduce((s, q) => s + q.responseMs, 0) / timed.length : refMs;
  const speedBonus = refMs > 0 ? Math.max(0, 1 - avgMs / refMs) : 0;
  return Math.min(100, Math.max(0, Math.round((correctRatio * 0.8 + speedBonus * 0.2) * 100)));
}

/**
 * Answered-only metric bundle stored alongside every scored task, so a reader
 * can report accuracy (of the answers actually given) separately from completion
 * (how much of the drill was reached) and average speed — instead of only the
 * blended headline `score` (issue #2094). Unanswered trials (`answered == null`)
 * lower `completion`, never `accuracy`. Fields are `null` (never NaN) when there
 * is no data to derive them from, so downstream readers/aggregators stay safe.
 *
 * NOTE: this treats `answered == null` as "not reached". It is therefore the
 * right helper for skip-means-blank drills (Stroop, mental rotation, digit span,
 * reaction time) but NOT for Schulte (event stream) or n-back (go/no-go). In
 * n-back, withholding a press is a
 * deliberate "no-match" answer — n-back computes its own signal-detection metrics.
 */
export function answeredMetrics(recomputed) {
  const list = Array.isArray(recomputed) ? recomputed : [];
  const totalCount = list.length;
  const answered = list.filter(q => q?.answered != null);
  const answeredCount = answered.length;
  const correct = answered.filter(q => q?.correct).length;
  return {
    accuracy: answeredCount ? correct / answeredCount : null,
    completion: totalCount ? answeredCount / totalCount : null,
    avgResponseMs: answeredCount
      ? Math.round(answered.reduce((s, q) => s + (q.responseMs || 0), 0) / answeredCount)
      : null,
    answeredCount,
    totalCount,
  };
}

// Median of a numeric list (integer-rounded for the even case). `null` when empty.
export function median(nums) {
  const list = (Array.isArray(nums) ? nums : []).filter(n => Number.isFinite(n)).sort((a, b) => a - b);
  if (!list.length) return null;
  const mid = Math.floor(list.length / 2);
  return list.length % 2 ? list[mid] : Math.round((list[mid - 1] + list[mid]) / 2);
}

// --- Mental rotation: grid-cell shape helpers -------------------------------
// Four chiral pentomino footprints, each within a 4x4 box. Verified (see the
// "ROTATION_SHAPES chirality invariant" test in meatspacePostCognitive.test.js,
// which exercises this exact set via the exported ROTATION_SHAPES) that every
// rotation is distinct from every mirrored-rotation, AND all 4 rotations of
// each are themselves distinct — so "rotated match" vs "mirrored distractor"
// is always unambiguous and there are always 3 distinct mirrored candidates
// to fill the distractor slots. (The classic Z/S-pentomino was excluded: it
// has 180deg rotational symmetry, leaving only 2 distinct mirrored variants —
// not enough for 3 distractors.) Exported so the test can assert the
// invariant directly against the real shape set, not a hand-copied one.
export const ROTATION_SHAPES = {
  F: [[1, 0], [2, 0], [0, 1], [1, 1], [1, 2]],
  L: [[0, 0], [0, 1], [0, 2], [0, 3], [1, 3]],
  N: [[0, 0], [0, 1], [1, 1], [1, 2], [1, 3]],
  Y: [[1, 0], [0, 1], [1, 1], [1, 2], [1, 3]],
};

function normalizeCells(cells) {
  const minX = Math.min(...cells.map(([x]) => x));
  const minY = Math.min(...cells.map(([, y]) => y));
  return cells.map(([x, y]) => [x - minX, y - minY]).sort((a, b) => a[0] - b[0] || a[1] - b[1]);
}

// Rotate 90deg clockwise `times` times (0-3) around the origin, then
// re-normalize into the non-negative quadrant. Exported so tests can verify
// the ROTATION_SHAPES chirality invariant directly (see meatspacePostCognitive.test.js).
export function rotateCells(cells, times) {
  let pts = cells;
  for (let t = 0; t < ((times % 4) + 4) % 4; t++) {
    pts = pts.map(([x, y]) => [y, -x]);
  }
  return normalizeCells(pts);
}

// Mirror across the vertical axis (flip x) — same footprint size, opposite
// chirality, so it looks similar but is not reachable by rotation alone.
export function mirrorCells(cells) {
  return normalizeCells(cells.map(([x, y]) => [-x, y]));
}

export function cellsKey(cells) {
  return cells.map(([x, y]) => `${x},${y}`).join('|');
}

// =============================================================================
// GENERATORS
// =============================================================================

/**
 * N-back sequence. ~30% of decision positions (index >= n) are targets — the
 * current letter equals the one N steps back. `targets` is a convenience mirror
 * for the client; scoring recomputes it from `sequence` + `config.n`.
 */
export function generateNBack(config = {}) {
  const n = clampInt(config.n, 1, 3, 2);
  const length = clampInt(config.length, n + 5, 60, 20);
  const sequence = [];
  const targets = [];
  for (let i = 0; i < length; i++) {
    if (i < n) {
      sequence.push(pick(NBACK_LETTERS));
      targets.push(false);
    } else if (Math.random() < 0.3) {
      sequence.push(sequence[i - n]);
      targets.push(true);
    } else {
      const nBackItem = sequence[i - n];
      let letter = pick(NBACK_LETTERS);
      if (letter === nBackItem) letter = pick(NBACK_LETTERS.filter(l => l !== nBackItem));
      sequence.push(letter);
      targets.push(false);
    }
  }

  // Guarantee BOTH signal classes among the decision positions (issue #2094):
  // the SDT scorer needs at least one target and one non-target, or a missing
  // class degrades to chance and caps the achievable score at 75. The random
  // 30% roll can produce an all-non-target (or, rarely, all-target) run, so
  // mutate one decision position until both classes exist. Targets are always
  // recomputed from the sequence after a mutation — changing sequence[i] also
  // flips whether i+n is a target, so the mirror can never be hand-patched.
  const recomputeTargets = () => {
    for (let i = 0; i < length; i++) {
      targets[i] = i >= n && sequence[i] === sequence[i - n];
    }
  };
  let classGuard = 0;
  while (classGuard++ < 20) {
    const decisions = targets.slice(n);
    const hasTarget = decisions.some(Boolean);
    const hasNonTarget = decisions.some(t => !t);
    if (hasTarget && hasNonTarget) break;
    const i = n + Math.floor(Math.random() * (length - n));
    if (!hasTarget) {
      sequence[i] = sequence[i - n];
    } else {
      sequence[i] = pick(NBACK_LETTERS.filter(l => l !== sequence[i - n]));
    }
    recomputeTargets();
  }

  return {
    type: 'n-back',
    config: { n, length, stimulusMs: clampInt(config.stimulusMs, 1000, 5000, 2500) },
    sequence,
    targets,
  };
}

/**
 * Digit-span trials of increasing length, from startLength to maxLength. The
 * expected recall is the sequence forward, or reversed for the backward variant.
 */
export function generateDigitSpan(config = {}) {
  const direction = config.direction === 'backward' ? 'backward' : 'forward';
  const { low, high } = COGNITIVE_PAIR_CONSTRAINTS['digit-span'];
  const startLength = clampInt(config.startLength, low.min, low.max, low.fallback);
  const maxLength = clampInt(config.maxLength, Math.max(high.min, startLength), high.max, high.fallback);
  const sequences = [];
  for (let len = startLength; len <= maxLength; len++) {
    const digits = [];
    for (let i = 0; i < len; i++) digits.push(Math.floor(Math.random() * 10));
    sequences.push({ digits, length: len });
  }
  return {
    type: 'digit-span',
    config: { direction, startLength, maxLength, showMs: clampInt(config.showMs, 400, 4000, 1000) },
    sequences,
  };
}

/**
 * Stroop trials with an exact configured conflict mix. Congruent trials have a
 * matching word and ink; incongruent trials deliberately disagree. The correct
 * answer is always the INK color.
 */
export function generateStroop(config = {}) {
  const count = clampInt(config.count, 5, 40, 15);
  const incongruentPct = clampInt(config.incongruentPct, 0, 100, 75);
  const incongruentCount = Math.round(count * incongruentPct / 100);
  const conflictFlags = shuffle([
    ...Array.from({ length: incongruentCount }, () => true),
    ...Array.from({ length: count - incongruentCount }, () => false),
  ]);
  const trials = [];
  for (let i = 0; i < count; i++) {
    const wordColor = pick(STROOP_COLORS);
    const inkColor = conflictFlags[i]
      ? pick(STROOP_COLORS.filter(c => c.name !== wordColor.name))
      : wordColor;
    trials.push({
      word: wordColor.name,
      inkColor: inkColor.name,
      inkHex: inkColor.hex,
      congruent: wordColor.name === inkColor.name,
    });
  }
  return {
    type: 'stroop',
    config: { count, incongruentPct },
    trials,
    options: STROOP_COLORS.map(c => ({ name: c.name, hex: c.hex })),
  };
}

/**
 * Schulte table: a size x size grid holding the numbers 1..size*size shuffled
 * into random cells. The player scans the grid and taps 1, 2, 3... in order —
 * pure visual-attention/scan-speed, no recall required.
 */
export function generateSchulteTable(config = {}) {
  const size = clampInt(config.size, 3, 7, 5);
  const total = size * size;
  const numbers = Array.from({ length: total }, (_, i) => i + 1);
  const cells = shuffle(numbers);
  return {
    type: 'schulte-table',
    config: { size },
    cells,
  };
}

/**
 * Mental rotation: each trial shows a reference shape (an asymmetric
 * grid-cell footprint) and 2-4 candidate shapes — exactly one is the reference
 * rotated (0/90/180/270deg); the rest are mirrored (reflected) at a random
 * rotation, so they share a silhouette "feel" without being a true rotation
 * match. The stored `correctIndex` supports immediate client feedback; server
 * scoring independently derives the answer from `shape`/`rotationSteps` and
 * the generated options.
 */
export function generateMentalRotation(config = {}) {
  const count = clampInt(config.count, 4, 20, 8);
  const rotationComplexity = clampInt(config.rotationComplexity, 1, 3, 3);
  const optionCount = clampInt(config.optionCount, 2, 4, 4);
  const shapeKeys = Object.keys(ROTATION_SHAPES);
  const trials = [];
  for (let i = 0; i < count; i++) {
    const shapeKey = pick(shapeKeys);
    const baseCells = ROTATION_SHAPES[shapeKey];
    const rotationSteps = 1 + Math.floor(Math.random() * rotationComplexity);
    const correctCells = rotateCells(baseCells, rotationSteps);

    const options = [{ cells: correctCells, isMatch: true }];
    let guard = 0;
    while (options.length < optionCount && guard < 50) {
      guard++;
      const mirrored = mirrorCells(rotateCells(baseCells, Math.floor(Math.random() * 4)));
      const key = cellsKey(mirrored);
      if (options.some(o => cellsKey(o.cells) === key)) continue;
      options.push({ cells: mirrored, isMatch: false });
    }
    const shuffled = shuffle(options);
    const correctIndex = shuffled.findIndex(o => o.isMatch);

    trials.push({
      shape: shapeKey,
      rotationSteps,
      target: normalizeCells(baseCells),
      options: shuffled.map(o => o.cells),
      correctIndex,
    });
  }
  return { type: 'mental-rotation', config: { count, gridSize: 4, rotationComplexity, optionCount }, trials };
}

/**
 * Reaction time: simple (react the instant a stimulus appears) or choice
 * (react to WHICH of `choices` stimuli appeared) RT baseline. Each trial's
 * `delayMs` is randomized so the stimulus onset can't be anticipated.
 */
export function generateReactionTime(config = {}) {
  const mode = config.mode === 'choice' ? 'choice' : 'simple';
  const count = clampInt(config.count, 5, 40, 15);
  const { low, high } = COGNITIVE_PAIR_CONSTRAINTS['reaction-time'];
  const minDelayMs = clampInt(config.minDelayMs, low.min, low.max, low.fallback);
  const maxDelayMs = Math.max(minDelayMs, clampInt(config.maxDelayMs, high.min, high.max, high.fallback));
  // `choices` is only meaningful (and only schema-valid, min 2) in choice mode —
  // simple mode omits it entirely rather than persisting an out-of-range value
  // like 1, which session submission's `choices: min(2)` schema would reject.
  const choices = mode === 'choice' ? clampInt(config.choices, 2, 4, 3) : undefined;

  const trials = [];
  for (let i = 0; i < count; i++) {
    const delayMs = minDelayMs + Math.floor(Math.random() * (maxDelayMs - minDelayMs + 1));
    const trial = { delayMs };
    if (mode === 'choice') trial.target = Math.floor(Math.random() * choices);
    trials.push(trial);
  }
  const trialConfig = { mode, count, minDelayMs, maxDelayMs };
  if (choices !== undefined) trialConfig.choices = choices;
  return { type: 'reaction-time', config: trialConfig, trials };
}

const TASK_SWITCH_RULES = [
  { id: 'color', values: ['blue', 'orange'] },
  { id: 'shape', values: ['circle', 'triangle'] },
  { id: 'fill', values: ['solid', 'outline'] },
];

function taskSwitchAnswer(trial) {
  const rule = TASK_SWITCH_RULES.find(candidate => candidate.id === trial?.rule);
  const value = trial?.stimulus?.[trial?.rule];
  const index = rule?.values.indexOf(value) ?? -1;
  return index === 0 ? 'left' : index === 1 ? 'right' : null;
}

/** Seeded cued task switching with an exact switch/conflict mix. */
export function generateTaskSwitching(config = {}) {
  const seed = seedString(config.seed);
  const random = seededRandom(seed);
  const count = clampInt(config.count, 6, 50, 18);
  const ruleCount = clampInt(config.ruleCount, 2, 3, 2);
  const switchRatePct = clampInt(config.switchRatePct, 0, 100, 50);
  const cueStimulusIntervalMs = clampInt(config.cueStimulusIntervalMs, 100, 2000, 700);
  const incongruentPct = clampInt(config.incongruentPct, 0, 100, 50);
  const responseDeadlineMs = clampInt(config.responseDeadlineMs, 500, 5000, 2200);
  const rules = TASK_SWITCH_RULES.slice(0, ruleCount);
  const switchCount = Math.round(Math.max(0, count - 1) * switchRatePct / 100);
  const switchFlags = [false, ...shuffleWith([
    ...Array.from({ length: switchCount }, () => true),
    ...Array.from({ length: Math.max(0, count - 1 - switchCount) }, () => false),
  ], random)];
  const incongruentCount = Math.round(count * incongruentPct / 100);
  const conflictFlags = shuffleWith([
    ...Array.from({ length: incongruentCount }, () => true),
    ...Array.from({ length: count - incongruentCount }, () => false),
  ], random);
  let currentRule = pickWith(rules, random);
  const trials = switchFlags.map((switched, index) => {
    if (switched) currentRule = pickWith(rules.filter(rule => rule.id !== currentRule.id), random);
    const activeIndex = random() < 0.5 ? 0 : 1;
    const stimulus = {};
    for (const rule of rules) stimulus[rule.id] = rule.values[activeIndex];
    if (conflictFlags[index]) {
      const competing = pickWith(rules.filter(rule => rule.id !== currentRule.id), random);
      stimulus[competing.id] = competing.values[1 - activeIndex];
    }
    return {
      rule: currentRule.id,
      stimulus,
      switched,
      incongruent: conflictFlags[index],
    };
  });
  return {
    type: 'task-switching',
    config: { seed, count, ruleCount, switchRatePct, cueStimulusIntervalMs, incongruentPct, responseDeadlineMs },
    rules,
    trials,
  };
}

/** Seeded Go/No-Go sequence with an exact no-go frequency. */
export function generateGoNoGo(config = {}) {
  const seed = seedString(config.seed);
  const random = seededRandom(seed);
  const count = clampInt(config.count, 6, 60, 20);
  const noGoPct = clampInt(config.noGoPct, 5, 80, 25);
  const { low, high } = COGNITIVE_PAIR_CONSTRAINTS['go-no-go'];
  const stimulusMs = clampInt(config.stimulusMs, low.min, low.max, low.fallback);
  const responseDeadlineMs = clampInt(config.responseDeadlineMs, Math.max(high.min, stimulusMs), high.max, high.fallback);
  const lureSimilarity = config.lureSimilarity === 'high' ? 'high' : 'low';
  const noGoCount = Math.round(count * noGoPct / 100);
  const flags = shuffleWith([
    ...Array.from({ length: noGoCount }, () => true),
    ...Array.from({ length: count - noGoCount }, () => false),
  ], random);
  const trials = flags.map((noGo, index) => ({
    kind: noGo ? 'no-go' : 'go',
    symbol: lureSimilarity === 'high' ? (noGo ? '◉' : '●') : (noGo ? '■' : '●'),
    tone: lureSimilarity === 'high' ? (noGo ? 'amber' : 'green') : (noGo ? 'red' : 'green'),
    variant: index % 2,
  }));
  return {
    type: 'go-no-go',
    config: { seed, count, noGoPct, stimulusMs, lureSimilarity, responseDeadlineMs },
    trials,
  };
}

/** Seeded Eriksen-style flanker trials with an exact congruency mix. */
export function generateFlanker(config = {}) {
  const seed = seedString(config.seed);
  const random = seededRandom(seed);
  const count = clampInt(config.count, 6, 60, 20);
  const congruentPct = clampInt(config.congruentPct, 0, 100, 60);
  const flankerDistance = clampInt(config.flankerDistance, 1, 4, 2);
  const flankerStrength = clampInt(config.flankerStrength, 1, 3, 2);
  const responseDeadlineMs = clampInt(config.responseDeadlineMs, 500, 5000, 1600);
  const congruentCount = Math.round(count * congruentPct / 100);
  const flags = shuffleWith([
    ...Array.from({ length: congruentCount }, () => true),
    ...Array.from({ length: count - congruentCount }, () => false),
  ], random);
  const trials = flags.map(congruent => {
    const target = random() < 0.5 ? 'left' : 'right';
    return { target, flanker: congruent ? target : target === 'left' ? 'right' : 'left', congruent };
  });
  return {
    type: 'flanker',
    config: { seed, count, congruentPct, flankerDistance, flankerStrength, responseDeadlineMs },
    trials,
  };
}

export function generateCognitiveDrill(type, config = {}) {
  let drill;
  switch (type) {
    case 'n-back':
      drill = generateNBack(config);
      break;
    case 'digit-span':
      drill = generateDigitSpan(config);
      break;
    case 'stroop':
      drill = generateStroop(config);
      break;
    case 'schulte-table':
      drill = generateSchulteTable(config);
      break;
    case 'mental-rotation':
      drill = generateMentalRotation(config);
      break;
    case 'reaction-time':
      drill = generateReactionTime(config);
      break;
    case 'task-switching':
      drill = generateTaskSwitching(config);
      break;
    case 'go-no-go':
      drill = generateGoNoGo(config);
      break;
    case 'flanker':
      drill = generateFlanker(config);
      break;
    default:
      return null;
  }
  // Stamp the effective progression level into the generated drill's config so
  // it round-trips through the client and is persisted per-task on session
  // submit — the difficulty stamp that lets stats bucket by rung (n=2 vs n=3),
  // exactly as multiplication stamps `config.level` (issue #2095).
  if (drill && Number.isInteger(config.level)) {
    drill.config = { ...drill.config, level: config.level };
  }
  return drill;
}

// =============================================================================
// SCORERS (recompute the answer key from drillData — never trust client marks)
// =============================================================================

function scoreNBack(drillData, questions) {
  const sequence = drillData?.sequence || [];
  const n = drillData?.config?.n ?? 2;
  const refMs = drillData?.config?.stimulusMs || 2500;
  const recomputed = questions.map(q => {
    const i = Number.isInteger(q.index) ? q.index : -1;
    const isTarget = i >= n && sequence[i] != null && sequence[i] === sequence[i - n];
    const expected = isTarget ? 'match' : 'no-match';
    // Withholding a press IS the "no-match" answer — n-back is a go/no-go task,
    // so a skip is a deliberate response, not an unreached trial.
    const answered = q.answered === 'match' ? 'match' : q.answered == null ? null : 'no-match';
    const effective = answered === 'match' ? 'match' : 'no-match';
    return {
      prompt: q.prompt ?? (i >= 0 ? sequence[i] : ''),
      index: i,
      expected,
      answered,
      correct: effective === expected,
      responseMs: clampMs(q.responseMs, refMs),
    };
  });

  // Signal-detection tally: hits/misses over targets, correct-rejections/false-
  // alarms over non-targets. Scoring on RAW position accuracy (the old behaviour)
  // rewarded never pressing — with ~30% target density a do-nothing run scored
  // ~70%. Balanced accuracy — the mean of hit rate and correct-rejection rate —
  // fixes that: a zero-response run scores ~50 (chance) and an always-press run
  // is equally penalised for its false alarms (issue #2094).
  let hits = 0, misses = 0, falseAlarms = 0, correctRejections = 0;
  for (const q of recomputed) {
    const pressed = q.answered === 'match';
    if (q.expected === 'match') {
      if (pressed) hits += 1; else misses += 1;
    } else if (pressed) {
      falseAlarms += 1;
    } else {
      correctRejections += 1;
    }
  }
  const targets = hits + misses;
  const nonTargets = correctRejections + falseAlarms;
  const hitRate = targets ? hits / targets : null;
  const correctRejectionRate = nonTargets ? correctRejections / nonTargets : null;
  // Balanced accuracy. A missing signal class (a run with only targets or only
  // non-targets — possible in legacy/short stored sequences even though the
  // generator now guarantees both) counts as CHANCE (0.5), not as a free pass:
  // otherwise never pressing through an all-non-target run would bank a perfect
  // correct-rejection rate and score 100 — the exact do-nothing exploit this
  // scorer exists to close. Single-class ceilings are therefore 75, floors 25.
  const accuracy = hitRate == null && correctRejectionRate == null
    ? null
    : ((hitRate ?? 0.5) + (correctRejectionRate ?? 0.5)) / 2;

  const presses = recomputed.filter(q => q.answered === 'match' && q.responseMs > 0);
  const avgResponseMs = presses.length
    ? Math.round(presses.reduce((s, q) => s + q.responseMs, 0) / presses.length)
    : null;

  return {
    score: accuracy == null ? 0 : Math.min(100, Math.max(0, Math.round(accuracy * 100))),
    questions: recomputed,
    accuracy,
    // Every trial in a go/no-go n-back gets a decision, so completion is 1 when
    // any trial ran (the metric exists for reader uniformity, not signal).
    completion: recomputed.length ? 1 : null,
    avgResponseMs,
    answeredCount: recomputed.length,
    totalCount: recomputed.length,
    hits,
    misses,
    falseAlarms,
    correctRejections,
  };
}

function scoreDigitSpan(drillData, questions) {
  const sequences = drillData?.sequences || [];
  const direction = drillData?.config?.direction === 'backward' ? 'backward' : 'forward';
  const maxLength = drillData?.config?.maxLength || 12;
  const recomputed = questions.map(q => {
    const seq = sequences[q.index] || {};
    const digits = Array.isArray(seq.digits) ? seq.digits : [];
    const ordered = direction === 'backward' ? [...digits].reverse() : digits;
    const expected = ordered.join('');
    const answered = q.answered == null ? null : String(q.answered).replace(/\D/g, '');
    const correct = expected.length > 0 && answered === expected;
    return {
      prompt: q.prompt ?? `${digits.length}-digit (${direction})`,
      index: q.index,
      expected,
      answered,
      correct,
      length: digits.length,
      responseMs: clampMs(q.responseMs, (digits.length || 1) * 2000),
    };
  });
  // Span-weighted: accuracy + reaching longer spans. Speed is not part of a
  // recall span, so this scorer intentionally omits the RT bonus.
  const correctRatio = recomputed.length ? recomputed.filter(q => q.correct).length / recomputed.length : 0;
  const span = recomputed.filter(q => q.correct).reduce((m, q) => Math.max(m, q.length || 0), 0);
  const spanBonus = maxLength > 0 ? Math.min(1, span / maxLength) : 0;
  const score = Math.min(100, Math.max(0, Math.round((correctRatio * 0.7 + spanBonus * 0.3) * 100)));
  return { score, questions: recomputed, span, ...answeredMetrics(recomputed) };
}

function scoreStroop(drillData, questions) {
  const trials = drillData?.trials || [];
  const refMs = 1500;
  const recomputed = questions.map(q => {
    const trial = trials[q.index] || {};
    const expected = trial.inkColor || '';
    const answered = q.answered == null ? null : String(q.answered).toLowerCase().trim();
    return {
      prompt: q.prompt ?? trial.word ?? '',
      index: q.index,
      expected,
      answered,
      correct: expected !== '' && answered === expected,
      responseMs: clampMs(q.responseMs, refMs),
    };
  });
  return { score: accuracySpeedScore(recomputed, refMs), questions: recomputed, ...answeredMetrics(recomputed) };
}

// Schulte table: questions are the COMPLETE ordered click event stream. The
// server owns `currentTarget` and advances it only after a valid matching click;
// client-supplied index/expected/correct fields are ignored. That preserves
// wrong taps and repeated inputs as performance evidence instead of reconstructing
// an impossible perfect run from only successful targets.
function scoreSchulteTable(drillData, questions) {
  const size = drillData?.config?.size || 5;
  const generatedCells = Array.isArray(drillData?.cells)
    ? drillData.cells.filter(value => Number.isInteger(value) && value > 0)
    : [];
  const total = generatedCells.length || size * size;
  const tableValues = new Set(generatedCells.length
    ? generatedCells
    : Array.from({ length: total }, (_, i) => i + 1));
  const refMs = 1000 + Math.round(Math.sqrt(total)) * 500;
  const recomputed = [];
  let currentTarget = 1;
  for (const event of questions) {
    if (currentTarget > total) break;
    const selected = event?.answered == null ? null : Number(event.answered);
    const answered = Number.isInteger(selected) && tableValues.has(selected) ? selected : null;
    const correct = answered === currentTarget;
    recomputed.push({
      prompt: `${currentTarget}`,
      index: currentTarget - 1,
      expected: currentTarget,
      answered,
      correct,
      responseMs: clampMs(event?.responseMs, refMs),
    });
    if (correct) currentTarget += 1;
  }

  const correctEvents = recomputed.filter(event => event.correct);
  const attemptCount = recomputed.length;
  const answeredCount = correctEvents.length;
  const errorCount = attemptCount - answeredCount;
  const accuracy = attemptCount ? answeredCount / attemptCount : null;
  const completion = total ? answeredCount / total : null;
  const avgResponseMs = answeredCount
    ? Math.round(correctEvents.reduce((sum, event) => sum + event.responseMs, 0) / answeredCount)
    : null;
  const speedBonus = avgResponseMs == null ? 0 : Math.max(0, 1 - avgResponseMs / refMs);
  const score = Math.round(((accuracy || 0) * 0.8 + speedBonus * 0.2) * (completion || 0) * 100);
  return {
    score,
    questions: recomputed,
    accuracy,
    completion,
    avgResponseMs,
    answeredCount,
    totalCount: total,
    attemptCount,
    errorCount,
  };
}

// Mental rotation: `index` selects the trial; `answered` is the option index
// (0-3) the player picked. Expected is recomputed from `trials[index]`, never
// trusted from the client round-trip.
function scoreMentalRotation(drillData, questions) {
  const trials = drillData?.trials || [];
  const refMs = 6000;
  const recomputed = questions.map(q => {
    const trial = trials[q.index] || {};
    const baseCells = ROTATION_SHAPES[trial.shape];
    const generatedExpected = baseCells && Number.isInteger(trial.rotationSteps) && Array.isArray(trial.options)
      ? trial.options.findIndex(cells => cellsKey(normalizeCells(cells)) === cellsKey(rotateCells(baseCells, trial.rotationSteps)))
      : -1;
    // Legacy generated drills predate rotationSteps, so retain their stored
    // answer-key fallback. New drills recompute from shape + transformation +
    // options and never trust correctIndex.
    const expected = generatedExpected >= 0
      ? generatedExpected
      : Number.isInteger(trial.correctIndex) ? trial.correctIndex : null;
    const answered = q.answered == null ? null : Number(q.answered);
    return {
      prompt: q.prompt ?? `shape ${trial.shape ?? ''}`,
      index: q.index,
      expected,
      answered,
      correct: expected != null && answered === expected,
      responseMs: clampMs(q.responseMs, refMs),
    };
  });
  return { score: accuracySpeedScore(recomputed, refMs), questions: recomputed, ...answeredMetrics(recomputed) };
}

// Reaction time: 'simple' trials just need a clean (non-false-start) press;
// 'choice' trials must also match the lit target index. A `falseStart` (press
// before the stimulus appeared) is always wrong regardless of client claims.
function scoreReactionTime(drillData, questions) {
  const trials = drillData?.trials || [];
  const mode = drillData?.config?.mode === 'choice' ? 'choice' : 'simple';
  // `refMs` is the "slow" bound (score 0); `fastMs` the "elite" ceiling (score
  // 100). A choice reaction is inherently slower, so both shift up in choice mode.
  const refMs = mode === 'choice' ? 1200 : 600;
  const fastMs = mode === 'choice' ? 400 : 200;
  const recomputed = questions.map(q => {
    const trial = trials[q.index] || {};
    const falseStart = q.falseStart === true;
    let expected;
    let answered;
    let correct;
    if (mode === 'choice') {
      expected = Number.isInteger(trial.target) ? String(trial.target) : null;
      answered = falseStart || q.answered == null ? null : String(q.answered);
      correct = !falseStart && expected != null && answered === expected;
    } else {
      expected = 'react';
      answered = falseStart ? 'false-start' : q.responseMs > 0 ? 'react' : null;
      correct = answered === 'react';
    }
    return {
      prompt: mode === 'choice' ? `target ${trial.target ?? ''}` : 'react',
      index: q.index,
      expected,
      answered,
      correct,
      falseStart,
      responseMs: clampMs(q.responseMs, refMs * 3),
    };
  });

  // Latency IS the score: reaction time is a speed measure, so a valid trial's
  // median RT vs a reference curve drives the score (issue #2094). A false start
  // (pressing before the stimulus) invalidates its trial; in choice mode a wrong
  // target also invalidates it. In simple mode "correct" == a clean, timed press.
  // The latency score is then scaled by the VALID-TRIAL RATE — otherwise one
  // lucky 200ms press among a run of false starts would persist a perfect 100
  // headline score. Mirrors the blended-score convention everywhere else, where
  // completion/invalid trials fold into the headline number while the separated
  // medianMs/accuracy metrics stay pure.
  const valid = recomputed.filter(q => q.correct && !q.falseStart && q.responseMs > 0);
  const latencies = valid.map(q => q.responseMs);
  const medianMs = median(latencies);
  const bestMs = latencies.length ? Math.min(...latencies) : null;
  const totalTrials = recomputed.length;
  const validRate = totalTrials ? valid.length / totalTrials : 0;
  const latencyScore = medianMs == null
    ? 0
    : Math.min(100, Math.max(0, (100 * (refMs - medianMs)) / (refMs - fastMs)));
  const score = Math.round(latencyScore * validRate);

  // A press attempt is any non-false-start trial with a real latency; accuracy is
  // the share of those that were valid (in simple mode every clean press is valid,
  // so accuracy tracks the false-start-free rate; in choice mode it's target hits).
  const pressed = recomputed.filter(q => !q.falseStart && q.responseMs > 0);
  const totalCount = recomputed.length;
  return {
    score,
    questions: recomputed,
    medianMs,
    bestMs,
    accuracy: pressed.length ? valid.length / pressed.length : null,
    completion: totalCount ? pressed.length / totalCount : null,
    avgResponseMs: latencies.length
      ? Math.round(latencies.reduce((s, ms) => s + ms, 0) / latencies.length)
      : null,
    answeredCount: pressed.length,
    totalCount,
  };
}

function averageLatency(questions) {
  const timed = questions.filter(question => question.correct && question.responseMs > 0);
  return timed.length ? Math.round(timed.reduce((sum, question) => sum + question.responseMs, 0) / timed.length) : null;
}

function groupAccuracy(questions, predicate) {
  const group = questions.filter(predicate);
  return group.length ? group.filter(question => question.correct).length / group.length : null;
}

function costBetween(questions, costlyPredicate, baselinePredicate) {
  const costly = averageLatency(questions.filter(costlyPredicate));
  const baseline = averageLatency(questions.filter(baselinePredicate));
  return costly == null || baseline == null ? null : costly - baseline;
}

function executiveMetrics(recomputed, refMs) {
  const totalCount = recomputed.length;
  const attempted = recomputed.filter(question => question.attempted);
  const answered = recomputed.filter(question => question.answered != null);
  const accuracy = attempted.length ? attempted.filter(question => question.correct).length / attempted.length : null;
  const completion = totalCount ? attempted.length / totalCount : null;
  const avgResponseMs = averageLatency(attempted);
  const speedBonus = avgResponseMs == null ? 0 : Math.max(0, 1 - avgResponseMs / refMs);
  return {
    score: Math.round(((accuracy || 0) * 0.8 + speedBonus * 0.2) * (completion || 0) * 100),
    questions: recomputed,
    accuracy,
    completion,
    avgResponseMs,
    answeredCount: answered.length,
    totalCount,
    commissionErrors: answered.filter(question => !question.correct).length,
    omissions: attempted.filter(question => question.answered == null && !question.correct).length,
    latencyDistributionMs: answered.map(question => question.responseMs).filter(ms => ms > 0),
  };
}

function scoreTaskSwitching(drillData, questions) {
  const regenerated = generateTaskSwitching(drillData?.config || {});
  const trials = regenerated.trials;
  const refMs = regenerated.config.responseDeadlineMs;
  const responses = new Map(questions.map(question => [question.index, question]));
  const recomputed = trials.map((trial, index) => {
    const question = responses.get(index);
    const expected = taskSwitchAnswer(trial);
    const answered = question?.answered === 'left' || question?.answered === 'right' ? question.answered : null;
    return {
      prompt: trial.rule || '',
      index,
      expected,
      answered,
      correct: question != null && expected != null && answered === expected,
      attempted: question != null,
      responseMs: clampMs(question?.responseMs, refMs),
      rule: trial.rule,
      switched: trial.switched === true,
      incongruent: trial.incongruent === true,
    };
  });
  return {
    ...executiveMetrics(recomputed, refMs),
    switchCostMs: costBetween(recomputed, question => question.switched, question => !question.switched),
    switchAccuracy: groupAccuracy(recomputed, question => question.attempted && question.switched),
    repeatAccuracy: groupAccuracy(recomputed, question => question.attempted && !question.switched),
  };
}

function scoreGoNoGo(drillData, questions) {
  const regenerated = generateGoNoGo(drillData?.config || {});
  const trials = regenerated.trials;
  const refMs = regenerated.config.responseDeadlineMs;
  const responses = new Map(questions.map(question => [question.index, question]));
  const recomputed = trials.map((trial, index) => {
    const question = responses.get(index);
    const shouldRespond = trial.kind === 'go';
    const answered = question?.answered === 'go' ? 'go' : null;
    return {
      prompt: trial.symbol || '',
      index,
      expected: shouldRespond ? 'go' : 'withhold',
      answered,
      correct: question != null && (shouldRespond ? answered === 'go' : answered == null),
      attempted: question != null,
      responseMs: clampMs(question?.responseMs, refMs),
      noGo: !shouldRespond,
    };
  });
  const attempted = recomputed.filter(question => question.attempted);
  const hits = attempted.filter(question => !question.noGo && question.answered === 'go').length;
  const omissions = attempted.filter(question => !question.noGo && question.answered == null).length;
  const falseAlarms = attempted.filter(question => question.noGo && question.answered === 'go').length;
  const correctRejections = attempted.filter(question => question.noGo && question.answered == null).length;
  const goCount = hits + omissions;
  const noGoCount = falseAlarms + correctRejections;
  const hitRate = goCount ? hits / goCount : null;
  const correctRejectionRate = noGoCount ? correctRejections / noGoCount : null;
  const accuracy = hitRate == null && correctRejectionRate == null
    ? null
    : ((hitRate ?? 0.5) + (correctRejectionRate ?? 0.5)) / 2;
  const pressed = attempted.filter(question => question.answered === 'go');
  const latencies = pressed.map(question => question.responseMs).filter(ms => ms > 0);
  const completion = recomputed.length ? attempted.length / recomputed.length : null;
  return {
    score: accuracy == null ? 0 : Math.round(accuracy * (completion || 0) * 100),
    questions: recomputed,
    accuracy,
    completion,
    avgResponseMs: averageLatency(attempted),
    medianMs: median(latencies),
    bestMs: latencies.length ? Math.min(...latencies) : null,
    answeredCount: pressed.length,
    totalCount: recomputed.length,
    hits,
    omissions,
    falseAlarms,
    commissionErrors: falseAlarms,
    correctRejections,
    falseAlarmRate: noGoCount ? falseAlarms / noGoCount : null,
    latencyDistributionMs: latencies,
  };
}

function scoreFlanker(drillData, questions) {
  const regenerated = generateFlanker(drillData?.config || {});
  const trials = regenerated.trials;
  const refMs = regenerated.config.responseDeadlineMs;
  const responses = new Map(questions.map(question => [question.index, question]));
  const recomputed = trials.map((trial, index) => {
    const question = responses.get(index);
    const expected = trial.target === 'left' || trial.target === 'right' ? trial.target : null;
    const answered = question?.answered === 'left' || question?.answered === 'right' ? question.answered : null;
    return {
      prompt: `${trial.flanker || ''}-${trial.target || ''}`,
      index,
      expected,
      answered,
      correct: question != null && expected != null && answered === expected,
      attempted: question != null,
      responseMs: clampMs(question?.responseMs, refMs),
      congruent: trial.congruent === true,
    };
  });
  return {
    ...executiveMetrics(recomputed, refMs),
    congruencyCostMs: costBetween(recomputed, question => !question.congruent, question => question.congruent),
    congruentAccuracy: groupAccuracy(recomputed, question => question.attempted && question.congruent),
    incongruentAccuracy: groupAccuracy(recomputed, question => question.attempted && !question.congruent),
  };
}

/**
 * Rescore a completed cognitive drill from its generated `drillData` + the
 * player's per-trial `questions`. Returns `{ score, questions, span? }`.
 */
export function scoreCognitiveDrill(type, drillData, questions = []) {
  const list = Array.isArray(questions) ? questions : [];
  switch (type) {
    case 'n-back':
      return scoreNBack(drillData, list);
    case 'digit-span':
      return scoreDigitSpan(drillData, list);
    case 'stroop':
      return scoreStroop(drillData, list);
    case 'schulte-table':
      return scoreSchulteTable(drillData, list);
    case 'mental-rotation':
      return scoreMentalRotation(drillData, list);
    case 'reaction-time':
      return scoreReactionTime(drillData, list);
    case 'task-switching':
      return scoreTaskSwitching(drillData, list);
    case 'go-no-go':
      return scoreGoNoGo(drillData, list);
    case 'flanker':
      return scoreFlanker(drillData, list);
    default:
      return { score: 0, questions: list };
  }
}