trex-core/docs/batches/bat-041_20260612_long-term-instance-profile/design.md

BAT-041 Design

• Status: confirmed
• Batch: BAT-041

Architecture Summary

• watchdog timeout 설정을 단일 지점에서 per-instance 화한다: DaemonInstanceConfig.watchdog_timeout_sec(TOML, optional) → DaemonConfig.from_config 에서 값이 있으면 SafetySellConfig.watchdog_timeout_sec 를 dataclasses.replace 로 override. 소비자 2곳(slots RPC 핸들러의 expired 표시, SafetySellService 의 trigger gating)은 모두 config.safety_sell.watchdog_timeout_sec 를 읽으므로 자동으로 일치한다.
• 중장기 프로파일은 신규 코드 없이 기존 설정 메커니즘 조합(safety_sell_enabled=false + watchdog_timeout_sec=1800 + max_active_slots + market-close env 미설정)으로 표현되고, config/longterm.example.toml 로 표준화한다.
• runtime-flows 에 중장기 병행 운영 흐름(보호 경계 포함)을 추가한다.

Changed Areas

• Modules:
  • trex_core/runtime/config.py:
    • DaemonInstanceConfig.watchdog_timeout_sec: Optional[int] = None
    • from_toml: watchdog_timeout_sec 파싱 + <= 0 거부(기존 max_active_slots 검증 패턴)
    • from_config: inst.watchdog_timeout_sec is not None → safety_sell = dataclasses.replace(safety_sell, watchdog_timeout_sec=...)
  • config/longterm.example.toml (신규)
• Tests: tests/runtime/test_config*.py 패턴 — TOML 적용/env 폴백/독립/검증 거부
• Docs: docs/runtime-flows.md(중장기 운영 흐름 + Change Log), docs/project-structure.md(불필요 예상 — 구조 불변, config 필드 1개)

Key Decisions

1. override 지점 = from_config 단일 지점: TOML 값이 frozen SafetySellConfig 를 dataclasses.replace 로 교체. daemon.py·safety_sell.py·messaging_handlers.py 는 무변경 — 소비자가 이미 config.safety_sell.watchdog_timeout_sec 를 읽음(R-1 제거).
2. TOML 우선, env 폴백: watchdog_timeout_sec TOML 미설정 시 기존 env(TREX_WATCHDOG_TIMEOUT, 기본 120) 그대로 — 기존 인스턴스 byte-for-byte 무회귀(REQ-076 AC-2). REQ-060(env 폐기)과 달리 env 는 보존: 기존 운영 사용 중.
3. <= 0 명시 거부: max_active_slots/default_order_timeout_sec 와 동일한 from_toml 검증 패턴.
4. 프로파일 = 설정 조합(신규 코드 0): REQ-077 은 example TOML + 검증으로 충족. market-close 는 env 영역이므로 TOML 주석으로 "미설정 전제" 명시(코드 강제 없음 — 운영 절차).
5. S-1 검증 범위: 멀티데이 보유 유지는 영구 슬롯 DB 영속(dcy-020)의 기존 보장 + 자율 청산 미발화는 safety_sell_enabled=false 워커 미기동(BAT-036 evidence). 본 batch 는 프로파일 조합이 의도대로 로딩·적용되는지(워커 미기동 + timeout 1800 + 독립 instance_key)를 설정·기동 구성 단위로 검증하고, 실 데몬 장기 run 은 release 운영 검증으로 위임.

Edge Cases

• TOML watchdog_timeout_sec = 0 또는 음수: from_toml 명시 거부(RuntimeError).
• TOML 미설정 + env 미설정: 기본 120s(기존과 동일).
• TOML 설정 + env 도 설정: TOML 승리(per-instance 가 전역보다 구체적).
• 당일 인스턴스(TOML 미설정)와 중장기(1800) 병행: 인스턴스별 DaemonConfig 가 독립 생성되므로 분리 적용.

Architecture Impact

• runtime-flows (중장기 병행 운영 흐름 신설 — REQ-078 소관)

Reference Doc Update Plan

• project-structure.md: none 예상(구조 불변 — config 필드 1개 + 예시 파일. 예시 파일 위치 언급이 필요하면 한 줄)
• runtime-flows.md: 중장기 인스턴스 운영 섹션 신설 — 병행 토폴로지(instance_key 분리), 프로파일 구성(REQ-077 레시피), 보호 규칙 경계(전략 전적 책임 + CLI exit 백스톱, 코어 손절매 루틴 미사용), forced_close_at 미사용(발화 불가 근거), watchdog 중장기 의미(1800s, last_seen 가시성 유지). Change Log 항목 추가.