STATE-CROSS-PROCESS-RECONCILE-1.1 + 1.4 — Plan-Only

Datum: 2026-06-04 (post-cutover Commit c4651dd) Modus: READ-ONLY · keine Code/State/Env-Änderungen Re-Scope: ersetzt MS-LOCK-STATE-1 (Thread-Lock-Annahme war falsch)

1. Root Cause final

Konkrete Race-Sequenz

t=0  Bot _reload_state_if_externally_changed → state X eingelesen, cookie=mtime_X
t=1  Bot mutiert state in RAM (z.B. pos['BTC'].current_price=...)
t=2  Worker update_stop_loss → liest Disk X → setzt pos['BTC'].stop_loss=NEU
                              → _save_state → Disk wird X', mtime=mtime_X'
t=3  Bot _save_state (z.B. nach execute_buy) → schreibt RAM (mit STALE SL!)
                              → Disk wird X'' — Worker's SL VERLOREN
                              → cookie=mtime_X''

2. Betroffene Dateien

0× DB-Migration · 0× GUI · 0× env · 0× CommandBus · 0× Strategy-Param · 0× Mainnet.

3. Aktuelle _save_state / _load_state Call-Sites

_save_state (27 Aufrufer im Bot-Prozess + 2 im Worker)

_load_state (1 Aufrufer)

• trader_core.py:264 — __init__ einmalig

_reload_state_if_externally_changed

• Definiert: trader_core.py:1288
• Aufgerufen: trader_core.py:1346 (update_prices, 1× pro Tick)

4. Minimal-Fixplan 1.1 (PRE-SAVE-MTIME-RECHECK-1)

4.1 Neue Save-API

def _save_state(self, *, allow_abort: bool = False, source: str = 'unknown') -> bool:
    """Returns True on success, False on aborted-save."""

Backward-kompatibel: bestehende live_trader._save_state() calls behalten Default allow_abort=False, source='unknown'. Migration der labels passiert in einem Folge-Commit (P3).

4.2 Pre-Save-Recheck-Logik (pseudo)

def _save_state(allow_abort=False, source='unknown'):
    try:
        disk_mtime_ns = STATE_FILE.stat().st_mtime_ns
    except OSError:
        disk_mtime_ns = None

    if disk_mtime_ns and self._state_mtime_ns and disk_mtime_ns > self._state_mtime_ns:
        # Conflict detected
        self._state_coherence['conflict_count'] += 1
        self._state_coherence['last_conflict_at'] = utcnow()
        self._state_coherence['last_external_mtime_ns'] = disk_mtime_ns

        if allow_abort:
            logger.warning(f"[STATE-COHERENCE] save aborted, source={source}")
            self._state_coherence['retry_count'] += 1
            return False

        # must-merge path
        logger.warning(f"[STATE-COHERENCE] pre-save mtime conflict, source={source}")
        merged = self._merge_disk_into_ram_for_save(disk_mtime_ns)
        if merged is None:
            logger.error(f"[STATE-COHERENCE] merge failed — falling back to blind save")
        else:
            self.state = merged
            self._state_coherence['merged_count'] += 1

    # ── existing atomic write path ─────────────────────────────────
    STATE_FILE.parent.mkdir(exist_ok=True)
    tmp_file = STATE_FILE.with_suffix('.tmp')
    with open(tmp_file, 'w') as f:
        json.dump(self.state, f, indent=2)
    tmp_file.rename(STATE_FILE)
    self._state_mtime_ns = STATE_FILE.stat().st_mtime_ns
    return True

4.3 Section-Ownership-Matrix

4.4 _merge_disk_into_ram_for_save Helper (pseudo)

def _merge_disk_into_ram_for_save(disk_mtime_ns) -> Optional[dict]:
    try:
        with open(STATE_FILE, 'r') as f:
            D = json.load(f)
    except Exception as e:
        return None

    R = self.state
    merged = dict(R)  # Bot-only sections → R wins

    # closed_trades: union by position_id
    seen_ids = set()
    union = []
    for t in D.get('closed_trades', []) + R.get('closed_trades', []):
        tid = t.get('position_id')
        if tid and tid in seen_ids:
            continue
        seen_ids.add(tid)
        union.append(t)
    merged['closed_trades'] = union[-500:]

    # positions: 3-way merge
    R_pos = R.get('positions', {})
    D_pos = D.get('positions', {})
    merged_pos = {}
    for sym in set(R_pos.keys()) | set(D_pos.keys()):
        if sym in R_pos and sym not in D_pos:
            merged_pos[sym] = R_pos[sym]                # Bot added → keep
        elif sym in D_pos and sym not in R_pos:
            continue                                     # Worker removed → drop
        else:
            p = dict(R_pos[sym])
            for field in ('stop_loss', 'take_profit'):
                if D_pos[sym].get(field) != R_pos[sym].get(field):
                    p[field] = D_pos[sym].get(field)
            merged_pos[sym] = p
    merged['positions'] = merged_pos

    return merged

4.5 Antworten auf die 8 Operator-Fragen

5. Observability-Plan 1.4 (REGRESSION-OBSERVABILITY-1)

5.1 In-Memory Counter (auf TraderCore-Instanz)

self._state_coherence = {
    'reload_mtime_jump_count':      0,
    'save_precheck_conflict_count': 0,
    'save_precheck_retry_count':    0,
    'save_precheck_merged_count':   0,
    'last_conflict_at':           None,
    'last_external_mtime_ns':     None,
    'last_merge_source':          None,
    'last_merge_summary':         None,
}

5.2 Log-Messages (level=WARNING/INFO, kein DEBUG)

5.3 bot_statuses.metadata_json Erweiterung

trading/main.py:1917 emit_bot_status bekommt zusätzlichen Metadata-Key:

metadata={
    ...existing keys...,
    'state_coherence': {
        'reload_mtime_jump_count':    live_trader._state_coherence['reload_mtime_jump_count'],
        'save_precheck_conflict_count': live_trader._state_coherence['save_precheck_conflict_count'],
        'save_precheck_retry_count':    live_trader._state_coherence['save_precheck_retry_count'],
        'save_precheck_merged_count':   live_trader._state_coherence['save_precheck_merged_count'],
        'last_conflict_at':           live_trader._state_coherence['last_conflict_at'],
        'last_merge_source':          live_trader._state_coherence['last_merge_source'],
    },
}

Keine DB-Migration nötig — metadata_json ist JSONB.

5.4 Optional: Tagespanik-Schwelle

save_precheck_conflict_count > 10 / 24 h → Telegram-Alert. Für Phase 1.4 erstmal nur Log + bot_statuses, kein Telegram.

6. Tests

test_state_cross_process_reconcile_1_1.py (20 Tests)

test_state_observability_1_4.py (10 Tests)

Regression-Sweep (P0-Tests aus History)

• test_sync_balance_sanity_1 (20)
• test_exit_reason_fix_1 (20)
• test_ms_candidate_dedup_1 (20)
• test_ms_stablecoin_block_1 (12)
• test_phase_n7 + test_phase_n8 (cumulative)
• test_data_link_1 + test_data_link_1_fu2
• test_t_split_2_emitter_wiring

Ziel: 0 neue Failures (pre-existing N8-test bleibt erwartet failing).

7. Cutover-Plan (SOT-1d-Pattern)

Rollback

• git revert <commit> → Build + Recreate clawbot + clawbot-worker
• Backup-Datei restore (live_portfolio.json) wenn merged-state inkonsistent wirkt

8. Risiken

9. Bundle vs Split — Empfehlung

→ Empfehlung: BUNDLE 1.1+1.4 in EINEM Commit + EINEM Cutover.

Begründung

Alternative — Split (nicht empfohlen)

• Phase 1.1 zuerst → 7 Tage Beobachtung ohne Counter (nur Log)
• Phase 1.4 danach
• Kostet 2 Cutover, längere Beobachtung mit weniger Daten

10. MS-Live-Readiness-Update

Sobald 1.1+1.4 live + 24 h Counter sauber → MS-Live darf in Testnet-Execution geschaltet werden.

11. Boundaries dieses Plans

0× Code-Touch · 0× State-Edit · 0× Bot-Recreate · 0× Worker-Recreate · 0× MS-Live-Aktivierung · 0× Env-Änderung · 0× DB-Migration · 0× Order-Logik · 0× Mainnet · 0× CommandBus · 0× Push.

12. Operator-Entscheidungen vor GO EXECUTE

STOP

Plan abgeschlossen. Kein Code geändert. Warte auf Operator-Entscheidungen Q1–Q8 + GO EXECUTE STATE-CROSS-PROCESS-RECONCILE-1 für Bundle 1.1+1.4.