Summary

Implements an evidence-based pharmacokinetic caffeine clearance calculator in src/lib/health/caffeine-cutoff.ts to compute remaining active caffeine at bedtime, estimate sleep onset latency risk, and calculate daily personalized caffeine cutoff recommendations based on user sleep schedules.

Key Features

• Exponential Metabolic Decay Engine:
  • calculateRemainingCaffeine(doses, targetTimeIso, halfLifeHours?): Uses exponential clearance $C(t) = C_0 \cdot (0.5)^{\Delta t / t_{1/2}}$ across multiple doses throughout the day.
  • Automatically ignores doses consumed in the future relative to assessment time.
• Bedtime Sleep Cutoff Calculator:
  • calculateCaffeineCutoffTime(targetBedtimeIso, plannedDoseMg, options?): Derives exact cutoff timestamps backwards from bedtime using required half-lives $\Delta t = t_{1/2} \cdot \log_2(\text{dose} / \text{threshold})$. (e.g., 200mg coffee before 23:00 bedtime -> 08:00 AM cutoff).
• Sleep Disruption Risk Evaluator:
  • <= 25.0 mg -> 'minimal'
  • 25.1 mg to 60.0 mg -> 'moderate'
  • > 60.0 mg -> 'high'
• Daily Clearance Report Generator:
  • generateCaffeineClearanceReport(doses, targetBedtimeIso, options?): Aggregates total intake, bedtime residual, disruption risk, hours to safe clearance, and last intake recommendations.
• Pure Implementation: Zero external dependencies, pure TypeScript math and ISO 8601 validation.

Verification & Test Results

• Added tests/caffeine-cutoff.test.ts with 9 authoritative unit tests.
• node scratch/run-tests.mjs caffeine-cutoff.test.ts -> 9 passed, 0 failed.
• npm run typecheck -> 0 errors.

Resolves #616