Monte-Carlo: zwei Welten, vier Faelle statt widerspruechlicher Modi

Zwei Laeufe (historische / geplante Renditen, gemeinsamer Seed), aus jeder
Verteilung beide Schwellen abgelesen. Fall 1 und Fall 3 stammen damit aus
derselben Verteilung -- ein tieferes Ziel kann nie unwahrscheinlicher sein.

Nullpunkt fuer das Urteil ist Fall 2 (nicht 50 %), Toleranzband +/- 5 pp.

Neu: MonteCarloResult.finalWealthSorted, probabilityAtLeast.
Spezifikation 0.17 (4.12.7 und 9.26 neu gefasst), 3 Tests (121 -> 124).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

SPEZIFIKATION.md

@@ -4,7 +4,7 @@
 | | |
 |---|---|
 | **Dokument** | Funktionale und Technische Spezifikation FPT |
-| **Version** | 0.16 |
+| **Version** | 0.17 |
 | **Datum** | 2026-07-18 |
 | **Status** | Lebendes Dokument |
 | **Codestand** | Arbeitsstand nach `1d046e9` inkl. zwei Monte-Carlo-Fragestellungen (Branch `main`) |
@@ -17,6 +17,7 @@
 
 | Version | Datum | Autor | Änderung |
 |---|---|---|---|
+| 0.17 | 2026-07-19 | Claude (Opus 4.8) | **Monte-Carlo: zwei Welten, vier Fälle.** Behebt einen Darstellungs-Widerspruch: Zuvor konnte «Planung 69 % erreicht» neben «Ziel 3 Mio nur 41 %» stehen, obwohl 3 Mio unter dem Plan-Endbetrag von 3.7 Mio lag – die beiden Zahlen stammten aus **verschiedenen simulierten Welten**. Neu läuft die Simulation **immer zweimal** (historische Renditen / geplante Werte, gemeinsamer Seed) und liest aus **jeder** Verteilung **beide** Schwellen ab: Plan-Endbetrag und Zielbetrag. Fall 1 und Fall 3 stammen damit aus derselben Verteilung, wodurch ein tieferes Ziel **nie** unwahrscheinlicher sein kann als ein höheres – der Widerspruch ist strukturell ausgeschlossen (Test). Zweite Korrektur: Der Nullpunkt für das Urteil ist **nicht 50 %**, sondern **Fall 2** (derselbe Schwellwert in der eigenen geplanten Welt); durch den Volatilitäts-Drag liegt der je nach Streuung bei 27–48 %. Verglichen wird Fall 1 gegen Fall 2 mit ± 5 pp Toleranzband → «zurückhaltend / realistisch / zu optimistisch». Darstellung: Fall 1 prominent mit Urteil, Fall 3+4 als Satzpaar untergeordnet, Fall 2 und die Mediane klein als Referenz. Der Drei-Wege-Umschalter aus 0.16 entfällt; historische Mittelwerte **und** Zielbetrag sind jetzt beide Pflicht. Technisch: `MonteCarloResult.finalWealthSorted` (alle Endvermögen sortiert) plus neuer Helfer `probabilityAtLeast` (Binärsuche) – vier Zahlen aus zwei Läufen statt vier Läufen. Kapitel 4.12.7 und 9.26 neu gefasst; 3 Tests ergänzt (121 → 124). Keine Änderung am Rechenkern. |
 | 0.16 | 2026-07-19 | Claude (Opus 4.8) | **Monte-Carlo mit zwei Fragestellungen** (Roadmap Nr. 46). Ein Umschalter oben trennt: **«Planung prüfen»** (Fall 1, wie bisher) würfelt um die **historischen** Renditen und prüft gegen den **Planungs-Endbetrag** (read-only) – «wie realistisch ist meine Planung?». **«Ziel prüfen»** (Fall 2, neu) würfelt um die **geplanten** Werte aus dem Plan und prüft gegen einen **manuellen Zielbetrag** – «erreiche ich mein Ziel?»; hier sind keine historischen Mittelwerte nötig, nur die Streuung. **«Beides»** rechnet beide Durchgänge gleichzeitig (gemeinsamer Seed). Neue Ergebnis-**Deutungstexte** je Fall (weich formuliert wegen des Volatilitäts-Drags). Der Fächer stammt aus dem historischen Durchgang; der Zielbetrag ist in Fall 2 **einer für alle** Szenarien. `runMonteCarloMulti` nimmt neu die Inflation **je Szenario** (`inflationMeanFor`); neuer Helfer `plannedReturnOf`. Kapitel 4.12 überarbeitet, 4.12.7 und 9.26 neu; 8 Tests ergänzt (119 → 121). Nebenbei eine vom Umlaut-Sweep verstümmelte Hex-Farbe (`#7c3aed`) korrigiert. Keine Änderung am Rechenkern. |
 | 0.15 | 2026-07-19 | Claude (Opus 4.8) | **Plan-Assistent überarbeitet** (Schritt 2 und 4). Rein an der Oberfläche, keine Änderung an Berechnung, Datenmodell oder API. **(Schritt 2 – Lebensphasen):** Die Lebenslinie zerfällt neu an den **fixen Pensionierungszeitpunkten** in Abschnitte (neues reines Modul `phaseplan.ts`, `planSegments`): Erwerb (alle arbeiten), Misch (eine pensioniert, eine arbeitet), Pension (alle pensioniert) – jeweils mit **kurzer Definition**. In den durch eine Pensionierung **fest begrenzten** Abschnitten verteilt der Nutzer beliebig viele Phasen mit **+/Papierkorb** und **eigenem Namen je Phase**; eine Live-Summe erzwingt, dass die Phasendauern exakt aufgehen («Weiter» ist bis dahin gesperrt). Der letzte Pensions-Abschnitt ist **offen** (Lebensdauer frei). Die Anzahl Abschnitte wird **abgeleitet** – Einzelplan: 2 (Erwerb, Pension); Paar mit unterschiedlichem Pensionsalter: 3. Neue **Zeitachse** mit Pensionierungs-Flaggen und nummerierter Beschriftung **unter** dem Balken (auch kurze Phasen bleiben lesbar). Behebt den Fehler, dass die Erwerbsphase zuvor beliebig über die Pensionierung hinaus gesetzt werden konnte. **(Schritt 4 – Vorsorge & Vermögen):** bei Paaren aufgeteilt in **Gemeinsam / Person A / Person B**; PK und 3a sind je Person, Wertschriften/Wohneigentum/Schulden je Bereich (gemeinsam oder pro Person). Neue Kapitel 3.2.8 überarbeitet; 8 Tests ergänzt (111 → 119). |
 | 0.14 | 2026-07-18 | Claude (Opus 4.8) | **Phasenkopf überarbeitet und zwei Verteil-Werkzeuge.** (1) **Zweizeilige Wertdarstellung:** Im Anzeigemodus «Beide» steht der Realwert neu in Klammern in einer **eigenen Zeile** unter dem nominalen Wert statt daneben – im Phasenkopf *und* in den Matrix-Zellen. Der Pfeil wiederholt sich auf der zweiten Zeile, damit der Bezug Start → Ende erhalten bleibt. Nebeneffekt: Die Spalten werden schmaler, wodurch **jede Kennzahl umbruchfrei** (`whitespace-nowrap`) dargestellt werden kann. (2) Die Kennzahl heisst korrekt **«Sparquote»** bzw. **«Verzehrquote»** statt «Quote»/«Verzehr». (3) Neuer Block **«Verfügbares Kapital»** im Phasenkopf (ab Phase 2, nur wenn > 0): der beim Übergang zugeflossene Topf mit «davon verteilt» und «Rest auf Cash». (4) Zwei neue Werkzeuge als eigene Popups: **«Kapital verteilen»** (Zusatzeinlagen in PK/3a/Vermögen, Sonderamortisation, Sofort-Tilgung) und **«Sparquote/Bezug verteilen»** (jährliche Raten), beide mit **Live-Vorschau** über eine erneute `computePlan`-Rechnung im Browser – die angezeigte Wirkung ist dadurch per Konstruktion exakt die spätere, inklusive aller Kappungen. Der Quoten-Dialog weist neben erstem und letztem Jahr die **absolute Quote über die ganze Phase** aus und warnt, wenn die Quote über die Phase sinkt. Neues reines Modul `distribution.ts`. Neue Kapitel 3.6.9, 3.6.10, 9.25; 3.6.1 und 3.6.3 überarbeitet. 8 Tests ergänzt (103 → 111). **Keine Änderung an Berechnung, Datenmodell oder API** – beide Werkzeuge schreiben ausschliesslich bestehende Felder über bestehende Endpunkte. |
@@ -1974,44 +1975,66 @@ aus. Die Schätzung skaliert mit der Anzahl Szenarien.
 Referenz: `src/lib/montecarlo.ts` (`resolveRootElementId`, `buildElementGroups`,
 `paramsForScenario`, `runMonteCarloMulti`), `src/components/MonteCarloDialog.tsx`.
 
-### 4.12.7 Zwei Fragestellungen: Planung prüfen vs. Ziel prüfen
+### 4.12.7 Zwei Welten, vier Fälle
 
-Die Simulation beantwortet **zwei verschiedene Fragen**, die sich sauber trennen lassen (Roadmap
-Nr. 46). Ein Umschalter oben im Dialog wählt zwischen ihnen – oder rechnet beide gleichzeitig.
+Die Simulation läuft **immer zweimal** – einmal um die **historischen** Renditen, einmal um die
+**geplanten** Werte des Plans. Aus jeder der beiden Verteilungen werden **zwei Schwellen**
+abgelesen: der **Plan-Endbetrag** (read-only, der geplante Nachlass des Szenarios) und der
+**Zielbetrag** (manuell, einer für alle Szenarien). Das ergibt vier Zahlen:
 
-| | **Planung prüfen** (Fall 1) | **Ziel prüfen** (Fall 2) |
+| | Schwelle **Plan-Endbetrag** | Schwelle **Zielbetrag** |
 |---|---|---|
-| Gewürfelt wird um … | **historische** Mittelwerte (Eingabe) | **geplante** Werte (aus dem Plan) |
-| Geprüft wird gegen … | **Planungs-Endbetrag** (read-only) | **manueller Zielbetrag** |
-| Beantwortet | «Wie realistisch ist meine Planung?» | «Erreiche ich mein Ziel?» |
-| Nötige Eingaben | historische Renditen + Streuung | nur Streuung + Zielbetrag |
+| Welt **historisch** (Eingabe) | **Fall 1** – Realismus der Planung | **Fall 3** – Ziel, wenn der Markt wie früher läuft |
+| Welt **geplant** (aus dem Plan) | **Fall 2** – Nullpunkt für das Urteil | **Fall 4** – Ziel, wenn der Markt wie geplant läuft |
 
-Das baut direkt auf der **Trennung der zwei Renditezahlen** aus [4.12.3](#4123-zwei-renditezahlen--und-warum)
-auf. Fall 1 ist das bisherige Verhalten – nur wird das Zielfeld in «Planungs-Endbetrag» umbenannt
-und **read-only** (es ist der geplante Nachlass des jeweiligen Szenarios). Fall 2 dreht es um:
-Der Mittelpunkt ist nicht mehr ein historischer Wert, sondern die **plan-eigene** Rendite je
-Element (`plannedReturnOf`: erste Phase, bei Immobilien die Wertsteigerung) und die plan-eigene
-Inflation; geprüft wird gegen ein frei gewähltes Ziel. Die **Streuung bleibt in beiden Fällen**
-– ohne sie gäbe es keine Wahrscheinlichkeit.
+Das baut auf der **Trennung der zwei Renditezahlen** aus [4.12.3](#4123-zwei-renditezahlen--und-warum)
+auf. Die **Streuung ist in beiden Welten dieselbe**; nur der Mittelpunkt unterscheidet sie. In der
+geplanten Welt kommt der Mittelpunkt je Element aus `plannedReturnOf` (erste Phase, bei Immobilien
+die Wertsteigerung) und die Inflation aus `plan.inflationRateDefault`.
 
-**Zielbetrag in Fall 2:** genau **einer für alle** ausgewählten Szenarien – so vergleicht man
-Szenarien gegen dasselbe Ziel. **Ruin** und **Fächer** stammen immer aus dem historischen
-Durchgang (Fall 1), weil das das ehrliche Risikobild ist; im reinen Ziel-Modus aus Fall 2.
+**Warum zwei Läufe und nicht vier.** Eine Wahrscheinlichkeit P(Endvermögen ≥ X) hängt nur von der
+Verteilung und von X ab. Wird das gesamte Endvermögen eines Laufs sortiert aufbewahrt
+(`finalWealthSorted`), lässt sich jede Schwelle nachträglich per Binärsuche ablesen
+(`probabilityAtLeast`). Zwei Läufe genügen also für vier Zahlen – halbe Rechenzeit, und vor allem:
 
-**Deutungstexte** (bei einem einzelnen Szenario):
-- Fall 1, < 50 %: «Deine Planung ist tendenziell zu optimistisch …»; ≥ 50 %: «… realistisch bis
-  vorsichtig …».
-- Fall 2, > 50 %: «Mit deiner Planung solltest du dein Ziel tendenziell erreichen …»; sonst das
-  Gegenteil.
+**Fall 1 und Fall 3 stammen aus derselben Verteilung.** Liegt der Zielbetrag unter dem
+Plan-Endbetrag, ist Fall 3 damit **zwingend ≥ Fall 1**. Der Widerspruch, der die alte Darstellung
+unlesbar machte («Planung 69 %, Ziel 3 Mio nur 41 %» – zwei verschiedene Welten gegeneinander
+gestellt), ist strukturell nicht mehr möglich. Ein Test sichert das ab.
 
-Die Formulierung ist bewusst **weich** («tendenziell»): Schon eine faire Planung landet wegen des
-Volatilitäts-Drags leicht unter 50 % ([4.12.5](#4125-ergebnis), [9.26](#926-die-50--schwelle-ist-kein-scharfer-schnitt)).
+**Der Nullpunkt ist Fall 2, nicht 50 %.** Naiv erwartet man, dass der eigene Plan-Endbetrag in der
+eigenen geplanten Welt in ~50 % der Fälle erreicht wird. Das ist falsch: Der Volatilitäts-Drag
+drückt den Median unter den deterministischen Pfad, und zwar umso stärker, je höher die Streuung
+(gemessen: 37 % bei σ = 15 %, 27 % bei σ = 25 %; siehe [9.26](#926-fall-2-ist-der-nullpunkt--nicht-50-)).
+Fall 2 misst genau diesen Nullpunkt und wird deshalb als **Referenz** ausgewiesen, gegen die Fall 1
+verglichen wird – beides derselbe Schwellwert, nur andere Renditeannahme.
 
-**Technik:** kein Eingriff in den Rechenkern. `runMonteCarloMulti` nimmt die Inflation neu **je
-Szenario** (`inflationMeanFor`), damit Fall 2 die plan-eigene Inflation verwenden kann. Der
-Kombi-Modus rechnet zwei Durchgänge mit **demselben Seed**.
+**Urteil** (Toleranzband ± 5 Prozentpunkte):
 
-Referenz: `src/lib/montecarlo.ts` (`plannedReturnOf`), `src/components/MonteCarloDialog.tsx`.
+| Fall 1 vs. Fall 2 | Urteil |
+|---|---|
+| mehr als 5 pp höher | Planung **zurückhaltend** gerechnet |
+| innerhalb ± 5 pp | Planung **realistisch** gerechnet |
+| mehr als 5 pp tiefer | Planung tendenziell **zu optimistisch** |
+
+**Darstellung** (bei einem einzelnen Szenario):
+- **Prominent:** Fall 1 als grosse Prozentzahl mit dem Urteil.
+- **Untergeordnet:** Fall 3 und 4 als Satzpaar, dessen Wortwahl automatisch dreht, je nachdem
+  welche Welt besser dasteht («Wenn der Markt so ‹schlecht› läuft, wie du es in deiner Planung
+  vorgibst, … bei X %. Läuft er so ‹gut› wie in der Vergangenheit, … bei Y %.»).
+- **Kleingedruckt:** Fall 2 als Referenz plus der Median je Welt.
+
+Die Tabelle zeigt je Szenario `Fall 1 (Fall 2)` und `Fall 3 (Fall 4)`. **Ruin**, **Bandbreite** und
+**Fächer** stammen immer aus der historischen Welt, weil das das ehrliche Risikobild ist.
+
+**Eingaben:** Da beide Welten immer laufen, sind die historischen Mittelwerte **und** der
+Zielbetrag stets Pflichtfelder. Der frühere Drei-Wege-Umschalter entfällt.
+
+**Technik:** kein Eingriff in den Rechenkern. Beide Durchgänge laufen mit **demselben Seed**
+(Common Random Numbers), damit der Unterschied zwischen den Welten nicht Rauschen ist.
+
+Referenz: `src/lib/montecarlo.ts` (`finalWealthSorted`, `probabilityAtLeast`, `plannedReturnOf`),
+`src/components/MonteCarloDialog.tsx`.
 
 ## 4.13 Sensitivitätsanalyse (Tornado)
 
@@ -2836,13 +2859,13 @@ Include `src/**/*.test.ts`). Es gibt **keine** Komponenten-, API- oder E2E-Tests
 | `calculations.test.ts` | 43 | AHV-Rentenformel, Immobilie, Teilverkauf, Sonderamortisation, AHV einkommensabhängig, „V5 Golden Tests" |
 | `sensitivity.test.ts` | 15 | Treiber-Transformationen (Reinheit, Einheiten, Kappung), Verfügbarkeit, Tornado-Sortierung und -Richtung, Erklärung wirkungsloser Treiber |
 | `explain.test.ts` | 12 | Verlaufswerte je Element, Vollständigkeit beider Wasserfall-Zerlegungen, Rechenweg-Protokoll, Gültigkeit der Spezifikations-Verweise |
-| `montecarlo.test.ts` | 15 | Determinismus, Volatilität/Vol-Drag, Böden, Reproduzierbarkeit; Element-Gruppierung, Szenario-Vergleich, Inflation je Szenario, plannedReturnOf |
+| `montecarlo.test.ts` | 18 | Determinismus, Volatilität/Vol-Drag, Böden, Reproduzierbarkeit; Element-Gruppierung, Szenario-Vergleich, Inflation je Szenario, plannedReturnOf; Schwellen-Ablesung (probabilityAtLeast), Monotonie über Schwellen, Fall 2 systematisch unter 50 % |
 | `distribution.test.ts` | 8 | Kapitaltopf und Quoten-Zerlegung gegen die Cash-Brücke; Entwurfswerte anwenden ohne Verlust bestehender Felder |
 | `phaseplan.test.ts` | 8 | Ableitung der Lebensabschnitte aus den Pensionierungszeitpunkten (Einzel/Paar/bereits pensioniert); letzter Teil immer offen |
 | `bridges.test.ts` | 10 | Vermögens- und Cash-Brücke gehen über sieben Plankonstellationen ohne Restgrösse auf; Umbuchungen bleiben aus der Vermögensbrücke heraus |
 | `diff.test.ts` | 9 | Abweichungs-Erkennung gegen das Eltern-Szenario |
 | `migrations.test.ts` | 1 | spielt alle Migrationen gegen echtes PostgreSQL (PGlite) ein |
-| **Total** | **121** | |
+| **Total** | **124** | |
 
 ## 8.2 Testfälle
 
@@ -3244,20 +3267,39 @@ Bewusst **nicht** umgesetzt ist eine automatische Deckelung: Es gibt legitime Gr
 sparen als die laufende Quote hergibt (etwa wenn ein Cash-Polster aus der Vorphase abgebaut
 werden soll). Das Werkzeug informiert, es bevormundet nicht.
 
-## 9.26 Die 50-%-Schwelle ist kein scharfer Schnitt
+## 9.26 Fall 2 ist der Nullpunkt – nicht 50 %
 
-Die Deutungstexte ([4.12.7](#4127-zwei-fragestellungen-planung-prüfen-vs-ziel-prüfen)) kippen bei
-50 %. Das ist eine Vereinfachung: Schon eine **völlig faire** Planung (historischer Mittelwert =
-geplanter Mittelwert) erreicht ihren Endbetrag in etwas **weniger** als 50 % der Fälle, weil
-Schwankung den Median unter den arithmetischen Mittelwert drückt (Volatilitäts-Drag,
-[4.12.5](#4125-ergebnis)). Ein Wert knapp unter 50 % bedeutet also nicht zwingend «zu optimistisch»,
-sondern kann reiner Vol-Drag sein.
+Naiv erwartet man, dass eine Planung ihren eigenen Endbetrag in **50 %** der Fälle erreicht, sobald
+man um genau die geplanten Werte würfelt. Das ist falsch, und der Fehler ist gross genug, um ein
+Urteil zu verderben.
+
+Der Grund ist der **Volatilitäts-Drag** ([4.12.5](#4125-ergebnis)): Der deterministische Pfad
+kapitalisiert das arithmetische Mittel, der Median einer Simulation folgt aber näher dem
+geometrischen. Gemessen an einem Testplan (800k Startkapital, 30 Jahre, geplante Rendite 5.2 %,
+deterministisches Endvermögen 3'457'554):
+
+| Streuung σ | Median-Endvermögen | P(Plan-Endbetrag erreicht) |
+|---|---|---|
+| 0 % | 3'457'554 (= deterministisch) | – |
+| 3 % | 3'432'399 | ~48 % |
+| 6 % | 3'322'529 | ~45 % |
+| 15 % | 2'612'222 | **37 %** |
+| 25 % | 1'451'659 | **27 %** |
+
+Eine Planung mit hoher Aktienquote landet also bei **27–37 %**, obwohl an ihr nichts falsch ist.
+Ein fixer 50-%-Schnitt würde sie als «zu optimistisch» brandmarken.
+
+Deshalb ist der Nullpunkt für das Urteil **Fall 2** – dieselbe Schwelle, dieselbe Streuung, nur der
+Mittelpunkt aus den eigenen Planannahmen statt aus der Historie
+([4.12.7](#4127-zwei-welten-vier-fälle)). Der Vol-Drag steckt dann in **beiden** Zahlen und kürzt
+sich weg; übrig bleibt genau die Frage, die interessiert: *Ist meine Renditeannahme optimistischer
+als die Vergangenheit?* Das Toleranzband von ± 5 Prozentpunkten fängt Simulationsrauschen ab.
+
+Fall 2 selbst wird nur klein als Referenz gezeigt: als Zahl ist er wenig aussagekräftig (er misst
+im Wesentlichen die eigene Streuung), als **Vergleichsanker** dagegen unverzichtbar. Der Hinweis,
+dass die Simulation Risiko **um deine Annahmen** misst und nicht deren Richtigkeit
+([9.15](#915-monte-carlo-misst-risiko-um-die-annahmen-nicht-deren-richtigkeit)), bleibt bestehen.
 
-Deshalb ist die Formulierung weich gehalten («tendenziell») und der bestehende Hinweis bleibt,
-dass die Simulation Risiko **um deine Annahmen** misst, nicht deren Richtigkeit
-([9.15](#915-monte-carlo-misst-risiko-um-die-annahmen-nicht-deren-richtigkeit)). Eine exakte
-Schwelle müsste die Vol-Drag-Korrektur einrechnen – bewusst nicht getan, um die Aussage einfach
-zu halten.
 
 ---