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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* 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 };
}
}