fsrs_ex

# Porting Policy

This project follows a direct-port policy from `open-spaced-repetition/py-fsrs`.

## Baseline

- Upstream project: `open-spaced-repetition/py-fsrs`
- Baseline version: `v6.3.0`
- Algorithm generation: FSRS-6

## Alignment Priorities

1. **Algorithm semantics first**
   - Keep formula behavior and state transitions aligned with upstream.
2. **Data shape compatibility**
   - Keep serialized field names compatible with Python payloads.
3. **Validation compatibility**
   - Keep parameter count and bounds behavior aligned with upstream policy.
4. **Deterministic parity verification**
   - Use fixture-based tests generated by Python to detect divergence.

## Allowed Elixir Adaptations

Adaptations are allowed only when they do not change algorithm semantics, such as:

- idiomatic module decomposition
- atom-based enums (`:again`, `:hard`, `:good`, `:easy`)
- step input normalization helpers (`{:seconds, x}`, `{:minutes, x}`)

## Non-goals

- Introducing custom FSRS variants in core scheduler behavior
- Silent behavior changes that diverge from the baseline without explicit versioning

## Upgrade Workflow

When upstream releases a new stable scheduler version:

1. Compare upstream formulas/constants/validation behavior
2. Update code and tests
3. Regenerate parity fixture
4. Run parity + full test suite
5. Document migration notes in release notes