tomoaki/hakorune

Fork 0

Files

nyash-codex 8fd3a2b509 docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)

2025-10-31 18:00:10 +09:00

9.4 KiB

Raw Blame History

hako.toml メタ設定例

作成: 2025-10-02 ソース: ChatGPT Pro UltraThink Mode 用途: Python統合のメタデータ設定リファレンス

📋 概要

Python-Hakorune統合におけるhako.tomlの設定例集です。 Effect/Capability/Contract/Policyの具体的な設定方法を示します。

🎯 基本設定

最小構成

# hako.toml (minimal)
[box.PyRuntimeBox]
effects.allow = ["py.import:math"]

標準構成

# hako.toml (standard)
[box.PyRuntimeBox]
effects.allow = [
    "py.import:math",
    "py.import:json",
    "py.time:monotonic"
]
capabilities.enforce = true

🎭 Effect設定

利用可能なEffect一覧

[box.PyRuntimeBox.effects]
available = [
    # モジュールインポート
    "py.import",

    # ファイルシステム
    "py.fs.read",
    "py.fs.write",

    # ネットワーク
    "py.net.http",
    "py.net.socket",

    # 環境変数
    "py.env.read",
    "py.env.write",

    # 時刻
    "py.time.monotonic",
    "py.time.real",

    # ランダム
    "py.random",

    # プロセス
    "py.subprocess"
]

Effect許可例

[box.PyRuntimeBox.effects]
allow = [
    "py.import:math",
    "py.import:json",
    "py.import:re",
    "py.time:monotonic",
    "py.fs.read:/tmp/**"
]

🛡️ Capability設定

基本Capability

[box.PyRuntimeBox.capabilities]
# 許可リスト
allow = [
    "py.import:math",
    "py.import:json"
]

# 拒否リスト
deny = [
    "py.subprocess",
    "py.net"
]

# 厳格モード
enforce = true

詳細Capability（モジュール別）

[box.PyRuntimeBox.capabilities.import]
# 標準ライブラリ
stdlib = [
    "math",
    "json",
    "re",
    "datetime",
    "collections"
]

# サードパーティ（ホワイトリスト）
allow_third_party = [
    "numpy",
    "pandas"
]

# 拒否（ブラックリスト）
deny = [
    "os",
    "subprocess",
    "socket"
]

ファイルシステムCapability

[box.PyRuntimeBox.capabilities.fs]
# 読み取り許可
read_paths = [
    "/tmp/**",
    "/data/input/**",
    "~/.config/app/**"
]

# 書き込み許可
write_paths = [
    "/tmp/**",
    "/data/output/**"
]

# 拒否
deny_paths = [
    "/etc/**",
    "/sys/**",
    "~/.ssh/**"
]

ネットワークCapability

[box.PyRuntimeBox.capabilities.net]
# HTTP許可
http_allow = [
    "https://api.example.com/**",
    "https://data.example.org/api/**"
]

# Socket許可（ホスト:ポート）
socket_allow = [
    "localhost:8080",
    "127.0.0.1:5432"
]

# 拒否
deny = [
    "0.0.0.0:*",  # すべてのインターフェース
    "*:22",       # SSH
    "*:3389"      # RDP
]

✅ Contract設定

PyFunctionBox Contract

[contracts.PyFunctionBox.exec]
# Pre条件（引数チェック）
pre = [
    "args.len <= 8",              # 引数は8個まで
    "bytes_total <= 1_000_000",   # 合計1MB以下
    "no_file_descriptors"         # ファイルディスクリプタ禁止
]

# Post条件（返り値チェック）
post = [
    "result.size <= 1_000_000",   # 返り値1MB以下
    "no_exception",               # 例外禁止
    "allow_none = true",          # None許可
    "execution_time <= 5.0"       # 5秒以内
]

# 違反時の挙動
on_violation = "error"  # "error" | "warn" | "ignore"

PyModuleBox Contract

[contracts.PyModuleBox.import]
pre = [
    "module_name.len <= 100",     # モジュール名100文字以内
    "no_relative_import"          # 相対インポート禁止
]

post = [
    "module_size <= 10_000_000",  # モジュールサイズ10MB以下
    "no_native_code"              # ネイティブコード禁止（オプション）
]

PyInstanceBox Contract

[contracts.PyInstanceBox.call_method]
pre = [
    "method_name.len <= 50",      # メソッド名50文字以内
    "args.len <= 16"              # 引数16個まで
]

post = [
    "result.size <= 1_000_000",   # 返り値1MB以下
    "no_side_effects"             # 副作用禁止（Pure）
]

🎛️ Policy設定

開発モード（Dev）

[policy.dev]
# Capability
capabilities.enforce = false  # 観測のみ
capabilities.log = true       # ログ記録

# Contract
contracts.enforce = true      # 厳格チェック
contracts.on_violation = "error"  # 違反時エラー

# Deterministic
deterministic = false         # 非決定的許可

# Trace
trace.effects = true          # 効果トレース
trace.calls = true            # 呼び出しトレース
trace.errors = true           # エラートレース

# Verifier
verify.phi = true             # PHI検証
verify.ssa = true             # SSA検証
verify.on_fail = "error"      # 検証失敗時エラー

本番モード（Prod）

[policy.prod]
# Capability
capabilities.enforce = true   # 厳格適用
capabilities.log = false      # ログなし

# Contract
contracts.enforce = true      # 厳格チェック
contracts.on_violation = "warn"  # 違反時警告

# Deterministic
deterministic = true          # 決定的実行

# Trace
trace.effects = false         # トレースなし
trace.calls = false
trace.errors = true           # エラーのみ

# Verifier
verify.phi = true             # PHI検証
verify.ssa = true             # SSA検証
verify.on_fail = "warn"       # 検証失敗時警告

テストモード（Test）

[policy.test]
# Capability
capabilities.enforce = true   # 厳格適用
capabilities.log = true       # ログ記録

# Contract
contracts.enforce = true      # 厳格チェック
contracts.on_violation = "error"  # 違反時エラー

# Deterministic
deterministic = true          # 決定的実行（再現性）

# Trace
trace.effects = true          # 全トレース
trace.calls = true
trace.errors = true

# Verifier
verify.phi = true             # 全検証
verify.ssa = true
verify.on_fail = "error"      # 検証失敗時エラー

🔧 環境変数によるオーバーライド

優先順位

環境変数（最優先）
hako.toml
hakorune.toml
デフォルト値

環境変数例

# Capability
export HAKO_PLUGIN_CAPS_ENFORCE=1
export HAKO_TRACE_EFFECTS=1

# Contract
export HAKO_CHECK_CONTRACTS=1
export HAKO_CONTRACT_VIOLATION=error

# Deterministic
export HAKO_DETERMINISTIC=1

# ABI
export HAKO_ABI_VTABLE=1
export HAKO_ABI_STRICT=1

# Verifier
export HAKO_VERIFY_ALLOW_NO_PHI=0
export HAKO_VERIFY_ON_FAIL=error

# LLVM
export HAKO_LLVM_USE_HARNESS=1

📊 実用例

例1: 数学計算のみ許可

# hako.toml
[box.PyRuntimeBox]
effects.allow = ["py.import:math"]
capabilities.enforce = true

[contracts.PyFunctionBox.exec]
pre = ["args.len <= 4"]
post = ["no_exception", "execution_time <= 1.0"]

using "python"

box Main {
    flow main() {
        let py = PyRuntimeBox();
        let math = py.import("math");
        let sqrt = math.get("sqrt");
        let r = sqrt.exec([2.0]);
        print(r);  // OK
        py.fini();
    }
}

例2: データ処理（ファイル読み取り）

# hako.toml
[box.PyRuntimeBox]
effects.allow = [
    "py.import:json",
    "py.fs.read:/data/input/**"
]

[box.PyRuntimeBox.capabilities.fs]
read_paths = ["/data/input/**"]
write_paths = []  # 書き込み禁止

using "python"

box Main {
    flow main() {
        let py = PyRuntimeBox();
        let json = py.import("json");

        // ファイル読み取り（許可）
        let data = py.eval("open('/data/input/test.json').read()");
        let parsed = json.get("loads").exec([data]);

        print(parsed);
        py.fini();
    }
}

例3: API呼び出し（ネットワーク）

# hako.toml
[box.PyRuntimeBox]
effects.allow = [
    "py.import:urllib",
    "py.net.http"
]

[box.PyRuntimeBox.capabilities.net]
http_allow = [
    "https://api.example.com/**"
]

[contracts.PyFunctionBox.exec]
pre = ["args.len <= 2"]
post = [
    "result.size <= 1_000_000",
    "execution_time <= 10.0"
]

using "python"

box Main {
    flow main() {
        let py = PyRuntimeBox();

        let code = "
import urllib.request
def fetch(url):
    with urllib.request.urlopen(url) as r:
        return r.read()
";
        py.exec(code);
        let fetch = py.get("fetch");

        // API呼び出し（許可）
        let result = fetch.exec(["https://api.example.com/data"]);
        print(result);

        py.fini();
    }
}

🔍 デバッグ設定

詳細ログ

[debug]
# すべてのトレース有効化
trace.all = true

# 個別トレース
trace.effects = true
trace.capabilities = true
trace.contracts = true
trace.python_calls = true
trace.gil = true

# ログレベル
log_level = "debug"

# ログ出力先
log_file = "/tmp/hakorune-python-debug.log"

パフォーマンスプロファイル

[profile]
# タイミング記録
timing.enabled = true
timing.threshold = 0.1  # 100ms以上

# メモリ使用量
memory.track = true
memory.threshold = 10_000_000  # 10MB以上

# GC統計
gc.enabled = true

🔗 関連ドキュメント

強化版アーキテクチャv2 - 設計詳細
マイルストーン - 実装計画
リスクと対策 - リスク管理
Phase 20 README - 全体概要

最終更新: 2025-10-02 作成者: ChatGPT Pro (UltraThink Mode) ステータス: 設定リファレンス

9.4 KiB Raw Blame History Unescape Escape