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

102 KB
Raw Blame
/**
 * MeatSpace POST (Power On Self Test) Service
 *
 * Drill generators, scoring, and session CRUD for cognitive self-tests.
 * Reads/writes to meatspace data files.
 */

import { join } from 'path';
import { randomUUID } from 'crypto';
import { EventEmitter } from 'events';
import { atomicWrite, PATHS, ensureDir, readJSONFile } from '../lib/fileUtils.js';
import { deepMerge } from '../lib/objects.js';
import { createFileWriteQueue } from '../lib/fileWriteQueue.js';
import { LLM_DRILL_TYPES, MEMORY_DRILL_TYPES, POST_SUPPORTED_MEMORY_TYPES } from '../lib/postValidation.js';
import { nBackBalancedAccuracy, resolveEstimationTolerancePct } from '../lib/postScoring.js';
import { normalizeHistoricalPostLlmEvaluation, normalizePostLlmEvaluation } from '../lib/postLlmContracts.js';
import { resolveTopicForDrillType, isTopicEnabled, isMemoryItemEnabled } from '../lib/postTopics.js';
import {
  APPLIED_NUMERACY_DRILL_TYPE,
  APPLIED_NUMERACY_DIFFICULTIES,
  generateAppliedNumeracyDrill,
  scoreAppliedNumeracyDrill,
} from '../lib/postAppliedNumeracy.js';
import { resolveMultiplicationLevel, MASTERY_DEFAULTS } from '../lib/postMultiplicationLadder.js';
import {
  POWERS_MASTERY_DEFAULTS,
  powersPoolForLevel,
  powersTechniqueForPair,
  resolvePowersLevel,
} from '../lib/postPowersLadder.js';
import {
  cognitiveLadder,
  cognitiveLevelConfig,
  resolveCognitiveProgression,
  COGNITIVE_LADDER_TYPES,
  COGNITIVE_MASTERY_DEFAULTS,
} from '../lib/postProgression.js';
import { COGNITIVE_DRILL_TYPES, generateCognitiveDrill, scoreCognitiveDrill } from './meatspacePostCognitive.js';
import {
  applySessionToMemoryItems,
  getMemoryItems,
  getDueMemoryItems,
  expandMemoryQuestionResults,
  normalizeMemoryQuestionResults,
  MASTERY_TARGET_ACCURACY,
} from './meatspacePostMemory.js';
import { applySessionToReviewSchedule, getDueReviews, getRetentionReport } from './meatspacePostReview.js';
// From postTrainingLogStore.js (NOT meatspacePostTraining.js) — that module
// imports getUnifiedActivityStreak from postActivityStreak.js, which in turn
// needs getPostSessions from this file. Importing getAllTrainingEntries via
// meatspacePostTraining.js would close that into a 3-file circular import.
import { getAllTrainingEntries } from './postTrainingLogStore.js';
import { getMorseProgress, MAX_KOCH_LEVEL } from './meatspacePostMorse.js';
import { computePostStreaks, computeUnifiedStreak, normalizeYmd, recordDayKey, withDerivedDayKeys, ymdToUTC, ymdShift } from '../lib/postStreak.js';
import { todayInTimezone } from '../lib/timezone.js';
import { getUserTimezone, userLocalToday as localToday } from './userTimezone.js';
import { getStoredPostSession, listPostSessions, saveStoredPostSession } from './postRunStore.js';
import { ServerError } from '../lib/errorHandler.js';
import { validateCognitivePair } from '../lib/postCognitiveConfig.js';

// Re-export the shared streak helper so existing importers of
// `computePostStreaks` from this module keep working after it moved to
// server/lib/postStreak.js (single implementation — see that file).
export { computePostStreaks };

// `localToday()` = today's `YYYY-MM-DD` in the USER's configured timezone (shared
// helper in server/lib/timezone.js). The process runs `TZ=UTC`, so a bare
// `new Date().toISOString()` day derivation misfiles POSTs around the local/UTC
// midnight boundary — a scored session completed the previous local evening reads
// as "done today," or a just-completed local-day session reads as incomplete
// (issue #2681). Both the session `date` stamp (write side) and the
// `completedToday`/`todayScore`/streak derivations (read side) key off this so
// they agree on the user's local day, mirroring the Daily Driver's tz-correct
// first-visit/handled markers (#2666).

const MEATSPACE_DIR = PATHS.meatspace;
const CONFIG_FILE = join(MEATSPACE_DIR, 'post-config.json');
const queueConfigWrite = createFileWriteQueue();

// Tiny pub/sub (mirrors settingsEvents in server/services/settings.js) so
// features that react to a specific config slice — e.g. meatspacePostReminder.js
// rescheduling its cron when `reminder` changes — can subscribe without
// meatspacePost.js importing back into them (which would create a service
// cycle). This is what makes updatePostConfig() the single place ANY current
// or future caller gets slice-specific side effects "for free", instead of
// each route handler having to remember to bolt one on (#2015).
export const postConfigEvents = new EventEmitter();

// The first fixed benchmark battery is intentionally small and deterministic:
// one seeded arithmetic drill plus one seeded executive-control drill. It is a
// protocol, not a projection of the user's adaptive configuration, so later
// forms can be added without changing the meaning of an existing result.
export const POST_BENCHMARK_PROTOCOL = Object.freeze({
  protocolId: 'post-foundation-battery',
  protocolVersion: 1,
  // v2: benchmark scoring now ignores the user's live config.scoring.weights
  // and mentalMath.drillTypes[type].timeLimitSec, using the protocol's fixed
  // weighting (uniform) and the registered form's timeLimitSec instead — a
  // scoring-contract change, so the version bumps (issue #4442 codex
  // review). A v1-scored session (weighted by whatever config was active at
  // submit time) is no longer "compatible" with a v2 one — benchmarkCompatibility()
  // correctly buckets it as legacy/excluded rather than blending two
  // different scoring formulas into one trend.
  scorerVersion: 'post-deterministic-v2',
  forms: Object.freeze([
    Object.freeze({
      formId: 'a',
      tasks: Object.freeze([
        Object.freeze({ type: 'doubling-chain', domain: 'mental-math', config: Object.freeze({ startValue: 5, steps: 8 }), timeLimitSec: 60 }),
        Object.freeze({ type: 'task-switching', domain: 'cognitive', config: Object.freeze({ seed: 'post-foundation-a', count: 12, ruleCount: 2, switchRatePct: 50, cueStimulusIntervalMs: 700, incongruentPct: 50, responseDeadlineMs: 2200 }) }),
      ]),
    }),
    Object.freeze({
      formId: 'b',
      tasks: Object.freeze([
        Object.freeze({ type: 'doubling-chain', domain: 'mental-math', config: Object.freeze({ startValue: 7, steps: 8 }), timeLimitSec: 60 }),
        Object.freeze({ type: 'task-switching', domain: 'cognitive', config: Object.freeze({ seed: 'post-foundation-b', count: 12, ruleCount: 2, switchRatePct: 50, cueStimulusIntervalMs: 700, incongruentPct: 50, responseDeadlineMs: 2200 }) }),
      ]),
    }),
  ]),
});

// Scorer versions retired by a scoring-contract change (e.g. v1 → v2's fixed
// weights/timeLimit) but still ACCEPTABLE on submit — never rejected/lost —
// so an in-flight benchmark run started under the old formula (client
// fetched the old protocol before a server upgrade landed mid-session) can
// still be saved after the upgrade (issue #4442 codex review; mirrors the
// PROMPT_VERSIONS/integrity-snapshot cross-version pattern in
// taskPromptDefaults.js). Task/config shape is unchanged across scorer versions —
// only the scoring formula moved — so accepting it costs nothing: the
// submission is scored under the CURRENT rules regardless (submitPostSession
// only branches on `sessionData.benchmark` truthiness, not on which scorer
// version it names), and its stored scorerVersion is preserved as submitted,
// so benchmarkCompatibility() still correctly excludes it from the current
// trend as legacy rather than silently blending two formulas together.
const PREVIOUS_BENCHMARK_SCORER_VERSIONS = Object.freeze(['post-deterministic-v1']);

const cloneBenchmarkProtocol = (protocol) => JSON.parse(JSON.stringify(protocol));

export function getPostBenchmarkForm(formId) {
  return POST_BENCHMARK_PROTOCOL.forms.find((form) => form.formId === formId) || null;
}

export async function getPostBenchmarkProtocol() {
  const sessions = await getPostSessions();
  const formIds = new Set(sessions
    .filter((session) => session?.benchmark?.protocolId === POST_BENCHMARK_PROTOCOL.protocolId)
    .slice(-POST_BENCHMARK_PROTOCOL.forms.length)
    .map((session) => session.benchmark.formId));
  const nextForm = POST_BENCHMARK_PROTOCOL.forms.find((form) => !formIds.has(form.formId))
    || POST_BENCHMARK_PROTOCOL.forms[0];
  return { ...cloneBenchmarkProtocol(POST_BENCHMARK_PROTOCOL), nextFormId: nextForm.formId };
}

// A benchmark session is "compatible" only when its stored protocol/version/
// scorer triple exactly matches the CURRENTLY registered protocol — never
// fabricated, never inferred by shape. `null` marks a plain (non-benchmark)
// session so trend code can tell "not a benchmark run" apart from "a
// benchmark run under a retired protocol/scorer version" (issue #4442);
// both are excluded from the compatible series, but for different reasons.
export function benchmarkCompatibility(session) {
  const benchmark = session?.benchmark;
  if (!benchmark) return null;
  return benchmark.protocolId === POST_BENCHMARK_PROTOCOL.protocolId
    && benchmark.protocolVersion === POST_BENCHMARK_PROTOCOL.protocolVersion
    && benchmark.scorerVersion === POST_BENCHMARK_PROTOCOL.scorerVersion
    ? 'compatible'
    : 'legacy';
}

function assertBenchmarkSession(benchmark, tasks, modules) {
  if (!benchmark) return;
  // Accept the current scorer version OR a recognized-but-retired one — see
  // PREVIOUS_BENCHMARK_SCORER_VERSIONS. Rejecting an in-flight run just
  // because the server's scorer version moved on mid-session would lose the
  // user's completed work; the form/task shape hasn't changed, only scoring.
  const versionRecognized = benchmark.scorerVersion === POST_BENCHMARK_PROTOCOL.scorerVersion
    || PREVIOUS_BENCHMARK_SCORER_VERSIONS.includes(benchmark.scorerVersion);
  const form = benchmark.protocolId === POST_BENCHMARK_PROTOCOL.protocolId
    && benchmark.protocolVersion === POST_BENCHMARK_PROTOCOL.protocolVersion
    && versionRecognized
    ? getPostBenchmarkForm(benchmark.formId)
    : null;
  const expectedModules = form ? [...new Set(form.tasks.map((task) => task.domain))] : [];
  const modulesMatch = expectedModules.length === modules.length
    && expectedModules.every((module) => modules.includes(module));
  const tasksMatch = form
    && tasks.length === form.tasks.length
    && form.tasks.every((expected, index) => {
      const actual = tasks[index];
      return actual?.type === expected.type
        && Object.entries(expected.config).every(([key, value]) => actual.config?.[key] === value);
    });
  if (!form || !modulesMatch || !tasksMatch) {
    throw new ServerError('Benchmark session does not match its registered protocol form', {
      status: 400,
      code: 'INVALID_BENCHMARK',
    });
  }
}

const DEFAULT_CONFIG = {
  mentalMath: {
    enabled: true,
    drillTypes: {
      'doubling-chain': { enabled: true, steps: 8, timeLimitSec: 60 },
      'serial-subtraction': { enabled: true, steps: 10, subtrahend: 7, startRange: [100, 200], timeLimitSec: 90 },
      // `progressive` (default ON) makes multiplication ramp up a mastery-gated
      // difficulty ladder (server/lib/postMultiplicationLadder.js) starting at
      // single-digit × single-digit, instead of jumping straight to the fixed
      // `maxDigits` difficulty. `maxDigits` is retained as the fallback for when
      // a user turns the progressive ladder off.
      'multiplication': { enabled: true, count: 10, maxDigits: 2, progressive: true, timeLimitSec: 120 },
      'powers': { enabled: true, bases: [2, 3, 5], maxExponent: 10, count: 8, progressive: true, timeLimitSec: 90 },
      'estimation': { enabled: true, count: 5, tolerancePct: 10, timeLimitSec: 120 },
      // Pure, seeded everyday numeracy scenarios. No provider call or
      // high-stakes domain is involved; the returned seed is stored with each
      // session so the server can rebuild answer keys on submit.
      'applied-numeracy': { enabled: true, count: 5, difficulty: 1, timeLimitSec: 150 }
    }
  },
  llmDrills: {
    enabled: true,
    providerId: null,
    model: null,
    drillTypes: {
      'word-association': { enabled: true, count: 5, timeLimitSec: 120 },
      'story-recall': { enabled: true, count: 3, timeLimitSec: 180 },
      'verbal-fluency': { enabled: true, count: 3, timeLimitSec: 60 },
      'wit-comeback': { enabled: true, count: 5, timeLimitSec: 120 },
      'pun-wordplay': { enabled: true, count: 5, timeLimitSec: 120 }
    }
  },
  // Optional AI judging for the standalone rhetoric trainer. It is explicitly
  // off by default so loading POST or opening the practice page never queues a
  // provider call without a user opting in and saving this block.
  rhetoricEvaluator: {
    enabled: false,
    providerId: null,
    model: null,
    effort: null,
  },
  // Deterministic cognitive drills (working-memory / attention / inhibition).
  // No provider calls — enabled by default since they're free to run. No
  // timeLimitSec — these drills are self-paced/stimulus-driven and never
  // enforce a countdown (see client PostCognitiveDrillRunner.jsx / issue #2008).
  // `progressive` (default ON for laddered drills) ramps difficulty via the
  // per-skill ladders in server/lib/postProgression.js instead of a fixed knob;
  // the manual knobs (incl. stimulusMs/showMs) are the fallback when it's off.
  // reaction-time is a measurement baseline (no ladder, no progressive).
  cognitive: {
    enabled: true,
    drillTypes: {
      'n-back': { enabled: true, progressive: true, n: 2, length: 20, stimulusMs: 2500 },
      'digit-span': { enabled: true, progressive: true, direction: 'forward', startLength: 3, maxLength: 8, showMs: 1000 },
      'stroop': { enabled: true, progressive: true, count: 15, incongruentPct: 75 },
      'schulte-table': { enabled: true, progressive: true, size: 5 },
      'mental-rotation': { enabled: true, progressive: true, count: 8, rotationComplexity: 3, optionCount: 4 },
      'reaction-time': { enabled: true, mode: 'simple', count: 15, minDelayMs: 1000, maxDelayMs: 3000, choices: 3 },
      // Executive-control pack is opt-in for existing installs: additive config
      // must not silently lengthen a user's established composed session.
      'task-switching': { enabled: false, progressive: true, count: 18, ruleCount: 2, switchRatePct: 50, cueStimulusIntervalMs: 700, incongruentPct: 50, responseDeadlineMs: 2200 },
      'go-no-go': { enabled: false, progressive: true, count: 20, noGoPct: 25, stimulusMs: 600, lureSimilarity: 'low', responseDeadlineMs: 1400 },
      'flanker': { enabled: false, progressive: true, count: 20, congruentPct: 60, flankerDistance: 2, flankerStrength: 2, responseDeadlineMs: 1600 }
    }
  },
  // Memory practice (issue #3252). Present so the block's shape is discoverable
  // in the saved config; `items` is deliberately ABSENT — a per-item entry is
  // only written when the user actually switches an item off, and absent =
  // enabled, so a fresh or legacy install rotates every memory item as before.
  memory: {
    enabled: true,
    drillTypes: {
      'memory-fill-blank': { enabled: true },
      'memory-sequence': { enabled: true },
      'memory-element-flash': { enabled: true }
    }
  },
  // Morse participation (issue #3252) — on by default so existing installs keep
  // seeing Koch-progression recommendations; a user not learning CW turns it off
  // from the Practice Plan.
  morse: { enabled: true },
  // Default session composition is a balanced, interleaved mix of the free
  // (no-provider) modules the launcher can actually compose — mental math and
  // deterministic cognitive drills (issue #2100). LLM drills are deliberately
  // excluded: auto-enabling them would queue provider calls the user hasn't
  // consented to (see AGENTS.md's AI Provider Usage Policy) — a user who wants
  // wit/verbal drills in every session adds `llm-drills` here explicitly.
  // `memory` is intentionally NOT a default: composed memory practice is opt-in,
  // so existing installs keep exactly their prior daily session mix. Legacy
  // installs that persisted the old
  // `['mental-math']` default are upgraded to this by migration 159.
  sessionModules: ['mental-math', 'cognitive'],
  // Quick-session target presets are persisted so a user's chosen budget is
  // stable across launcher visits and refreshes. The client mirrors these
  // four values; validation rejects anything outside the supported presets.
  quickDurationMin: 5,
  // Optional practice goals (issue #2100). All fields absent by default so a
  // fresh/legacy install shows no goal UI until the user sets one. Bounds are
  // enforced by postGoalsSchema (server/lib/postValidation.js).
  //   dailyMinutes?   — minutes trained today target
  //   weeklySessions? — scored sessions per rolling 7 days target
  //   streakTarget?   — unified activity-streak (days) target
  //   morseWpmTarget? — Morse effective-WPM target
  goals: {},
  // Per-module weight applied to a session's blended score (issue #2099).
  // Uniform 1.0 defaults reproduce the old unweighted-mean behavior exactly —
  // a user only sees a change once they actually adjust a weight.
  scoring: { weights: { 'mental-math': 1.0, 'llm-drills': 1.0, 'cognitive': 1.0, 'memory': 1.0 } },
  // Opt-in adaptive difficulty (default OFF). When enabled, math drills are
  // nudged harder/easier at generation time from recent scored performance.
  adaptive: { enabled: false },
  // Opt-in daily reminder (default OFF, off-by-default per AGENTS.md's
  // single-user/no-surprise-background-behavior convention). When enabled,
  // meatspacePostReminder.js fires a deterministic (no-LLM) in-app notification
  // at `time` (HH:MM, user's configured timezone) if today's POST is incomplete.
  reminder: { enabled: false, time: '09:00' }
};

// Math tasks are logged under this coarse module in scored sessions, so the
// adaptive signal in meatspacePostAdaptive.js reads `byDrill['mental-math:<type>']`.
export const MATH_MODULE = 'mental-math';

async function ensureMeatspaceDir() {
  await ensureDir(MEATSPACE_DIR);
}

// =============================================================================
// CONFIG
// =============================================================================

export async function getPostConfig() {
  const baseDefaults = structuredClone(DEFAULT_CONFIG);
  const config = await readJSONFile(CONFIG_FILE, baseDefaults, { strict: true });
  return deepMerge(baseDefaults, config);
}

export function updatePostConfig(updates) {
  return queueConfigWrite(() => applyPostConfigUpdate(updates));
}

async function applyPostConfigUpdate(updates) {
  const config = await getPostConfig();
  const merged = deepMerge(config, updates);
  // A partial patch (one field of a pair) is judged against the merged record
  // so it can't evade a relation with an already-stored partner. Only drill
  // types in the patch are checked: unrelated saves never trip on legacy values.
  const pairErrors = Object.keys(updates?.cognitive?.drillTypes || {}).flatMap(type =>
    validateCognitivePair(type, merged.cognitive?.drillTypes?.[type])
      .map(e => ({ path: `cognitive.drillTypes.${type}.${e.field}`, message: e.message })));
  if (pairErrors.length) {
    throw new ServerError('Validation failed', { status: 400, code: 'VALIDATION_ERROR', context: { details: pairErrors } });
  }
  if (updates?.reminder) {
    // Stamp WHEN the reminder's enabled/time settings last changed. Read by
    // meatspacePostReminder.js's missed-slot catch-up: a cron occurrence
    // that fell before this timestamp happened under a DIFFERENT (possibly
    // disabled) configuration, so replaying it after a restart would nag for
    // a slot the current settings never actually owned — e.g. enabling the
    // reminder for an already-past time today, then restarting later that
    // same day, would otherwise catch up a slot the reminder wasn't even
    // active for.
    merged.reminder = { ...merged.reminder, updatedAt: new Date().toISOString() };
  }
  // `goals` is REPLACED wholesale when present in the patch, not deep-merged
  // (issue #2100). deepMerge would otherwise make a set goal impossible to
  // clear: JSON can't send `undefined`, `0` is out of the schema's range, and
  // `{}` would merge into the existing object rather than replace it. Sending
  // the full desired goals object — including `{}` to clear every goal — now
  // takes effect and the launcher/widget goal rows hide again.
  if (updates?.goals !== undefined) {
    merged.goals = { ...updates.goals };
  }
  await ensureMeatspaceDir();
  await atomicWrite(CONFIG_FILE, merged);
  console.log(`🧪 POST config updated`);
  // Emit AFTER the write succeeds so a subscriber (reminder rescheduler, etc.)
  // never reacts to a config change that didn't actually persist. `updates` is
  // included (not just `merged`) so subscribers can gate on which slice was
  // touched rather than re-evaluating on every unrelated save.
  postConfigEvents.emit('post-config:updated', { config: merged, updates });
  return merged;
}

// =============================================================================
// SESSIONS
// =============================================================================

/**
 * @param {{ strict?: boolean }} [options] - `strict: true` throws when
 *   post-sessions.json is present-but-unreadable/corrupt instead of falling back to
 *   an empty session list. Off by default: every existing caller wants the fallback
 *   (an unreadable file shouldn't break a drill you're mid-way through). Callers
 *   that COUNT sessions opt in — a fake 0 there is a lie, not a default (#2726).
 */
async function loadSessions({ strict = false } = {}) {
  return { sessions: await listPostSessions({ strict }) };
}

function normalizeHistoricalLlmEvaluations(session) {
  return {
    ...session,
    tasks: (session?.tasks || []).map((task) => (
      LLM_DRILL_TYPES.includes(task?.type) && task.evaluation
        ? { ...task, evaluation: normalizeHistoricalPostLlmEvaluation(task.evaluation) }
        : task
    )),
  };
}

/**
 * All scored sessions, with each record's `date` RE-DERIVED from its `startedAt`
 * instant in the user's CURRENT timezone (issue #4168). This is the single read
 * boundary for sessions — every stats/streak/history reader and the client go
 * through it — so a `settings.timezone` change re-keys existing history on read
 * instead of leaving days frozen in the zone that was active when they were
 * written. The stored `date` stays as a cache the readers ignore; the write path
 * (`submitPostSession`, via `loadSessions`) is untouched.
 */
export async function getPostSessions(from, to, options) {
  const data = await loadSessions(options);
  const timezone = await getUserTimezone();
  let sessions = withDerivedDayKeys(data.sessions, timezone).map(normalizeHistoricalLlmEvaluations);
  // Re-derivation can move a record across a day boundary, so re-sort rather
  // than trusting the stored-date order `submitPostSession` wrote.
  sessions.sort((a, b) => (a?.date || '').localeCompare(b?.date || ''));
  if (from || to) {
    sessions = sessions.filter((session) => {
      const date = session?.date;
      return date && (!from || date >= from) && (!to || date <= to);
    });
  }
  return sessions;
}

/**
 * One session by id, with the same re-derived `date` the list view gets (#4168)
 * — otherwise the detail drawer would quote the frozen write-time day while the
 * history row beside it shows the re-keyed one.
 */
export async function getPostSession(id) {
  const session = await getStoredPostSession(id);
  if (!session) return null;
  return normalizeHistoricalLlmEvaluations({ ...session, date: recordDayKey(session, await getUserTimezone()) });
}

export async function submitPostSession(sessionData) {
  const config = await getPostConfig();
  const data = await loadSessions();
  const nowDate = new Date();
  const now = nowDate.toISOString();
  // Stamp the session's day in the user's local timezone, so `completedToday`
  // and the day-keyed streak/stats math classify it by the local day the user
  // actually completed it — not the server's UTC day (issue #2681). Derive the
  // day from the SAME `nowDate` used for startedAt/completedAt so a midnight
  // boundary can't split the day key and the timestamps onto different days.
  const todayLocal = await localToday(nowDate);

  // Strip client-provided score/correct — plus every separated metric field
  // (issue #2094) — and recompute server-side. Stripping up front means the
  // LLM/memory branches (which trust the client `score` but never carry these
  // metrics) can't persist stale client-sent values that stats aggregation
  // would then prefer over a questions[] derivation.
  const rawTasks = Array.isArray(sessionData.tasks) ? sessionData.tasks : [];
  assertBenchmarkSession(sessionData.benchmark, rawTasks, sessionData.modules);
  // A math drill's time limit is normally the user's live, editable
  // mentalMath.drillTypes[type].timeLimitSec — but a benchmark's speed bonus
  // must come from the REGISTERED form, or the same protocol/version/scorer
  // could still score differently across runs if the user edits their
  // configured time limit in between (issue #4442 codex review). Resolved
  // once here; assertBenchmarkSession already confirmed the form exists and
  // matches when sessionData.benchmark is present.
  const benchmarkForm = sessionData.benchmark ? getPostBenchmarkForm(sessionData.benchmark.formId) : null;
  const rescoredTasks = rawTasks.map(t => {
    const {
      score: _score, correct: _correct,
      accuracy: _acc, completion: _comp, avgResponseMs: _avg,
      answeredCount: _ac, totalCount: _tc, attemptCount: _attempts, errorCount: _errors,
      medianMs: _med, bestMs: _best, span: _span,
      hits: _h, misses: _m, falseAlarms: _fa, correctRejections: _cr,
      omissions: _omissions, commissionErrors: _commissionErrors,
      switchCostMs: _switchCost, switchAccuracy: _switchAccuracy, repeatAccuracy: _repeatAccuracy,
      congruencyCostMs: _congruencyCost, congruentAccuracy: _congruentAccuracy,
      incongruentAccuracy: _incongruentAccuracy, falseAlarmRate: _falseAlarmRate,
      latencyDistributionMs: _latencyDistribution,
      ...rest
    } = t || {};

    // LLM drills: score was computed server-side via /post/score-llm and
    // passed back by the client. Re-scoring here would add latency + cost.
    // This is a single-user internal tool so client score trust is acceptable.
    // The evaluation field and per-response llmScore/llmFeedback contain the server-generated breakdown.
    if (LLM_DRILL_TYPES.includes(rest.type)) {
      if (!Number.isFinite(t.score)) {
        throw new Error(`Cannot store ${rest.type} result without a validated score`);
      }
      return {
        ...rest,
        evaluation: normalizePostLlmEvaluation(rest.evaluation),
        score: t.score,
      };
    }

    // Memory drills: trust client-side scoring only for supported types
    if (POST_SUPPORTED_MEMORY_TYPES.includes(rest.type)) {
      return {
        ...rest,
        // Multi-blank fill-in-the-blank results carry one indexed response per
        // generated blank. Recompute the question-level flag before storing so
        // history and later readers cannot turn one correct blank into a full
        // prompt pass.
        questions: normalizeMemoryQuestionResults(rest.questions || []),
        score: t.score || 0,
      };
    }
    // Unsupported memory drills: preserve data, zero score.
    if (MEMORY_DRILL_TYPES.includes(rest.type)) {
      return { ...rest, score: 0 };
    }

    // Cognitive drills: deterministic — recompute the answer key from the
    // generated drillData (never trust client `correct`/`score`). Spread the
    // full scored bundle so the separated metrics (accuracy/completion/
    // avgResponseMs, plus n-back SDT counts and reaction-time median/best) are
    // persisted alongside the blended score (issue #2094).
    if (COGNITIVE_DRILL_TYPES.includes(rest.type)) {
      const scored = scoreCognitiveDrill(rest.type, rest.drillData, rest.questions || []);
      return { ...rest, ...scored, scorerProvenance: 'server-deterministic' };
    }

    // Math drills: strip correct from individual questions and rescore
    const sanitizedQuestions = (rest.questions || []).map(q => {
      const { correct: _qCorrect, ...qRest } = q;
      return qRest;
    });
    const benchmarkTimeLimitSec = benchmarkForm?.tasks.find(bt => bt.type === rest.type)?.timeLimitSec;
    const drillConfig = config.mentalMath?.drillTypes?.[rest.type] || {};
    const timeLimitMs = (benchmarkTimeLimitSec ?? drillConfig.timeLimitSec ?? 120) * 1000;
    const scored = scoreDrill(rest.type, sanitizedQuestions, timeLimitMs, rest.config || drillConfig);
    return { ...rest, ...scored };
  });

  // Idempotent submit: the client generates the session id (uuid) and sends it,
  // so a retry after a dropped response upserts the SAME record instead of
  // pushing a duplicate. An id is only trusted here to key the upsert — every
  // scored field is still recomputed server-side above. Absent id (legacy
  // clients / direct service callers) falls back to a fresh uuid.
  const sessionId = sessionData.id || randomUUID();
  const existingIndex = data.sessions.findIndex(s => s.id === sessionId);
  let isNewSession = existingIndex < 0;
  const existing = isNewSession ? null : data.sessions[existingIndex];
  const requestedStartedAtMs = Date.parse(sessionData.startedAt || '');
  const requestedStartedAt = Number.isFinite(requestedStartedAtMs)
    && requestedStartedAtMs <= nowDate.getTime()
    && nowDate.getTime() - requestedStartedAtMs <= 24 * 60 * 60 * 1000
    ? new Date(requestedStartedAtMs).toISOString()
    : now;
  const startedAt = existing?.startedAt ?? requestedStartedAt;
  const startedAtMs = Date.parse(startedAt);
  const actualDurationMs = Number.isFinite(startedAtMs)
    ? Math.max(0, nowDate.getTime() - startedAtMs)
    : 0;

  let session = {
    id: sessionId,
    // Preserve the ORIGINAL day/start on an idempotent re-submit — a retry that
    // crosses midnight (or just arrives later) must not move the session to a
    // new date, which would corrupt history ordering and streak math. Only a
    // fresh insert stamps "now".
    date: existing?.date ?? todayLocal,
    startedAt,
    completedAt: now,
    durationMs: rescoredTasks.reduce((sum, t) => sum + (t.totalMs || 0), 0),
    actualDurationMs,
    cadence: sessionData.cadence || 'daily',
    modules: sessionData.modules,
    tasks: rescoredTasks,
    // Benchmark scoring is fixed by the protocol, never by the user's live
    // scoring.weights config — otherwise two "compatible" (same protocol/
    // version/scorer) runs scored under different weight configs would land
    // in the same trend as though they were on one scale (issue #4442 codex
    // review). Quick/Test/Train sessions keep the configured weights.
    score: computeSessionScore(rescoredTasks, sessionData.benchmark ? undefined : config.scoring?.weights),
    tags: sessionData.tags || {},
    ...(sessionData.conditions && Object.keys(sessionData.conditions).length
      ? { conditions: sessionData.conditions }
      : {}),
    ...(sessionData.plan ? { plan: sessionData.plan } : {}),
    ...(sessionData.benchmark ? { benchmark: sessionData.benchmark } : {}),
  };

  const stored = await saveStoredPostSession(session);
  session = stored.session;
  isNewSession = stored.isNew;
  console.log(`🧪 POST session ${isNewSession ? 'saved' : 'updated'}: score=${session.score} modules=${session.modules.join(',')}`);

  // A memory drill completed inside this session IS a review — mirror the
  // dedicated MemoryBuilder practice flow (submitPractice) and advance each
  // drilled item's spaced-repetition schedule (plus chunk/element mastery from
  // the per-question attribution usePostSession's submitAnswer preserves), so it
  // reschedules and clears from "Due Today". applySessionToMemoryItems reads and
  // writes the shared memory-items file exactly once for the whole session.
  //
  // Two invariants around this call:
  //  1. Only on a NEW session — a retry (same id) re-upserts the durable record
  //     but must NOT re-advance schedules a second time, or a dropped-response
  //     retry would double-count the review.
  //  2. Isolated so it can NEVER 500 an already-persisted session. This runs
  //     AFTER the durable write, so a memory-file failure here is post-response
  //     bookkeeping — log it single-line and still return 200. (Sanctioned
  //     try/catch: the session is already saved; there is nothing to roll back.)
  if (isNewSession) {
    // Pre-filter to POST-supported memory tasks with a memoryItemId — the exact
    // gate the prior per-task loop used, so a future generation-only memory
    // drill is never scheduled even if it somehow carries an id.
    const memoryTasks = rescoredTasks.filter(t => POST_SUPPORTED_MEMORY_TYPES.includes(t.type) && t.memoryItemId);
    try {
      await applySessionToMemoryItems(memoryTasks, new Date(now));
    } catch (err) {
      console.error(`❌ POST session memory post-processing failed (session ${sessionId} still saved): ${err.message}`);
    }
    // Reconcile the skill re-verification schedule (issue #2096): upsert newly-
    // mastered skills, record any maintenance-review reps in this session, and
    // reset the staleness clock for mastered skills actively practiced here.
    // Runs AFTER the memory update above so mastery reflects this session.
    // Isolated so it can never 500 an already-persisted session.
    try {
      await syncReviewScheduleForSession(session, new Date(now));
    } catch (err) {
      console.error(`❌ POST session review-schedule sync failed (session ${sessionId} still saved): ${err.message}`);
    }
  }

  return session;
}

// =============================================================================
// SKILL RE-VERIFICATION (issue #2096) — mastered-skill review scheduling
// =============================================================================

// A maintenance-review rep must reach at least this fraction of its questions to
// count as a genuine re-verification (mirrors COGNITIVE_MASTERY_DEFAULTS
// minCompletion). Below it, the review is recorded as failed rather than passed.
const MIN_REVIEW_COMPLETION = 0.75;
const APPLIED_NUMERACY_MASTERY = { minSamples: 3, accuracy: 0.8, completion: 0.75 };

/**
 * Aggregate complexity-level evidence for Applied Numeracy. Its rungs measure
 * representation changes, units, and multi-step transforms rather than larger
 * operands, so retention can schedule a targeted rep at the earned level.
 */
export async function getAppliedNumeracyProgress() {
  const sessions = await getPostSessions();
  const buckets = Object.fromEntries([1, 2, 3].map(level => [level, { samples: 0, accuracy: 0, completion: 0 }]));
  for (const session of sessions) {
    for (const task of session.tasks || []) {
      if (task.type !== APPLIED_NUMERACY_DRILL_TYPE) continue;
      const level = APPLIED_NUMERACY_DIFFICULTIES.includes(task.config?.difficulty) ? task.config.difficulty : 1;
      const accuracy = deriveTaskAccuracy(task);
      const completion = deriveTaskCompletion(task);
      if (accuracy == null) continue;
      buckets[level].samples += 1;
      buckets[level].accuracy += accuracy;
      buckets[level].completion += completion ?? 1;
    }
  }
  return {
    levels: Object.entries(buckets).map(([level, bucket]) => {
      const samples = bucket.samples;
      const accuracy = samples ? bucket.accuracy / samples : 0;
      const completion = samples ? bucket.completion / samples : 0;
      return {
        level: Number(level),
        samples,
        accuracy,
        completion,
        mastered: samples >= APPLIED_NUMERACY_MASTERY.minSamples
          && accuracy >= APPLIED_NUMERACY_MASTERY.accuracy
          && completion >= APPLIED_NUMERACY_MASTERY.completion,
      };
    }),
  };
}

/**
 * Current mastered-but-inactive skills eligible for re-verification tracking:
 *   - multiplication / Powers rungs strictly BELOW the resolved current level
 *     (you've moved past them, so they're no longer actively drilled),
 *   - cognitive rungs strictly below the current level, per laddered type.
 * Memory items own their durable-mastery + one-time spot-check lifecycle in
 * meatspacePostMemory.js, so they are intentionally not duplicated here.
 * Returns opaque skill descriptors the review scheduler upserts + schedules.
 */
export async function getMasteredSkills() {
  const skills = [];

  const [mul, powers, cog, numeracy] = await Promise.all([
    getMultiplicationProgress(),
    getPowersProgress(),
    getCognitiveProgress(),
    getAppliedNumeracyProgress(),
  ]);
  for (const rung of mul.levels || []) {
    if (rung.mastered && rung.level < mul.level) {
      skills.push({
        skillId: `multiplication:L${rung.level}`,
        kind: 'multiplication',
        label: `Multiplication ${rung.label}`,
        drillType: 'multiplication',
        module: 'mental-math',
        level: rung.level,
        factors: rung.factors,
      });
    }
  }

  for (const rung of powers.levels || []) {
    if (rung.mastered && rung.level < powers.level) {
      skills.push({
        skillId: `powers:L${rung.level}`,
        kind: 'powers',
        label: `Powers ${rung.label}`,
        drillType: 'powers',
        module: 'mental-math',
        level: rung.level,
        config: { technique: rung.technique },
      });
    }
  }

  for (const [type, prog] of Object.entries(cog)) {
    if (!prog) continue;
    for (const rung of prog.levels || []) {
      if (rung.mastered && rung.level < prog.level) {
        skills.push({
          skillId: `cognitive:${type}:L${rung.level}`,
          kind: 'cognitive',
          label: `${type} ${rung.label}`,
          drillType: type,
          module: 'cognitive',
          level: rung.level,
          config: cognitiveLevelConfig(type, rung.level),
        });
      }
    }
  }

  for (const rung of numeracy.levels || []) {
    if (!rung.mastered) continue;
    skills.push({
      skillId: `applied-numeracy:D${rung.level}`,
      kind: APPLIED_NUMERACY_DRILL_TYPE,
      label: `Applied Numeracy level ${rung.level}`,
      drillType: APPLIED_NUMERACY_DRILL_TYPE,
      module: 'mental-math',
      difficulty: rung.level,
    });
  }

  return skills;
}

/**
 * Extract, from a scored session, which tracked skills were exercised:
 *   - `reviewResults`: maintenance-review reps (tasks whose config carries a
 *     `reviewSkillId`), pass/fail decided by the task's answered accuracy.
 *   - `practicedSkillIds`: mastered skills a NORMAL (non-review) task drilled,
 *     so their staleness clock resets (an actively-used skill never goes stale).
 */
export function getSessionSkillContext(session) {
  const practicedSkillIds = new Set();
  const reviewResults = [];
  for (const task of session?.tasks || []) {
    const cfg = task.config || {};
    if (cfg.reviewSkillId) {
      // A review passes only when it's both accurate AND sufficiently completed:
      // accuracy is answered-only, so without the completion gate answering one
      // question correctly and skipping the rest would bank a "pass" (acc===1)
      // and push the interval out without actually re-verifying the skill. A
      // low-completion attempt is recorded as a FAIL → needs-refresh + sooner
      // re-review, which is the safe outcome for a bailed review.
      const acc = deriveTaskAccuracy(task);
      const completion = deriveTaskCompletion(task);
      const passed = acc != null && acc >= MASTERY_TARGET_ACCURACY
        && (completion == null || completion >= MIN_REVIEW_COMPLETION);
      reviewResults.push({ skillId: cfg.reviewSkillId, passed });
      continue;
    }
    if (task.type === 'multiplication' && Number.isInteger(cfg.level)) {
      practicedSkillIds.add(`multiplication:L${cfg.level}`);
    } else if (task.type === 'powers' && Number.isInteger(cfg.level)) {
      practicedSkillIds.add(`powers:L${cfg.level}`);
    } else if (cognitiveLadder(task.type) && Number.isInteger(cfg.level)) {
      practicedSkillIds.add(`cognitive:${task.type}:L${cfg.level}`);
    } else if (task.type === APPLIED_NUMERACY_DRILL_TYPE) {
      const difficulty = APPLIED_NUMERACY_DIFFICULTIES.includes(cfg.difficulty) ? cfg.difficulty : 1;
      practicedSkillIds.add(`applied-numeracy:D${difficulty}`);
    } else if (task.memoryItemId) {
      for (const q of task.questions || []) {
        if (q?.chunkId) practicedSkillIds.add(`memory:${task.memoryItemId}:${q.chunkId}`);
      }
    }
  }
  return { practicedSkillIds: [...practicedSkillIds], reviewResults };
}

/** Reconcile the review schedule against a just-completed scored session. */
export async function syncReviewScheduleForSession(session, now = new Date()) {
  const masteredSkills = await getMasteredSkills();
  const { practicedSkillIds, reviewResults } = getSessionSkillContext(session);
  return applySessionToReviewSchedule({ masteredSkills, practicedSkillIds, reviewResults, now });
}

/**
 * Ready-to-run "maintenance rep" drill specs for the mastered skills currently
 * due for review — the labeled review items the launcher mixes into a Quick
 * session (issue #2096). Multiplication, Powers, and cognitive reps are generated
 * through the standard /post/drill path; memory-chunk retention is served by
 * the existing spaced-repetition due-items flow. Each carries `review: true` +
 * `reviewSkillId` so the session-submit path records the pass/fail.
 */
export async function getPostReviewReps(now = new Date(), limit = 2) {
  // Fetch ALL due reviews, then filter to the runnable kinds BEFORE capping —
  // capping first would let older due memory-chunk entries (which have no
  // runnable rep) consume the limit slots and starve runnable multiplication/
  // cognitive reps that are due later in the schedule.
  const [due, config] = await Promise.all([
    getDueReviews(now, Infinity),
    getPostConfig(),
  ]);
  const reps = [];
  for (const entry of due) {
    if (reps.length >= limit) break;
    // Review reps are mixed directly into Quick sessions, so enforce the same
    // topic, module-composition, module, and per-drill gates as recommendations.
    // A skill may have become due after the user switched that practice off.
    if (!isRecDrillRunnable(config, recModuleForDrillType(entry.drillType, 'cognitive'), entry.drillType)) continue;
    if (entry.kind === 'multiplication') {
      reps.push({
        skillId: entry.skillId,
        label: entry.label,
        state: entry.status === 'needs-refresh' ? 'needs-refresh' : 'due',
        module: 'mental-math',
        type: 'multiplication',
        config: { count: 5, level: entry.level, factors: entry.factors, review: true, reviewSkillId: entry.skillId },
      });
    } else if (entry.kind === 'powers') {
      reps.push({
        skillId: entry.skillId,
        label: entry.label,
        state: entry.status === 'needs-refresh' ? 'needs-refresh' : 'due',
        module: 'mental-math',
        type: 'powers',
        config: { ...(entry.config || {}), count: 5, level: entry.level, review: true, reviewSkillId: entry.skillId },
      });
    } else if (entry.kind === 'cognitive') {
      reps.push({
        skillId: entry.skillId,
        label: entry.label,
        state: entry.status === 'needs-refresh' ? 'needs-refresh' : 'due',
        module: 'cognitive',
        type: entry.drillType,
        config: { ...(entry.config || cognitiveLevelConfig(entry.drillType, entry.level)), level: entry.level, review: true, reviewSkillId: entry.skillId },
      });
    } else if (entry.kind === APPLIED_NUMERACY_DRILL_TYPE) {
      reps.push({
        skillId: entry.skillId,
        label: entry.label,
        state: entry.status === 'needs-refresh' ? 'needs-refresh' : 'due',
        module: 'mental-math',
        type: APPLIED_NUMERACY_DRILL_TYPE,
        config: { count: 5, difficulty: entry.difficulty, review: true, reviewSkillId: entry.skillId },
      });
    }
  }
  return reps;
}

/**
 * Answered-only accuracy for a scored task, tolerant of legacy sessions that
 * predate the persisted `accuracy` field (issue #2094). Order: the stored value
 * first, else derive from `questions[]` (correct over ANSWERED, not total), else
 * `null` — never NaN. Used by stats aggregation and the adaptive signal so old
 * and new session shapes both read cleanly.
 */
// nBackBalancedAccuracy now lives in ../lib/postScoring.js (imported above) —
// re-exported here for existing importers of this module, and the client copy
// in components/meatspace/post/constants.js re-exports the same leaf.
export { nBackBalancedAccuracy };

export function deriveTaskAccuracy(task) {
  if (typeof task?.accuracy === 'number' && !Number.isNaN(task.accuracy)) return task.accuracy;
  const qs = Array.isArray(task?.questions) ? task.questions : [];
  if (!qs.length) return null;
  // n-back is go/no-go: a withheld press is a deliberate "no-match" decision,
  // and its legacy `correct` flags encode the OLD raw-position model — so the
  // fallback recomputes balanced SDT accuracy rather than averaging them
  // (otherwise a legacy never-press run still reads ~70%). Mirrors the client
  // fallbacks in PostHistory/PostSessionResults.
  if (task?.type === 'n-back') return nBackBalancedAccuracy(qs);
  if (task?.type === 'memory-fill-blank') {
    const attempts = expandMemoryQuestionResults(qs);
    return attempts.length ? attempts.filter(q => q?.correct).length / attempts.length : null;
  }
  const answered = qs.filter(q => q?.answered != null);
  if (!answered.length) return null;
  return answered.filter(q => q?.correct).length / answered.length;
}

/**
 * Completion (answered / total) for a scored task, with the same legacy fallback
 * as deriveTaskAccuracy. `null` when there are no questions to derive from.
 * n-back legacy tasks are always fully reached — every trial gets a decision.
 */
export function deriveTaskCompletion(task) {
  if (typeof task?.completion === 'number' && !Number.isNaN(task.completion)) return task.completion;
  const qs = Array.isArray(task?.questions) ? task.questions : [];
  if (!qs.length) return null;
  if (task?.type === 'n-back') return 1;
  if (task?.type === 'memory-fill-blank') {
    const attempts = expandMemoryQuestionResults(qs);
    if (!attempts.length) return null;
    return attempts.filter(q => q?.answered != null).length / attempts.length;
  }
  return qs.filter(q => q?.answered != null).length / qs.length;
}

/**
 * Mean response time (ms) for a scored task, tolerant of legacy sessions that
 * predate the persisted `avgResponseMs` field (issue #2094): the stored value
 * first, else the mean of the answered questions' `responseMs` (>0 only), else
 * `null` — never NaN. Used by progress aggregation so the "getting faster"
 * trend reads cleanly across old and new session shapes.
 */
export function deriveTaskAvgResponseMs(task) {
  if (typeof task?.avgResponseMs === 'number' && !Number.isNaN(task.avgResponseMs)) return task.avgResponseMs;
  const qs = Array.isArray(task?.questions) ? task.questions : [];
  const timed = qs.filter(q => (q?.responseMs || 0) > 0);
  if (!timed.length) return null;
  return Math.round(timed.reduce((sum, q) => sum + q.responseMs, 0) / timed.length);
}

// Normalizes a legacy training-log entry into the scored-task shape the
// session pipeline uses. Stays private: its only cross-module consumer reaches
// it through summarizeSkillEvidence below.
function trainingEntryTask(entry) {
  const rawQuestionCount = Number(entry?.questionCount);
  const rawCorrectCount = Number(entry?.correctCount);
  const questionCount = Number.isFinite(rawQuestionCount) && rawQuestionCount > 0 ? rawQuestionCount : 0;
  const correctCount = Number.isFinite(rawCorrectCount)
    ? Math.max(0, Math.min(questionCount, rawCorrectCount))
    : 0;
  const accuracy = typeof entry?.accuracy === 'number'
    ? entry.accuracy
    : questionCount > 0 ? correctCount / questionCount : null;
  return {
    id: entry?.id,
    module: entry?.module,
    type: entry?.drillType,
    config: entry?.difficulty || {},
    questions: Array.isArray(entry?.questions) ? entry.questions : [],
    score: Number.isFinite(entry?.score) ? entry.score : (accuracy == null ? null : accuracy * 100),
    accuracy,
    completion: typeof entry?.completion === 'number' ? entry.completion : (questionCount > 0 ? 1 : null),
    avgResponseMs: typeof entry?.avgResponseMs === 'number'
      ? entry.avgResponseMs
      : questionCount > 0 ? (entry?.totalMs || 0) / questionCount : null,
    totalMs: entry?.totalMs || 0,
    totalCount: questionCount,
  };
}

function skillEvidenceSessions(sessions, training) {
  return [
    ...sessions,
    ...training.map((entry) => ({
      id: entry.runId || entry.id,
      date: entry.date,
      startedAt: entry.timestamp,
      completedAt: entry.timestamp,
      evidenceMode: 'training',
      tasks: [trainingEntryTask(entry)],
    })),
  ];
}

// Rolls sessions + training entries into per-drill count/accuracy/completion
// means. Consumed by meatspacePostStats.js (getPostStats); declared here beside
// deriveTaskAccuracy/deriveTaskCompletion, which it is built on.
export function summarizeSkillEvidence(sessions, training) {
  const accuracyLists = {};
  const completionLists = {};
  const counts = {};
  const add = (task) => {
    if (!task?.module || !task?.type) return;
    const key = `${task.module}:${task.type}`;
    counts[key] = (counts[key] || 0) + 1;
    const accuracy = deriveTaskAccuracy(task);
    if (accuracy != null) (accuracyLists[key] ||= []).push(accuracy);
    const completion = deriveTaskCompletion(task);
    if (completion != null) (completionLists[key] ||= []).push(completion);
  };
  for (const session of sessions) for (const task of session.tasks || []) add(task);
  for (const entry of training) add(trainingEntryTask(entry));
  const meanMap = (lists) => Object.fromEntries(
    Object.entries(lists).map(([key, values]) => [key, values.reduce((sum, value) => sum + value, 0) / values.length]),
  );
  return {
    evidenceByDrillCount: counts,
    evidenceByDrillAccuracy: meanMap(accuracyLists),
    evidenceByDrillCompletion: meanMap(completionLists),
  };
}

// =============================================================================
// PROGRESS (time-series) — issue #2091
// =============================================================================

function mean(list) {
  return list.length ? list.reduce((a, b) => a + b, 0) / list.length : null;
}

// Accumulate one task's metrics into a `key -> (date -> bucket)` map, so a
// domain/drill series can aggregate multiple same-day tasks into one point.
function pushMetricSeries(map, key, date, score, accuracy, avgResponseMs) {
  if (key == null) return;
  let byDate = map.get(key);
  if (!byDate) { byDate = new Map(); map.set(key, byDate); }
  let bucket = byDate.get(date);
  if (!bucket) { bucket = { scores: [], accs: [], resp: [] }; byDate.set(date, bucket); }
  if (typeof score === 'number' && !Number.isNaN(score)) bucket.scores.push(score);
  if (accuracy != null) bucket.accs.push(accuracy);
  if (avgResponseMs != null) bucket.resp.push(avgResponseMs);
}

// Finalize a `key -> (date -> bucket)` map into `key -> [{ date, score,
// accuracy, avgResponseMs, count }]`, chronologically sorted. `count` is the
// number of score samples bucketed into that day — for a series pushed once
// per session (e.g. the benchmark trend) that's the session count; for a
// series pushed once per task (byDomain/byDrill) it's the task count.
function finalizeMetricSeries(map) {
  const out = {};
  for (const [key, byDate] of map) {
    out[key] = Array.from(byDate.entries())
      .sort(([a], [b]) => a.localeCompare(b))
      .map(([date, b]) => {
        const acc = mean(b.accs);
        const resp = mean(b.resp);
        const score = mean(b.scores);
        return {
          date,
          score: score == null ? null : Math.round(score),
          accuracy: acc == null ? null : acc,
          avgResponseMs: resp == null ? null : Math.round(resp),
          count: b.scores.length,
        };
      });
  }
  return out;
}

/**
 * Time-series progress across scored sessions, the training log, and memory
 * mastery — the data behind the unified Progress dashboard (issue #2091).
 *
 * - `series.byDay`     per-day buckets (same-day sessions aggregated) of score,
 *   accuracy, avg response time, minutes, and session count.
 * - `series.byDomain`  per-day series keyed by coarse module (`mental-math`, …).
 * - `series.byDrill`   per-day series keyed by drill type (`multiplication`, …).
 * - `series.benchmark` protocol-scoped trend: only sessions run under the
 *   CURRENT `POST_BENCHMARK_PROTOCOL` (protocolId+protocolVersion+
 *   scorerVersion), with `excludedCount` covering benchmark runs under a
 *   retired protocol/scorer version (issue #4442). Ordinary Quick/Test/Train
 *   sessions never appear here at all.
 * - `totals`           minutes trained (sessions + practice), session count,
 *   practice-entry count over the window.
 * - `streak`           ONE unified streak (sessions OR training-log activity),
 *   computed over ALL history like `getPostStats`.
 * - `mastery`          multiplication/cognitive ladder evidence + memory items.
 *
 * Accuracy/speed are reported separately (issue #2094): the persisted per-task
 * `accuracy`/`avgResponseMs` are preferred, with a per-question derivation
 * fallback for legacy sessions.
 */
export async function getPostProgress({ days = 90 } = {}) {
  const atDate = new Date();
  const timezone = await getUserTimezone();
  const todayStr = todayInTimezone(timezone, atDate);
  const window = Number.isFinite(days) && days > 0 ? Math.min(days, 365) : 0;

  const allSessions = await getPostSessions();
  const allTraining = await getAllTrainingEntries();

  // Unified streak is computed over ALL history, independent of the window.
  const streak = computeUnifiedStreak(allSessions, allTraining, todayStr, timezone);

  let cutoffStr = null;
  if (window > 0) {
    cutoffStr = new Date(ymdToUTC(todayStr) - window * 86400000).toISOString().split('T')[0];
  }
  const sessions = cutoffStr
    ? allSessions.filter(s => {
      const date = recordDayKey(s, timezone);
      return date && date >= cutoffStr;
    })
    : allSessions;
  const training = cutoffStr
    ? allTraining.filter(e => {
      const date = recordDayKey(e, timezone);
      return date && date >= cutoffStr;
    })
    : allTraining;

  // Per-day buckets for the headline trends, plus per-domain/per-drill series.
  const dayMap = new Map();      // date -> { scores, accs, resp, minutes, sessions }
  const domainMap = new Map();   // module -> Map(date -> metric bucket)
  const drillMap = new Map();    // type   -> Map(date -> metric bucket)
  // Protocol-scoped series (issue #4442): pushed through the SAME date-bucket
  // aggregator as byDomain/byDrill below, under a single constant key, so a
  // benchmark trend is "filter + reuse the existing bucketer" rather than a
  // bespoke Map/ensure/finalize block. Only sessions run under the CURRENT
  // POST_BENCHMARK_PROTOCOL contribute, so the trend never blends across a
  // protocol/scorer version change or with ordinary Quick/Test/Train
  // sessions. `excludedCount` surfaces what was left out (benchmark runs
  // under a retired version) so the UI can say so rather than silently
  // under-counting.
  const benchmarkMap = new Map();
  let benchmarkExcludedCount = 0;

  const ensureDay = (date) => {
    let d = dayMap.get(date);
    if (!d) { d = { scores: [], accs: [], resp: [], minutes: 0, sessions: 0 }; dayMap.set(date, d); }
    return d;
  };

  for (const s of sessions) {
    const date = recordDayKey(s, timezone);
    if (!date) continue;
    const day = ensureDay(date);
    day.sessions += 1;
    day.minutes += (s.durationMs || 0) / 60000;
    if (typeof s.score === 'number' && !Number.isNaN(s.score)) day.scores.push(s.score);

    const compat = benchmarkCompatibility(s);
    if (compat === 'compatible') {
      pushMetricSeries(benchmarkMap, 'benchmark', date, s.score, null, null);
    } else if (compat === 'legacy') {
      benchmarkExcludedCount += 1;
    }

    const sessionAccs = [];
    const sessionResp = [];
    for (const task of s.tasks || []) {
      const acc = deriveTaskAccuracy(task);
      const resp = deriveTaskAvgResponseMs(task);
      if (acc != null) sessionAccs.push(acc);
      if (resp != null) sessionResp.push(resp);
      pushMetricSeries(domainMap, task.module, date, task.score, acc, resp);
      pushMetricSeries(drillMap, task.type, date, task.score, acc, resp);
    }
    const sAcc = mean(sessionAccs);
    if (sAcc != null) day.accs.push(sAcc);
    const sResp = mean(sessionResp);
    if (sResp != null) day.resp.push(sResp);
  }

  // Practice time (Morse / memory) folds into each day's minutes — a practice-
  // only day still shows time-in-training even with no scored session.
  for (const e of training) {
    const date = recordDayKey(e, timezone);
    if (!date) continue;
    ensureDay(date).minutes += (e.totalMs || 0) / 60000;
    const task = trainingEntryTask(e);
    const accuracy = deriveTaskAccuracy(task);
    const responseMs = deriveTaskAvgResponseMs(task);
    // Training updates skill/domain evidence, but it does not enter the scored
    // benchmark headline (`byDay.score`, session count, or overall score).
    pushMetricSeries(domainMap, task.module, date, task.score, accuracy, responseMs);
    pushMetricSeries(drillMap, task.type, date, task.score, accuracy, responseMs);
  }

  const byDay = Array.from(dayMap.entries())
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([date, d]) => {
      const score = mean(d.scores);
      const acc = mean(d.accs);
      const resp = mean(d.resp);
      return {
        date,
        score: score == null ? null : Math.round(score),
        accuracy: acc == null ? null : acc,
        avgResponseMs: resp == null ? null : Math.round(resp),
        minutes: Math.round(d.minutes),
        sessions: d.sessions,
      };
    });

  const benchmarkByDay = (finalizeMetricSeries(benchmarkMap).benchmark || [])
    .map(({ date, score, count }) => ({ date, score, sessions: count }));

  const sessionMs = sessions.reduce((sum, s) => sum + (s.durationMs || 0), 0);
  const trainingMs = training.reduce((sum, e) => sum + (e.totalMs || 0), 0);

  // Mastery block: multiplication + cognitive ladder evidence and per-item
  // memory mastery/due. Cognitive entries retain every exact-rung measure used
  // to promote or hold so the Progress UI can explain the decision.
  const [mulProgress, cognitiveProgress, memoryItems, dueItems, reviews] = await Promise.all([
    getMultiplicationProgress(),
    getCognitiveProgress(),
    getMemoryItems(),
    getDueMemoryItems(),
    getRetentionReport(new Date()),
  ]);
  const dueIds = new Set(dueItems.map(i => i.id));
  // Skill re-verification retention state (issue #2096): per-skill fresh / due /
  // needs-refresh + a 90-day retention %. Empty on fresh installs (nothing
  // tracked until the first skill is mastered).
  return {
    days: window,
    series: {
      byDay,
      byDomain: finalizeMetricSeries(domainMap),
      byDrill: finalizeMetricSeries(drillMap),
      // Protocol-scoped benchmark trend (issue #4442) — additive, does not
      // change `byDay`'s existing blended-score semantics. `byDay` above
      // stays the general activity headline; this is the narrower "only
      // compatible, versioned benchmark runs" comparison the issue's
      // acceptance criteria require, with legacy/incompatible sessions
      // visibly excluded via `excludedCount` rather than silently dropped.
      benchmark: {
        protocolId: POST_BENCHMARK_PROTOCOL.protocolId,
        protocolVersion: POST_BENCHMARK_PROTOCOL.protocolVersion,
        scorerVersion: POST_BENCHMARK_PROTOCOL.scorerVersion,
        byDay: benchmarkByDay,
        excludedCount: benchmarkExcludedCount,
      },
    },
    totals: {
      minutesTrained: Math.round((sessionMs + trainingMs) / 60000),
      sessions: sessions.length,
      practiceEntries: training.length,
    },
    streak,
    mastery: {
      multiplication: {
        level: mulProgress.level,
        description: mulProgress.label,
        floorLevel: mulProgress.floorLevel,
      },
      cognitive: cognitiveProgress,
      memoryItems: memoryItems.map(it => ({
        id: it.id,
        title: it.title,
        overallPct: it.mastery?.overallPct ?? 0,
        // 0/1 per item so the client can sum to a total "due" count.
        dueCount: dueIds.has(it.id) ? 1 : 0,
      })),
      reviews,
    },
  };
}

// =============================================================================
// RECOMMENDATIONS ("what to practice next") — issue #2100
// =============================================================================

// Cap on how many recommendations the launcher/widget surface — enough to fill
// an "Up next" panel without becoming a wall of tasks.
const RECOMMENDATION_LIMIT = 5;
// Coarse module → domain routing for weak-skill recommendations. Only the
// domains a weak-skill rec can name are needed here; the full map lives on the
// client (constants.js DRILL_TO_DOMAIN). Prettify falls back to the drill type.
const DRILL_LABEL = (type) =>
  String(type || '').replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());

/**
 * EVERY scored drill with an accuracy signal, ranked weakest-first. Pure; reads
 * the shape `getPostStats` returns. Empty when there's no accuracy signal yet
 * (fresh install / all drills without derivable accuracy). Each entry is
 * `{ key, module, type, accuracy, samples }` where `key` is `"<module>:<type>"`.
 *
 * Ranked rather than single-valued because the caller has to keep looking past
 * the weakest drill when that one is disabled, excluded by `sessionModules`, or
 * was already practiced inside the recency window (issue #5319) — stopping at
 * the first candidate is what used to pin the tier to one drill forever.
 */
export function weakestSkillsFromStats(stats) {
  const acc = stats?.evidenceByDrillAccuracy || stats?.byDrillAccuracy || {};
  const counts = stats?.evidenceByDrillCount || stats?.byDrillCount || {};
  const ranked = [];
  for (const [key, a] of Object.entries(acc)) {
    if (typeof a !== 'number' || Number.isNaN(a)) continue;
    const samples = counts[key] || 0;
    if (samples < 1) continue;
    const sep = key.indexOf(':');
    ranked.push({
      key,
      module: sep >= 0 ? key.slice(0, sep) : null,
      type: sep >= 0 ? key.slice(sep + 1) : key,
      accuracy: a,
      samples,
    });
  }
  // Stable: equal-accuracy drills keep their `Object.entries` order here, and
  // the day rotation in `orderByRecencyRotation` is what breaks that tie later.
  return ranked.sort((a, b) => a.accuracy - b.accuracy);
}

/**
 * The single weakest scored drill by recent (windowed) accuracy — the head of
 * `weakestSkillsFromStats`. `null` when there's no accuracy signal yet.
 */
export function weakestSkillFromStats(stats) {
  return weakestSkillsFromStats(stats)[0] || null;
}

/**
 * Stalled-progression descriptors from the resolved multiplication, Powers, and cognitive
 * ladders: a laddered drill the user is partway up but not yet advancing, with
 * how many more clean/fast reps remain to reach the next rung. Pure — takes the
 * already-resolved progress objects. A ladder that's mastered-and-advancing or
 * at its hardest rung contributes nothing.
 *
 * @param {object} mulProgress - getMultiplicationProgress() result
 * @param {object} powersProgress - getPowersProgress() result
 * @param {Record<string,object>} cogProgress - getCognitiveProgress() result
 * @param {{kochLevel:number, kochLevelSet:boolean, maxKochLevel:number}} morse
 */
export function stalledProgressions(mulProgress, powersProgress, cogProgress, morse) {
  const out = [];

  const ladderStall = (prog, drillType, label, deepLink) => {
    if (!prog || prog.atHardest || prog.currentMastered) return null;
    const cur = (prog.levels || []).find((r) => r.level === prog.level);
    if (!cur) return null;
    // Only surface a ladder the user has actually engaged with. A fresh install
    // sits at level 0 with 0 samples and an unearned floor — telling it to "keep
    // climbing" a drill that's never been run is noise, and it would also crowd
    // out the fresh-state "run your first POST" default (issue #2100 review).
    const engaged = (cur.samples || 0) > 0 || (prog.floorLevel || 0) > 0 || prog.level > 0;
    if (!engaged) return null;
    const next = (prog.levels || []).find((r) => r.level === prog.level + 1);
    const minSamples = prog.thresholds?.minSamples ?? 0;
    const remaining = Math.max(1, minSamples - (cur.samples || 0));
    return {
      drillType,
      label,
      remaining,
      nextLabel: next?.label || null,
      deepLink,
    };
  };

  const mul = ladderStall(mulProgress, 'multiplication', 'Multiplication', '/post/launcher');
  if (mul) out.push(mul);

  const powers = ladderStall(powersProgress, 'powers', 'Powers', '/post/launcher');
  if (powers) out.push(powers);

  for (const [type, prog] of Object.entries(cogProgress || {})) {
    const stall = ladderStall(prog, type, DRILL_LABEL(type), '/post/launcher');
    if (stall) out.push(stall);
  }

  // Morse Koch progression: surface only once the user has engaged with Morse
  // (a level has been set) and isn't already at the final Koch level — so a
  // fresh install is never nagged about a track it hasn't started.
  if (morse?.kochLevelSet && morse.kochLevel < (morse.maxKochLevel ?? Infinity)) {
    out.push({
      drillType: 'morse-copy',
      label: 'Morse',
      remaining: null,
      nextLabel: `Koch level ${morse.kochLevel + 1}`,
      deepLink: '/post/morse/copy',
    });
  }

  return out;
}

/**
 * Compose the ordered "what to practice next" list from already-gathered
 * signals. PURE + fully unit-testable — the async `getPostRecommendations`
 * gathers the inputs and delegates here. Priority order (highest first):
 *   1. Due memory items (spaced-repetition overdue)
 *   2. Due skill re-verifications (mastered-but-inactive skills, issue #2096)
 *   3. Weakest scored skill by recent accuracy
 *   4. Stalled ladder progressions (N more reps to advance)
 * When nothing is actionable (e.g. a fresh install with no history), a single
 * sensible default ("run a full POST") is returned so the panel is never empty.
 *
 * `practicedToday` (from `practicedTodayFromActivity`) then demotes — never
 * drops — anything already practiced today, and stamps each rec with the flag
 * the daily routine reads to know it has run out of new work (issue #3563).
 */
// The built-in Elements Song has its own study surface (`/post/memory/elements`)
// rather than the generic per-item practice route.
const ELEMENTS_SONG_ID = 'elements-song';

/**
 * Deep link that lands a due memory item INSIDE a practice mode rather than on
 * the item list (issue #3249) — an "Up next" rec should start the drill, not
 * open a page the user still has to navigate. Mode choice per surface:
 *   - Elements Song → `element-flash` (recall test; its study deck is one click
 *     away on that surface)
 *   - any other item → `spaced`, which targets the weakest chunks — exactly what
 *     an item that has come due needs.
 * Pure — exported for unit tests.
 */
export function memoryPracticeDeepLink(itemId) {
  if (!itemId) return '/post/memory';
  if (itemId === ELEMENTS_SONG_ID) return '/post/memory/elements/element-flash';
  return `/post/memory/${itemId}/spaced`;
}

/**
 * The memory item a `kind: 'memory'` review entry belongs to. Prefers the
 * explicit `memoryItemId` field; falls back to parsing the `memory:<itemId>:<chunkId>`
 * skillId, splitting on the LAST colon so an item id containing one still
 * resolves. Returns null for a non-memory or unparseable entry. Pure.
 */
export function memoryItemIdFromReview(review) {
  if (review?.memoryItemId) return review.memoryItemId;
  const skillId = review?.skillId;
  if (typeof skillId !== 'string' || !skillId.startsWith('memory:')) return null;
  const rest = skillId.slice('memory:'.length);
  const lastColon = rest.lastIndexOf(':');
  const itemId = lastColon > 0 ? rest.slice(0, lastColon) : rest;
  return itemId || null;
}

/**
 * What the user has already practiced today, from BOTH scored POST sessions and
 * the training log (Morse/Wordplay/Memory practice never post a scored session).
 * Pure — exported for unit tests.
 *
 * "Continue Today's Routine" walks this recommendation list one item at a time,
 * but every signal feeding it (weakest recent accuracy, stalled ladder) is a
 * windowed average that a single rep barely moves — so without a
 * what-have-I-already-done gate the same drill stays pinned at the top and the
 * routine hands back the drill just finished, forever (issue #3563).
 *
 * @param {Array} sessions - all scored sessions (`{ date, tasks: [{ type }] }`)
 * @param {Array} trainingEntries - all training-log entries
 * @param {string|null} todayStr - the user's local `YYYY-MM-DD`
 * @param {string} [timezone] - user timezone for re-keying legacy ISO dates
 * @returns {{ drillTypes: Set<string>, memoryItemIds: Set<string>, completedSession: boolean }}
 */
function activityOnDays(sessions, trainingEntries, dayKeys, timezone) {
  const drillTypes = new Set();
  const memoryItemIds = new Set();
  let completedSession = false;

  // Both feeds go through recordDayKey, which re-derives the day from each
  // record's own instant in the CURRENT timezone (#4168) — matching against
  // the stored `date` would read a record written under a previous timezone (or
  // a memory-practice entry carrying a full ISO timestamp) as not-practiced.
  for (const session of sessions || []) {
    if (!dayKeys.has(recordDayKey(session, timezone))) continue;
    completedSession = true;
    for (const task of session.tasks || []) {
      if (task?.type) drillTypes.add(task.type);
      if (task?.memoryItemId) memoryItemIds.add(task.memoryItemId);
    }
  }
  for (const entry of trainingEntries || []) {
    if (!dayKeys.has(recordDayKey(entry, timezone))) continue;
    // Training entries are two shapes sharing one log: drill practice carries
    // `drillType`, memory practice carries `memoryItemId` + `mode`.
    if (entry.drillType) drillTypes.add(entry.drillType);
    if (entry.memoryItemId) memoryItemIds.add(entry.memoryItemId);
  }
  return { drillTypes, memoryItemIds, completedSession };
}

export function practicedTodayFromActivity(sessions = [], trainingEntries = [], todayStr = null, timezone) {
  // No resolvable local day ⇒ report nothing practiced rather than guessing, so
  // the routine degrades to its pre-#3563 ordering instead of silently demoting.
  const today = normalizeYmd(todayStr, timezone);
  if (!today) return { drillTypes: new Set(), memoryItemIds: new Set(), completedSession: false };
  return activityOnDays(sessions, trainingEntries, new Set([today]), timezone);
}

/**
 * How many local calendar days the heuristic-tier recency window spans — today
 * plus the previous two. Wide enough that a drill practiced yesterday yields to
 * something else, narrow enough that a three-drill rotation still comes back
 * around every third day.
 */
export const RECENT_PRACTICE_WINDOW_DAYS = 3;

/**
 * What the user has practiced across the last `windowDays` LOCAL calendar days,
 * from both scored sessions and the training log (issue #5319).
 *
 * This is the multi-day sibling of `practicedTodayFromActivity`, and it feeds a
 * different decision. `practicedToday` demotes an already-completed rec in
 * EVERY tier — including schedule-driven due memory items and due reviews. This
 * window only reorders the two HEURISTIC tiers (weakest skill, stalled ladder),
 * whose signals are windowed averages a single rep barely moves, so the same
 * drill would otherwise stay pinned to the top slot day after day. A genuinely
 * due item is never deprioritized by it.
 *
 * Pure — exported for unit tests. Carries no prompts or session content, only
 * drill types and memory item ids, and persists nothing.
 *
 * @param {Array} sessions - all scored sessions (`{ date, tasks: [{ type }] }`)
 * @param {Array} trainingEntries - all training-log entries
 * @param {string|null} todayStr - the user's local `YYYY-MM-DD`
 * @param {string} [timezone] - user timezone for re-keying legacy ISO dates
 * @param {number} [windowDays] - calendar days to look back over, including today
 * @returns {{ dayKey: string|null, drillTypes: Set<string>, memoryItemIds: Set<string> }}
 */
export function recentPracticeFromActivity(sessions = [], trainingEntries = [], todayStr = null, timezone, windowDays = RECENT_PRACTICE_WINDOW_DAYS) {
  // No resolvable local day ⇒ no window, and callers fall back to plain
  // priority order rather than rotating off a guessed day.
  const today = normalizeYmd(todayStr, timezone);
  if (!today) return { dayKey: null, drillTypes: new Set(), memoryItemIds: new Set() };

  const span = Math.max(1, Math.trunc(windowDays) || 1);
  const days = new Set(Array.from({ length: span }, (_, i) => ymdShift(today, -i)));
  const { drillTypes, memoryItemIds } = activityOnDays(sessions, trainingEntries, days, timezone);
  return { dayKey: today, drillTypes, memoryItemIds };
}

export function composePostRecommendations({
  dueMemoryItems = [],
  dueReviews = [],
  weakestSkill = null,
  stalled = [],
  hasHistory = false,
  practicedToday = null,
  limit = RECOMMENDATION_LIMIT,
} = {}) {
  // Copied into Sets so an array-shaped `practicedToday` (a JSON round-trip, or
  // a test literal) works the same as the live Set-bearing one.
  const doneTypes = new Set(practicedToday?.drillTypes || []);
  const doneItems = new Set(practicedToday?.memoryItemIds || []);
  const recs = [];

  for (const item of dueMemoryItems) {
    recs.push({
      id: `memory-due:${item.id}`,
      kind: 'memory-due',
      title: `Review "${item.title}"`,
      detail: 'Due for spaced-repetition practice',
      deepLink: memoryPracticeDeepLink(item.id),
      drillType: 'memory-sequence',
      memoryItemId: item.id,
    });
  }

  for (const review of dueReviews) {
    const reviewItemId = review.kind === 'memory' ? memoryItemIdFromReview(review) : null;
    // A memory-chunk re-verification can't run through the launcher's review-rep
    // path (getPostReviewReps only regenerates multiplication/cognitive reps —
    // memory retention lives under /post/memory), so route it there instead of a
    // dead /post/launcher link (issue #2100 review). It routes all the way INTO a
    // practice mode rather than the item list (issue #3249).
    recs.push({
      id: `skill-review:${review.skillId}`,
      kind: 'skill-review',
      title: `Re-verify ${review.label}`,
      detail: review.status === 'needs-refresh'
        ? 'Needs a refresh — last review slipped'
        : 'Maintenance rep due',
      deepLink: review.kind === 'memory'
        ? memoryPracticeDeepLink(reviewItemId)
        : '/post/launcher',
      drillType: review.drillType || null,
      memoryItemId: reviewItemId,
    });
  }

  if (weakestSkill) {
    recs.push({
      id: `weak-skill:${weakestSkill.key}`,
      kind: 'weak-skill',
      title: `Shore up ${DRILL_LABEL(weakestSkill.type)}`,
      detail: `Weakest skill lately — ${Math.round((weakestSkill.accuracy || 0) * 100)}% accuracy`,
      deepLink: weakestSkill.deepLink || '/post/launcher',
      drillType: weakestSkill.type,
    });
  }

  for (const stall of stalled) {
    const remainText = stall.remaining != null
      ? `${stall.remaining} more clean rep${stall.remaining === 1 ? '' : 's'} to reach ${stall.nextLabel || 'the next level'}`
      : `Advance to ${stall.nextLabel || 'the next level'}`;
    recs.push({
      id: `stalled:${stall.drillType}`,
      kind: 'stalled-progression',
      title: `${stall.label}: keep climbing`,
      detail: remainText,
      deepLink: stall.deepLink,
      drillType: stall.drillType,
    });
  }

  if (recs.length === 0) {
    recs.push({
      id: 'default:full-post',
      kind: 'default',
      title: hasHistory ? 'Keep your streak going' : 'Run your first POST',
      detail: hasHistory
        ? 'No specific gaps right now — run a full self-test to stay sharp.'
        : 'Complete a full self-test to start tracking what to practice next.',
      deepLink: '/post/launcher',
      drillType: null,
    });
  }

  // One rule, applied after the list is built, so a rec kind added later inherits
  // it instead of shipping an undefined flag. A rec's identity is whatever it
  // actually sends the user to practice: a memory ITEM for the two memory-shaped
  // recs, a drill TYPE for the ladder/weak-skill ones, and — for the "run a full
  // self-test" fallback, which names neither — any scored session at all.
  const isPracticedToday = (rec) => {
    if (rec.memoryItemId) return doneItems.has(rec.memoryItemId);
    if (rec.drillType) return doneTypes.has(rec.drillType);
    return Boolean(practicedToday?.completedSession);
  };
  // Demoted, not dropped: a fully-practiced day should still show what's up next
  // rather than an empty panel. `sort` is stable, so the priority order above is
  // preserved within each group; callers that want to STOP (the daily routine)
  // read the flag on the top rec.
  const ordered = recs
    .map(rec => ({ ...rec, practicedToday: isPracticedToday(rec) }))
    .sort((a, b) => a.practicedToday - b.practicedToday);

  return ordered.slice(0, Math.max(1, limit)).map((r, i) => ({ ...r, priority: i }));
}

// Coarse module → config key for the enabled-drill lookup.
const MODULE_CONFIG_KEY = { 'mental-math': 'mentalMath', 'llm-drills': 'llmDrills', cognitive: 'cognitive' };

/**
 * The module string `isRecDrillRunnable` should be called with for a given drill
 * type, derived from the topic registry rather than hardcoded per call site.
 *
 * Morse carries a null registry module (it never posts a scored POST task) but is
 * gated by its own config block, so it maps to the `morse` pseudo-module the gate
 * understands. `fallback` covers a drill type with no registry entry.
 */
function recModuleForDrillType(type, fallback) {
  const topic = resolveTopicForDrillType(type);
  return topic ? (topic.module || topic.id) : fallback;
}

/**
 * Whether a recommended drill can actually be run under the current config
 * (issue #2100 review): a weak-skill / stalled rec deep-links into a session,
 * so recommending a drill the user has since disabled — or a module they've
 * removed from Session Composition — would be a dead end.
 *
 * Three gates, checked in order (issue #3252):
 *   1. The drill's practice TOPIC — off means off everywhere, including the
 *      dedicated Memory and Morse practice routes.
 *   2. Recommendation-specific participation — memory due-item recommendations
 *      deep-link to dedicated practice, so `sessionModules` doesn't apply;
 *      memory still honors the per-ITEM toggle when the caller knows the item.
 *   3. Session composition + the per-module/per-drill `enabled` flags.
 *
 * `memoryItemId` is only meaningful for `module === 'memory'`; absent means
 * "no specific item", which is never filtered.
 * Pure — exported for unit tests.
 */
export function isRecDrillRunnable(config, module, type, memoryItemId = null) {
  // An unmapped drill type has no topic — treat it as not topic-gated rather
  // than disabled, so a type added ahead of its registry entry still surfaces.
  const topic = resolveTopicForDrillType(type);
  if (topic && !isTopicEnabled(config, topic.id)) return false;

  if (module === 'memory') {
    if (config?.memory?.enabled === false) return false;
    const dt = config?.memory?.drillTypes?.[type];
    if (dt && dt.enabled === false) return false;
    return isMemoryItemEnabled(config, memoryItemId);
  }
  // Morse isn't a POST module (it never posts a scored task), so it is gated by
  // its own block alone — never by sessionModules, which can't contain it.
  if (module === 'morse') return config?.morse?.enabled !== false;

  const sm = Array.isArray(config?.sessionModules) ? config.sessionModules : null;
  // null = legacy/absent → all modules allowed; an explicit array must include it.
  if (sm !== null && !sm.includes(module)) return false;
  const key = MODULE_CONFIG_KEY[module];
  if (!key) return true; // unknown module — don't filter it out
  // An absent module/drill entry means "default" (enabled) — getPostConfig
  // deep-merges the enabled-by-default config, so only an EXPLICIT `false`
  // disables it.
  const mod = config?.[key];
  if (mod && mod.enabled === false) return false;
  const dt = mod?.drillTypes?.[type];
  return !dt || dt.enabled !== false;
}

/**
 * Gather the recommendation signals and compose the ordered "Up next" list
 * (issue #2100). Reads due memory items, due skill re-verifications, recent
 * stats (weakest skill), and the resolved ladders (stalled progressions), then
 * filters the config-dependent ones (weakest/stalled) to drills the current
 * config can actually run.
 */
// =============================================================================
// DRILL GENERATORS (pure functions)
// =============================================================================

export function generateDoublingChain(startValue, steps = 8) {
  const start = startValue ?? (Math.floor(Math.random() * 7) + 3); // 3-9
  const questions = [];
  let current = start;
  for (let i = 0; i < steps; i++) {
    const next = current * 2;
    questions.push({ prompt: `${current} x 2`, expected: next });
    current = next;
  }
  return { type: 'doubling-chain', config: { startValue: start, steps }, questions };
}

export function generateSerialSubtraction(start, subtrahend = 7, steps = 10, startRange) {
  let startVal = start;
  if (startVal == null && Array.isArray(startRange) && startRange.length === 2) {
    const [lo, hi] = startRange;
    startVal = Math.floor(Math.random() * (hi - lo + 1)) + lo;
  }
  startVal = startVal ?? (Math.floor(Math.random() * 101) + 100); // 100-200
  const questions = [];
  let current = startVal;
  for (let i = 0; i < steps; i++) {
    const next = current - subtrahend;
    questions.push({ prompt: `${current} - ${subtrahend}`, expected: next });
    current = next;
  }
  return { type: 'serial-subtraction', config: { startValue: startVal, subtrahend, steps }, questions };
}

// Random integer in [min, max], inclusive.
function between(min, max) {
  return Math.floor(Math.random() * (max - min + 1)) + min;
}

// Random integer with exactly `digits` digits (1 → 1-9, 2 → 10-99, …).
function randInt(digits) {
  return between(digits > 1 ? Math.pow(10, digits - 1) : 1, Math.pow(10, digits) - 1);
}

/**
 * Generate a multiplication drill.
 *
 * Two shapes:
 *  - Progressive ladder: pass `factors` (an array of per-factor digit counts,
 *    e.g. `[1, 2]` or `[1, 1, 1]`) and, optionally, the `level` that produced it
 *    (stamped into the returned config so scored history can bucket by level).
 *  - Legacy: pass `maxDigits` for a symmetric two-factor problem (both factors
 *    have `maxDigits` digits). Kept for when the progressive ladder is off.
 */
export function generateMultiplication(count = 10, maxDigits = 2, factors = null, level = null) {
  const useFactors = Array.isArray(factors) && factors.length >= 2
    ? factors.map(d => Math.max(1, Math.min(4, Math.trunc(d))))
    : null;
  const digitPlan = useFactors || [maxDigits, maxDigits];
  const questions = [];
  for (let i = 0; i < count; i++) {
    const nums = digitPlan.map(d => randInt(d));
    const expected = nums.reduce((product, n) => product * n, 1);
    questions.push({ prompt: nums.join(' x '), expected });
  }
  const config = { count };
  if (useFactors) {
    config.factors = useFactors;
    if (Number.isInteger(level)) config.level = level;
  } else {
    config.maxDigits = maxDigits;
  }
  return { type: 'multiplication', config, questions };
}

export function generatePowers(bases, maxExponent = 10, count = 8, level = null, review = false) {
  if (Number.isInteger(level)) {
    const cumulativePool = powersPoolForLevel(level);
    const pool = review
      ? cumulativePool.filter(pair => pair.level === level)
      : cumulativePool;
    const questions = Array.from({ length: count }, () => {
      const pair = pool[Math.floor(Math.random() * pool.length)];
      return {
        prompt: `${pair.base}^${pair.exponent}`,
        expected: Math.pow(pair.base, pair.exponent),
        technique: pair.technique,
        techniqueLevel: pair.level,
      };
    }).sort((a, b) => a.techniqueLevel - b.techniqueLevel);
    return {
      type: 'powers',
      config: {
        count,
        level,
        technique: pool.at(-1).technique,
      },
      questions,
    };
  }
  bases = Array.isArray(bases) && bases.length > 0 ? bases : [2, 3, 5];
  const questions = [];
  for (let i = 0; i < count; i++) {
    const base = bases[Math.floor(Math.random() * bases.length)];
    const exp = Math.floor(Math.random() * (maxExponent - 1)) + 2; // 2 to maxExponent
    questions.push({ prompt: `${base}^${exp}`, expected: Math.pow(base, exp) });
  }
  return { type: 'powers', config: { bases, maxExponent, count }, questions };
}

const MIN_ESTIMATION_DIFFERENCE = 100;

// Subtraction operands, larger first and at least MIN_ESTIMATION_DIFFERENCE
// apart. Two independently-drawn 3-digit numbers land closer than that about a
// fifth of the time, and a PERCENTAGE tolerance of a tiny difference is a
// sub-unit band — `509 - 499` grades to ±1 at the default 10%, exact arithmetic
// wearing an estimation label. Keeping the answer itself 3-digit is what rules
// that out; how precise the drillee must then be is the tolerance's job to say,
// and the drill UI states it. Ordering the pair also settles whether a
// `309 - 925` prompt wants 616 or -616.
function estimationSubtractionPair() {
  const hi = between(100 + MIN_ESTIMATION_DIFFERENCE, 999);
  return [hi, between(100, hi - MIN_ESTIMATION_DIFFERENCE)];
}

export function generateEstimation(count = 5, tolerancePct) {
  const ops = ['+', '-', 'x'];
  const questions = [];
  for (let i = 0; i < count; i++) {
    const op = ops[Math.floor(Math.random() * ops.length)];
    const [a, b] = op === '-' ? estimationSubtractionPair() : [randInt(3), randInt(3)];
    const expected = op === '+' ? a + b : op === '-' ? a - b : a * b;
    questions.push({ prompt: `${a} ${op} ${b}`, expected });
  }
  const config = { count };
  if (tolerancePct != null) config.tolerancePct = tolerancePct;
  return { type: 'estimation', config, questions };
}

export function generateDrill(type, config = {}) {
  switch (type) {
    case 'doubling-chain':
      return generateDoublingChain(config.startValue, config.steps);
    case 'serial-subtraction':
      return generateSerialSubtraction(config.startValue, config.subtrahend, config.steps, config.startRange);
    case 'multiplication':
      return generateMultiplication(config.count, config.maxDigits, config.factors, config.level);
    case 'powers':
      return generatePowers(config.bases, config.maxExponent, config.count, config.level, config.review);
    case 'estimation':
      return generateEstimation(config.count, config.tolerancePct);
    case APPLIED_NUMERACY_DRILL_TYPE:
      return generateAppliedNumeracyDrill({
        ...config,
        // The generator itself is pure for a seed. New runs get a seed once;
        // it is stamped into the returned config and becomes the score key.
        seed: config.seed ?? Math.floor(Math.random() * 0x100000000),
      });
    case 'n-back':
    case 'digit-span':
    case 'stroop':
    case 'schulte-table':
    case 'mental-rotation':
    case 'reaction-time':
    case 'task-switching':
    case 'go-no-go':
    case 'flanker':
      return generateCognitiveDrill(type, config);
    default:
      return null;
  }
}

// =============================================================================
// PROGRESSIVE LADDERS — per-level history
// =============================================================================

/**
 * Aggregate multiplication performance per ladder level from scored history,
 * so the progressive ladder can decide whether each level has been *speed*
 * mastered. Only answered questions count as samples; each contributes its
 * correctness and clamped response time.
 *
 * Returns both the windowed per-level stats (for the mastery decision) and the
 * `floorLevel` — the highest rung the user has EVER generated (all-time, NOT
 * windowed). The floor is the anti-demotion signal: mastery is judged over a
 * rolling window, so a rung's samples fall to 0 once its evidence ages out, but
 * a user only reaches a higher rung by clearing the ones below it, so that
 * earned progress must survive the window (see resolveMultiplicationLevel).
 *
 * @returns {Promise<{stats: Record<number, {samples,accuracy,avgResponseMs}>, floorLevel: number}>}
 */
export async function getMultiplicationLevelStats(windowDays = MASTERY_DEFAULTS.windowDays) {
  const atDate = new Date();
  const [scoredSessions, training] = await Promise.all([getPostSessions(), getAllTrainingEntries()]);
  const sessions = skillEvidenceSessions(scoredSessions, training);
  // Window off the user's local today (DST-safe day math) so the cutoff stays
  // consistent with the tz-correct session dates submitPostSession now stamps
  // (issue #2681) — a UTC-day cutoff would skew the window edge by the tz offset.
  const timezone = await getUserTimezone();
  const todayStr = todayInTimezone(timezone, atDate);
  const cutoffStr = windowDays > 0 ? ymdShift(todayStr, -windowDays) : null;

  const byLevel = {};
  let floorLevel = 0;
  for (const session of sessions) {
    for (const task of session.tasks || []) {
      if (task.type !== 'multiplication') continue;
      const level = Number.isInteger(task.config?.level) ? task.config.level : null;
      if (level == null) continue; // legacy maxDigits-only tasks carry no level
      // All-time floor: any answered question at this level (regardless of the
      // window) proves the user reached — and thus earned — this rung.
      const anyAnswered = (task.questions || []).some(q => q?.answered != null);
      if (anyAnswered && level > floorLevel) floorLevel = level;
      // Mastery stats are windowed — skip out-of-window sessions for the buckets.
      const date = recordDayKey(session, timezone);
      if (cutoffStr && (!date || date < cutoffStr)) continue;
      const bucket = byLevel[level] || (byLevel[level] = { samples: 0, correct: 0, totalResponseMs: 0 });
      for (const q of task.questions || []) {
        if (q?.answered == null) continue;
        bucket.samples += 1;
        if (q.correct) bucket.correct += 1;
        // Clamp so one walked-away answer can't inflate avgResponseMs and block
        // mastery (mirrors scoreDrill's per-question clamp).
        bucket.totalResponseMs += Math.min(Math.max(0, q.responseMs || 0), MASTERY_DEFAULTS.responseMsCap);
      }
    }
  }

  const stats = {};
  for (const [level, b] of Object.entries(byLevel)) {
    stats[level] = {
      samples: b.samples,
      accuracy: b.samples ? b.correct / b.samples : 0,
      avgResponseMs: b.samples ? b.totalResponseMs / b.samples : 0,
    };
  }
  return { stats, floorLevel };
}

export async function getPowersLevelStats(windowDays = POWERS_MASTERY_DEFAULTS.windowDays) {
  const atDate = new Date();
  const [scoredSessions, training] = await Promise.all([getPostSessions(), getAllTrainingEntries()]);
  const sessions = skillEvidenceSessions(scoredSessions, training);
  const timezone = await getUserTimezone();
  const todayStr = todayInTimezone(timezone, atDate);
  const cutoffStr = windowDays > 0 ? ymdShift(todayStr, -windowDays) : null;
  const byLevel = {};
  let floorLevel = 0;
  for (const session of sessions) {
    for (const task of session.tasks || []) {
      if (task.type !== 'powers') continue;
      const level = Number.isInteger(task.config?.level) ? task.config.level : null;
      if (level == null) continue;
      const anyAnswered = (task.questions || []).some(question => question?.answered != null);
      if (anyAnswered && level > floorLevel) floorLevel = level;
      const date = recordDayKey(session, timezone);
      if (cutoffStr && (!date || date < cutoffStr)) continue;
      for (const question of task.questions || []) {
        if (question?.answered == null) continue;
        const match = typeof question.prompt === 'string' ? question.prompt.match(/^(\d+)\^(\d+)$/) : null;
        const pair = match ? powersTechniqueForPair(Number(match[1]), Number(match[2])) : null;
        // Progressive pools are cumulative for review, but mastery belongs to
        // the technique that actually covered this question. Otherwise quick
        // recall reps in a later-rung session could unlock that rung without
        // the user ever answering one of its new pairs.
        const sampleLevel = pair?.level ?? level;
        const bucket = byLevel[sampleLevel] || (byLevel[sampleLevel] = { samples: 0, correct: 0, totalResponseMs: 0 });
        bucket.samples += 1;
        if (question.correct) bucket.correct += 1;
        bucket.totalResponseMs += Math.min(
          Math.max(0, question.responseMs || 0),
          POWERS_MASTERY_DEFAULTS.responseMsCap
        );
      }
    }
  }
  return {
    stats: Object.fromEntries(Object.entries(byLevel).map(([level, bucket]) => [level, {
      samples: bucket.samples,
      accuracy: bucket.samples ? bucket.correct / bucket.samples : 0,
      avgResponseMs: bucket.samples ? bucket.totalResponseMs / bucket.samples : 0,
    }])),
    floorLevel,
  };
}

/**
 * Resolve the current progressive-multiplication difficulty from history.
 * Exposed for the config UI / route so it can show the ladder + mastery status.
 */
export async function getMultiplicationProgress() {
  const { stats, floorLevel } = await getMultiplicationLevelStats(MASTERY_DEFAULTS.windowDays);
  const progression = resolveMultiplicationLevel(stats, {}, floorLevel);
  return { ...progression, windowDays: MASTERY_DEFAULTS.windowDays, thresholds: { minSamples: MASTERY_DEFAULTS.minSamples, targetAccuracy: MASTERY_DEFAULTS.targetAccuracy } };
}

export async function getPowersProgress() {
  const { stats, floorLevel } = await getPowersLevelStats(POWERS_MASTERY_DEFAULTS.windowDays);
  const progression = resolvePowersLevel(stats, {}, floorLevel);
  return {
    ...progression,
    windowDays: POWERS_MASTERY_DEFAULTS.windowDays,
    thresholds: {
      minSamples: POWERS_MASTERY_DEFAULTS.minSamples,
      targetAccuracy: POWERS_MASTERY_DEFAULTS.targetAccuracy,
    },
  };
}

/**
 * Aggregate a laddered cognitive drill's performance per level from scored
 * history so its ladder can decide whether each rung is mastered. A "sample"
 * is one completion-qualified drill (not one answered question), bucketed by
 * its exact stamped level. Each task contributes task-level accuracy (balanced
 * SDT accuracy for n-back, #2094) and response latency for the two speed-gated
 * skills. Incomplete attempts remain visible but do not bank mastery samples.
 *
 * Returns the windowed per-level stats plus the all-time `floorLevel` (the
 * highest rung ever reached), the anti-demotion signal for resolveLevel.
 *
 * @returns {Promise<{stats: Record<number, {samples,attempts,accuracy,completion,incompleteSamples,avgResponseMs}>, floorLevel: number}>}
 */
export async function getCognitiveLevelStats(type, windowDays = COGNITIVE_MASTERY_DEFAULTS.windowDays) {
  const atDate = new Date();
  const [scoredSessions, training] = await Promise.all([getPostSessions(), getAllTrainingEntries()]);
  const sessions = skillEvidenceSessions(scoredSessions, training);
  // Window off the user's local today (DST-safe) so the cutoff stays consistent
  // with the tz-correct session dates submitPostSession now stamps (issue #2681).
  const timezone = await getUserTimezone();
  const todayStr = todayInTimezone(timezone, atDate);
  const cutoffStr = windowDays > 0 ? ymdShift(todayStr, -windowDays) : null;

  const byLevel = {};
  let floorLevel = 0;
  for (const session of sessions) {
    for (const task of session.tasks || []) {
      if (task.type !== type) continue;
      const level = Number.isInteger(task.config?.level) ? task.config.level : null;
      if (level == null) continue; // pre-#2095 tasks carry no level
      // All-time floor: any reached (non-empty) drill at this level proves the
      // user earned the rung, regardless of the window.
      const reached = ((task.totalCount ?? (task.questions?.length || 0)) > 0);
      if (reached && level > floorLevel) floorLevel = level;
      // Mastery stats are windowed.
      const date = recordDayKey(session, timezone);
      if (cutoffStr && (!date || date < cutoffStr)) continue;
      const acc = deriveTaskAccuracy(task);
      const derivedComp = deriveTaskCompletion(task);
      const comp = derivedComp == null ? 1 : derivedComp;
      const bucket = byLevel[level] || (byLevel[level] = {
        attempts: 0,
        samples: 0,
        incompleteSamples: 0,
        accSum: 0,
        completionSum: 0,
        responseSamples: 0,
        totalResponseMs: 0,
      });
      bucket.attempts += 1;
      bucket.completionSum += comp;
      // Skip low-completion runs: accuracy is answered-only, so a run that
      // leaves the harder trials blank must not bank a high-accuracy sample and
      // promote the rung (issue #2095 review). A null completion (legacy tasks)
      // is treated as complete so old history still counts.
      if (acc == null || comp < COGNITIVE_MASTERY_DEFAULTS.minCompletion) {
        bucket.incompleteSamples += 1;
        continue;
      }
      bucket.samples += 1;
      bucket.accSum += acc;
      const responseMs = deriveTaskAvgResponseMs(task);
      if (responseMs != null && responseMs > 0) {
        bucket.responseSamples += 1;
        bucket.totalResponseMs += Math.min(responseMs, COGNITIVE_MASTERY_DEFAULTS.responseMsCap);
      }
    }
  }

  const stats = {};
  for (const [level, b] of Object.entries(byLevel)) {
    stats[level] = {
      samples: b.samples,
      attempts: b.attempts,
      accuracy: b.samples ? b.accSum / b.samples : 0,
      completion: b.attempts ? b.completionSum / b.attempts : 0,
      incompleteSamples: b.incompleteSamples,
      timedSamples: b.responseSamples,
      avgResponseMs: b.responseSamples ? b.totalResponseMs / b.responseSamples : 0,
    };
  }
  return { stats, floorLevel };
}

/**
 * Resolve the current progressive difficulty for every laddered cognitive drill
 * from history — the current rung + per-rung mastery for the config/preview UI.
 * Keyed by drill type (`{ 'n-back': {...}, 'digit-span': {...}, … }`).
 */
export async function getCognitiveProgress() {
  const out = {};
  for (const type of COGNITIVE_LADDER_TYPES) {
    const { stats, floorLevel } = await getCognitiveLevelStats(type);
    out[type] = resolveCognitiveProgression(type, stats, floorLevel);
  }
  return out;
}

// =============================================================================
// SCORING (pure functions)
// =============================================================================

export function computeExpectedFromPrompt(prompt) {
  const s = typeof prompt === 'string' ? prompt.trim() : '';
  // Chained multiplication: "a x b" or "a x b x c x …" (progressive ladder can
  // emit 3+ factors). Handled first so a single "a x b" also flows through here.
  if (/^-?\d+(\s*x\s*-?\d+)+$/.test(s)) {
    const factors = s.split(/\s*x\s*/).map(n => parseInt(n, 10));
    if (factors.some(Number.isNaN)) return null;
    return factors.reduce((product, n) => product * n, 1);
  }
  const match = s.match(/^(-?\d+)\s*([+\-^])\s*(-?\d+)$/);
  if (!match) return null;
  const [, aStr, op, bStr] = match;
  const a = parseInt(aStr, 10);
  const b = parseInt(bStr, 10);
  switch (op) {
    case '+': return a + b;
    case '-': return a - b;
    case '^': return Math.pow(a, b);
    default: return null;
  }
}

export function scoreDrill(type, questions, timeLimitMs, config = {}) {
  if (type === APPLIED_NUMERACY_DRILL_TYPE) {
    return scoreAppliedNumeracyDrill(questions, timeLimitMs, config);
  }
  if (!questions?.length) {
    return { score: 0, questions, accuracy: null, completion: null, avgResponseMs: null, answeredCount: 0, totalCount: 0 };
  }

  // Recompute expected from the prompt server-side — never trust client-provided expected
  const recomputed = questions.map(q => {
    const expected = computeExpectedFromPrompt(q.prompt);
    // Coerce answered to number: empty/whitespace → null, NaN → null, "42" → 42
    let answered = null;
    if (q.answered != null) {
      if (typeof q.answered === 'string' && q.answered.trim() === '') {
        answered = null;
      } else {
        const rawNum = Number(q.answered);
        answered = Number.isNaN(rawNum) ? null : rawNum;
      }
    }
    let correct;
    if (expected == null || answered == null || isNaN(answered)) {
      correct = false;
    } else if (type === 'estimation') {
      const tolerance = resolveEstimationTolerancePct(config.tolerancePct) / 100;
      correct = Math.abs(answered - expected) <= Math.abs(expected * tolerance);
    } else {
      correct = answered === expected;
    }
    return { ...q, answered, expected, correct };
  });

  const answered = recomputed.filter(q => q.answered != null);
  const answeredCount = answered.length;
  const totalCount = recomputed.length;
  const correctCount = recomputed.filter(q => q.correct).length;
  // Blended `score` stays keyed on correct-over-TOTAL (== accuracy × completion),
  // so the headline gamification number is unchanged for existing sessions and
  // fully-answered tasks (back-compat). The separated metrics below are what
  // reporting and the adaptive signal now consume (issue #2094).
  const correctRatio = totalCount ? correctCount / totalCount : 0;

  // Clamp responseMs to [0, timeLimitMs] to prevent inflated speed bonuses
  const totalResponseMs = answered.reduce((sum, q) => sum + Math.min(Math.max(q.responseMs || 0, 0), timeLimitMs), 0);
  // Speed bonus falls back to the full time window when nothing was answered, so
  // an empty drill scores 0 (no accuracy, no bonus) rather than dividing by zero.
  const avgForBonus = answeredCount > 0 ? totalResponseMs / answeredCount : timeLimitMs;

  const speedBonus = Math.max(0, 1 - avgForBonus / timeLimitMs);
  const score = Math.round((correctRatio * 0.8 + speedBonus * 0.2) * 100);
  return {
    score: Math.min(100, Math.max(0, score)),
    questions: recomputed,
    // Accuracy is answered-only: running out of time reduces `completion`, never
    // accuracy (issue #2094). `null` (never NaN) when nothing was answered.
    accuracy: answeredCount ? correctCount / answeredCount : null,
    completion: totalCount ? answeredCount / totalCount : null,
    avgResponseMs: answeredCount ? Math.round(totalResponseMs / answeredCount) : null,
    answeredCount,
    totalCount,
  };
}

/**
 * Blend a session's per-task scores into one headline number, weighted by
 * each task's module (`config.scoring.weights`, issue #2099). A module absent
 * from `weights` (or a non-numeric entry) defaults to 1.0, so an all-uniform
 * (or empty/missing) weights map reproduces the exact old unweighted mean —
 * existing configs and sessions score identically until a user actually
 * adjusts a weight.
 */
function computeSessionScore(tasks, weights = {}) {
  const valid = (tasks || []).filter(t => typeof t.score === 'number' && !Number.isNaN(t.score));
  if (!valid.length) return 0;
  let totalWeighted = 0;
  let totalWeight = 0;
  for (const t of valid) {
    const w = typeof weights?.[t.module] === 'number' ? weights[t.module] : 1.0;
    totalWeighted += t.score * w;
    totalWeight += w;
  }
  // All-zero weights (every touched module explicitly zeroed) would otherwise
  // divide by zero — fall back to 0 rather than NaN.
  if (!totalWeight) return 0;
  return Math.round(totalWeighted / totalWeight);
}