feat(learning): add scenario attempt telemetry and curriculum completion rules
Evolves scenario_attempts (Phase 2B: one row per validation click) into a real attempt lifecycle — one row per continuous working session, with live counters (validation attempts/passes/fails, hint reveals, duration) updated in place, not re-inserted. Backward compatible: every new column is nullable/defaulted, existing rows backfilled under the new semantics rather than dropped. hint_count (Phase 2B, always NULL — 'not measurable') finally gets a real DEFAULT 0 and increments, since this is the phase that builds real hint tracking. curriculum-rules.js computes rule-driven stage lock/complete/percent/next-scenario state from scenarios/rootnode-path.json's new per-stage completion_rule (all_required/threshold/ prerequisites) against a student's progress. The capstone stage is no longer a hardcoded locked placeholder — it carries an unlock_rule and a pointer at the assessment definition that actually defines its scenario draw (see the assessment-engine commit).
This commit is contained in:
@@ -0,0 +1,83 @@
|
||||
// Attempt lifecycle — the Phase 3B core. One scenario_attempts row per continuous working
|
||||
// session on a scenario (not per validation click, see migrations/012). Every mutation here
|
||||
// updates that one row in place; nothing is ever inserted twice for the same open attempt.
|
||||
//
|
||||
// Deliberately does NOT try to detect "abandoned" attempts automatically (e.g. on Lab destroy)
|
||||
// — that would need a reaper-style background job wired to Provisioner environment_events,
|
||||
// which is more machinery than the instructional-visibility goal here needs. An attempt just
|
||||
// stays 'in_progress' if the student never returns to finish it; instructors can already see
|
||||
// "in_progress, N failed validations" as a real signal. Documented as a known limitation.
|
||||
|
||||
async function getOrCreateOpenAttempt(pool, { studentId, scenarioId, environmentId, cohortId, curriculumStage, assessmentSessionId }) {
|
||||
const { rows: existing } = await pool.query(
|
||||
`SELECT * FROM scenario_attempts
|
||||
WHERE student_id = $1 AND scenario_id = $2 AND environment_id = $3 AND status = 'in_progress'
|
||||
ORDER BY started_at DESC LIMIT 1`,
|
||||
[studentId, scenarioId, environmentId]
|
||||
);
|
||||
if (existing[0]) return existing[0];
|
||||
|
||||
const { rows } = await pool.query(
|
||||
`INSERT INTO scenario_attempts
|
||||
(student_id, scenario_id, environment_id, cohort_id, curriculum_stage, started_at, status, assessment_session_id)
|
||||
VALUES ($1, $2, $3, $4, $5, now(), 'in_progress', $6)
|
||||
RETURNING *`,
|
||||
[studentId, scenarioId, environmentId, cohortId || null, curriculumStage || null, assessmentSessionId || null]
|
||||
);
|
||||
return rows[0];
|
||||
}
|
||||
|
||||
// Records one validation outcome against the currently open attempt (creating one first if
|
||||
// none exists — a student can hit Validate without an explicit "start" call ever having fired,
|
||||
// e.g. if the frontend missed it; this stays correct either way). Closes the attempt on a pass.
|
||||
async function recordValidation(pool, ctx, passed) {
|
||||
const attempt = await getOrCreateOpenAttempt(pool, ctx);
|
||||
const now = new Date();
|
||||
if (passed) {
|
||||
const durationSeconds = attempt.started_at ? Math.max(0, Math.round((now - new Date(attempt.started_at)) / 1000)) : null;
|
||||
const { rows } = await pool.query(
|
||||
`UPDATE scenario_attempts SET
|
||||
validation_attempt_count = validation_attempt_count + 1,
|
||||
validation_pass_count = validation_pass_count + 1,
|
||||
status = 'completed', result = 'passed', completed_at = now(), duration_seconds = $2
|
||||
WHERE attempt_id = $1 RETURNING *`,
|
||||
[attempt.attempt_id, durationSeconds]
|
||||
);
|
||||
return rows[0];
|
||||
}
|
||||
const { rows } = await pool.query(
|
||||
`UPDATE scenario_attempts SET
|
||||
validation_attempt_count = validation_attempt_count + 1,
|
||||
validation_fail_count = validation_fail_count + 1
|
||||
WHERE attempt_id = $1 RETURNING *`,
|
||||
[attempt.attempt_id]
|
||||
);
|
||||
return rows[0];
|
||||
}
|
||||
|
||||
// Reveals the next hint, sequentially — level N can only be revealed once level N-1 has been.
|
||||
// Returns null if the requested reveal is out of order (caller treats that as a 409/400) or if
|
||||
// there are no more hints left.
|
||||
async function recordHintReveal(pool, ctx, totalHints) {
|
||||
const attempt = await getOrCreateOpenAttempt(pool, ctx);
|
||||
const nextLevel = attempt.highest_hint_level + 1;
|
||||
if (nextLevel > totalHints) return { ok: false, reason: 'no_more_hints', attempt };
|
||||
const { rows } = await pool.query(
|
||||
`UPDATE scenario_attempts SET hint_count = hint_count + 1, highest_hint_level = $2
|
||||
WHERE attempt_id = $1 RETURNING *`,
|
||||
[attempt.attempt_id, nextLevel]
|
||||
);
|
||||
return { ok: true, level: nextLevel, attempt: rows[0] };
|
||||
}
|
||||
|
||||
async function getAttemptSummary(pool, { studentId, scenarioId, environmentId }) {
|
||||
const { rows } = await pool.query(
|
||||
`SELECT * FROM scenario_attempts
|
||||
WHERE student_id = $1 AND scenario_id = $2 AND ($3::uuid IS NULL OR environment_id = $3)
|
||||
ORDER BY started_at DESC LIMIT 1`,
|
||||
[studentId, scenarioId, environmentId || null]
|
||||
);
|
||||
return rows[0] || null;
|
||||
}
|
||||
|
||||
module.exports = { getOrCreateOpenAttempt, recordValidation, recordHintReveal, getAttemptSummary };
|
||||
@@ -0,0 +1,83 @@
|
||||
// Curriculum progression rules — reads scenarios/rootnode-path.json's per-stage
|
||||
// completion_rule (and the capstone stage's unlock_rule) against a student's progress map to
|
||||
// answer: current stage, completed/locked stages, next required scenario, percent complete,
|
||||
// and what's blocking advancement. Rule-driven, not adaptive — see
|
||||
// docs/PHASE3B_LEARNING_AND_ASSESSMENT.md §4 for why that's a deliberate scope line.
|
||||
//
|
||||
// Capstone completeness itself isn't computed here (a capstone stage has no scenario_ids to
|
||||
// check against progress) — the caller supplies it after checking for a 'capstone_completed'
|
||||
// achievement, since that's Postgres-backed state this module has no access to.
|
||||
|
||||
function isStageComplete(stage, progress) {
|
||||
const ids = stage.scenario_ids || [];
|
||||
if (!ids.length) return false;
|
||||
const rule = stage.completion_rule || { type: 'all_required' };
|
||||
const completedIds = ids.filter((id) => progress[id]?.status === 'completed');
|
||||
switch (rule.type) {
|
||||
case 'threshold':
|
||||
return completedIds.length / ids.length >= (rule.percent || 100) / 100;
|
||||
case 'prerequisites': {
|
||||
const required = rule.scenario_ids && rule.scenario_ids.length ? rule.scenario_ids : ids;
|
||||
return required.every((id) => progress[id]?.status === 'completed');
|
||||
}
|
||||
case 'all_required':
|
||||
default:
|
||||
return completedIds.length === ids.length;
|
||||
}
|
||||
}
|
||||
|
||||
function nextIncompleteScenario(stage, progress) {
|
||||
return (stage.scenario_ids || []).find((id) => progress[id]?.status !== 'completed') || null;
|
||||
}
|
||||
|
||||
// capstoneStatus: 'locked' | 'unlocked' | 'completed' — supplied by the caller (server route),
|
||||
// since it depends on Postgres state (achievements) this module can't see.
|
||||
function computeCurriculumState(path, progress, capstoneStatus) {
|
||||
const contentStages = path.stages.filter((s) => s.type !== 'capstone');
|
||||
const capstoneStage = path.stages.find((s) => s.type === 'capstone');
|
||||
|
||||
let priorComplete = true; // the first content stage is always unlocked
|
||||
const stageCompletion = {}; // stage id -> bool, used by the capstone's stages_complete rule
|
||||
|
||||
const stages = contentStages.map((stage) => {
|
||||
const complete = isStageComplete(stage, progress);
|
||||
stageCompletion[stage.id] = complete;
|
||||
const locked = !priorComplete;
|
||||
if (!complete) priorComplete = false; // next stage stays locked until this one is done
|
||||
const ids = stage.scenario_ids || [];
|
||||
const completedCount = ids.filter((id) => progress[id]?.status === 'completed').length;
|
||||
return {
|
||||
id: stage.id, name: stage.name, icon: stage.icon, locked, complete,
|
||||
total: ids.length, completed: completedCount,
|
||||
pct: ids.length ? Math.round((completedCount / ids.length) * 100) : 0,
|
||||
next_scenario: locked || complete ? null : nextIncompleteScenario(stage, progress),
|
||||
};
|
||||
});
|
||||
|
||||
const currentStage = stages.find((s) => !s.locked && !s.complete) || null;
|
||||
const overallTotal = contentStages.reduce((n, s) => n + (s.scenario_ids || []).length, 0);
|
||||
const overallCompleted = contentStages.reduce(
|
||||
(n, s) => n + (s.scenario_ids || []).filter((id) => progress[id]?.status === 'completed').length, 0
|
||||
);
|
||||
|
||||
let capstone = null;
|
||||
if (capstoneStage) {
|
||||
const rule = capstoneStage.unlock_rule || { type: 'stages_complete', stage_ids: contentStages.map((s) => s.id) };
|
||||
const unlockedByRule = rule.type === 'stages_complete' && rule.stage_ids.every((id) => stageCompletion[id]);
|
||||
const blocking = rule.type === 'stages_complete' ? rule.stage_ids.filter((id) => !stageCompletion[id]) : [];
|
||||
capstone = {
|
||||
id: capstoneStage.id, name: capstoneStage.name, icon: capstoneStage.icon,
|
||||
assessment_definition_id: capstoneStage.capstone_assessment_id,
|
||||
status: capstoneStatus || (unlockedByRule ? 'unlocked' : 'locked'),
|
||||
blocking_stage_ids: blocking,
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
stages, current_stage: currentStage?.id || null,
|
||||
percent_complete: overallTotal ? Math.round((overallCompleted / overallTotal) * 100) : 0,
|
||||
capstone,
|
||||
};
|
||||
}
|
||||
|
||||
module.exports = { computeCurriculumState, isStageComplete };
|
||||
Reference in New Issue
Block a user