Vector Forge

ミューテーション テスト を使用してテストベクトル カバレッジのギャップを体系的に特定し、その後、それらのギャップを埋める新しいテストベクトルを生成します。ミューテーション キル率の前後を比較して有効性を測定します。

使用時

• 暗号アルゴリズムまたはプロトコルのテストベクトルを生成する場合
• 既存のテストベクトルが実装をいかによくカバーしているかを評価する場合
• テストベクトルが実行しない実装のコードパスを見つける場合
• Wycheproof スタイルのクロス実装テストベクトルを作成する場合
• テストベクトル スイートの具体的なカバレッジ値を測定する場合

使用しない時

• 実装がまだ存在しない場合（変更するコードが必要）
• エッジケースのない単一の簡単な実装
• アルゴリズム実装ではなく、アプリケーションロジックをテストする場合
• アルゴリズムに比較用のパブリック テストベクトルがない場合

前提条件

• trailmark がインストールされている — uv run trailmark が失敗する場合は、次を実行してください：

  uv pip install trailmark
  

• ミューテーション テスト をサポートする言語で、対象アルゴリズムの実装が少なくとも1つ
• テストベクトルを使用して実装を実行するテスト ハーネス
• 対象言語用のミューテーション テスト フレームワーク

---

却下すべき正当化

正当化	問題点	必要なアクション
「十分なテストベクトルがある」	ミューテーション テスト がそれを否定する	ベースラインを最初に実行する
「実装自体のテストで十分である」	独自のテストは実装と盲点を共有することが多い	クロス実装ベクトルは異なるバグを検出
「FFI クレートはバインディングレイヤーでミューテーション テスト できる」	ラッパーへの変更は基礎となる実装に影響しない	実装の実際の言語を変更する
「タイムアウトはミューテーションが検出されたことを意味する」	タイムアウトはあいまいである — キルされているか生存しているか不確定	結論を引き出す前にタイムアウトを解決する
「すべてのミューテーションは同等である」	ほとんどはそうではない — ミューテーションを読むことで検証する	エスケープされたミューテーションを個別に分類する
「有効なベクトルをチェックするだけで十分である」	許容的なミューテーションは負の表明なしで生存する	すべての無効なベクトルに対して拒否を表明する
「手動分析で十分である」	手動分析はツーリングが検出するものを見落とす	ツールをインストールして実行する

---

ワークフロー概要

フェーズ 1: 発見         → テストする実装を検出
      ↓
フェーズ 2: ハーネス     → 各実装のテストベクトル ハーネスを記述/適応
      ↓
フェーズ 3: ベースライン → 既存ベクトルでミューテーション テスト を実行
      ↓
フェーズ 4: エスケープ分析 → エスケープされたミューテーションをコードパスで分類
      ↓
フェーズ 5: ベクトル生成 → エスケープをターゲットにした新しいテストベクトルを作成
      ↓
フェーズ 6: 検証        → ミューテーション テスト を再実行、前後を比較
      ↓
出力: カバレッジ レポート + 新しいテストベクトル

---

フェーズ 1: 発見

対象アルゴリズムの実装を見つけます。以下を探してください：

1. 純粋な実装 高レベル言語（Go、Rust、Python） — これらはミューテーション テスト の最高のターゲット
2. FFI ラッパー クレート — ラッパーグルーコードの変更に時間を無駄にしないよう早期に特定
3. 参照実装 — クロス検証に有用ですが、最高のミューテーション テスト ターゲットではない場合があります

各実装について、以下をメモします：

• 言語とミューテーション テスト フレームワーク
• 純粋なコードか FFI ラッパーか
• 既存のテスト スイートのサイズとカバレッジ
• テストベクトルがどの API サーフェスを実行するか

実装タイプの分類

タイプ	ミューテーション価値	例
純粋実装	高	zkcrypto/bls12_381（Rust）、gnark-crypto（Go）
C/asm への FFI バインディング	バインディングレイヤーで低	blst Rust クレート
C/C++ 実装	高（Mull を使用）	blst C ライブラリ
生成されたコード	中（ミューテーションは同等の場合あり）	gnark-crypto 生成フィールド演算

重要な洞察： 実装が FFI 経由で別の言語にデリゲートする場合、バインディングではなく基礎となる実装を変更する必要があります。Rust/Go/Python の下の C/C++ の場合は、Mull またはそれに類するツールを使用してください。

---

フェーズ 2: ハーネス

各実装について、以下を行うテスト ハーネスを作成します：

1. JSON ファイル（Wycheproof 形式推奨）からテストベクトルを読み込む
2. 各ベクトルに対して実装の API を実行する
3. 承認と拒否の両方をアサートする：
   • 有効なベクトル：逆シリアル化が成功、出力が期待値と一致
   • 無効なベクトル：逆シリアル化が失敗、または検証が拒否
4. 有効な逆シリアル化ベクトルのラウンドトリップ アサーションを追加： serialize(deserialize(bytes)) == bytes
5. テスト ID でベクトルごとのパス/失敗を報告する

重要： 有効なベクトルのみをチェックするハーネスは、すべての許容的なミューテーション（例：検証内の & → |）を見落とします。references/lessons-learned.md §7 を参照してください。

ハーネスはミューテーション テスト フレームワークで実行可能である必要があります。ほとんどのフレームワークでは、これは次を意味します：

• Go： 実装と同じパッケージ内の _test.go ファイル
• Rust： tests/ 内の統合テスト、または インラインの #[test] 関数
• Python： pytest テストファイル
• C/C++： 実装にリンクされたテストバイナリ

ハーネスの配置

ハーネスはミューテーション フレームワークが見えるように実装パッケージ内に存在する必要があります。通常は：

# Go: テストパッケージに追加
cp wycheproof_test.go /path/to/impl/package/

# Rust: 統合テストを追加
cp wycheproof.rs /path/to/crate/tests/

# Python: テストディレクトリにテストを追加
cp test_wycheproof.py /path/to/package/tests/

既存ベクトルの処理

実装がすでにテストベクトルを持っている場合：

1. 既存ベクトルのみでミューテーション テスト を実行（ベースライン）
2. 新しいベクトルのみでミューテーション テスト を実行
3. 両方を組み合わせてミューテーション テスト を実行
4. (1) と (3) の差は新しいベクトルの価値を示す

---

フェーズ 3: ベースライン

既存のテストベクトルのみでミューテーション テスト を実行します。

フレームワークの選択

言語別のセットアップについては references/mutation-frameworks.md を参照してください。

言語	フレームワーク	コマンド
Go	gremlins	gremlins unleash ./path/to/package
Rust	cargo-mutants	cargo mutants -j N --timeout T
Python	mutmut	mutmut run --paths-to-mutate src/
C/C++	Mull	mull-runner -test-framework=GoogleTest binary

並列実行

大規模なコードベースの場合は常に並列実行を使用してください：

• cargo mutants -j 8（Rust、8つの並列ワーカー）
• gremlins unleash --timeout-coefficient 3（Go、タイムアウトを増加）
• mutmut run --runner "pytest -x -q"（Python、失敗時は停止）

ベースライン結果の記録

実装ごとに次のメトリクスをキャプチャしてください：

メトリクス	説明
総ミューテーション	生成されたミューテーション数
キルされた	テストにより検出されたミューテーション
生存/生活	テストで検出されなかったミューテーション（これがターゲット）
カバーされていない	テストがまったく到達しないコードパス
タイムアウト	あいまい — 比較する前に解決する
有効率 %	キルされた / (キルされた + 生存)
カバレッジ %	(合計 - カバーされていない) / 合計

フェーズ 4 の分析のために完全なミューテーション ログを保存します。

---

フェーズ 4: エスケープ分析（グラフ情報トリアージ）

到達可能性とブラスト半径分析のため、Trailmark コールグラフを使用してエスケープされた（生存 + カバーされていない）ミューテーションを分類します。

このフェーズは必ず genotoxic スキルのトリアージ方法論を使用する必要があります。 コールグラフはミューテーション結果を、生存ミューテーションのフラットリストから、アクション可能でプライオリティ化されたベクトル ターゲットのセットに変換します。

ステップ 1: コールグラフを構築

トリアージミューテーションの前に、各実装に対して Trailmark コードグラフを構築してください：

# Go
uv run trailmark analyze --language go --summary {targetDir}

# Rust
uv run trailmark analyze --language rust --summary {targetDir}

グラフは以下を提供します：

• 呼び出し元チェーン — パブリック API エントリポイントからミューテーション関数まで追跡して、到達可能性を判定
• 環状複雑度 — 高 CC 関数に優先順位をつける
• ブラスト半径 — 多くの呼び出し元を持つ関数は、ミューテーションが生存する場合の影響が広い

ステップ 2: 関連コードにフィルタ

ミューテーション フレームワークはパッケージ全体をテストします。テストベクトルが実行すべきファイル/関数のみに結果をフィルタしてください：

# Go（gremlins）
grep -E "(LIVED|NOT COVERED)" baseline.log \
  | grep -E " at (relevant|files)" \
  | sort

# Rust（cargo-mutants）
cat mutants.out/missed.txt | grep "src/relevant"

ステップ 3: グラフ情報トリアージ

エスケープされたミューテーションごとに、それを含む関数をコールグラフにマップし、genotoxic トリアージ基準を適用してください：

グラフシグナル	分類	アクション
グラフに呼び出し元がない	偽陽性	デッドコード、スキップ
テスト呼び出し元のみ	偽陽性	テストインフラ
ログ/表示/フォーマット	偽陽性	コスメティック
クロスパッケージ呼び出し元ただしカバーされていない	クロスパッケージ ギャップ	以下を参照
パブリック API から到達可能、低 CC	欠落ベクトル	ターゲット化されたベクトルを設計
パブリック API から到達可能、高 CC（>10）	ファジング ターゲット	ベクトル + ファジング ハーネスの両方
検証/エラーハンドリング パス	負ベクトル	パスをトリガーする無効な入力を作成
最適化パス（GLV、SIMD、バッチ）	エッジケース ベクトル	最適化閾値をトリガーする入力
左シフト後の |→^（例：(t<<1) | carry）	同等ミューテーション	スキップ — ビット 0 は常に 0、OR=XOR
Montgomery リム上の ct_eq &→|	API 到達不可	ライブラリ内部テストが必要、ベクトルではない
同等ミューテーション（動作変更なし）	偽陽性	スキップ

ステップ 4: クロスパッケージ テスト ギャップを特定

重大な落とし穴： ミューテーション フレームワークはしばしば、ミューテーションと同じパッケージ内のテストのみを実行します。Go（gremlins）と Rust（cargo-mutants）では、これは次を意味します：

• hash_to_curve/g2.go 内のミューテーションは、hash_to_curve パッケージ内のテストのみを実行、それをインポートする親 bls12381 パッケージのテストは実行しない
• クロスパッケージ テストによって完全に実行される関数は、カバーされていないと表示される — これらは偽陽性
• 確認するには：ミューテーション関数が、実行されない異なるパッケージのテストから呼び出されているかをチェック

クロスパッケージ ギャップを解決するには：

1. サブパッケージに薄いテストを追加し、クロスパッケージ テストと同じコードパスを呼び出す
2. または gremlins を --test-pkg ./... で実行（サポートされている場合）
3. または、フレームワーク制限としてレポートで文書化

ステップ 5: セキュリティ インパクトで優先順位付け

コールグラフを使用してサバイビング ミューテーションをインパクト別にランク付けしてください：

優先度	基準	例
P0 — 重大	ミューテーション が検証/等式/認証を弱体化	ct_eq: & → | で等式が許容的に
P1 — 高	逆シリアル化フラグ解析内のミューテーション	from_compressed: & → | で無効フラグを承認
P2 — 中	フィールド演算内部内のミューテーション	Fp::square: | → ^ で計算を破損
P3 — 低	最適化パス内のミューテーション	phi エンドモルフィズム：パフォーマンスパスのみに影響
スキップ	フォーマット、表示、同等ミューテーション	Debug::fmt 戻り値置換

ステップ 6: ベクトル戦略でグループ化

エスケープされたミューテーションを、それが表すコードパスと必要なテスト ベクトルのタイプでグループ化してください：

逆シリアル化フラグ検証（P1）:
  - g1.rs:339,363-365,384 — from_compressed_unchecked フラグ
  → 必要：有効なポイント間違ったフラグ ベクトル

フィールド演算（P2）:
  - fp.rs:371-376,406,635-643 — subtract_p、neg、square
  → 必要：エッジケース値での フィールド演算 KAT

最適化閾値（P3）:
  - g1.go:68、g2.go:75 — GLV vs 窓化乗算
  → 必要：大きなスカラーでの スカラー乗算

クロスパッケージ（フレームワーク制限）:
  - hash_to_curve/g2.go:242-278 — isogeny、sgn0
  → 偽陽性として文書化、またはサブパッケージ テストを追加

各グループはフェーズ 5 で新しいテストベクトルのターゲットになります。

---

フェーズ 5: ベクトル生成

エスケープされたコードパス グループごとに、そのパスを通る実行を強制するテストベクトルを設計してください。

ベクトル設計パターン

コードパス タイプ	ベクトル戦略
ポイント逆シリアル化	不正なポイント：長さ間違い、無効なフィールド要素、オフカーブ、間違ったサブグループ、アイデンティティ ポイント
署名検証	有効な署名 + 署名、pk、msg のすべての単一ビット破損
Hash-to-curve	既知の回答テスト（KAT）エッジケース入力付き：空、単一バイト、最大長
集約操作	1 署名者、多くの署名者、重複署名者、有効/無効混合
エラー処理	すべてのエラーパスはそれをトリガーするベクトルを持つべき
演算エッジケース	ゼロ、1、フィールド モジュラス - 1、無限遠点
シリアル化フラグ	有効なすべてのフラグ組み合わせ + 無効なすべてのフラグ組み合わせ
ラウンドトリップ整合性	すべての有効な逆シリアル化ベクトルについて、serialize(deserialize(b)) == b をアサート
キャリー/削減障害	リデュース リム幅で再実装、障害を注入、区別入力を抽出

単一障害ネガティブ ベクトル

各ネガティブ ベクトルは正確に 1 つの障害を持ち、その他はすべて有効である必要があります — これは、テストされている検証チェックを分離します。フラグごとの構成例については references/vector-patterns.md を参照してください。

障害シミュレーション（リム幅削減再実装）

ミューテーション テスト がローカル演算子スワップのみを適用する場合、より深いアーキテクチャバグ（キャリー伝播、削減オーバーフロー）がテストされずに残ります。このギャップを埋めるため、リデュース リム幅（8、16、25、32 ビット）でターゲット アルゴリズムを再実装し、意図的に障害を注入してください — その後、それらをキャッチするベクトルを生成します。

完全な方法論については references/fault-simulation.md を参照してください：リム幅選択、障害注入カタログ、ベクトル抽出、検証ワークフロー。

クロスインプリメンテーション検証

新しいテスト ベクトルはすべて、スイートに追加される前に少なくとも 2 つの独立した実装に対して検証される必要があります：

1. 実装 A を使用してベクトルを生成
2. 実装 B で検証（異なるコードベース、理想的には異なる言語）
3. B が同意しない場合は、調査してください — 1 つの実装にバグがあります

ベクトル フォーマット

Wycheproof JSON 形式（algorithm、testGroups[].tests[]、tcId、comment、result、flags付き）を使用してください。完全なスキーマについては references/vector-patterns.md を参照してください。

JSON エンコーディング： Wycheproof は reformat_json.py でベクトルを正規化し、HTML エンティティを非エスケープします。HTML エスケープシーケンスではなく、リテラル文字でベクトルを生成してください：

• Go： json.NewEncoder + enc.SetEscapeHTML(false) を使用 — json.Marshal/json.MarshalIndent は決して使用しないこと（暗黙的に > → \u003e、< → \u003c、& → \u0026 にエスケープ）
• Python： json.dumps はデフォルトで安全
• Node.js： JSON.stringify はデフォルトで安全

詳細については references/lessons-learned.md §14 を参照してください。

---

フェーズ 6: 検証

新しいテストベクトルを含めて、ミューテーション テスト を再実行します。

ヒント： ベクトル開発中の高速イテレーションにはファイルごとのミューテーション テスト を使用してください（references/lessons-learned.md §12 を参照）。最終比較のためだけに完全なクレート テストを実行してください。

前後の比較

メトリクス	ベースライン	新しいベクトル付き	デルタ
キルされた	X	Y	Y - X
生存	A	B	A - B（減少すべき）
カバーされていない	C	D	C - D（減少すべき）
有効率 %	E%	F%	F - E

成功基準

ベクトルは遡及的な価値（既存コード内のミューテーションをキル）と先制的な価値（将来の実装でバグをキャッチ）の両方を持ちます。両方の種類を生成してください — 境界条件ベクトルは成熟したライブラリでキル率を改善しないかもしれませんが、新しい実装のバグをキャッチします。どのケースが適用されるかについては references/lessons-learned.md §13 を参照してください。

遡及的（測定可能）： 以前に生存/カバーされていなかったミューテーション がキルされる、回帰がない。

キル率が変わらない場合： 実装自体のテストは可能性としてそれらのパスをすでにカバーしています。ベクトルはまだクロスインプリメンテーション検証値を追加します。どのケースが適用されるかを文書化してください。

---

出力フォーマット

VECTOR_FORGE_REPORT.md を作成して：対象アルゴリズム、テストされた実装、ベースライン結果、エスケープ分析、生成されたベクトル、後の結果、前後デルタ、結論をカバーしてください。完全なテンプレートについては references/report-template.md を参照してください。

---

品質チェックリスト

提供する前に確認してください：

• 少なくとも 1 つの純粋実装がミューテーション テスト 済み（FFI ラッパーのみではない）
• 既存ベクトルでベースライン実行が完了
• 各実装に対して Trailmark コールグラフが構築済み
• すべてのエスケープされたミューテーション がグラフ情報分類を使用してトリアージ済み
• クロスパッケージ 偽陽性が特定され文書化済み
• セキュリティ重大ミューテーション（ct_eq、検証、認証）が P0/P1 として優先順位付け済み
• 障害シミュレーション と ミューテーション派生ベクトルがクロス検証済み（2+ 実装）
• 新しいベクトルを含めて実行後が完了
• 前後デルタが計算され説明済み
• レポートが VECTOR_FORGE_REPORT.md に記述済み
• 新しいテストベクトルが標準フォーマット（Wycheproof JSON）で保存済み

---

統合

スキル	関係
genotoxic（フェーズ 4 に必須）	グラフ情報トリアージを提供 — コールグラフはアクション可能ミューテーション を 30～50% カット
mutation-testing（mewt/muton）	Solidity に使用；Vector Forge は言語に依存しない
property-based-testing	フィールド演算内のビット単位ミューテーション には手作業ベクトルより優れている
testing-handbook-skills（ファジング）	CC > 10 で生存ミューテーションを持つ関数はベクトル + ファジング ハーネスの両方が必要

---

サポートドキュメント

• references/mutation-frameworks.md - 言語別ミューテーション テスト フレームワークセットアップ
• references/vector-patterns.md - 暗号プリミティブの一般的なテストベクトル パターン
• references/fault-simulation.md - キャリー、削減、オーバーフロー障害のためのリム幅再実装
• references/report-template.md - Vector Forge レポートの完全な Markdown テンプレート
• references/lessons-learned.md - BLS12-381 ケース スタディ：FFI キル率、タイムアウト マスキング、クロスパッケージ 偽陽性、ビット単位ミューテーション ギャップ、セキュリティ重大優先度