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

53.6 KB
Raw Blame
/**
 * MeatSpace POST - Memory Builder Service
 *
 * CRUD and practice tracking for memory items (songs, poems, speeches, sequences).
 * Built-in content: Tom Lehrer's "The Elements" song.
 */

import { join } from 'path';
import { randomUUID } from 'crypto';
import { atomicWrite, PATHS, ensureDir, readJSONFile } from '../lib/fileUtils.js';
import { createFileWriteQueue } from '../lib/fileWriteQueue.js';
import { shuffle } from '../lib/arrayUtils.js';
import { isMemoryItemEnabled } from '../lib/postTopics.js';
import { userLocalToday } from './userTimezone.js';
import {
  DEFAULT_EASE,
  advanceSchedule,
  defaultSchedule,
  isScheduleDue,
  mergeScheduleAdvance,
  scheduleOrDefault,
} from '../lib/spacedRepetition.js';
import { listStoredTrainingEntries, saveStoredTrainingRun } from './postRunStore.js';

const MEATSPACE_DIR = PATHS.meatspace;
const MEMORY_ITEMS_FILE = join(MEATSPACE_DIR, 'post-memory-items.json');

// One queue for the whole store: every mutator's load → edit → save cycle runs
// under it so overlapping writes (e.g. the per-chunk submits of a spaced session)
// cannot each rewrite the other's result. Reads stay unqueued.
const queueMemoryWrite = createFileWriteQueue();

// =============================================================================
// SPACED-REPETITION SCHEDULER (SM-2 inspired)
// =============================================================================
//
// Every memory item carries a lightweight review schedule:
//   { ease, intervalDays, nextReview, lastReviewed }
// An item is "due" when `nextReview <= now`. Practicing it advances the schedule
// (a correct-heavy session pushes the next review further out; a miss resets it
// to "due now" so the item resurfaces immediately). The 4-field shape is
// additive and migration-safe — legacy items with no schedule are treated as
// due now (see `ensureSchedule`) and get a persisted default by migration 154.
//
// The scheduling MATH itself now lives in `lib/spacedRepetition.js`, shared with
// SongBook repertoire practice (#4102). It is re-exported here so the existing
// callers and tests of this service keep their import site.

export { DEFAULT_EASE, advanceSchedule, defaultSchedule, mergeScheduleAdvance };

// =============================================================================
// WINDOWED (DECAY-AWARE) MASTERY
// =============================================================================
//
// Element/chunk mastery is judged over a rolling window of the most-recent
// attempts, NOT cumulative all-time counts — so a run of recent misses lowers
// mastery (decay-aware) instead of an early wrong answer being permanently
// diluted, and mastery reflects whether you STILL know it. The cumulative
// `correct`/`attempts` counts are kept for history; the window rides alongside
// as a bounded `recent` array of per-attempt correctness (1/0, most-recent
// last, capped at MASTERY_WINDOW). Legacy items with no `recent` array fall back
// to the cumulative counts so old data still reports sensibly (issue #2096).
export const MASTERY_WINDOW = 10;
// Mastery gate: at least this many attempts (in the window) at ≥ this accuracy.
export const MASTERY_MIN_ATTEMPTS = 3;
export const MASTERY_TARGET_ACCURACY = 0.8;
export const SPOT_CHECK_MIN_DAYS = 30;
export const SPOT_CHECK_MAX_DAYS = 90;

const DAY_MS = 24 * 60 * 60 * 1000;

/** Push a per-attempt correctness flag onto a mastery stat's rolling window. */
function pushRecent(stat, correct) {
  if (!Array.isArray(stat.recent)) stat.recent = [];
  stat.recent.push(correct ? 1 : 0);
  if (stat.recent.length > MASTERY_WINDOW) {
    stat.recent = stat.recent.slice(-MASTERY_WINDOW);
  }
}

/**
 * Recency-weighted accuracy for a mastery stat: uses the bounded `recent`
 * window when present (decay-aware — recent misses lower it), else falls back to
 * the cumulative all-time `correct`/`attempts` for legacy items with no window.
 * Returns `{ attempts, accuracy }` where `attempts` is the count the mastery
 * gate is judged against.
 */
export function windowedAccuracy(stat) {
  if (Array.isArray(stat?.recent) && stat.recent.length) {
    const attempts = stat.recent.length;
    const correct = stat.recent.reduce((sum, r) => sum + (r ? 1 : 0), 0);
    return { attempts, accuracy: attempts ? correct / attempts : 0 };
  }
  const attempts = Number.isFinite(stat?.attempts) ? stat.attempts : 0;
  const correct = Number.isFinite(stat?.correct) ? stat.correct : 0;
  return { attempts, accuracy: attempts ? correct / attempts : 0 };
}

/** True when a mastery stat clears the windowed gate (≥3 recent attempts, ≥0.8). */
export function isStatMastered(stat) {
  if (typeof stat?.masteredAt === 'string') return true;
  const { attempts, accuracy } = windowedAccuracy(stat);
  return attempts >= MASTERY_MIN_ATTEMPTS && accuracy >= MASTERY_TARGET_ACCURACY;
}

/** Freeze a fact once it has cleared the mastery gate. */
function preserveStatMastery(stat, nowIso, source = 'verified') {
  if (!stat.masteredAt && isStatMastered(stat)) {
    stat.masteredAt = nowIso;
    stat.masterySource = source;
  }
  return stat;
}

/** Randomized one-time retention audit, 30–90 days after mastery. */
export function scheduleSpotCheckAt(now = new Date(), random = Math.random) {
  const sample = random();
  const clamped = Math.max(0, Math.min(0.999999, Number.isFinite(sample) ? sample : 0));
  const days = SPOT_CHECK_MIN_DAYS
    + Math.floor(clamped * (SPOT_CHECK_MAX_DAYS - SPOT_CHECK_MIN_DAYS + 1));
  return new Date(now.getTime() + days * DAY_MS).toISOString();
}

/**
 * Guarantee an item has a valid schedule. Legacy/built-in items with none get a
 * default anchored to their own `updatedAt`/`createdAt` (stable + in the past →
 * due now), so "due" state doesn't flap between reads. Mutates in place.
 */
function ensureSchedule(item) {
  item.schedule = scheduleOrDefault(item);
  return item;
}

function ensureMastery(item) {
  if (!item.mastery || typeof item.mastery !== 'object') {
    item.mastery = { overallPct: 0, chunks: {}, elements: {}, retention: { status: 'learning' } };
  }
  if (!item.mastery.chunks || typeof item.mastery.chunks !== 'object') item.mastery.chunks = {};
  if (!item.mastery.elements || typeof item.mastery.elements !== 'object') item.mastery.elements = {};
  if (!item.mastery.retention || typeof item.mastery.retention !== 'object') {
    item.mastery.retention = { status: 'learning' };
  }
  return item.mastery;
}

function targetMasteryEntries(item) {
  ensureMastery(item);
  if (item.id === 'elements-song' && item.content?.elementMap) {
    return Object.keys(item.content.elementMap).map(key => [key, item.mastery.elements, item.mastery.elements[key]]);
  }
  return (item.content?.chunks || []).map(chunk => [chunk.id, item.mastery.chunks, item.mastery.chunks[chunk.id]]);
}

function isItemFullyMastered(item) {
  const targets = targetMasteryEntries(item);
  return targets.length > 0 && targets.every(([, , stat]) => isStatMastered(stat));
}

function setAuditSchedule(item, spotCheckAt, now = new Date()) {
  ensureSchedule(item);
  item.schedule = {
    ...item.schedule,
    intervalDays: Math.max(0, Math.round((Date.parse(spotCheckAt) - now.getTime()) / DAY_MS)),
    nextReview: spotCheckAt,
  };
}

function promoteCompletedMastery(item, now, random = Math.random) {
  const mastery = ensureMastery(item);
  const retention = mastery.retention;
  if (!isItemFullyMastered(item) || ['attested', 'mastered'].includes(retention.status)) return false;
  const nowIso = now.toISOString();
  const spotCheckAt = scheduleSpotCheckAt(now, random);
  mastery.retention = {
    status: 'mastered',
    masteredAt: nowIso,
    spotCheckAt,
    spotCheckCompletedAt: null,
    lapsedAt: null,
  };
  setAuditSchedule(item, spotCheckAt, now);
  return true;
}

export function isMemorySpotCheckDue(item, now = new Date()) {
  const retention = item?.mastery?.retention;
  if (!['attested', 'mastered'].includes(retention?.status) || retention.spotCheckCompletedAt) return false;
  const dueAt = Date.parse(retention.spotCheckAt ?? '');
  return Number.isFinite(dueAt) && dueAt <= now.getTime();
}

function completeSpotCheck(item, now) {
  const retention = ensureMastery(item).retention;
  const nowIso = now.toISOString();
  item.mastery.retention = {
    ...retention,
    status: 'mastered',
    masteredAt: retention.masteredAt || nowIso,
    spotCheckCompletedAt: nowIso,
    lapsedAt: null,
  };
  for (const [, , stat] of targetMasteryEntries(item)) {
    if (!stat) continue;
    stat.masteredAt ||= nowIso;
    stat.masterySource = 'verified';
  }
}

function resumeTrainingAfterFailedSpotCheck(item, now) {
  const nowIso = now.toISOString();
  for (const [, , stat] of targetMasteryEntries(item)) {
    if (!stat) continue;
    delete stat.masteredAt;
    delete stat.masterySource;
    stat.recent = [];
  }
  item.mastery.retention = {
    status: 'lapsed',
    masteredAt: null,
    spotCheckAt: null,
    spotCheckCompletedAt: null,
    lapsedAt: nowIso,
  };
  item.schedule = defaultSchedule(nowIso);
}

/** True when an item is due for routine learning or its one-time spot check. */
export function isMemoryItemDue(item, now = new Date()) {
  const retention = item?.mastery?.retention;
  if (['attested', 'mastered'].includes(retention?.status)) {
    return isMemorySpotCheckDue(item, now);
  }
  return isScheduleDue(item?.schedule, now);
}

// =============================================================================
// TOM LEHRER'S ELEMENTS SONG — BUILT-IN CONTENT
// =============================================================================

const ELEMENTS_SONG = {
  id: 'elements-song',
  title: "The Elements (Tom Lehrer)",
  type: 'song',
  builtin: true,
  content: {
    lines: [
      { text: "There's antimony, arsenic, aluminum, selenium,", elements: ["Sb", "As", "Al", "Se"] },
      { text: "And hydrogen and oxygen and nitrogen and rhenium,", elements: ["H", "O", "N", "Re"] },
      { text: "And nickel, neodymium, neptunium, germanium,", elements: ["Ni", "Nd", "Np", "Ge"] },
      { text: "And iron, americium, ruthenium, uranium,", elements: ["Fe", "Am", "Ru", "U"] },
      { text: "Europium, zirconium, lutetium, vanadium,", elements: ["Eu", "Zr", "Lu", "V"] },
      { text: "And lanthanum and osmium and astatine and radium,", elements: ["La", "Os", "At", "Ra"] },
      { text: "And gold and protactinium and indium and gallium,", elements: ["Au", "Pa", "In", "Ga"] },
      { text: "And iodine and thorium and thulium and thallium.", elements: ["I", "Th", "Tm", "Tl"] },
      { text: "There's yttrium, ytterbium, actinium, rubidium,", elements: ["Y", "Yb", "Ac", "Rb"] },
      { text: "And boron, gadolinium, niobium, iridium,", elements: ["B", "Gd", "Nb", "Ir"] },
      { text: "And strontium and silicon and silver and samarium,", elements: ["Sr", "Si", "Ag", "Sm"] },
      { text: "And bismuth, bromine, lithium, beryllium, and barium.", elements: ["Bi", "Br", "Li", "Be", "Ba"] },
      { text: "There's holmium and helium and hafnium and erbium,", elements: ["Ho", "He", "Hf", "Er"] },
      { text: "And phosphorus and francium and fluorine and terbium,", elements: ["P", "Fr", "F", "Tb"] },
      { text: "And manganese and mercury, molybdenum, magnesium,", elements: ["Mn", "Hg", "Mo", "Mg"] },
      { text: "Dysprosium and scandium and cerium and cesium.", elements: ["Dy", "Sc", "Ce", "Cs"] },
      { text: "And lead, praseodymium, and platinum, plutonium,", elements: ["Pb", "Pr", "Pt", "Pu"] },
      { text: "Palladium, promethium, potassium, polonium,", elements: ["Pd", "Pm", "K", "Po"] },
      { text: "And tantalum, technetium, titanium, tellurium,", elements: ["Ta", "Tc", "Ti", "Te"] },
      { text: "And cadmium and calcium and chromium and curium.", elements: ["Cd", "Ca", "Cr", "Cm"] },
      { text: "There's sulfur, californium, and fermium, berkelium,", elements: ["S", "Cf", "Fm", "Bk"] },
      { text: "And also mendelevium, einsteinium, nobelium,", elements: ["Md", "Es", "No"] },
      { text: "And argon, krypton, neon, radon, xenon, zinc, and rhodium,", elements: ["Ar", "Kr", "Ne", "Rn", "Xe", "Zn", "Rh"] },
      { text: "And chlorine, carbon, cobalt, copper, tungsten, tin, and sodium.", elements: ["Cl", "C", "Co", "Cu", "W", "Sn", "Na"] },
      { text: "These are the only ones of which the news has come to Harvard,", elements: [] },
      { text: "And there may be many others, but they haven't been discovered.", elements: [] },
      // Appendix: Elements discovered since Tom Lehrer's song (103-118)
      { text: "There's lawrencium, rutherfordium, dubnium, seaborgium,", elements: ["Lr", "Rf", "Db", "Sg"] },
      { text: "And bohrium and hassium and also meitnerium,", elements: ["Bh", "Hs", "Mt"] },
      { text: "Darmstadtium, roentgenium, copernicium,", elements: ["Ds", "Rg", "Cn"] },
      { text: "Nihonium, flerovium, moscovium, livermorium,", elements: ["Nh", "Fl", "Mc", "Lv"] },
      { text: "And tennessine and oganesson complete the set—", elements: ["Ts", "Og"] },
      { text: "These are the ones that Lehrer hadn't discovered yet.", elements: [] },
    ],
    chunks: [
      { id: "verse-1", lineRange: [0, 7], label: "Verse 1" },
      { id: "verse-2", lineRange: [8, 11], label: "Verse 2" },
      { id: "verse-3", lineRange: [12, 15], label: "Verse 3" },
      { id: "verse-4", lineRange: [16, 19], label: "Verse 4" },
      { id: "verse-5", lineRange: [20, 23], label: "Verse 5" },
      { id: "coda", lineRange: [24, 25], label: "Coda" },
      { id: "appendix", lineRange: [26, 31], label: "Appendix (Post-Lehrer)" },
    ],
    // Element symbol → { name, atomicNumber } for the periodic table visualization
    elementMap: {
      H: { name: "Hydrogen", atomicNumber: 1 }, He: { name: "Helium", atomicNumber: 2 },
      Li: { name: "Lithium", atomicNumber: 3 }, Be: { name: "Beryllium", atomicNumber: 4 },
      B: { name: "Boron", atomicNumber: 5 }, C: { name: "Carbon", atomicNumber: 6 },
      N: { name: "Nitrogen", atomicNumber: 7 }, O: { name: "Oxygen", atomicNumber: 8 },
      F: { name: "Fluorine", atomicNumber: 9 }, Ne: { name: "Neon", atomicNumber: 10 },
      Na: { name: "Sodium", atomicNumber: 11 }, Mg: { name: "Magnesium", atomicNumber: 12 },
      Al: { name: "Aluminum", atomicNumber: 13 }, Si: { name: "Silicon", atomicNumber: 14 },
      P: { name: "Phosphorus", atomicNumber: 15 }, S: { name: "Sulfur", atomicNumber: 16 },
      Cl: { name: "Chlorine", atomicNumber: 17 }, Ar: { name: "Argon", atomicNumber: 18 },
      K: { name: "Potassium", atomicNumber: 19 }, Ca: { name: "Calcium", atomicNumber: 20 },
      Sc: { name: "Scandium", atomicNumber: 21 }, Ti: { name: "Titanium", atomicNumber: 22 },
      V: { name: "Vanadium", atomicNumber: 23 }, Cr: { name: "Chromium", atomicNumber: 24 },
      Mn: { name: "Manganese", atomicNumber: 25 }, Hg: { name: "Mercury", atomicNumber: 80 }, Fe: { name: "Iron", atomicNumber: 26 },
      Co: { name: "Cobalt", atomicNumber: 27 }, Ni: { name: "Nickel", atomicNumber: 28 },
      Cu: { name: "Copper", atomicNumber: 29 }, Zn: { name: "Zinc", atomicNumber: 30 },
      Ga: { name: "Gallium", atomicNumber: 31 }, Ge: { name: "Germanium", atomicNumber: 32 },
      As: { name: "Arsenic", atomicNumber: 33 }, Se: { name: "Selenium", atomicNumber: 34 },
      Br: { name: "Bromine", atomicNumber: 35 }, Kr: { name: "Krypton", atomicNumber: 36 },
      Rb: { name: "Rubidium", atomicNumber: 37 }, Sr: { name: "Strontium", atomicNumber: 38 },
      Y: { name: "Yttrium", atomicNumber: 39 }, Zr: { name: "Zirconium", atomicNumber: 40 },
      Nb: { name: "Niobium", atomicNumber: 41 }, Mo: { name: "Molybdenum", atomicNumber: 42 },
      Tc: { name: "Technetium", atomicNumber: 43 }, Ru: { name: "Ruthenium", atomicNumber: 44 },
      Rh: { name: "Rhodium", atomicNumber: 45 }, Pd: { name: "Palladium", atomicNumber: 46 },
      Ag: { name: "Silver", atomicNumber: 47 }, Cd: { name: "Cadmium", atomicNumber: 48 },
      In: { name: "Indium", atomicNumber: 49 }, Sn: { name: "Tin", atomicNumber: 50 },
      Sb: { name: "Antimony", atomicNumber: 51 }, Te: { name: "Tellurium", atomicNumber: 52 },
      I: { name: "Iodine", atomicNumber: 53 }, Xe: { name: "Xenon", atomicNumber: 54 },
      Cs: { name: "Cesium", atomicNumber: 55 }, Ba: { name: "Barium", atomicNumber: 56 },
      La: { name: "Lanthanum", atomicNumber: 57 }, Ce: { name: "Cerium", atomicNumber: 58 },
      Pr: { name: "Praseodymium", atomicNumber: 59 }, Nd: { name: "Neodymium", atomicNumber: 60 },
      Pm: { name: "Promethium", atomicNumber: 61 }, Sm: { name: "Samarium", atomicNumber: 62 },
      Eu: { name: "Europium", atomicNumber: 63 }, Gd: { name: "Gadolinium", atomicNumber: 64 },
      Tb: { name: "Terbium", atomicNumber: 65 }, Dy: { name: "Dysprosium", atomicNumber: 66 },
      Ho: { name: "Holmium", atomicNumber: 67 }, Er: { name: "Erbium", atomicNumber: 68 },
      Tm: { name: "Thulium", atomicNumber: 69 }, Yb: { name: "Ytterbium", atomicNumber: 70 },
      Lu: { name: "Lutetium", atomicNumber: 71 }, Hf: { name: "Hafnium", atomicNumber: 72 },
      Ta: { name: "Tantalum", atomicNumber: 73 }, W: { name: "Tungsten", atomicNumber: 74 },
      Re: { name: "Rhenium", atomicNumber: 75 }, Os: { name: "Osmium", atomicNumber: 76 },
      Ir: { name: "Iridium", atomicNumber: 77 }, Pt: { name: "Platinum", atomicNumber: 78 },
      Au: { name: "Gold", atomicNumber: 79 }, Tl: { name: "Thallium", atomicNumber: 81 },
      Pb: { name: "Lead", atomicNumber: 82 }, Bi: { name: "Bismuth", atomicNumber: 83 },
      Po: { name: "Polonium", atomicNumber: 84 }, At: { name: "Astatine", atomicNumber: 85 },
      Rn: { name: "Radon", atomicNumber: 86 }, Fr: { name: "Francium", atomicNumber: 87 },
      Ra: { name: "Radium", atomicNumber: 88 }, Ac: { name: "Actinium", atomicNumber: 89 },
      Th: { name: "Thorium", atomicNumber: 90 }, Pa: { name: "Protactinium", atomicNumber: 91 },
      U: { name: "Uranium", atomicNumber: 92 }, Np: { name: "Neptunium", atomicNumber: 93 },
      Pu: { name: "Plutonium", atomicNumber: 94 }, Am: { name: "Americium", atomicNumber: 95 },
      Cm: { name: "Curium", atomicNumber: 96 }, Bk: { name: "Berkelium", atomicNumber: 97 },
      Cf: { name: "Californium", atomicNumber: 98 }, Es: { name: "Einsteinium", atomicNumber: 99 },
      Fm: { name: "Fermium", atomicNumber: 100 }, Md: { name: "Mendelevium", atomicNumber: 101 },
      No: { name: "Nobelium", atomicNumber: 102 }, Lr: { name: "Lawrencium", atomicNumber: 103 },
      Rf: { name: "Rutherfordium", atomicNumber: 104 }, Db: { name: "Dubnium", atomicNumber: 105 },
      Sg: { name: "Seaborgium", atomicNumber: 106 }, Bh: { name: "Bohrium", atomicNumber: 107 },
      Hs: { name: "Hassium", atomicNumber: 108 }, Mt: { name: "Meitnerium", atomicNumber: 109 },
      Ds: { name: "Darmstadtium", atomicNumber: 110 }, Rg: { name: "Roentgenium", atomicNumber: 111 },
      Cn: { name: "Copernicium", atomicNumber: 112 }, Nh: { name: "Nihonium", atomicNumber: 113 },
      Fl: { name: "Flerovium", atomicNumber: 114 }, Mc: { name: "Moscovium", atomicNumber: 115 },
      Lv: { name: "Livermorium", atomicNumber: 116 }, Ts: { name: "Tennessine", atomicNumber: 117 },
      Og: { name: "Oganesson", atomicNumber: 118 },
    }
  },
  mastery: { overallPct: 0, chunks: {}, elements: {}, retention: { status: 'learning' } },
  createdAt: '2026-03-08T00:00:00.000Z',
  updatedAt: '2026-03-08T00:00:00.000Z',
};

// =============================================================================
// DATA ACCESS
// =============================================================================

async function loadMemoryItems() {
  const data = await readJSONFile(MEMORY_ITEMS_FILE, { items: [] }, { allowArray: false, strict: true });
  const items = data?.items && Array.isArray(data.items) ? data.items : [];

  // Ensure built-in Elements Song is always present and content stays current
  const existingIdx = items.findIndex(i => i.id === 'elements-song');
  if (existingIdx === -1) {
    items.unshift(structuredClone(ELEMENTS_SONG));
  } else {
    const existing = items[existingIdx];
    const fresh = structuredClone(ELEMENTS_SONG);
    fresh.mastery = existing.mastery || fresh.mastery;
    // Preserve the learned review schedule across content re-seeds (like mastery).
    if (existing.schedule) fresh.schedule = existing.schedule;
    fresh.updatedAt = existing.updatedAt;
    items[existingIdx] = fresh;
  }

  // Backfill a schedule on any item that predates spaced-repetition (built-in
  // or legacy custom items) so every item is schedulable + surfaces as due.
  for (const item of items) {
    ensureSchedule(item);
    ensureMastery(item);
  }

  return items;
}

async function saveMemoryItems(items) {
  await ensureDir(MEATSPACE_DIR);
  await atomicWrite(MEMORY_ITEMS_FILE, { items });
}

// =============================================================================
// MEMORY ITEMS CRUD
// =============================================================================

export async function getMemoryItems() {
  return loadMemoryItems();
}

export async function getMemoryItem(id) {
  const items = await loadMemoryItems();
  return items.find(i => i.id === id) || null;
}

export function createMemoryItem(data) {
  return queueMemoryWrite(() => createMemoryItemLocked(data));
}

async function createMemoryItemLocked(data) {
  const items = await loadMemoryItems();
  const now = new Date().toISOString();

  const rawLines = (data.lines || []).map(l => ({
    text: l.text || l,
    ...(l.elements ? { elements: l.elements } : {})
  }));

  // Auto-chunk uses all lines (including blanks for boundary detection)
  const chunks = data.chunks || autoChunk(rawLines);

  // Store only non-empty lines for practice
  const contentLines = rawLines.filter(l => l.text.trim().length > 0);

  // Remap chunk lineRanges to match filtered line indices
  const remappedChunks = remapChunksAfterFilter(rawLines, contentLines, chunks);

  const item = {
    id: randomUUID(),
    title: data.title,
    type: data.type || 'text',
    builtin: false,
    content: {
      lines: contentLines,
      chunks: remappedChunks,
    },
    mastery: { overallPct: 0, chunks: {}, elements: {}, retention: { status: 'learning' } },
    // Honor a client-provided schedule (e.g. importing an item with progress),
    // else stamp a fresh "due now" default.
    schedule: data.schedule || defaultSchedule(now),
    createdAt: now,
    updatedAt: now,
  };

  items.push(item);
  await saveMemoryItems(items);
  console.log(`🧠 Memory item created: "${item.title}" (${contentLines.length} lines, ${remappedChunks.length} chunks)`);
  return item;
}

export function updateMemoryItem(id, updates) {
  return queueMemoryWrite(() => updateMemoryItemLocked(id, updates));
}

async function updateMemoryItemLocked(id, updates) {
  const items = await loadMemoryItems();
  const idx = items.findIndex(i => i.id === id);
  if (idx === -1) return null;
  if (items[idx].builtin) {
    // Only allow mastery / schedule updates on built-in items
    if (updates.mastery || updates.schedule) {
      if (updates.mastery) items[idx].mastery = updates.mastery;
      if (updates.schedule) items[idx].schedule = updates.schedule;
      items[idx].updatedAt = new Date().toISOString();
      await saveMemoryItems(items);
      return items[idx];
    }
    return items[idx];
  }

  const item = items[idx];
  if (updates.title) item.title = updates.title;
  if (updates.type) item.type = updates.type;
  if (updates.schedule) item.schedule = updates.schedule;
  if (updates.mastery) item.mastery = updates.mastery;
  if (updates.lines) {
    item.content.lines = updates.lines.map(l => ({
      text: l.text || l,
      ...(l.elements ? { elements: l.elements } : {})
    }));
  }
  if (updates.chunks) {
    item.content.chunks = updates.chunks;
  }
  item.updatedAt = new Date().toISOString();
  await saveMemoryItems(items);
  console.log(`🧠 Memory item updated: "${item.title}"`);
  return item;
}

/**
 * User attestation is trusted provisionally: remove the item from routine
 * training now, then schedule one randomized future audit. Passing that audit
 * makes the attestation verified; failing it resumes ordinary learning.
 */
export function attestMemoryItemMastery(id, now = new Date(), random = Math.random) {
  return queueMemoryWrite(() => attestMemoryItemMasteryLocked(id, now, random));
}

async function attestMemoryItemMasteryLocked(id, now, random) {
  const items = await loadMemoryItems();
  const item = items.find(i => i.id === id);
  if (!item) return null;

  const targets = targetMasteryEntries(item);
  if (!targets.length) return null;
  const nowIso = now.toISOString();
  for (const [key, bucket, existing] of targets) {
    const stat = existing || { correct: 0, attempts: 0 };
    stat.masteredAt = nowIso;
    stat.masterySource = 'attested';
    bucket[key] = stat;
  }

  const spotCheckAt = scheduleSpotCheckAt(now, random);
  item.mastery.retention = {
    status: 'attested',
    attestedAt: nowIso,
    masteredAt: null,
    spotCheckAt,
    spotCheckCompletedAt: null,
    lapsedAt: null,
  };
  item.mastery.overallPct = computeOverallMastery(item);
  setAuditSchedule(item, spotCheckAt, now);
  item.updatedAt = nowIso;
  await saveMemoryItems(items);
  console.log(`🧠 Memory mastery attested: "${item.title}" → one future spot check scheduled`);
  return { mastery: item.mastery, schedule: item.schedule };
}

export function deleteMemoryItem(id) {
  return queueMemoryWrite(() => deleteMemoryItemLocked(id));
}

async function deleteMemoryItemLocked(id) {
  const items = await loadMemoryItems();
  const idx = items.findIndex(i => i.id === id);
  if (idx === -1) return null;
  if (items[idx].builtin) return null; // Can't delete built-in items
  const removed = items.splice(idx, 1)[0];
  await saveMemoryItems(items);
  console.log(`🧠 Memory item deleted: "${removed.title}"`);
  return removed;
}

// =============================================================================
// PRACTICE & MASTERY
// =============================================================================

// Only these modes are scored retrieval. Learn, flash-card study, and other
// non-scored surfaces may record time/activity, but must never promote mastery
// or move the spaced-repetition schedule from a self-reported exposure.
const RETRIEVAL_PRACTICE_MODES = new Set(['spaced', 'sequence', 'fill-blank', 'element-flash']);

function recordChunkResults(item, chunkId, results, nowIso) {
  if (!item.mastery.chunks[chunkId]) {
    item.mastery.chunks[chunkId] = { correct: 0, attempts: 0, lastPracticed: null };
  }
  const chunk = item.mastery.chunks[chunkId];
  chunk.attempts += results.length;
  chunk.correct += results.filter(r => r.correct).length;
  chunk.lastPracticed = nowIso;
  for (const result of results) pushRecent(chunk, result.correct);
  preserveStatMastery(chunk, nowIso);
}

async function saveMemoryPracticeRun({ memoryItemId, mode, chunkId, results, totalMs, date, timestamp, exposure = false }) {
  const practiceId = randomUUID();
  const runId = `memory-practice:${practiceId}`;
  const correctCount = results.filter(result => result.correct).length;
  const record = {
    id: practiceId,
    runId,
    memoryItemId,
    mode,
    chunkId: chunkId || null,
    totalMs: totalMs || 0,
    date,
    timestamp,
    ...(exposure ? {} : {
      correct: correctCount,
      total: results.length,
    }),
    inputMode: 'unknown',
    scorerProvenance: 'memory-practice',
  };
  await saveStoredTrainingRun({
    id: runId,
    mode: 'training',
    localDay: date,
    startedAt: timestamp,
    completedAt: timestamp,
    status: 'completed',
    planned: { modules: ['memory'] },
    data: { id: runId, mode: 'training' },
    attempts: [{
      id: practiceId,
      module: 'memory',
      drillType: mode || 'unknown',
      correct: exposure || results.length === 0 ? null : correctCount === results.length,
      score: exposure || results.length === 0 ? null : (correctCount / results.length) * 100,
      latencyMs: totalMs || 0,
      completion: exposure || results.length === 0 ? null : 1,
      hintUsed: !exposure && results.some(result => result?.hintUsed === true),
      inputMode: 'unknown',
      scorerProvenance: 'memory-practice',
      data: record,
    }],
  });
  return practiceId;
}

export async function submitPractice(id, practiceData) {
  const { mode, chunkId, results = [], totalMs } = practiceData;
  const nowDate = new Date();
  const now = nowDate.toISOString();
  // Day-key in the user's local timezone (issue #2681): this practice is a
  // training-log entry feeding the SHARED unified streak, which now reads against
  // the user's local `today`. A full UTC ISO here (the old `date: now`) split to
  // the UTC day would drop a local-evening practice from today's streak. `date`
  // is a day-key (every reader does `String(date).split('T')[0]`); `timestamp`
  // keeps the exact instant, matching submitTrainingEntry's shape. Derive the day
  // from the SAME `nowDate` so a midnight boundary can't split date and timestamp.
  const todayLocal = await userLocalToday(nowDate);

  // Passive study is activity, not retrieval. Keep the event for time/streak
  // reporting, but do not touch mastery, retention, schedule, or correctness.
  // This also makes old clients that sent a synthetic `{ correct: true }` learn
  // result harmless: the service ignores the payload entirely in this branch.
  if (!RETRIEVAL_PRACTICE_MODES.has(mode)) {
    const item = await getMemoryItem(id);
    if (!item) return null;
    const practiceId = await saveMemoryPracticeRun({
      memoryItemId: id,
      mode,
      chunkId: null,
      results,
      totalMs,
      date: todayLocal,
      timestamp: now,
      exposure: true,
    });
    console.log(`🧠 Memory exposure logged: "${item.title}" mode=${mode}`);
    return { mastery: item.mastery, schedule: item.schedule, practiceId };
  }

  // Only the item load/edit/save runs under the store queue; the training-log
  // append does not depend on the item pre-image, so it stays outside the lock.
  const applied = await queueMemoryWrite(() => applyRetrievalPracticeLocked(id, { chunkId, results, nowDate, now }));
  if (!applied) return null;
  const { item, correctCount } = applied;

  const practiceId = await saveMemoryPracticeRun({
    memoryItemId: id,
    mode,
    chunkId,
    results,
    totalMs,
    date: todayLocal,
    timestamp: now,
  });

  console.log(`🧠 Practice logged: "${item.title}" mode=${mode} ${correctCount}/${results.length} → next review in ${item.schedule.intervalDays}d`);
  return { mastery: item.mastery, schedule: item.schedule, practiceId };
}

// Mutation half of submitPractice. Callers must hold queueMemoryWrite.
async function applyRetrievalPracticeLocked(id, { chunkId, results, nowDate, now }) {
  const items = await loadMemoryItems();
  const item = items.find(i => i.id === id);
  if (!item) return null;

  const correctCount = results.filter(r => r.correct).length;
  const ratio = results.length ? correctCount / results.length : 0;
  const spotCheckDue = isMemorySpotCheckDue(item, nowDate);
  if (spotCheckDue && ratio < MASTERY_TARGET_ACCURACY) {
    resumeTrainingAfterFailedSpotCheck(item, nowDate);
  }

  // Update chunk mastery
  if (chunkId) {
    recordChunkResults(item, chunkId, results, now);
  } else {
    const resultsByChunk = new Map();
    for (const result of results) {
      if (!result.chunkId) continue;
      const bucket = resultsByChunk.get(result.chunkId) || [];
      bucket.push(result);
      resultsByChunk.set(result.chunkId, bucket);
    }
    for (const [resultChunkId, chunkResults] of resultsByChunk) {
      recordChunkResults(item, resultChunkId, chunkResults, now);
    }
  }

  // Update element-level mastery (for elements song)
  if (results) {
    for (const r of results) {
      if (r.element) {
        if (!item.mastery.elements[r.element]) {
          item.mastery.elements[r.element] = { correct: 0, attempts: 0 };
        }
        const el = item.mastery.elements[r.element];
        el.attempts++;
        if (r.correct) el.correct++;
        pushRecent(el, r.correct);
        preserveStatMastery(el, now);
      }
    }
  }

  // Recompute overall mastery percentage
  item.mastery.overallPct = computeOverallMastery(item);

  // Advance the spaced-repetition schedule from this session's accuracy. The
  // schedule is per-ITEM (mastery is per-chunk); practicing any part of an item
  // counts as reviewing it, so it resurfaces on the next review day rather than
  // staying due today. `mergeScheduleAdvance` gates interval growth to once per
  // day so the per-chunk submits of a spaced session don't compound the interval,
  // while a miss anywhere still resets the item to due-now.
  if (spotCheckDue && ratio >= MASTERY_TARGET_ACCURACY) {
    completeSpotCheck(item, nowDate);
  } else if (!spotCheckDue && promoteCompletedMastery(item, nowDate)) {
    item.mastery.overallPct = computeOverallMastery(item);
  } else if (!['attested', 'mastered'].includes(item.mastery.retention?.status)) {
    const advanced = advanceSchedule(item.schedule, ratio, nowDate);
    item.schedule = mergeScheduleAdvance(item.schedule, advanced, nowDate);
  }

  item.updatedAt = now;
  await saveMemoryItems(items);
  return { item, correctCount };
}

/**
 * Advance a memory item's spaced-repetition schedule from a POST-session
 * memory drill's accuracy ratio (0..1). Mirrors the schedule half of
 * `submitPractice` — a POST-session memory drill IS a review, so it should
 * reschedule the item and clear it from "Due Today" just like MemoryBuilder's
 * dedicated practice flow. Unlike `submitPractice`, this does NOT touch
 * chunk/element mastery — POST sessions don't carry the chunk/element-level
 * result data `submitPractice` uses for that.
 *
 * Returns the updated schedule, or `null` when `memoryItemId` is absent or
 * doesn't match a known item. The composed-session path uses
 * `applySessionToMemoryItems`, which gates tasks to scored retrieval types.
 */
export function advanceScheduleFromSession(memoryItemId, ratio, now = new Date()) {
  if (!memoryItemId) return Promise.resolve(null);
  return queueMemoryWrite(() => advanceScheduleFromSessionLocked(memoryItemId, ratio, now));
}

async function advanceScheduleFromSessionLocked(memoryItemId, ratio, now) {
  const items = await loadMemoryItems();
  const item = items.find(i => i.id === memoryItemId);
  if (!item) return null;

  applyScheduleAdvanceToItem(item, ratio, now);
  await saveMemoryItems(items);

  console.log(`🧠 POST session reviewed "${item.title}" → next review in ${item.schedule.intervalDays}d`);
  return item.schedule;
}

// In-place schedule advance shared by advanceScheduleFromSession (one load+save)
// and applySessionToMemoryItems (one load+save for the WHOLE session). Keeping a
// single core guarantees the consolidated one-pass path produces byte-identical
// schedule results to the legacy per-task path.
function applyScheduleAdvanceToItem(item, ratio, now) {
  if (isMemorySpotCheckDue(item, now)) {
    if (ratio >= MASTERY_TARGET_ACCURACY) completeSpotCheck(item, now);
    else resumeTrainingAfterFailedSpotCheck(item, now);
    item.updatedAt = now.toISOString();
    return item.schedule;
  }
  if (['attested', 'mastered'].includes(item.mastery?.retention?.status)) {
    item.updatedAt = now.toISOString();
    return item.schedule;
  }
  const advanced = advanceSchedule(item.schedule, ratio, now);
  item.schedule = mergeScheduleAdvance(item.schedule, advanced, now);
  item.updatedAt = now.toISOString();
  return item.schedule;
}

function normalizeFillBlankValue(value) {
  return String(value ?? '').toLowerCase().trim();
}

/**
 * Expand the indexed answer list introduced for multi-blank recall into the
 * per-blank attempts used by mastery and scheduling. A legacy scalar question
 * deliberately remains one attempt, even if its generated prompt once had
 * several hidden words.
 */
export function expandMemoryQuestionResults(questions = []) {
  return (Array.isArray(questions) ? questions : []).flatMap(question => {
    if (!Array.isArray(question?.answered)) return [question];
    return question.answered.map(answer => {
      const answered = answer?.value ?? null;
      // New clients send the answer key with each indexed response. For a
      // one-entry legacy structured payload, the question-level expected value
      // is a safe fallback; never apply a scalar key to every blank.
      const expected = answer?.expected ?? (
        question.answered.length === 1 && typeof question.expected === 'string'
          ? question.expected
          : undefined
      );
      const correct = typeof expected === 'string'
        ? answered !== null && normalizeFillBlankValue(answered) === normalizeFillBlankValue(expected)
        : Boolean(answer?.correct);
      return {
        ...question,
        expected,
        answered,
        correct,
        ...(answer?.element !== undefined ? { element: answer.element } : {}),
      };
    });
  });
}

/** Recompute question-level correctness for persisted multi-blank results. */
export function normalizeMemoryQuestionResults(questions = []) {
  return (Array.isArray(questions) ? questions : []).map(question => {
    if (!Array.isArray(question?.answered)) return question;
    const attempts = expandMemoryQuestionResults([question]);
    return {
      ...question,
      answered: question.answered.map((answer, index) => ({
        ...answer,
        value: attempts[index]?.answered ?? null,
        ...(attempts[index]?.expected !== undefined ? { expected: attempts[index].expected } : {}),
        correct: attempts[index]?.correct ?? false,
        ...(attempts[index]?.element !== undefined ? { element: attempts[index].element } : {}),
      })),
      correct: attempts.length > 0 && attempts.every(attempt => attempt.correct),
    };
  });
}

// In-place mastery merge shared by mergeMasteryFromSession and
// applySessionToMemoryItems — same single-core-of-truth rationale as
// applyScheduleAdvanceToItem above.
function applyMasteryMergeToItem(item, questions, now) {
  const nowIso = now.toISOString();
  const correct = questions.filter(q => q.correct).length;
  const ratio = questions.length ? correct / questions.length : 0;
  const spotCheckDue = isMemorySpotCheckDue(item, now);
  if (spotCheckDue && ratio < MASTERY_TARGET_ACCURACY) {
    resumeTrainingAfterFailedSpotCheck(item, now);
  }
  for (const q of questions) {
    if (q.chunkId) {
      if (!item.mastery.chunks[q.chunkId]) {
        item.mastery.chunks[q.chunkId] = { correct: 0, attempts: 0, lastPracticed: null };
      }
      const chunk = item.mastery.chunks[q.chunkId];
      chunk.attempts += 1;
      if (q.correct) chunk.correct += 1;
      chunk.lastPracticed = nowIso;
      pushRecent(chunk, q.correct);
      preserveStatMastery(chunk, nowIso);
    }
    if (q.element) {
      if (!item.mastery.elements[q.element]) {
        item.mastery.elements[q.element] = { correct: 0, attempts: 0 };
      }
      const el = item.mastery.elements[q.element];
      el.attempts += 1;
      if (q.correct) el.correct += 1;
      pushRecent(el, q.correct);
      preserveStatMastery(el, nowIso);
    }
  }

  item.mastery.overallPct = computeOverallMastery(item);
  if (spotCheckDue && ratio >= MASTERY_TARGET_ACCURACY) {
    completeSpotCheck(item, now);
  } else if (!spotCheckDue && promoteCompletedMastery(item, now)) {
    item.mastery.overallPct = computeOverallMastery(item);
  }
  item.updatedAt = nowIso;
  return item.mastery;
}

/**
 * Merge a POST session's per-question memory drill results into an item's
 * chunk/element mastery (`item.mastery.chunks`/`item.mastery.elements`) —
 * the mastery half of what `submitPractice` does, deferred out of #2010
 * (schedule-only) into #2016 because POST-session answers didn't carry
 * chunk/element attribution until `usePostSession.js`'s `submitAnswer` started
 * preserving `q.chunkId` / `q.element` onto each answer.
 *
 * Unlike `submitPractice` (one `chunkId` for the whole batch — a dedicated
 * chunk-practice session), a POST-session memory-sequence drill can span
 * several chunks and a memory-element-flash drill spans several elements, so
 * this buckets PER-QUESTION by whichever attribution that question carries.
 * Questions with neither `chunkId` nor `element` (e.g. an unsupported/legacy
 * shape) are counted toward correctness of nothing — they simply don't shift
 * `item.mastery`.
 *
 * Returns the updated mastery, or `null` when `memoryItemId`/`questions` are
 * absent or the id doesn't match a known item.
 */
export function mergeMasteryFromSession(memoryItemId, questions, now = new Date()) {
  if (!memoryItemId || !Array.isArray(questions) || !questions.length) return Promise.resolve(null);
  return queueMemoryWrite(() => mergeMasteryFromSessionLocked(memoryItemId, questions, now));
}

async function mergeMasteryFromSessionLocked(memoryItemId, questions, now) {
  const items = await loadMemoryItems();
  const item = items.find(i => i.id === memoryItemId);
  if (!item) return null;

  const attempts = expandMemoryQuestionResults(questions);
  if (!attempts.length) return null;
  applyMasteryMergeToItem(item, attempts, now);
  await saveMemoryItems(items);

  console.log(`🧠 POST session mastery merged: "${item.title}" ${attempts.length} answers → ${item.mastery.overallPct}% overall`);
  return item.mastery;
}

/**
 * Consolidated post-session memory bookkeeping: advance schedule AND merge
 * chunk/element mastery for every memory drill in a session, reading and writing
 * the shared memory-items file exactly ONCE regardless of task count (the
 * previous path did 2 full read-modify-write round-trips PER memory task). A
 * task is a memory drill iff it carries a `memoryItemId` — the only tasks the
 * submit path attaches one to (POST_SUPPORTED_MEMORY_TYPES). Per task the
 * schedule ratio is correct-over-total, matching the legacy per-task caller.
 *
 * @param {Array<{memoryItemId?, questions?}>} tasks - the session's scored tasks
 * @returns {Promise<{updated:number}>} how many memory items were touched
 */
export function applySessionToMemoryItems(tasks, now = new Date()) {
  const memoryTasks = (Array.isArray(tasks) ? tasks : []).filter(t => (
    t?.memoryItemId
    && (!t.type || ['memory-fill-blank', 'memory-sequence', 'memory-element-flash'].includes(t.type))
  ));
  if (!memoryTasks.length) return Promise.resolve({ updated: 0 });
  return queueMemoryWrite(() => applySessionToMemoryItemsLocked(memoryTasks, now));
}

async function applySessionToMemoryItemsLocked(memoryTasks, now) {
  const items = await loadMemoryItems();
  let updated = 0;
  for (const task of memoryTasks) {
    const item = items.find(i => i.id === task.memoryItemId);
    if (!item) continue;
    const questions = expandMemoryQuestionResults(task.questions);
    const total = questions.length;
    const correct = questions.filter(q => q?.correct).length;
    const ratio = total ? correct / total : 0;
    applyScheduleAdvanceToItem(item, ratio, now);
    // mergeMasteryFromSession is a no-op on empty questions; mirror that so the
    // one-pass path stays identical to the legacy schedule+mastery sequence.
    if (questions.length) applyMasteryMergeToItem(item, questions, now);
    updated += 1;
    console.log(`🧠 POST session reviewed "${item.title}" → next review in ${item.schedule.intervalDays}d`);
  }

  if (updated) await saveMemoryItems(items);
  return { updated };
}

/**
 * List memory items currently due for review (`nextReview <= now`), sorted by
 * how overdue they are (most overdue first).
 */
export async function getDueMemoryItems(now = new Date()) {
  const items = await loadMemoryItems();
  return items
    .filter(i => isMemoryItemDue(i, now))
    .sort((a, b) => Date.parse(a.schedule?.nextReview || 0) - Date.parse(b.schedule?.nextReview || 0));
}

export async function getMastery(id) {
  const item = await getMemoryItem(id);
  if (!item) return null;
  return item.mastery;
}

// =============================================================================
// DRILL GENERATION (for POST sessions)
// =============================================================================

/**
 * Generate a memory drill for a POST session.
 * Picks the memory item with the lowest mastery (or user-configured item)
 * and creates a fill-in-the-blank or sequence recall exercise.
 * Uses spaced repetition: focuses on lowest-mastery chunks.
 *
 * `postConfig` (the saved POST config) scopes the automatic lowest-mastery
 * candidate pool to items the user hasn't switched off in their Practice Plan
 * (issue #3252). An EXPLICIT `config.memoryItemId` always wins — a disabled item
 * stays practiceable on demand from its own page, it just isn't auto-picked.
 * When every item is disabled the pool falls back to all of them rather than
 * failing the drill: a composed session that asked for a memory drill should
 * still get one.
 */
export async function generateMemoryDrill(config = {}, postConfig = null) {
  const items = await loadMemoryItems();
  if (!items.length) return null;

  // Pick target item — configured or lowest mastery
  let item;
  if (config.memoryItemId) {
    item = items.find(i => i.id === config.memoryItemId);
  }
  if (!item) {
    const enabled = items.filter(i => isMemoryItemEnabled(postConfig, i.id));
    const pool = enabled.length ? enabled : items;
    item = pool.reduce((lowest, i) => i.mastery.overallPct < lowest.mastery.overallPct ? i : lowest, pool[0]);
  }

  const mode = config.mode || 'fill-blank';
  const count = config.count || 5;

  switch (mode) {
    case 'fill-blank':
      return generateFillBlank(item, count);
    case 'sequence':
      return generateSequenceRecall(item, count);
    case 'element-flash':
      return generateElementFlash(item, count);
    default:
      return generateFillBlank(item, count);
  }
}

/**
 * Get chunk mastery stats for spaced repetition.
 * Returns chunks sorted by mastery (lowest first) with hint level.
 */
export function getChunkMasteryOrder(item) {
  const chunks = item.content?.chunks || [];
  return chunks.map(chunk => {
    const stats = item.mastery?.chunks?.[chunk.id];
    const accuracy = stats?.attempts > 0 ? stats.correct / stats.attempts : 0;
    // Hint level: 0 = full hints, 1 = partial, 2 = minimal, 3 = no hints
    const hintLevel = accuracy >= 0.9 ? 3 : accuracy >= 0.7 ? 2 : accuracy >= 0.4 ? 1 : 0;
    return {
      ...chunk,
      accuracy: Math.round(accuracy * 100),
      attempts: stats?.attempts || 0,
      lastPracticed: stats?.lastPracticed || null,
      hintLevel,
    };
  }).sort((a, b) => a.accuracy - b.accuracy);
}

function generateFillBlank(item, count) {
  const lines = item.content.lines.filter(l => l.text.trim().length > 0);
  if (!lines.length) return null;

  const questions = [];
  const shuffled = shuffle(lines).slice(0, Math.min(count, lines.length));

  for (const line of shuffled) {
    const words = line.text.split(/\s+/);
    if (words.length < 3) continue;

    // Blank out ~30-50% of words, preferring element names if present
    const blankedIndices = new Set();
    const blankCount = Math.max(1, Math.floor(words.length * (0.3 + Math.random() * 0.2)));

    // Prioritize element names for blanking
    if (line.elements?.length) {
      for (const sym of line.elements) {
        const elementName = item.content.elementMap?.[sym]?.name?.toLowerCase();
        if (elementName) {
          const idx = words.findIndex((w, i) => !blankedIndices.has(i) && w.toLowerCase().replace(/[,.]$/, '') === elementName);
          if (idx >= 0 && blankedIndices.size < blankCount) blankedIndices.add(idx);
        }
      }
    }

    // Fill remaining blanks randomly
    while (blankedIndices.size < blankCount) {
      blankedIndices.add(Math.floor(Math.random() * words.length));
    }

    const display = words.map((w, i) => blankedIndices.has(i) ? '____' : w).join(' ');
    const answers = [...blankedIndices].sort((a, b) => a - b).map(i => ({
      index: i,
      word: words[i].replace(/[,.]$/, ''),
      element: line.elements?.length ? findElementForWord(words[i], item.content.elementMap) : null,
    }));

    questions.push({
      prompt: display,
      fullText: line.text,
      // Scalar primary answer (the first blanked word) — kept alongside the
      // indexed `answers[]` key for legacy consumers. New POST clients render
      // and submit every entry; a scalar response remains a one-blank legacy
      // attempt rather than a full-prompt pass.
      expected: answers[0]?.word ?? null,
      answers,
      chunkId: findChunkForLine(item, lines.indexOf(line)),
    });
  }

  return {
    type: 'memory-fill-blank',
    memoryItemId: item.id,
    memoryItemTitle: item.title,
    config: { count },
    questions,
  };
}

function generateSequenceRecall(item, count) {
  const lines = item.content.lines.filter(l => l.text.trim().length > 0);
  if (lines.length < 2) return null;

  const questions = [];
  const indices = shuffle([...Array(lines.length - 1).keys()]).slice(0, Math.min(count, lines.length - 1));

  for (const idx of indices) {
    questions.push({
      prompt: lines[idx].text,
      promptLabel: 'What comes next?',
      expected: lines[idx + 1].text,
      chunkId: findChunkForLine(item, idx),
    });
  }

  return {
    type: 'memory-sequence',
    memoryItemId: item.id,
    memoryItemTitle: item.title,
    config: { count },
    questions,
  };
}

function generateElementFlash(item, count) {
  if (item.id !== 'elements-song' || !item.content.elementMap) return null;

  const elements = Object.entries(item.content.elementMap);
  const shuffled = shuffle(elements).slice(0, Math.min(count, elements.length));

  const questions = shuffled.map(([symbol, info]) => {
    // Randomly ask name→symbol or symbol→name
    const askSymbol = Math.random() > 0.5;
    return askSymbol
      ? { prompt: info.name, promptLabel: 'Symbol?', expected: symbol, element: symbol, direction: 'name-to-symbol' }
      : { prompt: `${symbol} (${info.atomicNumber})`, promptLabel: 'Element name?', expected: info.name, element: symbol, direction: 'symbol-to-name' };
  });

  return {
    type: 'memory-element-flash',
    memoryItemId: item.id,
    memoryItemTitle: item.title,
    config: { count },
    questions,
  };
}

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

export function computeOverallMastery(item) {
  // For elements song: mastery is per-element, judged over the recency window
  // (decay-aware, issue #2096) — a recent run of misses lowers the count. The
  // ≥3-attempt gate is kept, but applied to the window (or the cumulative
  // fallback for legacy items with no window).
  if (item.id === 'elements-song' && item.content.elementMap) {
    const totalElements = Object.keys(item.content.elementMap).length;
    if (totalElements === 0) return 0;
    let masteredCount = 0;
    for (const sym of Object.keys(item.content.elementMap)) {
      const m = item.mastery.elements[sym];
      if (m && isStatMastered(m)) masteredCount++;
    }
    return Math.round((masteredCount / totalElements) * 100);
  }

  // For generic items: durable chunks remain at 100%; learning chunks continue
  // to show their rolling-window accuracy.
  const chunks = Object.values(item.mastery.chunks);
  if (!chunks.length) return 0;
  const avgAccuracy = chunks.reduce(
    (sum, c) => sum + (typeof c?.masteredAt === 'string' ? 1 : windowedAccuracy(c).accuracy),
    0,
  ) / chunks.length;
  return Math.round(avgAccuracy * 100);
}

function findChunkForLine(item, lineIndex) {
  for (const chunk of item.content.chunks || []) {
    const [start, end] = chunk.lineRange;
    if (lineIndex >= start && lineIndex <= end) return chunk.id;
  }
  return null;
}

function findElementForWord(word, elementMap) {
  if (!elementMap) return null;
  const clean = word.toLowerCase().replace(/[,.\s]/g, '');
  for (const [symbol, info] of Object.entries(elementMap)) {
    if (info.name.toLowerCase() === clean) return symbol;
  }
  return null;
}

/**
 * Auto-chunk content into learnable segments.
 * Splits on blank lines first (verse/stanza boundaries).
 * Falls back to groups of ~4 lines if no blank lines.
 */
function autoChunk(lines) {
  const texts = lines.map(l => (typeof l === 'string' ? l : l.text) || '');

  // Check for blank-line boundaries
  const groups = [];
  let current = [];
  let startIdx = 0;
  for (let i = 0; i < texts.length; i++) {
    if (texts[i].trim() === '' && current.length > 0) {
      groups.push({ start: startIdx, end: i - 1 });
      current = [];
      startIdx = i + 1;
    } else if (texts[i].trim() !== '') {
      current.push(i);
    }
  }
  if (current.length > 0) {
    groups.push({ start: startIdx, end: texts.length - 1 });
  }

  // If blank-line splitting produced reasonable chunks (2+), use them
  if (groups.length >= 2) {
    return groups.map((g, i) => ({
      id: `chunk-${i + 1}`,
      lineRange: [g.start, g.end],
      label: `Part ${i + 1}`,
    }));
  }

  // Fallback: fixed-size groups of ~4 lines
  const chunkSize = 4;
  const chunks = [];
  for (let i = 0; i < lines.length; i += chunkSize) {
    const end = Math.min(i + chunkSize - 1, lines.length - 1);
    chunks.push({
      id: `chunk-${Math.floor(i / chunkSize) + 1}`,
      lineRange: [i, end],
      label: `Part ${Math.floor(i / chunkSize) + 1}`,
    });
  }
  return chunks;
}

/**
 * Remap chunk lineRanges after blank lines are filtered out.
 * Maps original indices to new indices in the filtered array.
 */
function remapChunksAfterFilter(rawLines, filteredLines, chunks) {
  // Build mapping: original index → filtered index
  const indexMap = new Map();
  let filteredIdx = 0;
  for (let i = 0; i < rawLines.length; i++) {
    const text = typeof rawLines[i] === 'string' ? rawLines[i] : rawLines[i].text;
    if (text.trim().length > 0) {
      indexMap.set(i, filteredIdx);
      filteredIdx++;
    }
  }

  return chunks.map(chunk => {
    const [origStart, origEnd] = chunk.lineRange;
    // Find first and last non-empty lines in this chunk's range
    let newStart = null;
    let newEnd = null;
    for (let i = origStart; i <= origEnd; i++) {
      if (indexMap.has(i)) {
        if (newStart === null) newStart = indexMap.get(i);
        newEnd = indexMap.get(i);
      }
    }
    if (newStart === null) return null; // Empty chunk
    return { ...chunk, lineRange: [newStart, newEnd] };
  }).filter(Boolean);
}

export { ELEMENTS_SONG };