Copyright 2026 Moonlight Technologies Inc. All Rights Reserved.

Auth Masahiro Aoki

EvoSpikeNet-BrainOS — 実装計画書

最終更新: 2026-05-30 (v0.2.0 — Phase 1+2 完了、R5 クライアント実装)

エグゼクティブサマリー

v0.2.0 の主な実装（Phase 1 + Phase 2 + R5）:

Phase 1 Foundation 完了: brainos/config.py, brainos/models.py, brainos/event_bus/, brainos/security/, brainos/identity/, brainos/world_model/, brainos/observability/, brainos/audit/, api/app.py
Phase 2 Cognitive Loop 完了: brainos/pfc/, brainos/safety/, brainos/degradation/, brainos/memory/, brainos/adapters/
R5 Cross-Platform-Client 完了: Python SDK (brainos/client/sdk.py) + PWA Web ダッシュボード (api/static/) + Service Worker
テスト結果: 157 passed, 1 skipped

次フェーズ（Phase 3 — R1〜R4 実装）:

R1 Multi-Platform → R2 Offline-AI → R4 Zero-Disconnection → R3 Genome-Sync の順で 8 週間のロードマップで実装します。

Phase 1: Foundation（完了）

タスク	モジュール	完了条件（DoD）	状態
イベントバス起動	`brainos/event_bus/`	全ノード疎通確認	✅
API 認証基盤	`brainos/identity/`	`ALLOW_NO_AUTH=false` 本番強制・401 テストパス	✅
セキュア通信	`brainos/security/`	HMAC 署名の全メッセージ適用・未署名拒否テストパス	✅
World Model 最小実装	`brainos/world_model/`	エンティティ CRUD + スナップショット取得	✅
Observability	`brainos/observability/`	Prometheus 基本メトリクス収集	✅
監査ログ基盤	`brainos/audit/`	SHA-256 chain の `verify_chain()` テストパス	✅

テスト: tests/test_phase1_foundation.py — 52 passed

Phase 2: Cognitive Loop（完了）

タスク	モジュール	完了条件（DoD）	状態
PFC ノード起動	`brainos/pfc/`	`make_decision()` 往復・安定稼働	✅
倫理安全ガード	`brainos/safety/`	CRITICAL ブロック + Human Approval キュー動作確認	✅
縮退動作	`brainos/degradation/`	ノード障害時の `ServiceLevel` 降格確認	✅
記憶システム	`brainos/memory/`	書込み・検索・TTL 保持ポリシーの往復確認	✅
第 1 ドメインアダプタ	`brainos/adapters/`	Observe→Decide→Act→Learn の完全経路疎通	✅

テスト: tests/test_phase2_cognitive.py — 78 passed

R5: Cross-Platform-Client（完了 — v0.2.0）

タスク	モジュール	完了条件（DoD）	状態
Python SDK	`brainos/client/sdk.py`	Windows / Linux / macOS で httpx のみで動作	✅
PWA Web ダッシュボード	`api/static/index.html`	全 5 プラットフォーム動作、外部 CDN 不要	✅
Service Worker	`api/static/sw.js`	オフラインキャッシュ・ホーム画面インストール	✅
CORS ミドルウェア	`api/app.py`	`BRAINOS_CORS_ORIGINS` で制御	✅

テスト: tests/test_phase3_client.py — 27 passed

Phase 3: Multi-App Integration — R1–R4 実装

R1–R4 は全て BrainOS v1.0 のリリース条件（MUST）です。

優先度・依存関係

必須要件	対応フェーズ	優先度	依存関係
R1 Multi-Platform	Phase 3 前半	HIGH	Phase 2 完了（✅ 完了済み）
R2 Offline-AI	Phase 3 前半	HIGH	R1 `BrainOSHAL`, `LocalModelCache`
R4 Zero-Disconnection	Phase 3 前半〜通期	HIGH	Phase 2 完了（✅ 完了済み）
R3 Genome-Sync	Phase 3 後半	MEDIUM	R2 差分同期プロトコル
R5 Cross-Platform-Client	✅ 完了（v0.2.0）	—	—

詳細ロードマップ（8 週）

Phase 3 前半（4 週）
├── Week 1-2: brainos/platform/ 実装（R1）
│            ・PlatformDetector — 7 種プラットフォーム検出
│              （CPU / GPU / Jetson / RasPi / EdgeTPU / Loihi / Quantum）
│            ・BrainOSHAL — 統一 load_model / run_inference インタフェース
│            ・Dockerfile.raspi + requirements-raspi.txt 追加
├── Week 2-3: brainos/offline/ 実装（R2）
│            ・OfflineModeManager — 状態機械（ONLINE / DEGRADED_ONLINE / OFFLINE）
│            ・LocalModelCache — ONNX キャッシュ管理
│            ・オフライン決定 API の統合テスト
└── Week 3-4: brainos/watchdog/ 実装（R4）
             ・BrainOSSupervisor + HealthProbe
             ・AutoRecoverySystem 連携
             ・API エンドポイント 3 本追加

Phase 3 後半（4 週）
├── Week 5-6: brainos/genome/ 実装（R3）
│            ・GenomeSyncIntegrator — broadcast / receive / merge
│            ・差分同期プロトコル — export_delta / apply_delta
│            ・Zenoh トピック 3 本 + REST API 3 本追加
└── Week 7-8: 統合テスト・回帰テスト
             ・全 R1–R4 DoD 検証
             ・Phase 1+2 回帰テスト（157 passed ベースライン維持）
             ・カオステスト（Zenoh 断・ノード障害・オフライン切替）

新規モジュール（Phase 3）

モジュール	要件	主要クラス
`brainos/platform/detector.py`	R1	`PlatformDetector`, `PlatformKind`（7 種）
`brainos/platform/hal.py`	R1	`BrainOSHAL` — 統一 `load_model()`, `run_inference()`
`brainos/offline/mode.py`	R2	`OfflineModeManager`, `OfflineState`
`brainos/offline/local_cache.py`	R2	`LocalModelCache` — ONNX キャッシュ
`brainos/offline/client_agent.py`	R2	`OfflineClientAgent` — クライアント側オフライン推論
`brainos/offline/llm_router.py`	R2	`LLMRouter` — BrainOS API / ローカル LLM / ルールベースのフォールバック
`brainos/genome/integrator.py`	R3	`GenomeSyncIntegrator` — broadcast / merge / delta
`brainos/genome/protocol.py`	R3	Zenoh トピック定数（`brainos/genome/*`）
`brainos/genome/serializer.py`	R3	`GenomeSerializer` — 差分シリアライゼーション（MessagePack）
`brainos/genome/merger.py`	R3	`GenomeMerger` — 競合解決・重み平均・クロスオーバー
`brainos/watchdog/supervisor.py`	R4	`BrainOSSupervisor`, `RestartPolicy`, `SupervisedNode`
`brainos/watchdog/health_probe.py`	R4	`HealthProbe` — HTTP ポーリング + タイムアウト

R2 詳細設計: クライアント側オフライン動作 + ローカル LLM

現在の brainos/offline/ はサーバー側（BrainOS ノード）のオフライン継続のみカバーしている。クライアント（Python SDK / PWA）が BrainOS サーバーに繋がらない場合 の動作が未定義のため、以下を追加する。

LLM フォールバック階層（`brainos/offline/llm_router.py`）

クライアント → BrainOS API (/api/v1/cognitive/decide)
         ↓ タイムアウト / 接続断
         → ローカル LLM（Ollama / llama.cpp HTTP API, localhost:11434）
         ↓ Ollama も未起動 / モデル未ダウンロード
         → 内蔵ルールエンジン（決定木ベース最小 AI）

# brainos/offline/llm_router.py
class LLMBackendKind(str, Enum):
    BRAINOS_API  = "brainos_api"   # BrainOS REST API（通常）
    OLLAMA       = "ollama"        # ローカル Ollama（http://localhost:11434）
    LLAMACPP     = "llamacpp"      # llama.cpp HTTP サーバー
    RULE_ENGINE  = "rule_engine"   # フォールバック専用ルールエンジン

class LLMRouter:
    """
    推論要求をバックエンド優先順位に従って転送する。
    接続失敗時は自動的に次のバックエンドへフォールバックする。
    """
    def __init__(self, backends: list[LLMBackendKind], timeout_ms: int = 3000)

    def route(self, prompt: str, context: dict) -> LLMResponse
        # 1. BRAINOS_API → 失敗 → 2. OLLAMA → 失敗 → 3. RULE_ENGINE

    def get_active_backend(self) -> LLMBackendKind
    def get_latency_stats(self) -> dict  # 各バックエンドの p50/p95 レイテンシ

クライアント側オフラインエージェント（`brainos/offline/client_agent.py`）

# brainos/offline/client_agent.py
class OfflineClientAgent:
    """
    BrainOS SDK クライアント（brainos/client/sdk.py）が
    BrainOS サーバーに接続できない場合に自律動作するエージェント。

    - ローカル決定キャッシュ（直近 N 件の decide 結果を保存）
    - ローカル LLM を通じた推論
    - オフライン期間中の操作ログをキューに蓄積し、再接続後に同期
    """
    def __init__(self, llm_router: LLMRouter, local_cache: "LocalModelCache")

    def decide(self, objective: str, context: dict) -> DecisionResult
        # LLMRouter.route() でローカル推論、結果を offline_queue に enqueue

    def flush_queue(self, client: "BrainOSClient") -> SyncReport
        # 再接続後に蓄積した操作ログを BrainOS サーバーへ一括送信（べき等）

    def get_queue_size(self) -> int
    def is_offline(self) -> bool

PWA クライアントのオフライン動作（`api/static/`）

Service Worker がすでにキャッシュしているため、静的アセットはオフラインで動作する。API アクセスについては以下の方針とする:

ケース	動作
BrainOS サーバーに接続可能	通常 API 呼び出し
サーバー不達・Service Worker キャッシュあり	キャッシュレスポンスを表示（read-only）
Ollama が localhost で起動中	Ollama へ直接 fetch（`/api/chat`）
すべて不達	オフラインバナー表示 + ルールエンジン JSON レスポンス

オフライン時 Zenoh Topic（追加）

トピック	方向	説明
`brainos/offline/client_queue`	Client → Server	再接続後の操作ログ一括転送
`brainos/offline/sync_ack`	Server → Client	クライアントキュー受信確認

DoD 追加（R2 クライアント側）

[ ] BrainOS サーバー停止中に OfflineClientAgent.decide() がローカル LLM から結果を返す
[ ] Ollama 停止中に LLMRouter がルールエンジンへフォールバックする
[ ] 再接続後に flush_queue() で蓄積操作ログが BrainOS に送信される（統合テスト）
[ ] PWA がオフラインでもダッシュボードを表示できる（Service Worker + キャッシュ確認）

R3 詳細設計: Genome 送受信プロトコル

現在の計画では GenomeSyncIntegrator の broadcast / receive / merge のみ記述されており、実際のデータ構造・差分フォーマット・競合解決方針が未定義。以下を追加する。

Genome データ構造（`EvoSpikeNet-Core/evospikenet/genome.py` の利用）

BrainOS が送受信する Genome の単位は Core の EvoGenome を使用する。BrainOS 側では以下のエンベロープで包む:

@dataclass
class GenomePacket:
    packet_id: str              # UUID v4（べき等キー）
    sender_node_id: str         # 送信ノード ID
    genome: dict                # EvoGenome.to_dict() の結果
    generation: int             # 世代番号
    fitness_score: float        # 直近フィットネス（マージ優先度に使用）
    evolved_since: datetime     # 最終進化タイムスタンプ
    platform: str               # PlatformKind（ハードウェア依存進化の識別用）
    signature: bytes            # secure_serialization.pack() による HMAC-SHA256

差分シリアライゼーション（`brainos/genome/serializer.py`）

# brainos/genome/serializer.py
class GenomeSerializer:
    """
    EvoGenome の差分をコンパクトに送受信するための MessagePack シリアライザ。
    フルシリアライズと差分（delta）を使い分ける。
    """
    @staticmethod
    def serialize_full(genome: "EvoGenome") -> bytes           # MessagePack フルシリアライズ

    @staticmethod
    def serialize_delta(base: "EvoGenome", current: "EvoGenome") -> bytes
        # 変化した Gene/Chromosome のみを抽出して差分エンコード
        # 差分形式: {"changed": {gene_id: new_value}, "added": [...], "removed": [...]}

    @staticmethod
    def deserialize(data: bytes) -> "EvoGenome"

    @staticmethod
    def apply_delta(base: "EvoGenome", delta: bytes) -> "EvoGenome"

マージ・競合解決（`brainos/genome/merger.py`）

# brainos/genome/merger.py
class MergeStrategy(str, Enum):
    FED_AVG     = "fed_avg"     # DynamicFedAvgStrategy ベースの重み平均
    CROSSOVER   = "crossover"   # GenomePool のクロスオーバー（高フィットネス優先）
    TOURNAMENT  = "tournament"  # トーナメント選択（フィットネス上位優先）

class GenomeMerger:
    """
    複数ノードから受信した EvoGenome をマージする。
    競合解決: fitness_score が高い方の遺伝子を優先し、
    同スコアの場合は evolved_since が新しい方を採用する。
    """
    def __init__(self, strategy: MergeStrategy = MergeStrategy.FED_AVG)

    def merge(
        self,
        local: "EvoGenome",
        peers: list["EvoGenome"],
    ) -> "EvoGenome"
        # FED_AVG: 重みテンソルを fitness_score で重み付け平均
        # CROSSOVER: Core GenomePool.crossover() を使用
        # TOURNAMENT: fitness_score 上位 50% から選択

    def resolve_conflict(
        self,
        gene_a: "Gene",
        gene_b: "Gene",
    ) -> "Gene"
        # フィットネス同点の場合: evolved_since が新しい方を採用（LWW）

Zenoh トピック詳細（§10 への追記）

トピック	方向	ペイロード型	説明
`brainos/genome/updated`	Node → All	`GenomePacket`	世代進化完了後のブロードキャスト
`brainos/genome/sync_request`	Node → Peers	`{node_id, since: datetime}`	再接続後の差分リクエスト
`brainos/genome/delta`	Peer → Node	`GenomePacket` (delta)	差分 Genome 返信

REST API 追加（Phase 3）

エンドポイント	メソッド	説明
`GET /api/v1/genome/status`	GET	現在の Genome 状態・世代数・フィットネス・最終同期時刻
`POST /api/v1/genome/evolve`	POST	1 世代進化を即時実行しブロードキャスト
`POST /api/v1/genome/sync`	POST	ピアと Genome 強制同期（delta 取得・マージ）

クライアント側 Genome ストレージ

Python SDK（brainos/client/sdk.py）および PWA クライアントは Genome を直接進化させず、BrainOS サーバーが管理する Genome を参照するのみとする。エッジデバイス（Jetson / RasPi）で動作する BrainOS ノードのみがローカル進化を実施し、brainos/genome/updated でサーバーに送信する。

[エッジデバイス上の BrainOS ノード]
  ↓ ローカル進化（evolution_engine.py / GenomePool）
  → GenomeSyncIntegrator.evolve_and_sync()
  → Zenoh brainos/genome/updated
  → [BrainOS サーバー] GenomeMerger.merge()
  → 更新済み Genome を全クライアントへ配信

DoD 追加（R3 プロトコル）

[ ] GenomeSerializer.serialize_delta() が変化した Gene のみを抽出する（ユニットテスト）
[ ] GenomeMerger.merge() が FED_AVG / CROSSOVER / TOURNAMENT の各戦略で動作する
[ ] 競合解決で fitness_score 優先・同点時 evolved_since 優先が適用される
[ ] Zenoh 3 トピックすべてが HMAC-SHA256 署名付きペイロードで送受信される
[ ] REST API 3 本が TestClient で動作する（統合テスト）

テスト計画

テストファイル	対象要件	主要テストケース
`tests/test_phase3_platform.py`	R1	PlatformDetector 全 7 種・Jetson/RasPi は skip
`tests/test_phase3_offline.py`	R2	Zenoh 断時 `is_ai_operational=True`・オフライン決定 API
`tests/test_phase3_genome.py`	R3	Genome broadcast/receive/merge・delta 同期・REST API 3 本
`tests/test_phase3_watchdog.py`	R4	ノード障害検出・再起動・代替起動・EMERGENCY 降格・REST API 3 本

必須要件（BrainOS v1.0 リリース条件）

#	必須要件	状態	新規モジュール
R1	Multi-Platform — CPU / GPU / Jetson / Raspberry Pi / 量子コンピュータ上で動作	Phase 3 計画中	`brainos/platform/`
R2	Offline-AI — ネットワーク断でも AI として動作し続ける	Phase 3 計画中	`brainos/offline/`
R3	Genome-Sync — オンライン時にモデルを共有し個別進化を Genome として統合	Phase 3 計画中	`brainos/genome/`
R4	Zero-Disconnection — 機能断絶ゼロ・監視・再起動・代替起動サポート	Phase 3 計画中	`brainos/watchdog/`
R5	Cross-Platform-Client — Windows / Linux / macOS / Android / iOS 向けクライアント	✅ 完了（v0.2.0）	`brainos/client/`, `api/static/`

ギャップ分析・モジュール設計・DoD チェックリストの詳細は BrainOS.md §21 を参照してください。

Phase 4: Production Hardening

タスク	実装
カオステスト	意図的ノード断 + Zenoh 切断 + 遅延注入
4 週間ソークテスト	SLO 継続計測・MTTR -80% 達成確認
コンプライアンス監査	`audit_log.verify_chain()` 定期実行 + CSV エクスポート
自動修復強化	`auto_recovery.py` プレイブック拡張（新 `FailureCategory` 追加）
量子統合	`quantum/`, `advanced_quantum_decision.py`, `ibm_quantum_plugin.py`
フェデレーテッドラーニング	`federated.py`, `federated_strategy.py`

設計の詳細: BrainOS.md