Promote the survival machinery to heormodel.survival (item 18, phase 2)

[pedroliman]

Problem

Phase 1 (#58) proved the survival-to-engine path with bespoke, Weibull-only helpers inside an example. They are not reusable and are tied to one distribution and one hand-rolled maximum-likelihood fit.

Goal

Promote the machinery into a public heormodel.survival module with a clean, functional, composition-first interface that ingests a model fit from lifelines (any of its parametric families) and supports the curve operations a health economist needs. Phase 2 changes no acceptance number; it re-expresses the passing replication through the extracted layer.

Acceptance criteria

• SurvivalCurve is one composed value object (a cumulative-hazard function of time); the families, curve algebra, and adapter are functions returning curves, with no class hierarchy.
• Public surface: SurvivalCurve; families exponential, weibull, gompertz; adapter from_lifelines, sample_params; curve algebra apply_hazard_ratio, apply_acceleration_factor, mix, splice; and to_transition_matrix.
• The adapter is duck-typed, so the module imports without lifelines; the fitting package installs with a new survival extra.
• The two engines and the parameter recovery reproduce the item-18 acceptance values through the public interface: reference table (5.64394 / 4.92709 / 4.18803), both engines recover the discounted life expectancy, closed forms for a constant hazard and a hazard ratio hold, and the fitted-model and probabilistic discounted life expectancies converge to 4.92709 as the sample grows.
• Ship examples/survival_models.py, a website tutorial, an API reference section, changelog and roadmap updates, and doctest, closed-form, and convergence tests.

Follows #58.

[pedroliman]

Done on claude/roadmap-item-18-u6j1ak (commit 7c012ce).

Design notes worth recording:

• One composed value object. SurvivalCurve holds a cumulative-hazard function; survival, hazard, conditional probabilities, sampling, and per-cycle transition probabilities all derive from it. Families and curve algebra are plain functions returning new curves, so there is no distribution class hierarchy.
• One adapter covers every lifelines family. The adapter is duck-typed against params_, variance_matrix_, and _cumulative_hazard(values, times) / _hazard(values, times), which every lifelines parametric univariate fitter shares, so Weibull, log-normal, log-logistic, generalized gamma, and the rest work without reimplementing their math. Because it never imports lifelines, heormodel.survival imports fine without the extra installed.
• Sampling with no special cases. Families carry a closed-form quantile; mixtures, splices, and adapted fits invert the cumulative hazard by vectorized bisection (machine precision), so sample_time works for any curve.
• Transitions via the matrix exponential. to_transition_matrix builds each cycle's intensity matrix from cumulative-hazard increments and exponentiates it, which is exact (1 - S(k+1)/S(k)) for a single decrement and standard for competing risks.

Acceptance holds through the public interface: reference table 5.64394 / 4.92709 / 4.18803, both engines recover the discounted life expectancy, the constant-hazard and hazard-ratio closed forms are exact, and the fitted-model and probabilistic discounted life expectancies converge to 4.92709. Full suite plus doctests: 383 passed; ruff and mypy clean. The phase-1 survival_bridge example, tutorial, notebook, and test are replaced by survival_models on the public module. No pull request opened.

---

Generated by Claude Code