hakorune/docs/private/roadmap/phases/phase-20-python-integration/design/risks-and-mitigations.md

リスクと対策

作成: 2025-10-02 ソース: ChatGPT Pro UltraThink Mode 用途: Python統合における既知のリスクと対策

---

📋 概要

Python-Hakorune統合における技術的リスク、運用リスク、およびその対策をまとめます。

---

🔥 高リスク項目

1. GILデッドロック

リスク詳細

• 問題: Hakorune並列実行とPython GILのズレ
• 発生条件: Hakorune側マルチスレッド + Python呼び出しのネスト
• 影響: プログラム全体がハング、デバッグ困難

対策

アーキテクチャレベル:

// PyRuntimeBoxを専用スレッドで実行
pub struct PyRuntimeBox {
    thread: JoinHandle<()>,
    tx: Sender<PyCommand>,
    rx: Receiver<PyResult>,
}

impl PyRuntimeBox {
    pub fn init() -> Self {
        let (tx, rx_cmd) = channel();
        let (tx_result, rx) = channel();

        let thread = thread::spawn(move || {
            // このスレッドでGILを保持
            let gil = Python::acquire_gil();
            let py = gil.python();

            loop {
                match rx_cmd.recv() {
                    Ok(PyCommand::Import(name)) => {
                        let result = py.import(&name);
                        tx_result.send(PyResult::Module(result)).unwrap();
                    }
                    Ok(PyCommand::Shutdown) => break,
                    Err(_) => break,
                }
            }
        });

        PyRuntimeBox { thread, tx, rx }
    }
}

ガードレール:

[debug.gil]
# GIL獲得・解放のログ
trace = true

# タイムアウト検出
timeout = 5.0  # 5秒

# デッドロック検出
detect_deadlock = true

モニタリング:

# GILトレース有効化
export HAKO_TRACE_GIL=1

# タイムアウト設定
export HAKO_GIL_TIMEOUT=5.0

回避策

1. 専用スレッドでPython実行を隔離
2. メッセージパッシングでHakorune-Python間通信
3. タイムアウトで異常検出
4. ログで原因追跡

---

2. メモリリーク

リスク詳細

• 問題: Python参照カウント管理ミス
• 発生条件: Py_INCREF/Py_DECREFの不一致
• 影響: メモリ使用量増大、最悪OOM

対策

Arc管理:

// PythonオブジェクトをArcでラップ
pub struct PyObjectBox {
    inner: Arc<PyObjectInner>,
}

struct PyObjectInner {
    py_obj: Py<PyAny>,
}

impl Drop for PyObjectInner {
    fn drop(&mut self) {
        // 確実にDECREF
        Python::with_gil(|py| {
            self.py_obj.as_ref(py);
        });
    }
}

weakref.finalize:

# Python側で自動クリーンアップ
import weakref

def create_hakorune_object(obj):
    # finalizer登録
    finalizer = weakref.finalize(obj, cleanup_callback, obj_id)
    return obj

リーク検出:

[debug.memory]
# メモリトラッキング
track = true

# リーク検出
detect_leaks = true

# 定期チェック
check_interval = 10.0  # 10秒

ツール:

# Valgrind
valgrind --leak-check=full ./hakorune script.hkr

# AddressSanitizer
RUSTFLAGS="-Z sanitizer=address" cargo build

# Python memory profiler
export PYTHONTRACEMALLOC=1

回避策

1. Arc/Dropで自動管理
2. weakref.finalizeで循環参照対策
3. 定期チェックで早期発見
4. テストで継続監視

---

3. C拡張モジュールの扱い

リスク詳細

• 問題: numpy等のC拡張は特殊な扱いが必要
• 発生条件: ネイティブコードの直接呼び出し
• 影響: セグフォ、未定義動作

対策

Capability制御:

[box.PyRuntimeBox.capabilities.native]
# C拡張の許可
allow_native = true

# ホワイトリスト
allow_modules = [
    "numpy",
    "pandas",
    "_ctypes"
]

# ブラックリスト
deny_modules = [
    "ctypes",  # 任意ネイティブコード実行
    "cffi"
]

サンドボックス（将来）:

[sandbox]
# ネイティブコードをサンドボックスで実行
enable = true
mode = "seccomp"  # Linux

検証:

// ロード前に検証
fn verify_module_safety(module_name: &str) -> Result<()> {
    // シグネチャ確認
    // 既知の安全なモジュールか
    // ブラックリスト確認
}

回避策

1. ホワイトリストで既知の安全なモジュールのみ許可
2. サンドボックスで隔離実行（将来）
3. 検証でロード前チェック

---

⚠️ 中リスク項目

4. パフォーマンスオーバーヘッド

リスク詳細

• 問題: FFI境界・GIL・型変換のコスト
• 影響: 性能劣化

対策

最適化:

// 型変換キャッシュ
struct TypeCache {
    string_to_pyobject: HashMap<String, Py<PyString>>,
    int_to_pyobject: HashMap<i64, Py<PyLong>>,
}

impl TypeCache {
    fn get_or_create_string(&mut self, py: Python, s: &str) -> Py<PyString> {
        self.string_to_pyobject
            .entry(s.to_string())
            .or_insert_with(|| PyString::new(py, s).into())
            .clone()
    }
}

バッチ処理:

// 複数呼び出しをまとめる
fn batch_call(funcs: Vec<PyFunctionBox>, args: Vec<Vec<Value>>) -> Vec<Value> {
    Python::with_gil(|py| {
        funcs.iter().zip(args.iter())
            .map(|(f, a)| f.exec_with_gil(py, a))
            .collect()
    })
}

ベンチマーク:

# パフォーマンステスト
cargo bench --features python-integration

---

5. プラットフォーム固有問題

リスク詳細

• 問題: Python配布形態の違い（Linux/macOS/Windows）
• 影響: ビルド・実行時エラー

対策

プラットフォーム別設定:

# Linux
[target.x86_64-unknown-linux-gnu]
python-lib = "python3.11"
python-path = "/usr/lib/python3.11"

# macOS
[target.x86_64-apple-darwin]
python-lib = "python3.11"
python-path = "/usr/local/opt/python@3.11"

# Windows
[target.x86_64-pc-windows-msvc]
python-lib = "python311"
python-path = "C:/Python311"

CI/CD:

# .github/workflows/python-integration.yml
strategy:
  matrix:
    os: [ubuntu-latest, macos-latest, windows-latest]
    python-version: ['3.8', '3.9', '3.10', '3.11']

---

6. 例外伝播の複雑さ

リスク詳細

• 問題: Python例外とHakoruneエラーの境界
• 影響: エラーハンドリングの困難さ

対策

統一ErrorBox:

box ErrorBox {
    type: StringBox         // "ZeroDivisionError"
    message: StringBox      // "division by zero"
    traceback: StringBox    // フルスタックトレース
    source: StringBox       // "python" | "hakorune"
}

変換層:

fn convert_py_exception(py_err: &PyErr) -> ErrorBox {
    ErrorBox {
        type_: py_err.get_type().name().to_string(),
        message: py_err.to_string(),
        traceback: format_traceback(py_err),
        source: "python".to_string(),
    }
}

---

📊 低リスク項目

7. ドキュメント不足

対策

• 段階的にドキュメント整備
• コードサンプル充実
• チュートリアル作成

8. テストカバレッジ

対策

• ユニットテスト追加
• 統合テスト充実
• E2Eテスト自動化

---

🛡️ リスク管理マトリックス

リスク	深刻度	発生確率	優先度	対策状況
GILデッドロック	高	中	最優先	設計段階で対策
メモリリーク	高	中	最優先	Arc/Drop自動化
C拡張問題	高	低	高	ホワイトリスト
パフォーマンス	中	高	中	最適化計画
プラットフォーム	中	中	中	CI/CD網羅
例外伝播	中	低	低	ErrorBox統一
ドキュメント	低	高	低	段階的整備
テストカバレッジ	低	中	低	継続改善

---

🔍 監視・検出

自動検出

[monitoring]
# GIL監視
gil.timeout = 5.0
gil.alert_on_timeout = true

# メモリ監視
memory.threshold = 100_000_000  # 100MB
memory.alert_on_threshold = true

# パフォーマンス監視
performance.slow_call_threshold = 1.0  # 1秒
performance.alert_on_slow = true

ログ

# すべての監視ログ
export HAKO_TRACE_GIL=1
export HAKO_TRACE_MEMORY=1
export HAKO_TRACE_PERFORMANCE=1

---

📝 インシデント対応

1. GILデッドロック発生時

# 1. ログ確認
cat /tmp/hakorune-debug.log | grep GIL

# 2. スタックトレース取得
kill -QUIT <pid>

# 3. デバッガー接続
gdb -p <pid>

2. メモリリーク発生時

# 1. メモリ使用量確認
ps aux | grep hakorune

# 2. Valgrind実行
valgrind --leak-check=full ./hakorune script.hkr

# 3. Python側確認
export PYTHONTRACEMALLOC=1

---

🔗 関連ドキュメント

• 強化版アーキテクチャv2 - 設計詳細
• マイルストーン - 実装計画
• メタ設定例 - 設定例
• Phase 20 README - 全体概要

---

最終更新: 2025-10-02 作成者: ChatGPT Pro (UltraThink Mode) ステータス: リスク管理ドキュメント