CAP-1-PREFLIGHT — Profit-Reinvestment / Profit-Reserve Mode — Audit-Bericht

Datum: 2026-05-09 (UTC 11:20)
Status: Read-only Audit, keine Mutation, durable Architecture-Vorschlag
Scope: Profit-Reinvestment / Profit-Reserve Mode für den Trading-Bot

1. Aktueller Kapitalfluss als Baum

.env STARTING_CAPITAL=10000 USDT
        │
        ▼
PaperTrader._load_state()                               (paper_trade.py:42)
  state['starting_capital'] ───────────────────────►  STATIC, never updated
  state['cash']             ───────────────────────►  DYNAMIC, mutated per trade
  state['positions']        ───────────────────────►  open positions
  state['closed_trades']    ───────────────────────►  history (no aggregate!)
  state['tier3_budget']     ───────────────────────►  T3 SEPARATE pool ⚠
  state['tier3_used']       ───────────────────────►  T3 already has split!
  state['_audit_log']

execute_buy()    →  state['cash'] -= total_cost      (paper_trade.py:209)
execute_sell()   →  state['cash'] += net_proceeds    (paper_trade.py:322)
execute_t3_buy() →  state['cash'] -= (size + fee)    (paper_trade.py:416)
execute_partial_sell → state['cash'] += net          (paper_trade.py:514)

get_portfolio() returns:                               (paper_trade.py:86-110)
  cash             = state['cash']                   (current, after-trade)
  positions_value  = Σ qty × current_price
  total_value      = cash + positions_value
  starting_capital = state['starting_capital']  (static)
  pnl              = total_value − starting_capital  (= unrealized + realized)
  pnl_pct          = pnl / starting × 100

Sizer-Inputs (alle Pfade — main.py + sizers):
  portfolio['cash']           ← used for "available cash"
  portfolio['total_value']    ← used for "portfolio_value" (sizing-base)
  portfolio['positions_value']← used for exposure-check

Drawdown-Check (risk_manager.py:90-100):
  drawdown = (starting_capital − total_value) / starting_capital

Daily-Loss-Limit (main.py:192):
  daily_limit = starting_capital × 0.02

Befund (Aufgabe 1)

Read-Sites Tabelle

2. Datenmodell-Befund

Bot-State (live_portfolio.json)

GUI-DB

Source-of-Truth-Empfehlung

Bot-State (live_portfolio.json) ist die Source-of-Truth für Cash + Positions. GUI-DB ist Read-only Spiegelung via Bot-Emitter (G6.1).

CAP-1 sollte abgeleitete Werte im Bot-State berechnen (z.B. realized_profit_total = Σ closed_trades.pnl), zusätzliches profit_reserve als persistierten Wert, plus den mode. Die GUI würde diese Werte nur anzeigen, nicht selbst berechnen.

3. Modell-Vergleich

Wichtige Beobachtung Reserve-Mode: Wenn der Bot Verluste macht, fällt cash < starting_capital. Soll dann die Reserve „aufgegessen" werden (= Reserve = max(0, realized_pnl_total))? Empfehlung: Ja, Reserve ist nur realized profit, nie negativ. Bei Verlust gibt es einfach keine Reserve. Drawdown ist dann separater Mechanismus.

Empfehlung Aufgabe 3

• Modell B (Reserve Profits Mode) zuerst, A bleibt der Compound-Default.
• Modell C ist Phase 1.1, weil der zusätzliche pct-Parameter neue Bounds + Cross-Field-Validation braucht (analog G9 Risk Settings).
• Default: für Testnet compound (status-quo, kein Behavior-Change), für Mainnet reserve_profits (sicherer).

4. Begriffe + Formeln (eigener Vorschlag)

Minimaler Begriffs-Satz

Verworfen als redundant: current_cash (= state['cash']), realized_profit_total / realized_loss_total (split überflüssig, realized_pnl_total bereits signed), net_realized_pnl (gleich wie realized_pnl_total), reinvestable_profit (derived).

Formeln

realized_pnl_total = Σ closed_trades[i].pnl                # signed
locked_in_positions = Σ positions[s].quantity × entry_price # cost basis

# Compound-Mode (status quo):
investable_capital_compound = state['cash']

# Reserve-Mode:
profit_reserve = max(0, realized_pnl_total)                # ≥ 0, never negative
investable_capital_reserve = state['cash'] − profit_reserve

# Wenn Verluste angefallen sind:
#   realized_pnl_total < 0 → profit_reserve = 0 → investable = cash (= base − loss)
#   → Bot kann mit verbleibendem Kapital weitertraden, Reserve schützt nichts mehr.

Sicherheits-Eigenschaften

• investable_capital ≥ 0 durch max(0, …) und cash ≥ 0-Invariante (paper_trade hat keine Negativ-Cash-Logik).
• investable_capital ≤ cash immer (Reserve ≤ realized_pnl_total ≤ cash − base + positions_value … fast).
• Kein Doppel-Counting: investable_capital wird NUR vom Sizer gelesen; cash bleibt für Bookkeeping (Buy/Sell-Mutation) zuständig.
• Reserve bei Verlust: schrumpft automatisch auf 0, kein Negativ-Wert, keine doppelte Drawdown-Wirkung.

5. Sizing-Integration

Kritische Regel: Wenn Reserve-Mode aktiv und exchange_balance > investable_capital, darf der Bot nicht den Exchange-Wert nutzen. BalanceGuard capt auf investable_capital.

6. GUI-Vorschlag

Empfehlung: Eigener Bereich „Capital Management" in Filament, NICHT in Risk Settings.

Begründung: Risk Settings sind Per-Trade-Limits (max_risk, exposure, etc.). Capital-Management ist ein architektonischer Mode-Switch plus Dashboard-Anzeige. Eigener Resource bleibt sauber.

Filament Resources:
├── Risk Settings (G9)             ← per-trade gates
├── Config Profiles (G7)            ← G10-Apply-Profile
└── Capital Management (CAP)        ← NEW
    ├── Mode Selector: [compound | reserve_profits | partial_reinvest (1.1)]
    ├── Base Capital (editable, audit-logged)
    ├── Realized PnL (computed, read-only)
    ├── Profit Reserve (computed, read-only)
    ├── Investable Capital (computed, read-only)
    └── History tab: mode-changes mit timestamps + by-user

Dashboard-Widget: „Capital Allocation"-Donut: cash / positions_value / profit_reserve.

G10 Apply-Required? Mode-Wechsel ist substantieller Behavior-Change → JA, sollte über Apply-Mechanik laufen (analog G9). Konkret: mode als 14. Phase-1.1-Key in G7-Allowlist UND/ODER neue G9-Allowlist-Erweiterung.

7. G10 / Runtime Config — Empfehlung

Audit-Schicht: jeder Mode-Wechsel schreibt audit_events.event_type='capital.mode_apply_requested' analog profile.apply.requested.

8. T-SPLIT-Auswirkung

Phase-Reihenfolge: CAP-1 → T-SPLIT-Detection. Nach T-SPLIT kann CAP-2 (per-T-bereich-Pools) folgen.

CAP-1 / T-SPLIT sind orthogonal. Reihenfolge offen.

9. Safety / Defaults

10. Migration / Backfill

11. Phasenplan (eigener Vorschlag)

Gesamt: ~5–6 Etappen, jede 1–2 Sessions, ~1080 LoC + ~115 Tests.

Empfohlene Position in Roadmap: NACH G10 Closure, vor T-SPLIT. Begründung: G10-Apply-Mechanik ist Voraussetzung für CAP-1.5; T-SPLIT braucht globalen CAP-Mode als Default, bevor per-T-Pools zugeschaltet werden.

12. Testplan

Total: ~95–115 Tests über alle CAP-Phasen.

13. Risiken + Stop-Regeln

Stop-Regeln:

• Falls investable_capital < 0 rechnerisch → Bot abort + Audit
• Falls realized_pnl_total != Σ closed_trades.pnl → Bot Warning + Reconcile
• Falls Mode-Wechsel ohne Audit-Event → Test-Failure (boundary AST)

14. Eigene Empfehlung — Kurzfassung

1. CAP-1 ist sinnvoll und gehört nach G10-Closure, weil G10-Apply-Mechanik Voraussetzung für saubere Mode-Wechsel ist.
2. Eigene CAP-Serie, nicht in G9 oder G7 einbauen — semantisch klar getrennt.
3. Modell B (Reserve Profits) zuerst als optional-aktivierbarer Mode, Compound bleibt Default für minimal-invasive Migration.
4. Architektur-Schwerpunkt: neue Computed-Properties in PaperTrader.get_portfolio() + Sizer-Migration cash → investable_capital (analog G10-4.1 Etappe 2).
5. Phasen: CAP-1.1 bis CAP-1.5 (oder 1.6 mit partial), gleiches Etappen-Muster wie G10-4.x.
6. Default Testnet: compound (status-quo). Default Mainnet: reserve_profits + admin-confirm-required.
7. T-SPLIT-Interaktion: orthogonal — CAP-1 global zuerst, per-T-bereich-Pools später (T-SPLIT ist Vorbedingung).
8. Backfill ablehnen — Activation-Marker setzt Schnittlinie.

15. Offene Fragen (für späteren CAP-1-Start)

• Q-1: Soll base_capital an STARTING_CAPITAL (.env) gekoppelt sein, oder unabhängig editierbar?
• Q-2: Soll T3 in CAP-1 explizit ausgeklammert werden (eigener Pool)? Oder T3 auch im global-Pool?
• Q-3: Bei Mode-Switch mit offenen Positionen: alle bestehenden Positions in „pre-CAP" Bucket markieren? Oder bei nächstem Sell wie-bisher behandeln?
• Q-4: Soll realized_pnl_total auch fees abziehen (= net) oder nur PnL? Aktuell closed_trades.pnl ist already-netted (siehe paper_trade.py:208).
• Q-5: Reserve-Wert als separates Feld in live_portfolio.json persistieren, oder always derived aus closed_trades? (Performance: 32 Trades sind trivial; bei 10 000 Trades wird Recompute teuer.)

Boundary-Bestätigungen

Empfohlene Roadmap-Position: Post-G10 Backlog Item #3 (zwischen T-SPLIT-PREFLIGHT und D-DEPLOY).