tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)

Browse Source
This commit is contained in:
nyash-codex
2025-10-31 18:00:10 +09:00
parent 1d49e24bf0
commit 8fd3a2b509
433 changed files with 108935 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

531
docs/private/roadmap/phases/phase-20-python-integration/design/meta-config-examples.md Normal file
View File

@ -0,0 +1,531 @@
# hako.toml メタ設定例
**作成**: 2025-10-02
**ソース**: ChatGPT Pro UltraThink Mode
**用途**: Python統合のメタデータ設定リファレンス
---
## 📋 概要
Python-Hakorune統合における`hako.toml`の設定例集です。
Effect/Capability/Contract/Policyの具体的な設定方法を示します。
---
## 🎯 基本設定
### 最小構成
```toml
# hako.toml (minimal)
[box.PyRuntimeBox]
effects.allow = ["py.import:math"]
```
### 標準構成
```toml
# hako.toml (standard)
[box.PyRuntimeBox]
effects.allow = [
"py.import:math",
"py.import:json",
"py.time:monotonic"
]
capabilities.enforce = true
```
---
## 🎭 Effect設定
### 利用可能なEffect一覧
```toml
[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許可例
```toml
[box.PyRuntimeBox.effects]
allow = [
"py.import:math",
"py.import:json",
"py.import:re",
"py.time:monotonic",
"py.fs.read:/tmp/**"
]
```
---
## 🛡️ Capability設定
### 基本Capability
```toml
[box.PyRuntimeBox.capabilities]
# 許可リスト
allow = [
"py.import:math",
"py.import:json"
]
# 拒否リスト
deny = [
"py.subprocess",
"py.net"
]
# 厳格モード
enforce = true
```
### 詳細Capability（モジュール別）
```toml
[box.PyRuntimeBox.capabilities.import]
# 標準ライブラリ
stdlib = [
"math",
"json",
"re",
"datetime",
"collections"
]
# サードパーティ（ホワイトリスト）
allow_third_party = [
"numpy",
"pandas"
]
# 拒否（ブラックリスト）
deny = [
"os",
"subprocess",
"socket"
]
```
### ファイルシステムCapability
```toml
[box.PyRuntimeBox.capabilities.fs]
# 読み取り許可
read_paths = [
"/tmp/**",
"/data/input/**",
"~/.config/app/**"
]
# 書き込み許可
write_paths = [
"/tmp/**",
"/data/output/**"
]
# 拒否
deny_paths = [
"/etc/**",
"/sys/**",
"~/.ssh/**"
]
```
### ネットワークCapability
```toml
[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
```toml
[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
```toml
[contracts.PyModuleBox.import]
pre = [
"module_name.len <= 100", # モジュール名100文字以内
"no_relative_import" # 相対インポート禁止
]
post = [
"module_size <= 10_000_000", # モジュールサイズ10MB以下
"no_native_code" # ネイティブコード禁止（オプション）
]
```
### PyInstanceBox Contract
```toml
[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）
```toml
[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）
```toml
[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）
```toml
[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" # 検証失敗時エラー
```
---
## 🔧 環境変数によるオーバーライド
### 優先順位
1. 環境変数（最優先）
2. hako.toml
3. hakorune.toml
4. デフォルト値
### 環境変数例
```bash
# 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: 数学計算のみ許可
```toml
# 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"]
```
```hakorune
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: データ処理（ファイル読み取り）
```toml
# hako.toml
[box.PyRuntimeBox]
effects.allow = [
"py.import:json",
"py.fs.read:/data/input/**"
]
[box.PyRuntimeBox.capabilities.fs]
read_paths = ["/data/input/**"]
write_paths = [] # 書き込み禁止
```
```hakorune
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呼び出し（ネットワーク）
```toml
# 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"
]
```
```hakorune
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();
}
}
```
---
## 🔍 デバッグ設定
### 詳細ログ
```toml
[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"
```
### パフォーマンスプロファイル
```toml
[profile]
# タイミング記録
timing.enabled = true
timing.threshold = 0.1 # 100ms以上
# メモリ使用量
memory.track = true
memory.threshold = 10_000_000 # 10MB以上
# GC統計
gc.enabled = true
```
---
## 🔗 関連ドキュメント
- [強化版アーキテクチャv2](enhanced-architecture-v2.md) - 設計詳細
- [マイルストーン](../planning/milestones.md) - 実装計画
- [リスクと対策](risks-and-mitigations.md) - リスク管理
- [Phase 20 README](../README.md) - 全体概要
---
**最終更新**: 2025-10-02
**作成者**: ChatGPT Pro (UltraThink Mode)
**ステータス**: 設定リファレンス