spaced-repetition

# spaced-repetition

SM-2 algorithm reference for flashcard-engine.

## When to use

- Implementing the SM-2 algorithm in `packages/server/src/lib/sm2.ts`
- Writing tests for SM-2 calculations
- Debugging incorrect review intervals
- Modifying scheduling behavior

## SM-2 Algorithm

All SM-2 logic lives in `packages/server/src/lib/sm2.ts`. No other file performs SM-2 calculations.

### State

```typescript
interface SM2State {
  interval: number;      // days until next review
  repetitions: number;   // consecutive correct reviews
  easeFactor: number;    // difficulty multiplier (min 1.3)
  nextReview: string;    // YYYY-MM-DD date string
}
```

### Grade meanings

| Grade | Behavior |
|---|---|
| 0, 1, 2 | Reset: interval = 1, repetitions = 0 |
| 3, 4, 5 | Advance using SM-2 formula |

### Interval calculation (grade >= 3)

```
if repetitions == 0: interval = 1
if repetitions == 1: interval = 6
if repetitions > 1:  interval = round(prevInterval * easeFactor)
```

### EaseFactor update (grade >= 3)

```
easeFactor = max(1.3, easeFactor + 0.1 - (5 - grade) * (0.08 + (5 - grade) * 0.02))
```

Grade 5 (perfect): easeFactor increases by 0.1
Grade 4 (easy): easeFactor unchanged
Grade 3 (good): easeFactor decreases by 0.14

### Next review date

```
nextReview = today + interval days (YYYY-MM-DD format, UTC)
```

## Test Cases

The SM-2 unit tests in `packages/server/src/lib/sm2.test.ts` must cover:

1. Grade 0 on new card: interval=1, repetitions=0, easeFactor=2.5
2. Grade 5 on new card: interval=1, repetitions=1
3. Grade 5 twice: interval=6, repetitions=2
4. Grade 5 three times: interval=round(6*2.6)=16, repetitions=3
5. Grade 4 three times: easeFactor stays 2.5, interval grows correctly
6. Grade 3 repeatedly: easeFactor decreases, stays >= 1.3
7. Grade 2 on mature card: resets interval to 1, repetitions to 0
8. EaseFactor minimum 1.3 is enforced

## Database integration

The review flow in `packages/server/src/routes/study.ts`:

```typescript
// 1. Load current card state from database
// 2. Call applyGrade(currentState, grade)
// 3. Write new state to cards table
// 4. Insert row into review_log table
// 5. Return new state in response
```

All database writes happen in a single transaction per review.