dsh-aha-tutor 1.5.0 → 1.6.0

package/lib/index.js

@@ -1,4 +1,4 @@
-import { $ as conceptIndex, A as generateText, B as readProgress, C as revisePrompt, D as TutorError, E as summaryPrompt, F as materialImages, G as applyEvidence, H as formatPassages, I as materialsSummary, J as recommendNext, K as createConceptState, L as passagesFor, M as EMPTY_PROFILE, N as emptyProgress, O as generateJson, P as masteryFor, Q as blueprintOutline, R as readMaterials, S as researchQueriesPrompt, T as shortPrompt, U as passageRange, V as documentParts, W as spreadPassages, X as boardToPlainText, Y as extractJson, Z as normalizeBoard, _ as projectReviewPrompt, _t as assertId, a as blueprintPrompt, at as lessonAfter, b as quizPrompt, c as detectLanguage, ct as normalizeCards, d as flashcardsPrompt, dt as normalizePractice, et as courseProgress, f as gradePrompt, ft as normalizeProject, g as profilePrompt, gt as text, h as practicePrompt, ht as safeRelativePath, i as assistPrompt, it as intakeSummary, j as streamCounter, k as generateSteps, l as digestPartPrompt, lt as normalizeCheatsheet, m as materialBriefPrompt, mt as outlineForPrompt, n as publishRuntime, nt as flattenLessons, o as cheatsheetPrompt, ot as nextLesson, p as lessonPrompt, pt as normalizeQuestionnaire, q as masteryPercent, r as askPrompt, rt as insertLesson, s as correctionPrompt, st as normalizeBlueprint, tt as findLesson, u as digestPrompt, ut as normalizeLesson, v as projectsPrompt, vt as newId, w as reworkPrompt, x as reexplainPrompt, y as questionnairePrompt, z as readProfile } from "./runtime-DqCjJ0yL.js";
+import { $ as BOARD_LIMITS, A as TutorError, B as passagesFor, C as researchQueriesPrompt, Ct as text, D as summaryPrompt, E as shortPrompt, Et as newId, F as EMPTY_PROFILE, G as formatPassages, H as readProfile, I as emptyProgress, J as applyEvidence, K as passageRange, L as masteryFor, M as generateSteps, N as generateText, O as verifyItemPrompt, P as streamCounter, Q as extractJson, R as materialImages, S as reexplainPrompt, St as safeRelativePath, T as reworkPrompt, Tt as assertId, U as readProgress, V as readMaterials, W as documentParts, X as masteryPercent, Y as createConceptState, Z as recommendNext, _ as profilePrompt, _t as normalizeLesson, a as blueprintPrompt, at as conceptIndex, b as questionnairePrompt, bt as normalizeQuestionnaire, c as correctionPrompt, ct as flattenLessons, d as digestPrompt, dt as lessonAfter, et as boardToPlainText, f as flashcardsPrompt, ft as nextLesson, g as practicePrompt, gt as normalizeItem, h as materialBriefPrompt, ht as normalizeCheatsheet, i as assistPrompt, it as blueprintOutline, j as generateJson, k as verifyStepPrompt, l as detectLanguage, lt as insertLesson, m as lessonPrompt, mt as normalizeCards, n as publishRuntime, nt as normalizeBoard, o as challengePrompt, ot as courseProgress, p as gradePrompt, pt as normalizeBlueprint, q as spreadPassages, r as askPrompt, rt as normalizeOp, s as cheatsheetPrompt, st as findLesson, tt as estimateSpeechMs, u as digestPartPrompt, ut as intakeSummary, v as projectReviewPrompt, vt as normalizePractice, w as revisePrompt, wt as plotToText, x as quizPrompt, xt as outlineForPrompt, y as projectsPrompt, yt as normalizeProject, z as materialsSummary } from "./runtime-B6zUpJjA.js";
 import { createRequire } from "node:module";
 import { dirname, join, relative, sep } from "node:path";
 import { credentialKey } from "@deepseek-ai/dsh-credentials";
@@ -932,7 +932,7 @@ function createJobs({ logger, now = Date.now } = {}) {
 		const aborted = new Promise((_, reject) => {
 			controller.signal.addEventListener("abort", () => reject(controller.signal.reason ?? /* @__PURE__ */ new Error("cancelled")), { once: true });
 		});
-		Promise.race([Promise.resolve().then(() => run(api)), aborted]).then((result) => {
+		job.settled = Promise.race([Promise.resolve().then(() => run(api)), aborted]).then((result) => {
 			job.status = "done";
 			job.result = result;
 		}).catch((error) => {
@@ -979,6 +979,12 @@ function createJobs({ logger, now = Date.now } = {}) {
 		const job = id ? jobs.get(id) : void 0;
 		return job && !job.finishedAt && !job.controller.signal.aborted ? snapshot(job) : null;
 	}
+	async function wait(id) {
+		const job = jobs.get(id);
+		if (!job) return null;
+		await job.settled;
+		return snapshot(job);
+	}
 	function cancelKey(key) {
 		const job = running(key);
 		return job ? cancel(job.id) : null;
@@ -991,6 +997,7 @@ function createJobs({ logger, now = Date.now } = {}) {
 	return Object.freeze({
 		start,
 		get,
+		wait,
 		cancel,
 		cancelKey,
 		running,
@@ -2368,16 +2375,33 @@ function createLearner({ store, llm, now = () => /* @__PURE__ */ new Date(), log
 				const lesson = findLesson(course, concept.lessonId)?.lesson;
 				const set = await store.readJson(store.paths.practice(course.id, concept.lessonId), null);
 				const board = await store.readJson(store.paths.board(course.id, concept.lessonId), null);
-				const candidates = [...set?.items ?? [], ...(board?.steps ?? []).map((step) => step.check).filter(Boolean)].filter((item) => item.conceptIds?.includes(conceptId) && item.kind !== "short" && item.kind !== "work");
-				const item = candidates[Math.floor(Math.random() * candidates.length)];
-				if (item) items.push({
+				const candidates = [...(set?.items ?? []).map((item) => ({
+					item,
+					source: {
+						kind: "practice",
+						courseId: course.id,
+						lessonId: concept.lessonId,
+						itemId: item.id
+					}
+				})), ...(board?.steps ?? []).filter((step) => step.check).map((step) => ({
+					item: step.check,
+					source: {
+						kind: "check",
+						courseId: course.id,
+						lessonId: concept.lessonId,
+						stepId: step.id
+					}
+				}))].filter(({ item }) => item.conceptIds?.includes(conceptId) && item.kind !== "short" && item.kind !== "work");
+				const pick = candidates[Math.floor(Math.random() * candidates.length)];
+				if (pick) items.push({
 					courseId: course.id,
 					courseTitle: course.title,
 					lessonId: concept.lessonId,
 					lessonTitle: lesson?.title ?? "",
 					conceptId,
 					conceptName: concept.name,
-					item
+					item: pick.item,
+					source: pick.source
 				});
 			}
 		}
@@ -2426,6 +2450,223 @@ function cleanProfile(profile) {
 	};
 }
 //#endregion
+//#region src/core/board-fix.js
+const VERDICTS = Object.freeze([
+	"wrong",
+	"right",
+	"unclear"
+]);
+const LAYOUT = /* @__PURE__ */ new Set([
+	"col",
+	"page",
+	"mark"
+]);
+function opPlain(op) {
+	switch (op?.t) {
+		case "title":
+		case "h":
+		case "p":
+		case "note": return op.text;
+		case "math": return op.text || op.tex;
+		case "list": return op.items.join("; ");
+		case "table": return [op.head, ...op.rows].filter((row) => row.length).map((row) => row.join(" | ")).join(" / ");
+		case "code": return op.code;
+		case "chart": return [
+			op.title,
+			...op.series.map((series) => `${series.name} ${series.points.slice(0, 6).map((point) => `(${point.join(", ")})`).join(" ")}`),
+			...op.data.map((item) => `${item.label} ${item.value}`)
+		].filter(Boolean).join("; ");
+		case "plot": return plotToText(op).replace(/\n/gu, "; ");
+		case "svg":
+		case "anim": return op.caption ?? "";
+		default: return "";
+	}
+}
+const withoutPlace = (op) => JSON.stringify({
+	...op,
+	id: void 0,
+	at: void 0,
+	fixed: void 0
+});
+function normalizeVerdict(raw, steps) {
+	const verdict = VERDICTS.includes(raw?.verdict) ? raw.verdict : null;
+	if (!verdict) throw new Error("the check names no verdict");
+	const summary = text(raw?.summary ?? raw?.reason, 400);
+	const fixes = [];
+	if (verdict !== "wrong") return {
+		verdict,
+		summary,
+		fixes
+	};
+	const byId = new Map(steps.map((step) => [step.id, step]));
+	const done = /* @__PURE__ */ new Set();
+	const keep = (key, fix) => {
+		if (done.has(key) || fixes.length >= 12) return;
+		done.add(key);
+		fixes.push(fix);
+	};
+	for (const fix of (Array.isArray(raw?.fixes) ? raw.fixes : []).slice(0, 36)) {
+		const step = byId.get(String(fix?.step ?? fix?.stepId ?? ""));
+		if (!step) continue;
+		const replacement = fix.replace ?? fix.with ?? fix.op_new;
+		if (replacement && typeof replacement === "object") {
+			const old = step.ops.find((op) => op.id === String(fix.op ?? fix.opId ?? ""));
+			const next = normalizeOp(replacement, 0);
+			if (old && next && !LAYOUT.has(old.t) && !LAYOUT.has(next.t) && withoutPlace(next) !== withoutPlace(old)) keep(`${step.id}:${old.id}`, {
+				step: step.id,
+				op: old.id,
+				replace: next
+			});
+		}
+		if (typeof fix.say === "string") {
+			const say = text(fix.say, BOARD_LIMITS.say);
+			if (say && say !== step.say) keep(`${step.id}:say`, {
+				step: step.id,
+				say
+			});
+		}
+		if (fix.check && typeof fix.check === "object" && step.check) {
+			const check = normalizeItem(fix.check, 0, step.check.conceptIds ?? []);
+			if (check && check.kind !== "order") {
+				const next = {
+					...check,
+					id: step.check.id,
+					conceptIds: step.check.conceptIds ?? []
+				};
+				if (JSON.stringify(next) !== JSON.stringify(step.check)) keep(`${step.id}:check`, {
+					step: step.id,
+					check: next
+				});
+			}
+		}
+	}
+	return {
+		verdict,
+		summary,
+		fixes
+	};
+}
+function applyFixes(steps, fixes, { at = (/* @__PURE__ */ new Date()).toISOString() } = {}) {
+	const applied = [];
+	return {
+		steps: steps.map((step) => {
+			const own = fixes.filter((fix) => fix.step === step.id);
+			if (!own.length) return step;
+			const copy = {
+				...step,
+				ops: [...step.ops]
+			};
+			for (const fix of own) {
+				if (fix.replace) {
+					const index = copy.ops.findIndex((op) => op.id === fix.op);
+					if (index < 0) continue;
+					const old = copy.ops[index];
+					const note = fix.replace.fixed;
+					const op = {
+						...fix.replace,
+						id: old.id,
+						...old.at !== void 0 ? { at: old.at } : {},
+						fixed: {
+							was: old.fixed?.was ?? note?.was ?? text(opPlain(old), 300),
+							at: note?.at ?? at
+						}
+					};
+					copy.ops[index] = op;
+					applied.push({
+						step: step.id,
+						op: old.id,
+						replace: op
+					});
+				}
+				if (fix.say !== void 0) {
+					copy.say = fix.say;
+					applied.push({
+						step: step.id,
+						say: fix.say
+					});
+				}
+				if (fix.check && copy.check) {
+					copy.check = {
+						...fix.check,
+						id: copy.check.id,
+						conceptIds: copy.check.conceptIds ?? []
+					};
+					applied.push({
+						step: step.id,
+						check: copy.check
+					});
+				}
+			}
+			return copy;
+		}),
+		applied
+	};
+}
+function sanitizeStep(raw) {
+	const id = String(raw?.id ?? "");
+	if (!/^[\w-]{1,48}$/u.test(id) || !Array.isArray(raw?.ops)) return null;
+	const ops = raw.ops.slice(0, BOARD_LIMITS.opsPerStep).map((op) => {
+		const clean = normalizeOp(op, 0);
+		if (!clean || typeof op.id !== "string" || !/^[\w-]{1,48}$/u.test(op.id)) return null;
+		return {
+			...clean,
+			id: op.id,
+			...Number.isInteger(op.at) && op.at >= 0 && op.at < 20 ? { at: op.at } : {}
+		};
+	}).filter(Boolean);
+	const say = text(raw.say, BOARD_LIMITS.say);
+	if (!say && !ops.length) return null;
+	return {
+		id,
+		say,
+		ops
+	};
+}
+function stepJson(step, { full = false } = {}) {
+	const ops = step.ops.map(({ fixed, ...op }) => {
+		if (op.t === "svg") return full ? {
+			...op,
+			svg: op.svg.slice(0, 16e3)
+		} : {
+			...op,
+			svg: "…"
+		};
+		if (op.t === "anim") return {
+			...op,
+			html: full ? op.html.slice(0, 8e3) : "…",
+			poster: "…"
+		};
+		return op;
+	});
+	return JSON.stringify({
+		id: step.id,
+		say: step.say,
+		ops,
+		...step.check ? { check: step.check } : {}
+	});
+}
+function boardForCheck(steps, stepId, { maxChars = 14e3 } = {}) {
+	const lines = steps.map((step) => stepJson(step));
+	const center = Math.max(0, steps.findIndex((step) => step.id === stepId));
+	const kept = /* @__PURE__ */ new Set([center]);
+	let used = lines[center]?.length ?? 0;
+	for (let distance = 1; distance < steps.length; distance += 1) for (const index of [center - distance, center + distance]) {
+		if (index < 0 || index >= steps.length || used + lines[index].length > maxChars) continue;
+		kept.add(index);
+		used += lines[index].length;
+	}
+	return lines.filter((line, index) => kept.has(index)).join("\n");
+}
+function describeFixes(fixes, steps) {
+	const byId = new Map(steps.map((step) => [step.id, step]));
+	return fixes.map((fix) => {
+		const step = byId.get(fix.step);
+		if (fix.replace) return `${fix.step} ${fix.op}: ${opPlain(step?.ops.find((op) => op.id === fix.op))} → ${opPlain(fix.replace)}`;
+		if (fix.say !== void 0) return `${fix.step} narration: ${step?.say ?? ""} → ${fix.say}`;
+		return `${fix.step} check answer: ${JSON.stringify(step?.check?.answer ?? "")} → ${JSON.stringify(fix.check?.answer ?? "")}`;
+	}).join("\n");
+}
+//#endregion
 //#region src/core/srs.js
 const GRADES$1 = Object.freeze([
 	"again",
@@ -2457,7 +2698,7 @@ function review(card, grade, now = Date.now()) {
 	if (!GRADES$1.includes(grade)) throw new TypeError(`grade must be one of ${GRADES$1.join(", ")}`);
 	const quality = GRADE_QUALITY[grade];
 	const next = { ...card };
-	next.ease = Math.max(MIN_EASE, round2(card.ease + .1 - (5 - quality) * (.08 + (5 - quality) * .02)));
+	next.ease = Math.max(MIN_EASE, round2$1(card.ease + .1 - (5 - quality) * (.08 + (5 - quality) * .02)));
 	if (grade === "again") {
 		next.reps = 0;
 		next.lapses = card.lapses + 1;
@@ -2483,10 +2724,371 @@ function gradeFromScore(score, confidence) {
 	if (score >= .95 && confidence === "sure") return "easy";
 	return "good";
 }
+function round2$1(value) {
+	return Math.round(value * 100) / 100;
+}
+//#endregion
+//#region src/core/evidence-log.js
+const scored = (evidence) => evidence?.kind !== "reexplain" && evidence?.kind !== "self" && Number.isFinite(Number(evidence?.score));
+const withoutHistory = ({ history, ...state }) => state;
+function takeEvidence(state, card, evidence, at) {
+	const next = applyEvidence(state, evidence, at);
+	if (!scored(evidence)) return {
+		state: next,
+		card
+	};
+	return {
+		state: next,
+		card: review(card ?? createCard(state.id, at), gradeFromScore(Number(evidence.score), evidence.confidence), at)
+	};
+}
+function stateBefore(state, card) {
+	return {
+		state: state ? withoutHistory(state) : null,
+		card: card ?? null
+	};
+}
+function logEvidence(progress, entry) {
+	progress.evidenceLog = [...Array.isArray(progress.evidenceLog) ? progress.evidenceLog : [], entry].slice(-50);
+}
+function correctEvidence(progress, id, patch, { known = (conceptId) => conceptId, at = (/* @__PURE__ */ new Date()).toISOString() } = {}) {
+	const log = Array.isArray(progress.evidenceLog) ? progress.evidenceLog : [];
+	const index = log.findIndex((entry) => entry.id === id);
+	if (index < 0) return null;
+	const entry = log[index];
+	const evidence = {
+		...entry.evidence,
+		...patch
+	};
+	if (!scored(entry.evidence) || !scored(evidence)) return null;
+	const later = log.slice(index + 1);
+	progress.concepts ??= {};
+	progress.reviews ??= {};
+	const changed = [];
+	for (const conceptId of entry.conceptIds ?? []) {
+		const name = known(conceptId);
+		if (name === null || name === void 0) continue;
+		const after = later.filter((item) => item.conceptIds?.includes(conceptId));
+		const history = progress.concepts[conceptId]?.history ?? [];
+		const base = entry.before?.[conceptId];
+		let state = {
+			...base?.state ?? createConceptState(conceptId, name),
+			history: history.slice(0, Math.max(0, history.length - 1 - after.length))
+		};
+		let card = base?.card ?? null;
+		({state, card} = takeEvidence(state, card, evidence, Date.parse(entry.at)));
+		for (const item of after) {
+			item.before = {
+				...item.before,
+				[conceptId]: stateBefore(state, card)
+			};
+			({state, card} = takeEvidence(state, card, item.evidence, Date.parse(item.at)));
+		}
+		progress.concepts[conceptId] = state;
+		if (card) progress.reviews[conceptId] = card;
+		changed.push(conceptId);
+	}
+	entry.corrected = {
+		score: entry.corrected?.score ?? entry.evidence.score,
+		at
+	};
+	entry.evidence = evidence;
+	return { conceptIds: changed };
+}
+//#endregion
+//#region src/core/grading.js
+const OBJECTIVE_KINDS = Object.freeze([
+	"choice",
+	"multi",
+	"blank",
+	"number",
+	"order"
+]);
+const FULLWIDTH = /[！-～]/gu;
+function normalizeAnswerText(value) {
+	return String(value ?? "").normalize("NFKC").replace(FULLWIDTH, (char) => String.fromCharCode(char.charCodeAt(0) - 65248)).toLowerCase().replace(/[\s　]+/gu, " ").replace(/^[\s.,;:!?'"`，。；：！？、“”‘’]+|[\s.,;:!?'"`，。；：！？、“”‘’]+$/gu, "").trim();
+}
+function parseNumber(value) {
+	if (typeof value === "number") return value;
+	const text = normalizeAnswerText(value).replace(/,/gu, "").replace(/\s/gu, "");
+	const fraction = /^(-?\d+(?:\.\d+)?)\/(\d+(?:\.\d+)?)$/u.exec(text);
+	if (fraction) return Number(fraction[1]) / Number(fraction[2]);
+	const percent = /^(-?\d+(?:\.\d+)?)%$/u.exec(text);
+	if (percent) return Number(percent[1]) / 100;
+	const number = Number(text);
+	return Number.isFinite(number) ? number : NaN;
+}
+function gradeObjective(item, response) {
+	if (!item || !OBJECTIVE_KINDS.includes(item.kind)) return {
+		score: 0,
+		correct: false,
+		gradable: false
+	};
+	if (item.kind === "choice") {
+		const correct = String(response ?? "") === String(item.answer ?? "");
+		return {
+			score: correct ? 1 : 0,
+			correct,
+			gradable: true
+		};
+	}
+	if (item.kind === "multi") {
+		const expected = new Set((Array.isArray(item.answer) ? item.answer : [item.answer]).map(String));
+		const given = new Set((Array.isArray(response) ? response : []).map(String));
+		if (!expected.size) return {
+			score: 0,
+			correct: false,
+			gradable: false
+		};
+		let hits = 0;
+		let wrong = 0;
+		for (const id of given) if (expected.has(id)) hits += 1;
+		else wrong += 1;
+		const score = Math.max(0, (hits - wrong) / expected.size);
+		const correct = hits === expected.size && wrong === 0;
+		return {
+			score: round2(score),
+			correct,
+			gradable: true
+		};
+	}
+	if (item.kind === "order") {
+		const expected = (Array.isArray(item.answer) ? item.answer : []).map(String);
+		const given = (Array.isArray(response) ? response : []).map(String);
+		if (!expected.length) return {
+			score: 0,
+			correct: false,
+			gradable: false
+		};
+		let inPlace = 0;
+		expected.forEach((id, index) => {
+			if (given[index] === id) inPlace += 1;
+		});
+		return {
+			score: round2(inPlace / expected.length),
+			correct: inPlace === expected.length,
+			gradable: true
+		};
+	}
+	if (item.kind === "number") {
+		const expected = parseNumber(item.answer);
+		const given = parseNumber(response);
+		if (!Number.isFinite(expected)) return {
+			score: 0,
+			correct: false,
+			gradable: false
+		};
+		if (!Number.isFinite(given)) return {
+			score: 0,
+			correct: false,
+			gradable: true
+		};
+		const tolerance = Number.isFinite(Number(item.tolerance)) && Number(item.tolerance) >= 0 ? Number(item.tolerance) : Math.max(1e-9, Math.abs(expected) * .01);
+		const correct = Math.abs(given - expected) <= tolerance;
+		return {
+			score: correct ? 1 : 0,
+			correct,
+			gradable: true
+		};
+	}
+	const accepted = (Array.isArray(item.answer) ? item.answer : [item.answer]).map(normalizeAnswerText).filter(Boolean);
+	if (!accepted.length) return {
+		score: 0,
+		correct: false,
+		gradable: false
+	};
+	const given = normalizeAnswerText(response);
+	const correct = accepted.includes(given);
+	if (correct) return {
+		score: 1,
+		correct,
+		gradable: true
+	};
+	const asNumber = parseNumber(response);
+	const numeric = accepted.map(parseNumber).filter(Number.isFinite);
+	if (Number.isFinite(asNumber) && numeric.some((value) => Math.abs(value - asNumber) <= Math.max(1e-9, Math.abs(value) * .001))) return {
+		score: 1,
+		correct: true,
+		gradable: true
+	};
+	return {
+		score: 0,
+		correct: false,
+		gradable: true
+	};
+}
 function round2(value) {
 	return Math.round(value * 100) / 100;
 }
 //#endregion
+//#region src/core/item-fix.js
+const ITEM_VERDICTS = Object.freeze([
+	"wrong",
+	"unclear",
+	"misgraded",
+	"right"
+]);
+const MODEL_GRADED = Object.freeze(["short", "work"]);
+const FIELDS = [
+	"prompt",
+	"options",
+	"answer",
+	"tolerance",
+	"unit",
+	"explanation",
+	"hints",
+	"rubric",
+	"figure"
+];
+const modelGraded = (item) => MODEL_GRADED.includes(item?.kind);
+function cleanResponse(item, response) {
+	const ids = (item?.options ?? []).map((option) => option.id);
+	if (item?.kind === "choice") return ids.includes(response) ? response : "";
+	if (item?.kind === "multi" || item?.kind === "order") return [...new Set((Array.isArray(response) ? response : []).filter((id) => ids.includes(id)))];
+	return typeof response === "string" || typeof response === "number" ? text(response, 4e3) : "";
+}
+function responseText(item, response) {
+	const option = (id) => {
+		const found = item.options?.find((entry) => entry.id === id);
+		return found ? `${id.toUpperCase()}. ${found.text}` : String(id);
+	};
+	if (item.kind === "choice") return response ? option(response) : "";
+	if (item.kind === "multi") return response.map(option).join("; ");
+	if (item.kind === "order") return response.map(option).join(" → ");
+	if (item.kind === "number" && item.unit && response) return `${response} ${item.unit}`;
+	return String(response ?? "");
+}
+function itemForCheck(item) {
+	const { id, conceptIds, difficulty, fixed, svg, plot, ...rest } = item;
+	return JSON.stringify({
+		...rest,
+		...svg ? { svg: svg.slice(0, 8e3) } : {},
+		...plot ? { plot } : {}
+	});
+}
+function normalizeGrade(raw, kind) {
+	if (!raw || typeof raw !== "object" || !Number.isFinite(Number(raw.score))) return null;
+	const score = Math.min(1, Math.max(0, Number(raw.score)));
+	return {
+		score,
+		verdict: [
+			"correct",
+			"partial",
+			"incorrect"
+		].includes(raw.verdict) ? raw.verdict : score >= .8 ? "correct" : score >= .4 ? "partial" : "incorrect",
+		feedback: text(raw.feedback, 1200),
+		errorTag: text(raw.errorTag, 80),
+		...kind === "work" ? {
+			wrongStep: text(raw.wrongStep, 400),
+			why: text(raw.why, 400),
+			fix: text(raw.fix, 400)
+		} : {}
+	};
+}
+const figureOf = (item) => item.svg ? { svg: item.svg } : item.plot ? { plot: item.plot } : {};
+function correctedItem(old, raw) {
+	if (!raw || typeof raw !== "object" || raw.kind !== void 0 && raw.kind !== old.kind) return null;
+	const next = normalizeItem({
+		...raw,
+		kind: old.kind
+	}, 0);
+	if (!next || (old.options?.length ?? 0) !== (next.options?.length ?? 0)) return null;
+	const redrawn = [
+		"svg",
+		"figure",
+		"plot"
+	].some((key) => raw[key] !== void 0);
+	const { svg, plot, ...rest } = next;
+	return {
+		...rest,
+		...redrawn ? figureOf(next) : figureOf(old),
+		id: old.id,
+		conceptIds: old.conceptIds ?? [],
+		difficulty: old.difficulty ?? next.difficulty
+	};
+}
+const empty = (value) => value === void 0 || value === null || value === "" || Array.isArray(value) && !value.length;
+const same = (a, b) => empty(a) && empty(b) || JSON.stringify(a) === JSON.stringify(b);
+function changedParts(old, next) {
+	const was = {};
+	for (const field of FIELDS) if (field === "options") {
+		const options = Object.fromEntries((old.options ?? []).filter((option, index) => option.text !== next.options?.[index]?.text).map((option) => [option.id, option.text]));
+		if (Object.keys(options).length) was.options = options;
+	} else if (field === "figure") {
+		if (!same(figureOf(old), figureOf(next))) was.figure = true;
+	} else if (!same(old[field], next[field])) was[field] = empty(old[field]) ? null : old[field];
+	return was;
+}
+function normalizeItemVerdict(raw, item) {
+	const verdict = ITEM_VERDICTS.includes(raw?.verdict) ? raw.verdict : null;
+	if (!verdict) throw new Error("the check names no verdict");
+	if (verdict === "misgraded" && !modelGraded(item)) throw new Error("a choice, multi, blank, number or order question is graded by its answer key: when the key misjudged the answer, the verdict is \"wrong\" with the key corrected in \"item\"");
+	const summary = text(raw?.summary ?? raw?.reason, 400);
+	const explanation = text(raw?.explanation, 2e3);
+	const credit = verdict === "unclear" && raw?.credit === true;
+	let fixed = null;
+	if (verdict === "wrong" || verdict === "unclear") {
+		fixed = correctedItem(item, raw?.item);
+		if (!fixed) throw new Error(`a "${verdict}" verdict needs the whole corrected question in "item": the same kind, the same number of options`);
+		if (!Object.keys(changedParts(item, fixed)).length) throw new Error("the corrected question in \"item\" changes nothing");
+	}
+	const grade = modelGraded(item) && verdict !== "right" && !credit ? normalizeGrade(raw?.grade, item.kind) : null;
+	if (modelGraded(item) && verdict !== "right" && !credit && !grade) throw new Error("give the new \"grade\" of the learner's answer against the corrected question");
+	return {
+		verdict,
+		summary,
+		explanation,
+		item: fixed,
+		credit,
+		grade
+	};
+}
+function fixItem(stored, next, { at = (/* @__PURE__ */ new Date()).toISOString() } = {}) {
+	const { fixed: note, ...old } = stored;
+	const changed = changedParts(old, next);
+	const was = {
+		...changed,
+		...note?.was
+	};
+	if (changed.options && note?.was?.options) was.options = {
+		...changed.options,
+		...note.was.options
+	};
+	return {
+		...next,
+		id: stored.id,
+		conceptIds: stored.conceptIds ?? next.conceptIds ?? [],
+		fixed: {
+			was,
+			at: note?.at ?? at
+		}
+	};
+}
+function regrade(item, response, checked) {
+	if (checked.verdict === "right") return null;
+	if (checked.credit) return {
+		score: 1,
+		correct: true,
+		partial: false,
+		errorTag: ""
+	};
+	if (OBJECTIVE_KINDS.includes(item.kind)) {
+		const graded = gradeObjective(item, response);
+		return {
+			score: graded.score,
+			correct: graded.correct,
+			partial: !graded.correct && graded.score > 0
+		};
+	}
+	if (!checked.grade) return null;
+	const { verdict, ...grade } = checked.grade;
+	return {
+		...grade,
+		correct: verdict === "correct",
+		partial: verdict === "partial"
+	};
+}
+//#endregion
 //#region src/host/lessons.js
 const EVENTS_KEPT = 200;
 const STEP_ID = /^s\d{1,4}$/u;
@@ -2661,7 +3263,8 @@ function createLessons({ store, llm, jobs, courses, learner, now = () => /* @__P
 				course,
 				lesson: row.lesson,
 				board,
-				language: course.language
+				language: course.language,
+				writing
 			};
 		}
 		if (scope?.kind === "thread" || scope?.kind === "short") {
@@ -2678,7 +3281,8 @@ function createLessons({ store, llm, jobs, courses, learner, now = () => /* @__P
 					objectives: []
 				},
 				board,
-				language
+				language,
+				writing
 			};
 		}
 		throw new TutorError("invalid", "Unknown board");
@@ -2779,11 +3383,166 @@ function createLessons({ store, llm, jobs, courses, learner, now = () => /* @__P
 			};
 		});
 	}
+	async function challengedPlace(scope, board, target) {
+		const stepId = String(target?.stepId ?? "");
+		if (target?.asideId) {
+			const aside = (scope.kind === "lesson" ? await store.readJson(store.paths.asides(scope.courseId, scope.lessonId), null) : null)?.items?.find((item) => item.id === target.asideId);
+			const index = aside?.steps?.findIndex((item) => item.id === stepId) ?? -1;
+			if (index < 0) throw new TutorError("not-found", "Not found");
+			const anchor = board?.steps?.findIndex((step) => step.id === aside.anchorStepId) ?? -1;
+			return {
+				ref: { asideId: aside.id },
+				steps: aside.steps,
+				step: aside.steps[index],
+				context: [...(board?.steps ?? []).slice(0, anchor + 1), ...aside.steps.slice(0, index + 1)]
+			};
+		}
+		if (target?.step) {
+			const step = sanitizeStep(target.step);
+			if (!step) throw new TutorError("invalid", "Nothing to check");
+			const anchor = board?.steps?.findIndex((item) => item.id === target.anchorStepId) ?? -1;
+			return {
+				ref: { local: true },
+				steps: [step],
+				step,
+				context: [...(board?.steps ?? []).slice(0, anchor + 1), step]
+			};
+		}
+		const index = board?.steps?.findIndex((step) => step.id === stepId) ?? -1;
+		if (index < 0) throw new TutorError(board?.steps?.length ? "not-found" : "no-board", board?.steps?.length ? "Not found" : "The board is not written yet. Try again once its first step is up.");
+		return {
+			ref: { main: true },
+			steps: board.steps,
+			step: board.steps[index],
+			context: board.steps.slice(0, index + 1)
+		};
+	}
+	async function storeFixes(scope, place, fixes, writing) {
+		let applied = [];
+		const fix = (steps) => {
+			const result = applyFixes(Array.isArray(steps) ? steps : [], fixes);
+			applied = result.applied;
+			return result.steps;
+		};
+		if (place.ref.local) {
+			fix(place.steps);
+			return applied;
+		}
+		if (place.ref.asideId) {
+			await store.updateJson(store.paths.asides(scope.courseId, scope.lessonId), null, (value) => ({ items: (Array.isArray(value?.items) ? value.items : []).map((item) => item.id === place.ref.asideId ? {
+				...item,
+				steps: fix(item.steps)
+			} : item) }));
+			return applied;
+		}
+		if (writing && (await jobs.wait(writing.id))?.status !== "done") return applyFixes(place.steps, fixes).applied;
+		const missing = () => new TutorError("not-found", "Not found");
+		if (scope.kind === "lesson") await store.updateJson(store.paths.board(scope.courseId, scope.lessonId), null, (saved) => {
+			if (!saved) throw missing();
+			return {
+				...saved,
+				steps: fix(saved.steps)
+			};
+		});
+		else if (scope.kind === "thread") await store.updateJson(store.paths.item("assist", scope.id), null, (thread) => {
+			const turn = thread?.turns?.[Math.max(0, Math.min(thread.turns.length - 1, Number(scope.turn) || 0))];
+			if (!turn?.board) throw missing();
+			turn.board = {
+				...turn.board,
+				steps: fix(turn.board.steps)
+			};
+			return thread;
+		});
+		else await store.updateJson(store.paths.item("shorts", scope.id), null, (short) => {
+			if (!short?.board) throw missing();
+			return {
+				...short,
+				board: {
+					...short.board,
+					steps: fix(short.board.steps)
+				}
+			};
+		});
+		return applied;
+	}
+	function challenge({ scope, stepIndex = 0, anchorStepId, target = {}, note }) {
+		const doubt = text(note, 800);
+		return jobs.start("lesson/challenge", async (api) => {
+			const { course, lesson, board, language, writing } = await scopeBoard(scope);
+			const place = await challengedPlace(scope, board, {
+				...target,
+				anchorStepId
+			});
+			api.preview({ phase: "checking" });
+			const checked = await generateJson(llm, {
+				purpose: "teach",
+				effort: "low",
+				prompt: verifyStepPrompt({
+					course,
+					lesson,
+					language,
+					board: boardForCheck(place.steps, place.step.id),
+					step: stepJson(place.step, { full: true }),
+					stepId: place.step.id,
+					note: doubt
+				}),
+				maxTokens: 6e3,
+				signal: api.signal,
+				normalize: (raw) => normalizeVerdict(raw, place.steps)
+			});
+			api.preview({
+				phase: "answering",
+				verdict: checked.verdict
+			});
+			const answer = await generateSteps(llm, {
+				purpose: "teach",
+				effort: "lowest",
+				prompt: challengePrompt({
+					course,
+					lesson,
+					language,
+					boardSoFar: boardToPlainText({ steps: place.context }, { maxChars: 5e3 }),
+					step: boardToPlainText({ steps: [place.step] }, { maxChars: 3e3 }),
+					note: doubt,
+					verdict: checked.verdict,
+					summary: checked.summary,
+					fixes: describeFixes(checked.fixes, place.steps)
+				}),
+				maxTokens: 5e3,
+				signal: api.signal,
+				conceptIds: lesson?.concepts?.map((concept) => concept.id) ?? [],
+				onStep: (step) => api.push(step)
+			});
+			const fixes = checked.fixes.length ? await storeFixes(scope, place, checked.fixes, writing) : [];
+			const aside = await keepAside(scope, {
+				kind: "challenge",
+				verdict: checked.verdict,
+				note: doubt,
+				summary: checked.summary,
+				anchorStepId: anchorFor(board, stepIndex, anchorStepId),
+				steps: answer.steps
+			});
+			if (scope.kind === "lesson") await logEvent(scope.courseId, {
+				type: "challenge",
+				lessonId: scope.lessonId,
+				verdict: checked.verdict
+			});
+			return {
+				verdict: checked.verdict,
+				summary: checked.summary,
+				target: place.ref,
+				fixes,
+				steps: answer.steps,
+				aside
+			};
+		});
+	}
 	async function record({ courseId, lessonId, conceptIds = [], evidence = {} }) {
 		const course = await courses.readCourse(courseId);
 		const index = conceptIndex(course);
 		const ids = (Array.isArray(conceptIds) && conceptIds.length ? conceptIds : findLesson(course, lessonId)?.lesson.concepts.map((concept) => concept.id) ?? []).filter((id) => index.has(id)).slice(0, 8);
 		const at = now().getTime();
+		const evidenceId = newId("evd");
 		const next = await store.updateJson(store.paths.progress(courseId), null, (progress) => {
 			const value = progress ?? {
 				courseId,
@@ -2796,14 +3555,21 @@ function createLessons({ store, llm, jobs, courses, learner, now = () => /* @__P
 			};
 			value.concepts ??= {};
 			value.reviews ??= {};
+			const before = {};
 			for (const id of ids) {
-				const state = value.concepts[id] ?? createConceptState(id, index.get(id).name);
-				value.concepts[id] = applyEvidence(state, evidence, at);
-				if (evidence.kind !== "reexplain" && evidence.kind !== "self" && Number.isFinite(Number(evidence.score))) {
-					const card = value.reviews[id] ?? createCard(id, at);
-					value.reviews[id] = review(card, gradeFromScore(Number(evidence.score), evidence.confidence), at);
-				}
+				before[id] = stateBefore(value.concepts[id], value.reviews[id]);
+				const taken = takeEvidence(value.concepts[id] ?? createConceptState(id, index.get(id).name), value.reviews[id], evidence, at);
+				value.concepts[id] = taken.state;
+				if (taken.card) value.reviews[id] = taken.card;
 			}
+			if (ids.length) logEvidence(value, {
+				id: evidenceId,
+				at: new Date(at).toISOString(),
+				lessonId: lessonId ?? null,
+				conceptIds: ids,
+				evidence: JSON.parse(JSON.stringify(evidence)),
+				before
+			});
 			pushEvent(value, {
 				type: "evidence",
 				lessonId: lessonId ?? null,
@@ -2816,11 +3582,177 @@ function createLessons({ store, llm, jobs, courses, learner, now = () => /* @__P
 			return value;
 		});
 		const states = ids.map((id) => next.concepts[id]).filter(Boolean);
+		return {
+			mastery: Object.fromEntries(states.map((state) => [state.id, masteryPercent(state)])),
+			recommendation: recommendNext(states),
+			evidenceId: ids.length ? evidenceId : null
+		};
+	}
+	async function regradeEvidence(course, evidenceId, patch) {
+		const index = conceptIndex(course);
+		let changed = null;
+		const next = await store.updateJson(store.paths.progress(course.id), null, (progress) => {
+			const value = progress ?? {
+				courseId: course.id,
+				lessons: {},
+				concepts: {},
+				reviews: {},
+				events: []
+			};
+			changed = correctEvidence(value, evidenceId, patch, {
+				known: (id) => index.get(id)?.name ?? null,
+				at: stamp()
+			});
+			if (changed) pushEvent(value, {
+				type: "regrade",
+				evidenceId,
+				conceptIds: changed.conceptIds,
+				score: patch.score,
+				at: stamp()
+			});
+			return value;
+		});
+		if (!changed?.conceptIds.length) return null;
+		const states = changed.conceptIds.map((id) => next.concepts[id]).filter(Boolean);
 		return {
 			mastery: Object.fromEntries(states.map((state) => [state.id, masteryPercent(state)])),
 			recommendation: recommendNext(states)
 		};
 	}
+	async function itemPlace(source) {
+		const missing = () => new TutorError("not-found", "Not found");
+		const rewrite = (path, listOf) => async (change) => {
+			let saved = null;
+			await store.updateJson(path, null, (value) => {
+				const items = listOf(value);
+				const index = Array.isArray(items) ? items.findIndex((entry) => entry.id === source.itemId) : -1;
+				if (index < 0) throw missing();
+				saved = change(items[index]);
+				items[index] = saved;
+				return value;
+			});
+			return saved;
+		};
+		if (source.kind === "deck") {
+			const path = store.paths.item("decks", source.deckId);
+			const deck = await store.readJson(path, null);
+			const item = deck?.kind === "quiz" ? deck.items?.find((entry) => entry.id === source.itemId) : null;
+			if (!item) throw missing();
+			return {
+				item,
+				course: null,
+				lessonId: null,
+				language: deck.language,
+				scope: deck.title,
+				save: rewrite(path, (value) => value?.kind === "quiz" ? value.items : null)
+			};
+		}
+		const course = await courses.readCourse(source.courseId);
+		if (source.kind === "quiz") {
+			const unit = course.units?.find((entry) => entry.id === source.unitId);
+			const path = unit ? store.paths.unitQuiz(course.id, unit.id) : null;
+			const item = path ? (await store.readJson(path, null))?.items?.find((entry) => entry.id === source.itemId) : null;
+			if (!item) throw missing();
+			return {
+				item,
+				course,
+				lessonId: null,
+				language: course.language,
+				scope: `${course.title} — ${unit.title}`,
+				save: rewrite(path, (value) => value?.items)
+			};
+		}
+		const row = findLesson(course, source.lessonId);
+		if (!row) throw missing();
+		const scope = `${course.title} — ${row.lesson.title}`;
+		if (source.kind === "check") {
+			const path = store.paths.board(course.id, row.lesson.id);
+			const item = (await store.readJson(path, null))?.steps?.find((step) => step.id === source.stepId)?.check;
+			if (!item) throw missing();
+			const save = async (change) => {
+				let saved = null;
+				await store.updateJson(path, null, (board) => {
+					const step = board?.steps?.find((entry) => entry.id === source.stepId);
+					if (!step?.check) throw missing();
+					saved = change(step.check);
+					step.check = saved;
+					return board;
+				});
+				return saved;
+			};
+			return {
+				item,
+				course,
+				lessonId: row.lesson.id,
+				language: course.language,
+				scope,
+				save
+			};
+		}
+		const path = store.paths.practice(course.id, row.lesson.id);
+		const item = (await store.readJson(path, null))?.items?.find((entry) => entry.id === source.itemId);
+		if (!item) throw missing();
+		return {
+			item,
+			course,
+			lessonId: row.lesson.id,
+			language: course.language,
+			scope,
+			save: rewrite(path, (value) => value?.items)
+		};
+	}
+	function challengeItem({ source, response, shown = {}, evidenceId, note }) {
+		const doubt = text(note, 800);
+		return jobs.start("item/challenge", async (api) => {
+			const place = await itemPlace(source);
+			const answer = cleanResponse(place.item, response);
+			const told = place.item.kind === "short" || place.item.kind === "work" ? [
+				`A grader gave this answer a score of ${shown.score} (${shown.correct ? "correct" : shown.partial ? "partial" : "incorrect"}).`,
+				shown.feedback ? `Feedback shown: ${shown.feedback}` : "",
+				shown.wrongStep ? `First wrong line found: ${shown.wrongStep}` : "",
+				shown.fix ? `Fix shown: ${shown.fix}` : ""
+			].filter(Boolean).join("\n") : `The answer key marked this answer ${shown.correct ? "correct" : shown.partial ? "partly correct" : "incorrect"}.`;
+			api.preview({ phase: "checking" });
+			const checked = await generateJson(llm, {
+				purpose: "teach",
+				effort: "low",
+				prompt: verifyItemPrompt({
+					scope: place.scope,
+					language: place.language,
+					item: itemForCheck(place.item),
+					kind: place.item.kind,
+					response: responseText(place.item, answer),
+					grading: told,
+					note: doubt
+				}),
+				maxTokens: 5e3,
+				signal: api.signal,
+				normalize: (raw) => normalizeItemVerdict(raw, place.item)
+			});
+			const item = checked.item ? await place.save((stored) => fixItem(stored, checked.item, { at: stamp() })) : place.item;
+			const result = regrade(item, answer, checked);
+			const changed = Boolean(result) && (result.correct !== Boolean(shown.correct) || Math.abs(result.score - (Number(shown.score) || 0)) > 1e-6);
+			const corrected = changed && evidenceId && place.course ? await regradeEvidence(place.course, evidenceId, {
+				score: result.score,
+				...result.correct ? { errorTag: "" } : result.errorTag ? { errorTag: result.errorTag } : {}
+			}) : null;
+			if (place.course) await logEvent(place.course.id, {
+				type: "item-challenge",
+				lessonId: place.lessonId,
+				verdict: checked.verdict,
+				changed
+			});
+			return {
+				verdict: checked.verdict,
+				summary: checked.summary,
+				explanation: checked.explanation,
+				item: checked.item ? item : null,
+				result: changed ? result : null,
+				mastery: corrected?.mastery ?? null,
+				recommendation: corrected?.recommendation ?? null
+			};
+		});
+	}
 	async function grade({ item, response, language = "zh-CN" }) {
 		if (!item?.prompt) throw new TutorError("invalid", "Missing question");
 		const work = item.kind === "work";
@@ -3183,6 +4115,8 @@ function createLessons({ store, llm, jobs, courses, learner, now = () => /* @__P
 		prepare,
 		ask,
 		reexplain,
+		challenge,
+		challengeItem,
 		record,
 		grade,
 		correct,
@@ -4251,7 +5185,9 @@ const IDS = {
 	chs: ID("chs"),
 	dck: ID("dck"),
 	exm: ID("exm"),
-	nte: ID("nte")
+	nte: ID("nte"),
+	asd: ID("asd"),
+	evd: ID("evd")
 };
 function need(payload, key, prefix) {
 	const value = payload?.[key];
@@ -4287,6 +5223,66 @@ function scopeOf(payload) {
 	};
 	throw new TutorError("invalid", "Invalid board scope");
 }
+function challengeTarget(payload) {
+	const target = payload?.target && typeof payload.target === "object" ? payload.target : {};
+	if (target.step && typeof target.step === "object") return { step: target.step };
+	if (typeof target.stepId !== "string" || !/^s\d{1,4}$/u.test(target.stepId)) throw new TutorError("invalid", "Invalid step");
+	return {
+		stepId: target.stepId,
+		...target.asideId === void 0 ? {} : { asideId: need(target, "asideId", "asd") }
+	};
+}
+function itemSource(payload) {
+	const source = payload?.source && typeof payload.source === "object" ? payload.source : {};
+	const itemId = () => {
+		if (typeof source.itemId !== "string" || !/^[a-z0-9_-]{1,24}$/iu.test(source.itemId)) throw new TutorError("invalid", "Invalid question");
+		return source.itemId;
+	};
+	if (source.kind === "practice") return {
+		kind: "practice",
+		courseId: need(source, "courseId", "crs"),
+		lessonId: need(source, "lessonId", "les"),
+		itemId: itemId()
+	};
+	if (source.kind === "quiz") return {
+		kind: "quiz",
+		courseId: need(source, "courseId", "crs"),
+		unitId: need(source, "unitId", "unt"),
+		itemId: itemId()
+	};
+	if (source.kind === "deck") return {
+		kind: "deck",
+		deckId: need(source, "deckId", "dck"),
+		itemId: itemId()
+	};
+	if (source.kind === "check") {
+		if (typeof source.stepId !== "string" || !/^s\d{1,4}$/u.test(source.stepId)) throw new TutorError("invalid", "Invalid step");
+		return {
+			kind: "check",
+			courseId: need(source, "courseId", "crs"),
+			lessonId: need(source, "lessonId", "les"),
+			stepId: source.stepId
+		};
+	}
+	throw new TutorError("invalid", "Invalid question");
+}
+function answerOf(value) {
+	if (typeof value === "string") return value.slice(0, 4e3);
+	if (typeof value === "number" && Number.isFinite(value)) return String(value);
+	return Array.isArray(value) ? value.filter((id) => typeof id === "string" && /^[a-z]$/u.test(id)).slice(0, 12) : "";
+}
+function shownGrade(value) {
+	const grade = value && typeof value === "object" ? value : {};
+	const words = (key, max) => typeof grade[key] === "string" ? grade[key].slice(0, max) : "";
+	return {
+		score: Math.min(1, Math.max(0, Number(grade.score) || 0)),
+		correct: grade.correct === true,
+		partial: grade.partial === true,
+		feedback: words("feedback", 1200),
+		wrongStep: words("wrongStep", 400),
+		fix: words("fix", 400)
+	};
+}
 const ITEM_KINDS = {
 	sheets: "chs",
 	decks: "dck",
@@ -4396,6 +5392,13 @@ function createRoutes({ courses, lessons, learner, studio, projects, jobs, setti
 			style: STYLES.includes(payload.style) ? payload.style : "example",
 			anchorStepId: payload.anchorStepId
 		}) }),
+		"lesson/challenge": (payload) => ({ job: lessons.challenge({
+			scope: scopeOf(payload),
+			stepIndex: payload.stepIndex,
+			anchorStepId: payload.anchorStepId,
+			target: challengeTarget(payload),
+			note: typeof payload.note === "string" ? payload.note : ""
+		}) }),
 		"lesson/record": (payload) => lessons.record({
 			courseId: need(payload, "courseId", "crs"),
 			lessonId: optional(payload, "lessonId", "les"),
@@ -4416,6 +5419,13 @@ function createRoutes({ courses, lessons, learner, studio, projects, jobs, setti
 			response: payload.response,
 			language: typeof payload.language === "string" ? payload.language.slice(0, 12) : void 0
 		}),
+		"item/challenge": (payload) => ({ job: lessons.challengeItem({
+			source: itemSource(payload),
+			response: answerOf(payload.response),
+			shown: shownGrade(payload.shown),
+			evidenceId: optional(payload, "evidenceId", "evd"),
+			note: typeof payload.note === "string" ? payload.note : ""
+		}) }),
 		"lesson/correct": (payload) => ({ job: lessons.correct({
 			scope: scopeOf(payload),
 			stepIndex: payload.stepIndex,
@@ -4686,8 +5696,12 @@ const TTS_PROVIDERS = Object.freeze([
 	"minimax",
 	"azure"
 ]);
-const REQUEST_TIMEOUT_MS = 45e3;
+const TTS_LIMITS = Object.freeze({
+	totalMs: 45e3,
+	quietMs: 1e4
+});
 const MAX_AUDIO_BYTES = 12 * 1024 * 1024;
+const MAX_JSON_BYTES = 3 * MAX_AUDIO_BYTES;
 const CACHE_MAX_BYTES = 300 * 1024 * 1024;
 var TtsError = class extends Error {
 	constructor(code, message, status) {
@@ -4826,28 +5840,75 @@ function splitForTts(content, maxUnits) {
 	if (current) chunks.push(current);
 	return chunks;
 }
-async function boundedFetch(fetchImpl, url, init, signal) {
-	const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
-	const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
-	let response;
+function firstByteMs(text, limits = TTS_LIMITS) {
+	return Math.min(limits.totalMs, limits.quietMs + Math.round(estimateSpeechMs(text) / 10));
+}
+async function boundedFetch(fetchImpl, url, init, { text, signal, limits, maxBytes }) {
+	const limit = new AbortController();
+	let reason = null;
+	const stop = (code) => {
+		reason ??= code;
+		limit.abort();
+	};
+	const total = setTimeout(() => stop("timeout"), limits.totalMs);
+	let quiet = setTimeout(() => stop("stalled"), firstByteMs(text, limits));
+	const combined = signal ? AbortSignal.any([signal, limit.signal]) : limit.signal;
+	const failure = (error) => {
+		if (signal?.aborted) return signal.reason ?? error;
+		if (reason === "stalled") return new TtsError("stalled", "The TTS service is not responding");
+		if (reason === "timeout") return new TtsError("timeout", "TTS request timed out");
+		return null;
+	};
 	try {
-		response = await fetchImpl(url, {
-			...init,
-			redirect: "error",
-			signal: combined
-		});
-	} catch (error) {
-		if (signal?.aborted) throw signal.reason ?? error;
-		throw new TtsError(timeout.aborted ? "timeout" : "network", timeout.aborted ? "TTS request timed out" : "Could not reach the TTS service");
+		let response;
+		try {
+			response = await fetchImpl(url, {
+				...init,
+				redirect: "error",
+				signal: combined
+			});
+		} catch (error) {
+			throw failure(error) ?? new TtsError("network", "Could not reach the TTS service");
+		}
+		if (!response.ok) {
+			response.body?.cancel().catch(() => void 0);
+			throw httpError(response.status);
+		}
+		const length = Number(response.headers.get("content-length"));
+		if (Number.isFinite(length) && length > maxBytes) throw new TtsError("too-large", "TTS response is too large");
+		const parts = [];
+		let size = 0;
+		const reader = response.body?.getReader();
+		while (reader) {
+			let chunk;
+			try {
+				chunk = await reader.read();
+			} catch (error) {
+				throw failure(error) ?? error;
+			}
+			if (chunk.done) break;
+			if (!chunk.value?.byteLength) continue;
+			clearTimeout(quiet);
+			quiet = setTimeout(() => stop("stalled"), limits.quietMs);
+			size += chunk.value.byteLength;
+			if (size > maxBytes) {
+				reader.cancel().catch(() => void 0);
+				throw new TtsError("too-large", "TTS response is too large");
+			}
+			parts.push(chunk.value);
+		}
+		return Buffer.concat(parts);
+	} finally {
+		clearTimeout(total);
+		clearTimeout(quiet);
 	}
-	return response;
 }
-async function readBounded(response) {
-	const length = Number(response.headers.get("content-length"));
-	if (Number.isFinite(length) && length > MAX_AUDIO_BYTES) throw new TtsError("too-large", "TTS response is too large");
-	const buffer = Buffer.from(await response.arrayBuffer());
-	if (buffer.length > MAX_AUDIO_BYTES) throw new TtsError("too-large", "TTS response is too large");
-	return buffer;
+function parseJson(body, service) {
+	try {
+		return JSON.parse(body.toString("utf8"));
+	} catch {
+		throw new TtsError("response", `${service} returned an unreadable response`);
+	}
 }
 function httpError(status) {
 	if (status === 401 || status === 403) return new TtsError("auth", "The TTS service rejected the key", status);
@@ -4869,10 +5930,10 @@ function xmlEscape(value) {
 	})[char]);
 }
 const synthesizers = {
-	async openai({ text, config, secret, rate, fetchImpl, signal }) {
+	async openai({ text, config, secret, rate, send }) {
 		const base = checkEndpoint(config.baseUrl || "https://api.openai.com/v1");
 		const path = base.pathname.replace(/\/+$/u, "");
-		const response = await boundedFetch(fetchImpl, new URL(`${path}/audio/speech`, base), {
+		return send(new URL(`${path}/audio/speech`, base), {
 			method: "POST",
 			headers: {
 				Authorization: `Bearer ${secret}`,
@@ -4886,13 +5947,11 @@ const synthesizers = {
 				response_format: "mp3",
 				speed: rateNumber(rate)
 			})
-		}, signal);
-		if (!response.ok) throw httpError(response.status);
-		return readBounded(response);
+		}, MAX_AUDIO_BYTES);
 	},
-	async volcengine({ text, config, secret, rate, fetchImpl, signal }) {
+	async volcengine({ text, config, secret, rate, send }) {
 		if (!config.appId) throw new TtsError("app-id", "Volcengine App ID is required");
-		const response = await boundedFetch(fetchImpl, "https://openspeech.bytedance.com/api/v1/tts", {
+		const body = parseJson(await send("https://openspeech.bytedance.com/api/v1/tts", {
 			method: "POST",
 			headers: {
 				Authorization: `Bearer;${secret}`,
@@ -4916,24 +5975,17 @@ const synthesizers = {
 					operation: "query"
 				}
 			})
-		}, signal);
-		if (!response.ok) throw httpError(response.status);
-		let body;
-		try {
-			body = await response.json();
-		} catch {
-			throw new TtsError("response", "Volcengine returned an unreadable response");
-		}
+		}, MAX_JSON_BYTES), "Volcengine");
 		if (body?.code !== 3e3 || typeof body?.data !== "string") throw new TtsError(body?.code === 3001 || body?.code === 3003 ? "auth" : "request", `Volcengine TTS failed (${body?.code ?? "unknown"})`);
 		const audio = Buffer.from(body.data, "base64");
 		if (audio.length > MAX_AUDIO_BYTES) throw new TtsError("too-large", "TTS response is too large");
 		return audio;
 	},
-	async minimax({ text, config, secret, rate, fetchImpl, signal }) {
+	async minimax({ text, config, secret, rate, send }) {
 		const base = checkEndpoint(config.baseUrl || "https://api.minimaxi.com");
 		const url = new URL("/v1/t2a_v2", base);
 		if (config.groupId) url.searchParams.set("GroupId", config.groupId);
-		const response = await boundedFetch(fetchImpl, url, {
+		const body = parseJson(await send(url, {
 			method: "POST",
 			headers: {
 				Authorization: `Bearer ${secret}`,
@@ -4956,21 +6008,14 @@ const synthesizers = {
 					channel: 1
 				}
 			})
-		}, signal);
-		if (!response.ok) throw httpError(response.status);
-		let body;
-		try {
-			body = await response.json();
-		} catch {
-			throw new TtsError("response", "MiniMax returned an unreadable response");
-		}
+		}, MAX_JSON_BYTES), "MiniMax");
 		const status = body?.base_resp?.status_code;
 		if (status !== 0 || typeof body?.data?.audio !== "string") throw new TtsError(status === 1004 || status === 2049 ? "auth" : "request", `MiniMax TTS failed (${status ?? "unknown"})`);
 		const audio = Buffer.from(body.data.audio, "hex");
 		if (audio.length > MAX_AUDIO_BYTES) throw new TtsError("too-large", "TTS response is too large");
 		return audio;
 	},
-	async azure({ text, config, secret, rate, fetchImpl, signal }) {
+	async azure({ text, config, secret, rate, send }) {
 		const region = String(config.region || "").trim().toLowerCase();
 		if (!/^[a-z0-9]{2,30}$/u.test(region)) throw new TtsError("azure", "Azure region is invalid");
 		const voice = String(config.voice || "zh-CN-XiaoxiaoNeural");
@@ -4978,7 +6023,7 @@ const synthesizers = {
 		const lang = voice.split("-").slice(0, 2).join("-");
 		const percent = Math.round((rateNumber(rate) - 1) * 100);
 		const ssml = `<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="${lang}"><voice name="${voice}"><prosody rate="${percent >= 0 ? "+" : ""}${percent}%">${xmlEscape(text)}</prosody></voice></speak>`;
-		const response = await boundedFetch(fetchImpl, `https://${region}.tts.speech.microsoft.com/cognitiveservices/v1`, {
+		return send(`https://${region}.tts.speech.microsoft.com/cognitiveservices/v1`, {
 			method: "POST",
 			headers: {
 				"Ocp-Apim-Subscription-Key": secret,
@@ -4987,9 +6032,7 @@ const synthesizers = {
 				"User-Agent": "dsh-aha-tutor"
 			},
 			body: ssml
-		}, signal);
-		if (!response.ok) throw httpError(response.status);
-		return readBounded(response);
+		}, MAX_AUDIO_BYTES);
 	}
 };
 const CHUNK_UNITS = Object.freeze({
@@ -4998,7 +6041,7 @@ const CHUNK_UNITS = Object.freeze({
 	minimax: 9e3,
 	azure: 6e3
 });
-function createTts({ cacheDir, fetchImpl = globalThis.fetch, getSecret }) {
+function createTts({ cacheDir, fetchImpl = globalThis.fetch, getSecret, limits = TTS_LIMITS }) {
 	if (typeof getSecret !== "function") throw new TypeError("createTts needs getSecret");
 	let pruning;
 	const cacheKey = (provider, config, rate, text) => createHash("sha256").update(JSON.stringify([
@@ -5032,18 +6075,25 @@ function createTts({ cacheDir, fetchImpl = globalThis.fetch, getSecret }) {
 		const secret = await getSecret(provider);
 		if (!secret) throw new TtsError("no-key", "No key saved for this TTS provider");
 		const parts = [];
-		for (const chunk of splitForTts(content, CHUNK_UNITS[provider])) parts.push(await synthesizers[provider]({
-			text: chunk,
-			config: merged,
-			secret,
-			rate,
-			fetchImpl,
-			signal
-		}));
+		for (const chunk of splitForTts(content, CHUNK_UNITS[provider])) {
+			const send = (url, init, maxBytes) => boundedFetch(fetchImpl, url, init, {
+				text: chunk,
+				signal,
+				limits,
+				maxBytes
+			});
+			parts.push(await synthesizers[provider]({
+				text: chunk,
+				config: merged,
+				secret,
+				rate,
+				send
+			}));
+		}
 		const audio = Buffer.concat(parts);
 		if (!audio.length) throw new TtsError("response", "The TTS service returned no audio");
 		if (file) {
-			await writeFileAtomic(file, audio).catch(() => void 0);
+			await mkdir(cacheDir, { recursive: true }).then(() => writeFileAtomic(file, audio)).catch(() => void 0);
 			pruning ??= prune().finally(() => {
 				pruning = void 0;
 			});