Study/server/services/attempts.ts
Elijah ccdad9728b
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 33s
Add drag reordering, exam deadlines, frozen shared quizzes, batched OCR and semantic search
- Drag-to-reorder for class materials, folders, quiz questions and deck cards. Pointer-based
  so touch works, plus keyboard (arrows/Home/End) with screen-reader announcements.
- Timed exams get a wall-clock deadline. The server refuses late answers, submits overdue
  exams with what was saved, and the countdown keeps running while the page is closed.
- Shared quiz sessions keep a frozen copy of their questions and flag later owner edits.
- Scanned PDFs are read in cached 8-page batches with real page numbers (pdf-lib), removing
  the 30 MB whole-file limit. Compatible providers now receive PDFs as file parts.
- Semantic search: embeddings for OpenAI, Gemini, Ollama and compatible servers, background
  indexing into chunk_vectors (migration 2), hybrid keyword + vector ranking for search, the
  assistant and focused generation, and a Settings -> AI section.

181 tests pass locally and in the Docker test stage on Node 24.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 11:48:20 -07:00

479 lines
19 KiB
TypeScript

/**
* Quiz sessions. An attempt freezes its questions (and their shuffled answer order) in a
* snapshot when it starts, so editing or deleting the quiz later can never corrupt a session
* in progress or the review of a finished one.
*/
import { z } from 'zod';
import { isFullyCorrect, scoreQuestion, seededShuffle, type Option, type QuestionType, type SataScoring } from '../../shared/content.ts';
import type { DB } from '../db.ts';
import { HttpError, badRequest, notFound } from '../http.ts';
import { newId, now, parseJson } from '../util.ts';
import { getClass, getQuiz, mapQuestion, type QuestionRow } from './content.ts';
export interface SnapshotQuestion {
id: string;
quizId: string | null;
quizTitle: string;
type: QuestionType;
stem: string;
options: Option[];
rationale: string;
topic: string;
difficulty: string;
}
export interface AnswerState {
selected: string[];
/** Practice mode: the answer has been checked and feedback shown. */
checked: boolean;
at: number;
}
export interface AttemptSettings {
shuffleQuestions: boolean;
shuffleOptions: boolean;
timeLimitSec: number | null;
sataScoring: SataScoring;
/**
* Wall-clock end of a timed session (epoch ms), fixed when it starts. The clock keeps
* running while the session is closed; answers after it are refused and the session is
* submitted with what was saved. Sessions from before this field use the active clock.
*/
deadlineAt?: number | null;
}
/** Saves sent a few seconds after the deadline (network delay, the final autosave) still count. */
export const DEADLINE_GRACE_MS = 5_000;
const DEFAULT_SETTINGS: AttemptSettings = { shuffleQuestions: true, shuffleOptions: true, timeLimitSec: null, sataScoring: 'partial' };
interface AttemptRow {
id: string;
quiz_id: string | null;
class_id: string | null;
title: string;
mode: 'practice' | 'exam';
kind: string;
status: 'active' | 'completed';
settings: string;
snapshot: string;
answers: string;
flags: string;
current_index: number;
elapsed_sec: number;
question_count: number;
score: number | null;
max_score: number | null;
started_at: number;
updated_at: number;
completed_at: number | null;
}
export const attemptCreateSchema = z.object({
mode: z.enum(['practice', 'exam']).default('practice'),
source: z.discriminatedUnion('type', [
z.object({ type: z.literal('quiz'), quizId: z.string() }),
/** Questions missed in one finished attempt. */
z.object({ type: z.literal('retake'), attemptId: z.string() }),
/** Questions answered wrong most often, across a class or everything. */
z.object({ type: z.literal('missed'), classId: z.string().optional(), quizId: z.string().optional() }),
/** Every question on the given topics within a class. */
z.object({ type: z.literal('topics'), classId: z.string(), topics: z.array(z.string()).min(1).max(50) }),
z.object({ type: z.literal('questions'), questionIds: z.array(z.string()).min(1).max(1000), title: z.string().max(200).optional() }),
]),
shuffleQuestions: z.boolean().default(true),
shuffleOptions: z.boolean().default(true),
count: z.number().int().min(1).max(1000).optional(),
timeLimitMin: z.number().min(1).max(600).nullish(),
});
export type AttemptCreate = z.input<typeof attemptCreateSchema>;
const PINNED_OPTION = /^(all|none|both|neither)\b.*\b(above|these|options|answers)\b|^(a|b|c|d)\s*(and|&)\s*(a|b|c|d)\b/i;
/** Shuffles options but keeps "All of the above"-style choices at the end. */
function shuffleOptions(options: Option[], seed: number): Option[] {
const pinned = options.filter((o) => PINNED_OPTION.test(o.text.trim()));
const free = options.filter((o) => !PINNED_OPTION.test(o.text.trim()));
return [...seededShuffle(free, seed), ...pinned];
}
function loadQuestionRows(db: DB, ids: string[]): (QuestionRow & { quiz_title: string })[] {
if (ids.length === 0) return [];
const out: (QuestionRow & { quiz_title: string })[] = [];
for (let i = 0; i < ids.length; i += 400) {
const batch = ids.slice(i, i + 400);
out.push(
...db.all<QuestionRow & { quiz_title: string }>(
`SELECT q.*, z.title AS quiz_title FROM questions q JOIN quizzes z ON z.id = q.quiz_id WHERE q.id IN (${batch.map(() => '?').join(',')})`,
...batch,
),
);
}
const order = new Map(ids.map((id, i) => [id, i]));
return out.sort((a, b) => (order.get(a.id) ?? 0) - (order.get(b.id) ?? 0));
}
/** Question ids ordered from most to least troublesome, using recent responses. */
export function missedQuestionIds(db: DB, scope: { classId?: string; quizId?: string }, limit = 200): string[] {
const where = scope.quizId ? 'AND r.quiz_id = ?' : scope.classId ? 'AND r.class_id = ?' : '';
const params = scope.quizId ? [scope.quizId] : scope.classId ? [scope.classId] : [];
const rows = db.all<{ question_id: string }>(
`SELECT r.question_id, COUNT(*) AS seen, SUM(CASE WHEN r.correct = 0 THEN 1 ELSE 0 END) AS wrong,
(SELECT r2.correct FROM responses r2 WHERE r2.question_id = r.question_id ORDER BY r2.answered_at DESC LIMIT 1) AS last_correct
FROM responses r JOIN questions q ON q.id = r.question_id
WHERE 1 = 1 ${where}
GROUP BY r.question_id
HAVING wrong > 0 AND (last_correct = 0 OR wrong * 2 >= seen)
ORDER BY last_correct ASC, (wrong * 1.0 / seen) DESC, wrong DESC
LIMIT ?`,
...params,
limit,
);
return rows.map((r) => r.question_id);
}
export function createAttempt(db: DB, input: AttemptCreate, sataScoring: SataScoring): string {
const opts = attemptCreateSchema.parse(input);
const src = opts.source;
let quizId: string | null = null;
let classId: string | null = null;
let title = '';
let kind = 'full';
let rows: (QuestionRow & { quiz_title: string })[] = [];
let frozen: SnapshotQuestion[] | null = null;
if (src.type === 'quiz') {
const quiz = getQuiz(db, src.quizId);
quizId = quiz.id;
classId = quiz.class_id;
title = quiz.title;
rows = db
.all<QuestionRow>('SELECT * FROM questions WHERE quiz_id = ? ORDER BY sort_order, created_at', quiz.id)
.map((r) => ({ ...r, quiz_title: quiz.title }));
} else if (src.type === 'retake') {
const prev = db.get<AttemptRow>('SELECT * FROM attempts WHERE id = ?', src.attemptId);
if (!prev) throw notFound('Attempt');
const snap = parseJson<{ questions: SnapshotQuestion[] }>(prev.snapshot, { questions: [] });
const answers = parseJson<Record<string, AnswerState>>(prev.answers, {});
const prevSettings = parseJson<AttemptSettings>(prev.settings, { shuffleQuestions: true, shuffleOptions: true, timeLimitSec: null, sataScoring });
const missed = snap.questions.filter((q) => !isFullyCorrect(scoreQuestion(q, answers[q.id]?.selected ?? [], prevSettings.sataScoring)));
const current = new Map(loadQuestionRows(db, missed.map((q) => q.id)).map((r) => [r.id, r]));
// Prefer the live question (it may have been corrected since); fall back to the frozen copy.
frozen = missed.map((q) => {
const live = current.get(q.id);
if (!live) return q;
const m = mapQuestion(live);
return { id: m.id, quizId: m.quizId, quizTitle: live.quiz_title, type: m.type, stem: m.stem, options: m.options, rationale: m.rationale, topic: m.topic, difficulty: m.difficulty };
});
quizId = prev.quiz_id;
classId = prev.class_id;
title = `${prev.title.replace(/ · missed$/, '')} · missed`;
kind = 'retake';
} else if (src.type === 'missed') {
const ids = missedQuestionIds(db, { classId: src.classId, quizId: src.quizId });
rows = loadQuestionRows(db, ids);
kind = 'missed';
if (src.quizId) {
const quiz = getQuiz(db, src.quizId);
quizId = quiz.id;
classId = quiz.class_id;
title = `${quiz.title} · missed`;
} else if (src.classId) {
classId = src.classId;
title = `${getClass(db, src.classId).name} · missed questions`;
} else {
title = 'Missed questions';
}
} else if (src.type === 'topics') {
const cls = getClass(db, src.classId);
classId = cls.id;
rows = db.all<QuestionRow & { quiz_title: string }>(
`SELECT q.*, z.title AS quiz_title FROM questions q JOIN quizzes z ON z.id = q.quiz_id
WHERE z.class_id = ? AND q.topic IN (${src.topics.map(() => '?').join(',')}) ORDER BY z.sort_order, q.sort_order`,
cls.id,
...src.topics,
);
title = src.topics.length === 1 ? `${src.topics[0]} · practice` : `${cls.name} · ${src.topics.length} topics`;
kind = 'topics';
} else {
rows = loadQuestionRows(db, src.questionIds);
title = src.title ?? 'Custom practice';
kind = 'custom';
const classes = new Set(rows.map((r) => db.get<{ class_id: string }>('SELECT class_id FROM quizzes WHERE id = ?', r.quiz_id)?.class_id));
if (classes.size === 1) classId = [...classes][0] ?? null;
}
let questions: SnapshotQuestion[] =
frozen ??
rows.map((r) => {
const m = mapQuestion(r);
return { id: m.id, quizId: m.quizId, quizTitle: r.quiz_title, type: m.type, stem: m.stem, options: m.options, rationale: m.rationale, topic: m.topic, difficulty: m.difficulty };
});
if (questions.length === 0) {
throw badRequest(src.type === 'quiz' ? 'This quiz has no questions yet' : src.type === 'missed' || src.type === 'retake' ? 'No missed questions to review' : 'No questions matched');
}
const seed = (Math.random() * 2 ** 32) >>> 0;
if (opts.shuffleQuestions) questions = seededShuffle(questions, seed);
if (opts.count && opts.count < questions.length) questions = questions.slice(0, opts.count);
if (opts.shuffleOptions) questions = questions.map((q, i) => ({ ...q, options: shuffleOptions(q.options, seed + i + 1) }));
const id = newId();
const at = now();
const timeLimitSec = opts.timeLimitMin ? Math.round(opts.timeLimitMin * 60) : null;
const settings: AttemptSettings = {
shuffleQuestions: opts.shuffleQuestions,
shuffleOptions: opts.shuffleOptions,
timeLimitSec,
sataScoring,
deadlineAt: timeLimitSec ? at + timeLimitSec * 1000 : null,
};
db.run(
`INSERT INTO attempts (id, quiz_id, class_id, title, mode, kind, status, settings, snapshot, question_count, started_at, updated_at)
VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?)`,
id,
quizId,
classId,
title,
opts.mode,
kind,
JSON.stringify(settings),
JSON.stringify({ questions }),
questions.length,
at,
at,
);
return id;
}
function loadRaw(db: DB, id: string): AttemptRow {
const row = db.get<AttemptRow>('SELECT * FROM attempts WHERE id = ?', id);
if (!row) throw notFound('Session');
return row;
}
/** Loads a session, first submitting it if its deadline has passed. */
function loadAttempt(db: DB, id: string): AttemptRow {
const row = loadRaw(db, id);
if (isOverdue(row)) {
completeAttempt(db, row.id);
return db.get<AttemptRow>('SELECT * FROM attempts WHERE id = ?', id)!;
}
return row;
}
function isOverdue(row: AttemptRow, at = now()): boolean {
if (row.status !== 'active') return false;
const deadline = parseJson<AttemptSettings>(row.settings, DEFAULT_SETTINGS).deadlineAt;
return typeof deadline === 'number' && at > deadline + DEADLINE_GRACE_MS;
}
/** Submits every timed session whose deadline has passed. Returns how many were submitted. */
export function expireOverdueAttempts(db: DB): number {
const rows = db.all<{ id: string }>(
`SELECT id FROM attempts WHERE status = 'active' AND json_extract(settings, '$.deadlineAt') IS NOT NULL AND json_extract(settings, '$.deadlineAt') < ?`,
now() - DEADLINE_GRACE_MS,
);
for (const r of rows) completeAttempt(db, r.id);
return rows.length;
}
function recordResponse(db: DB, row: AttemptRow, q: SnapshotQuestion, selected: string[], sata: SataScoring, at: number): void {
const score = scoreQuestion(q, selected, sata);
db.run(
`INSERT INTO responses (attempt_id, question_id, quiz_id, class_id, topic, score, correct, answered_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
ON CONFLICT(attempt_id, question_id) DO UPDATE SET score = excluded.score, correct = excluded.correct, answered_at = excluded.answered_at`,
row.id,
q.id,
q.quizId ?? row.quiz_id,
row.class_id,
q.topic,
score,
isFullyCorrect(score) ? 1 : 0,
at,
);
}
export function mapAttempt(row: AttemptRow) {
const settings = parseJson<AttemptSettings>(row.settings, DEFAULT_SETTINGS);
const snapshot = parseJson<{ questions: SnapshotQuestion[] }>(row.snapshot, { questions: [] });
const answers = parseJson<Record<string, AnswerState>>(row.answers, {});
const results =
row.status === 'completed'
? Object.fromEntries(
snapshot.questions.map((q) => {
const selected = answers[q.id]?.selected ?? [];
const score = scoreQuestion(q, selected, settings.sataScoring);
return [q.id, { score, correct: isFullyCorrect(score), answered: selected.length > 0 }];
}),
)
: null;
return {
id: row.id,
quizId: row.quiz_id,
classId: row.class_id,
title: row.title,
mode: row.mode,
kind: row.kind,
status: row.status,
settings,
questions: snapshot.questions,
answers,
flags: parseJson<string[]>(row.flags, []),
currentIndex: row.current_index,
elapsedSec: row.elapsed_sec,
score: row.score,
maxScore: row.max_score,
startedAt: row.started_at,
updatedAt: row.updated_at,
completedAt: row.completed_at,
results,
/** Server clock when this was produced, so clients can correct for clock skew. */
serverNow: now(),
};
}
export type AttemptDto = ReturnType<typeof mapAttempt>;
export const mapAttemptSummary = (row: AttemptRow) => {
const answers = parseJson<Record<string, AnswerState>>(row.answers, {});
return {
id: row.id,
quizId: row.quiz_id,
classId: row.class_id,
title: row.title,
mode: row.mode,
kind: row.kind,
status: row.status,
questionCount: row.question_count,
answeredCount: Object.values(answers).filter((a) => a.selected.length > 0).length,
currentIndex: row.current_index,
elapsedSec: row.elapsed_sec,
score: row.score,
maxScore: row.max_score,
startedAt: row.started_at,
updatedAt: row.updated_at,
completedAt: row.completed_at,
};
};
export type AttemptSummary = ReturnType<typeof mapAttemptSummary>;
export function getAttempt(db: DB, id: string): AttemptDto {
return mapAttempt(loadAttempt(db, id));
}
export const attemptPatchSchema = z.object({
answers: z
.record(z.string(), z.object({ selected: z.array(z.string().max(40)).max(12), checked: z.boolean().optional().default(false) }))
.optional(),
flags: z.array(z.string()).max(1000).optional(),
currentIndex: z.number().int().min(0).optional(),
elapsedSec: z.number().int().min(0).max(1_000_000).optional(),
});
export function patchAttempt(db: DB, id: string, input: z.input<typeof attemptPatchSchema>): AttemptDto {
const patch = attemptPatchSchema.parse(input);
const overdue = isOverdue(loadRaw(db, id));
const row = loadAttempt(db, id);
if (overdue) throw new HttpError(409, 'time_up', 'Time is up. The exam was submitted with the answers saved before the deadline.');
if (row.status !== 'active') throw badRequest('This session is already finished');
const snapshot = parseJson<{ questions: SnapshotQuestion[] }>(row.snapshot, { questions: [] });
const settings = parseJson<AttemptSettings>(row.settings, DEFAULT_SETTINGS);
const answers = parseJson<Record<string, AnswerState>>(row.answers, {});
const at = now();
db.tx(() => {
if (patch.answers) {
const byId = new Map(snapshot.questions.map((q) => [q.id, q]));
for (const [qid, a] of Object.entries(patch.answers)) {
const q = byId.get(qid);
if (!q) continue;
const prev = answers[qid];
// A checked practice answer is final: feedback has been shown.
if (prev?.checked && row.mode === 'practice') continue;
const valid = new Set(q.options.map((o) => o.id));
const selected = [...new Set(a.selected.filter((s) => valid.has(s)))];
const checked = row.mode === 'practice' && a.checked && selected.length > 0;
answers[qid] = { selected, checked, at };
if (checked) recordResponse(db, row, q, selected, settings.sataScoring, at);
}
}
db.run(
'UPDATE attempts SET answers = ?, flags = ?, current_index = ?, elapsed_sec = ?, updated_at = ? WHERE id = ?',
JSON.stringify(answers),
patch.flags ? JSON.stringify(patch.flags) : row.flags,
patch.currentIndex !== undefined ? Math.min(patch.currentIndex, Math.max(0, snapshot.questions.length - 1)) : row.current_index,
patch.elapsedSec !== undefined ? Math.max(row.elapsed_sec, patch.elapsedSec) : row.elapsed_sec,
at,
id,
);
});
return getAttempt(db, id);
}
/**
* Finishes a session. Exams score every question (blank = wrong). Practice sessions that are
* ended early are scored on the questions actually answered.
*/
export function completeAttempt(db: DB, id: string, elapsedSec?: number): AttemptDto {
const row = loadRaw(db, id);
if (row.status === 'completed') return mapAttempt(row);
const snapshot = parseJson<{ questions: SnapshotQuestion[] }>(row.snapshot, { questions: [] });
const settings = parseJson<AttemptSettings>(row.settings, DEFAULT_SETTINGS);
const answers = parseJson<Record<string, AnswerState>>(row.answers, {});
const at = now();
let elapsed = elapsedSec !== undefined ? Math.max(row.elapsed_sec, elapsedSec) : row.elapsed_sec;
if (settings.deadlineAt && settings.timeLimitSec) {
// Timed sessions run on the wall clock: time used is time since the start, capped at the limit.
elapsed = Math.min(settings.timeLimitSec, Math.max(0, Math.round((at - row.started_at) / 1000)));
}
let score = 0;
let max = 0;
db.tx(() => {
for (const q of snapshot.questions) {
const selected = answers[q.id]?.selected ?? [];
const answered = selected.length > 0;
if (row.mode === 'practice' && !answered) continue;
max += 1;
score += scoreQuestion(q, selected, settings.sataScoring);
const already = row.mode === 'practice' && answers[q.id]?.checked;
if (!already) recordResponse(db, row, q, selected, settings.sataScoring, answers[q.id]?.at ?? at);
}
db.run(
`UPDATE attempts SET status = 'completed', score = ?, max_score = ?, completed_at = ?, updated_at = ?, elapsed_sec = ? WHERE id = ?`,
score,
max,
at,
at,
elapsed,
id,
);
});
return getAttempt(db, id);
}
export function deleteAttempt(db: DB, id: string): void {
const row = loadAttempt(db, id);
db.run('DELETE FROM attempts WHERE id = ?', row.id);
}
export function listAttempts(db: DB, filter: { status?: 'active' | 'completed'; quizId?: string; classId?: string; limit?: number }): AttemptSummary[] {
const where: string[] = [];
const params: (string | number)[] = [];
if (filter.status) {
where.push('status = ?');
params.push(filter.status);
}
if (filter.quizId) {
where.push('quiz_id = ?');
params.push(filter.quizId);
}
if (filter.classId) {
where.push('class_id = ?');
params.push(filter.classId);
}
const rows = db.all<AttemptRow>(
`SELECT * FROM attempts ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY COALESCE(completed_at, updated_at) DESC LIMIT ?`,
...params,
Math.min(filter.limit ?? 50, 500),
);
return rows.map(mapAttemptSummary);
}