C2: Failure calculation (#24, #25, #26)

[yaniv-kwb]

Do not merge before the release. Failure work stays out of main until C1–C5 are released together (roadmap decision D5). This PR targets main only because the pipeline deploys pull requests into main to dev (the production jobs run only for main itself). It is built on C1 (#28), so the diff also shows C1's commits: review only the three C2 commits 93c8f76, 2f6efec and a8a1972.

What changes

Results now include treatment failures (ADR-0001). The calculation module is the only code that changes: the result page, the reference-level exceedance, saved results, the assessment comparison and the export's result table show whatever it returns, with unchanged layout.

• Tidy-up (C2: Tidy-up: the calculation works per exposure event, with results unchanged #24): the simulation works per exposure event. Best-case and worst-case share the same concentration samples, and the statistics are computed in one place. Results are bit-identical.
• Failure days and worst-case (C2: Failure days drawn per exposure event; worst-case loses the positive LRVs of failing steps #25): each simulated exposure event falls on a failure day of each step with probability failure frequency / 365. The draws come from their own fixed-seed generator and are shared by both cases and all pathogens. On a failure day, worst-case loses the failing steps' positive minimum LRVs for the whole day (D4).
• Best-case with the mixed-water assumption (C2: Best-case applies the mixed-water assumption, including combined failures #26): on a failure day, best-case uses water mixed from the failure time and from normal operation, in proportion to the failure durations. For combined failures of one day, only steps that lose LRV for the pathogen group count:
  • durations that fit into a day don't overlap (for one step this is Eq. 5);
  • two steps longer than a day overlap by the extra minutes;
  • three or more steps longer than a day in total count like worst-case.

The combined-failure rule changed during implementation (decided 2026-09-25). The lowest-concentration arrangement for three or more steps needed a linear program, and the standard solver failed when the failing steps lose about 16 LRV or more together. Such days are a rare exception, so they now count like worst-case. This is updated in:

• the C2 Spec;
• CONTEXT.md (Combined failure);
• decision 6 of docs/QMRA_Failure_Approach.md;
• the roadmap and the vision.

C5's independent benchmark script must implement this rule.

A C1 test that required unchanged results with failure inputs was split:

• with failure frequency 0, results and export stay identical;
• with failures, the export keeps its files and table layout, and only values change.

Spec and Tickets

• Spec: docs/specs/c2-failure-calculation.md (Change C2 in docs/failure_roadmap.md)
• Tickets: C2: Tidy-up: the calculation works per exposure event, with results unchanged #24, C2: Failure days drawn per exposure event; worst-case loses the positive LRVs of failing steps #25, C2: Best-case applies the mixed-water assumption, including combined failures #26 (local copies docs/tickets/07–09)
• Builds on C1: C1: Failure inputs per treatment step (#21, #22, #23) #28

Checks

• Mock-data check (Controlled server):
  • The full suite passes: 63 tests, including 17 new calculation tests.
  • Without failures, results are bit-identical to before C2. This was checked with a script outside the repository on 28 scenarios (1932 values, 0 differences), because the existing regression test only compares with a tolerance.
  • Local timing, drinking water with 3 pathogens and 5 bundled steps: 0.07 s without failures, 0.13 s at 10 and 0.19 s at 100 failure days per year on every step.
  • Still to do: the manual check and the timing on dev (see below).
• Real-data check (Workstation): not done yet.
• Quality goals checked:

  • Scientific correctness: the internal checks from the Spec pass:

    • frequency 0 reproduces today's results;
    • an always-failing step equals the train without its positive LRVs (full day in best-case, any duration in worst-case);
    • Eq. 5 and the 900 + 900 minute overlap equal hand-computed values;
    • a higher frequency or longer duration never lowers the risk;
    • worst-case ≥ best-case;
    • LRVs of 0 or below are unaffected.

    Agreement with an independent calculation is C5.

  • Reproducibility: the same scenario gives identical results every time (fixed seeds), and assessments without failures keep their exact results.

  • Export stability: the export keeps its files and CSV layout; only the result values of assessments with failures change (HTTP test).

Manual check on dev

• Enter a scenario with failures (for example one step at 20 days per year) and run it as a guest and as a registered user. The result is higher than with frequency 0, and worst-case is at least best-case.
• Save it. The saved-assessments page, the assessment comparison and the export's result table show the changed results, with unchanged layout.
• An assessment saved without failures gives the same result as before when saved again.
• Record the calculation time of a drinking-water scenario (365 events per year) with failures, for example from the browser's network tab, in this PR.

Dev currently runs C1 (#28). This deploy replaces it with C1 + C2, so please tell the team.

Definition of Done

• Tests pass
• code-review findings are handled (fixed, or answered in this PR)
• Mock-data check done (automated checks done; the manual check and the timing on dev are open)
• Real-data check done, or marked not needed above
• No secrets or Real data committed
• Glossary, ADRs and Vision document updated if this Change affects them (CONTEXT.md Combined failure, vision MVP item 3, failure approach decision 6)
• Relevant Quality goals checked
• I can explain this Change in my own words

🤖 Generated with Claude Code