trader-explain

特徴寄与グラフを構築し、シグナル出力ノードから単一エントリーのフォワードプッシュ PageRank を実行して、トレーディングシグナルを説明します。上位 K 件のランキング済み特徴量は Markdown テーブルとして返され、SignedAttributionArtifact として trading-analysis にも永続化されます（ADR-126 Phase 6）。

このスキルが重要な理由：

• EU AI Act と SEC Reg-AI のガイダンスでは、個人投資家の資金に関わるアルゴリズム取引システムに、解釈可能なモデル出力を求めています。これは、基盤の残りの部分が待ち望んでいた、規制当局向けのアトリビューション経路です。
• 実行時に mcp__ruflo-sublinear__page-rank-entry ツールが登録されると、同じ呼び出し箇所で完全なネイティブ WASM PageRank が使用されます。それまでは、ローカルの反復計算カーネルが signed-attribution.mjs に含まれ、同じ順序を生成します（mulberry32 によるシード付き）。

手順：

1. シグナルを取得する（正規の trading-signals 名前空間から取得します。ADR-126 Phase 1 + Phase 2 のライフサイクル）：

   mcp__plugin_ruflo-core_ruflo__memory_retrieve({
     key: "SIGNAL_ID",
     namespace: "trading-signals"
   })
   

   シグナルエントリーには、推論時点の modelId、prediction、特徴ベクトルが含まれます。

2. モデルから特徴量ごとの寄与スコアを抽出する：

   npx neural-trader --predict --signal "$SIGNAL_ID" --explain --json
   

   期待される出力形式：

   {
     features: Array<{ name: string; contribution: number }>;
     // for Transformers, also includes per-head attention co-occurrence:
     attention?: Array<{ head: string; cooccur: Array<[number, number, number]> }>;
   }
   

   フォールバック経路 — インストール済みの neural-trader ビルドに --explain が含まれていない場合（古いバージョン。このフラグは後続の上流 PR 向けに範囲が定められていました）、このスキルはシグナルの入力ベクトルに対する決定論的な特徴重要度ヒューリスティックに切り替わります：contribution_i = |input_i - μ_i| / σ_i（z スコアの絶対値）。これは既知の代替指標であり、attention/SHAP ほど忠実ではありません。生成されるアーティファクトには attribution_method: "input-zscore-fallback" のタグが付くため、下流の利用者は規制当局への提出資料から除外できます。生成される Markdown の概要にフォールバック経路を記載し、エージェントがユーザーに伝えるようにしてください。

3. 特徴寄与グラフを構築する：

   • ノード：特徴量ごとに 1 つのノードと、予測用のソースノード __signal_output__ を作成します。
   • エッジ：__signal_output__ から各特徴ノードへの出辺を追加し、重みには contribution_i を指定します。attention の共起データを利用できる場合は、特徴ノード間にもエッジを追加し、重みには cooccur を指定します。これにより PageRank は単なる上位 K 件への縮退を免れ、単一エントリー方式になります。
   • ソース：__signal_output__（再現性を smoke でアサートできるよう、規約によりインデックス 0 にします）。

4. 単一エントリーの PageRank を実行する — mcp__ruflo-sublinear__page-rank-entry が登録されている場合は、こちらを優先します：

   mcp__ruflo-sublinear__page-rank-entry({
     nodes: GRAPH_NODES,
     edges: GRAPH_EDGES,
     sourceIndex: 0,
     damping: 0.85,
     maxIterations: 100,
     tolerance: 1e-8,
     seed: 42
   })
   

   ローカルのフォールバック（plugins/ruflo-neural-trader/src/signed-attribution.mjs の localSingleEntryPageRank）は、MCP ツールを利用できない場合に、シード付きの反復計算を約 30 行で実行します。計算は同じで、浮動小数点誤差の範囲内で同じ結果になり、同じシードでは同じ順序になります（Phase 6 の smoke でこれをアサートします）。

5. topKFeatures(graph, scores, k=10, excludeIndex=0) を使って、上位 K 件の AttributionFeature[] を構築します。ソースノードはランキング結果から除外されます。同順位の場合はノードインデックス（小さい方が優先）で決着するため、ランキングは決定論的です。

6. アーティファクトに署名する（Phase 4 の署名プリミティブを再利用します。同じ Ed25519 と正規化方式です）：

   • SignedAttributionArtifact の本文を構築します：

     {
       signalId: SIGNAL_ID,
       modelId: SIGNAL.modelId,
       features: TOP_K_FEATURES,             // step 5 から
       graphMetadata: {
         nodeCount: GRAPH.nodes.length,
         edgeCount: COUNT_EDGES,
         pageRankIterations: PR_RESULT.iterations,
         seed: SEED                          // 再現性を担保する重要な値
       },
       generatedAt: NEW_DATE_ISO
     }
     

   • 証人署名キーを解決します。検索順序は Phase 4 と同じです：
     1. RUFLO_WITNESS_KEY_PATH 環境変数 — { "privateKey": "<hex>" } を含む JSON ファイルです。
     2. verification/witness-key.json（ADR-103 のデフォルトパス）。
   • キーが解決された場合：plugins/ruflo-neural-trader/src/signed-attribution.mjs の signAttributionArtifact(body, privateKeyHex) を使用します。
   • どちらのパスでも解決できない場合："[WARN] ruflo-neural-trader: no witness signing key found — storing attribution artifact in UNSIGNED degraded mode. Regulator filings will reject UNSIGNED artifacts." をログに出力し、本文を未署名で保存します。黙ってフォールバックしてはいけません。

7. （署名済み、または未署名の）アーティファクトを、正規の trading-analysis 名前空間（ADR-126 Phase 1）に保存します：

   mcp__plugin_ruflo-core_ruflo__memory_store({
     key: "attribution-SIGNAL_ID-TIMESTAMP",
     namespace: "trading-analysis",
     value: JSON.stringify(signedArtifact)
   })
   

   trading-analysis 名前空間は、モデル分析の出力（レジーム分類、テクニカル指標の要約、モデルのトレーニング結果、そして今回追加されるアトリビューションのランキング）の正規の保存先です。監査証跡が成果物であるため、TTL を設定せず長期保存します。

8. Markdown の要約をエージェントに返します。推奨形式：

   ## Feature attribution for signal `SIGNAL_ID` (model: MODEL_ID)
   
   | Rank | Feature | Score |
   |------|---------|-------|
   | 1    | NAME    | 0.42  |
   | 2    | NAME    | 0.18  |
   | …    | …       | …     |
   
   - PageRank iterations: N
   - Graph: nodeCount nodes, edgeCount edges
   - Seed: 42 (reproducible — same seed → same ordering)
   - Path: mcp | local
   - Signature: ed25519:abcd… (or UNSIGNED — degraded warning above)
   

検証

下流のコンシューマーは、規制当局向けレポートやペーパーからライブへの移行を行う前に、アーティファクトを検証します：

import { verifyAttributionArtifact } from 'plugins/ruflo-neural-trader/src/signed-attribution.mjs';

const ok = await verifyAttributionArtifact(artifact, trustedPublicKey);
if (!ok) {
  // [ERROR] attribution verification failed — refuse to publish.
  // Pin to trustedPublicKey from project config; do NOT trust the
  // artifact.witnessPublicKey field (CWE-347 / #1922 — attacker-controllable).
  return;
}

受け入れ基準（ADR-126 Phase 6）：

• trader-explain <signalId> は、モデルのアテンションの argmax と上位 3 件の特徴量が重複する、特徴量のランキングリストを返します（--explain が利用可能な場合。許容範囲は文書化されています）。
• 再現性：同じ signalId と同じ --seed を指定した 2 回の実行では、バイト単位で同一のランキング順序が生成されます（scripts/smoke-neural-trader-feature-attribution.mjs で検証されます）。
• 署名済みアーティファクトは信頼済み公開鍵で検証できます。任意の特徴量スコアまたは graphMetadata.seed を改ざんすると、署名は無効になります。
• フォールバックパスが正常に動作します：MCP が利用できない場合はローカルカーネルを実行し、--explain フラグがない場合は z-score ヒューリスティックを実行して、アーティファクトにタグを付けます。

参照：

• ADR-126 Phase 6（このスキルの作成に関する ADR）
• ADR-126 Phase 4（再利用する署名方式）
• ADR-123（単一エントリーの PageRank 基盤。Phase 3 がポートフォリオ CG に活用するものと同じ系統です）
• plugins/ruflo-neural-trader/src/signed-attribution.ts（型付きコントラクト）
• plugins/ruflo-neural-trader/src/signed-attribution.mjs（ランタイムミラー）
• scripts/smoke-neural-trader-feature-attribution.mjs（回帰スモークテスト）