feat(ACRE): Implement Adaptive Concept Recovery Engine (V2)

[Rohit23f1001156]

feat(ACRE): Implement Adaptive Concept Recovery Engine (V2)

Problem

The existing recovery workflow redirects students to review material after a failed quiz, but the subsequent retry still uses random question selection. As a result, retry attempts are not focused on the concepts that caused the failure, reducing the effectiveness of the recovery loop.

Solution

ACRE V2 introduces adaptive concept recovery by preserving failed concept tags across the review workflow and using them to bias question selection during quiz retries. Recovery attempts prioritize weak concepts while reducing repeated questions and presenting them in Bloom's taxonomy order.

Workflow

Highlights

• Introduces adaptive concept recovery for quiz retries.

• Preserves failed concept tags across the review workflow.

• Prioritizes weak concepts using weighted adaptive selection.

• Applies repetition penalties while maintaining randomized sampling.

• Clears recovery state only after a successful retry.

---

Behavior Changes

• Failed quiz submissions now enter the recovery workflow even if the quiz item was previously completed.

• Recovery state is preserved until the retry quiz is successfully passed.

• Retry quizzes prioritize questions covering previously failed concepts.

• Recovery state is cleared only after a successful retry.

---

Implementation

Adaptive Selection (3 New Services)

| Service | Responsibility |

|----------|----------------|

| AdaptiveQuestionSelector | Weighted random sampling without replacement (roulette-wheel), repetition penalty, Bloom ordering |

| AdaptiveSelectionContextBuilder | Loads active recovery state and student quiz history from the database |

| AdaptiveWeightPolicy | Pure scoring: base weight, failed-tag boost (×5), repetition penalty (×0.2), priority multiplier |

---

Recovery Workflow

ProgressService

• Resolves failed concept tags.

• Matches review items using concept tags.

• Persists recovery state to the progress document.

• Fix: Prevents premature clearing of recoveryState when the review item is completed.

AttemptService

• Integrates the adaptive selection context.

• Fix: Updates the gate condition so failed submissions always enter recovery regardless of prior completion status.

---

Infrastructure

• Added repository support for adaptive selection queries.

• Registered adaptive selection services in the dependency injection container.

• Extended quiz and recovery interfaces.

---

Non-functional Changes

• Suppressed verbose face-recognition debug logs behind the DEBUG_FACE flag.

• No functional frontend behavior changes.

---

Testing

The adaptive recovery workflow was verified through build validation, targeted unit tests, and an end-to-end Fail → Review → Retry scenario.

✅ Build

pnpm run build

Result

Exit code: 0

Zero TypeScript build errors.

---

✅ ACRE Unit Tests

pnpm exec vitest run ProgressService.acre.test.ts

Result

✓ 3 tests passed

---

✅ End-to-End Integration Verification

Attempt 1 — Standard Selection

[ACRE] Candidate Count: 3

[ACRE] Recovery Active: false

[ACRE] Final Selected Questions: ["...2922","...2921"]

POST /api/quizzes/.../attempt

Status: 200 (99ms)

↓

Student fails quiz → Recovery state saved → Review item completed

POST /api/quizzes/.../submit

Status: 200 (171ms)

POST /api/users/progress/.../start

Status: 200 (72ms)

POST /api/users/progress/.../stop

Status: 200 (71ms)

↓

Retry attempt generated with adaptive selection

Attempt 2 — Adaptive Selection

[ACRE] Candidate Count: 3

[ACRE] Recovery Active: true

[ACRE] Failed Tags: ["database","mongodb"]

[ACRE] Selected questions (Bloom order): ["...2921","...2922"]

POST /api/quizzes/.../attempt

Status: 200 (83ms)

---

Known Test Failures (Not ACRE-Related)

Running the full backend test suite reveals several existing infrastructure-related failures (DI container bindings and test environment setup) that are unrelated to ACRE V2.

The ACRE-specific unit tests and end-to-end workflow pass successfully.

| Root Cause | Affected Suites |

|------------|-----------------|

| Missing CourseRegistrationRepository DI binding in test container | QuestionController, InviteController, ReportController |

| Auth emulator not configured in test environment | EnrollementController |

| Test fixture setup issues | CourseSettingController.backfill |

These failures reproduce identically on the current main branch.

---

Reviewer Guide

Suggested review order:

1. AdaptiveQuestionSelector.ts

2. AttemptService.ts

3. ProgressService.ts

4. QuestionBankService.ts

5. ProgressService.acre.test.ts