veris

Veris

veris — ラテン語で「真実の」

エージェントがファイルを40個変更しました。
実際に何が壊れ、何が検証されたのでしょうか？

---

VerisをVeris自身に使ったところ、55件の欠陥が見つかりました

すべて公開しています。何が壊れ、なぜ問題だったのか、修正内容、そしてそれを証明するテストはこちらです：docs/internal/BUG_TRACKER.md

自社ツールで見つかった、最も深刻な3件をご紹介します。

ベースラインを捏造していました。 gitが使えない場合、Verisは現在のグラフの最初の70%から「変更前」の状態を組み立て、その比較結果を実際の動作差分として報告していました。フラグも警告もありません。検証ツールが、自らの検証対象を捏造していたのです。

呼び出しエッジの91%は推測でした。 呼び出し名の末尾を、同じ名前を持つすべての宣言と照合していました。console.log()から、プロジェクト独自のLogger.logへエッジが引かれていました。実際の依存関係で測定したところ、3,077件中2,804件のエッジが、曖昧な名前を指していました。

評価対象のエージェントは、自分の失敗を消せました。 実行結果はINSERT OR REPLACEで保存されていました。failを送信した後にpassを送信すると、失敗が消えてしまいます。

これらを目立たないように修正することもできました。公開することが重要なのです。何が未検証かを伝えるツールに、自らの未検証の主張を隠す資格はありません。

これ自体がデモでもあります。 Verisが自分自身に対して実行した分析です。

---

Verisとは

AIが書いたコードの動作差分を、Model Context Protocolを通じて提供します。エージェントが作業中に質問でき、レビューで気づいた後に確認する必要はありません。

行差分では答えられない、次の2つの質問に答えます。

1. どのような動作が変わりましたか？ どの行かではなく、どの動作が変わり、何がその動作に到達するかを示します。
2. 実際に検証されましたか？ 公開された研究によると、エージェントが作成したPRの約65%では、変更行が一行もカバレッジされていません。

Verisは何も実行しません。 テストも、サンドボックスも、ランタイムもありません。コードを読み取り、モデル化し、何がリスクにさらされているか、どのような証拠があるかをエージェントに伝えます。実行は、実行を得意とするツールに任せます。

Verisではないもの	その理由
テストランナー	何も実行しません。何を実行する価値があるかをランナーに伝えます。
リンターまたはSASTツール	スタイルや既知の不適切なパターンに関するルールはありません。動作の変化をモデル化します。
「AIガードレール」	これはモデルの出力をフィルタリングするものです。Verisが扱うのは、モデルが書いたコードです。
カバレッジツール	カバレッジは、どの行が実行されたかを示します。Verisは、どの動作が変わり、それを裏付けるものは何かを示します。

## 30秒でわかる概要

$ npx veris-core . --base-ref=origin/main

-> Baseline: origin/main @ 1bebd2ce2e08 -> head 3ed9031421-dirty
   Working tree has 4 uncommitted changes; this run is not reproducible from commits alone.
-> Graph: 326 nodes, 602 edges (head), 131 tracked files
-> Call resolution: 403 resolved (97.1%), 6 single-candidate, 6 ambiguous (no edge emitted)
-> Workflows: 15 detected, 3 affected in diff
-> Adversarial probes generated: 4

2行目と4行目をもう一度読んでください。これが哲学のすべてです。

解決には曖昧すぎる呼び出しが6件あったため、Verisは推測せず、エッジを作成しませんでした。未コミットの変更が含まれているため、HEADには-dirtyが付いており、コミットだけから結果を再現することはできません。

ほとんどのツールは見つかったものだけを報告します。Verisは判断できなかったことも報告します。確信に満ちた誤答より、わからないことを認めるほうがよいからです。

---

インストール

MCP サーバーとして — 設定ブロックを1つ追加して、クライアントを再起動します。

{
  "mcpServers": {
    "veris": {
      "command": "npx",
      "args": ["-y", "veris-core", "mcp"]
    }
  }
}

Claude Code、Cursor、またはMCP互換エージェントで17個のツールが使えるようになります。

CLIとして：

npx veris-core .                            # analyze against origin/main
npx veris-core . --base-ref=HEAD~1          # explicit baseline
npx veris-core . --budget=10 --onboarding   # 10-min plan + onboarding map
npx veris-core doctor                       # check git, base ref, deps

実際の履歴があるgitリポジトリが必要です。 Verisはベース参照とのマージベースを使って差分を取得します。マージベースを確立できない場合、ベースラインを捏造せず、理由を示して処理を失敗させます。CIではfetch-depth: 0を指定してください。

npm 12では、実行履歴のために追加の設定が1行必要です。 npm 12では依存関係のインストールスクリプトがデフォルトで実行されなくなったため、better-sqlite3は事前ビルド済みバインディングを取得しません。Verisは引き続き分析、差分取得、リスク評価、検証計画を行います。必要なのは実行履歴と実行間のドリフト検出だけです。許可リストはプロジェクトごとに設定するもので、依存関係からは継承されないため、ご自身のpackage.jsonに追加する必要があります。

{ "allowScripts": { "better-sqlite3": true } }

次にnpm rebuild better-sqlite3を実行します。veris-core doctorは現在のモードを報告し、永続化が機能していない場合に機能していると偽ることはありません。

---

どのように考えるか

flowchart TD
    A[git-tracked source] -->|ts-morph + TypeScript checker| B[Behavioral graph]
    B -->|worktree at merge-base| C{Baseline exists?}
    C -->|no| X[Fail loudly<br/>never fabricate]
    C -->|yes| D[Diff: added / removed<br/>rewritten-body / edges]
    D --> E[Risk · Workflows · Fingerprints · Drift]
    E --> F[Probes · Tiered plan · Budget]
    F --> G[Coverage from<br/>trust-weighted evidence]
    G --> H[17 MCP tools · Dashboard · Reports]
    H -->|agent or CI executes| I[report_execution]
    I -->|append-only, hash-chained| G

    style X fill:#ff5d6c,stroke:#c1121f,color:#fff
    style G fill:#8b5cf6,stroke:#6d28d9,color:#fff
    style B fill:#0ea5e9,stroke:#0369a1,color:#fff

赤い枠は機能の一つです。カバレッジに戻るループもそうです。

---

他と異なる3つの考え方

1. すべてのエッジが確実性を示す

ほとんどのグラフツールはエッジを示すだけです。Verisは、そのエッジをなぜ信頼しているのかを示します。

resolution	意味
resolved	TypeScriptチェッカーが宣言を特定しました。信頼できます。
heuristic	チェッカーは特定できませんでしたが、その名前を持つ宣言が1つだけあります。
structural	包含関係またはインポート関係です。
(エッジなし)	候補が複数あり、それらを区別できません。推測せず、何も示しません。

推測に基づいて判断してはならないもの（ゲートやポリシールールなど）は、resolvedでフィルタリングします。エッジが欠けていれば結合度は実際より低く示されますが、決して捏造されることはありません。

2. 証拠は追記専用で、誰が報告したかも記録します

結果を投稿するエージェントは、通常、評価される側のエージェントです。そのため：

{ "nodeId": "src/pay.ts::charge",
  "result": "pass",
  "trustClass": "harness-observed",   // ← default is "agent-asserted"
  "producer": "github-actions:e2e" }

信頼クラス	報告者	重み
veris-derived	Verisが算出	完全
harness-observed	外部ランナーが観測	完全
agent-asserted	エージェントの申告 — デフォルト	半分

記録はハッシュチェーンで連結されています。後続の処理で以前の失敗が上書きされることはありません。データベースを直接編集するとチェーンが壊れ、verifyEvidenceChain()が該当箇所を正確に報告します。エージェントは、強く主張するだけで自らの保証レベルを高めることはできません。

3. 名前はそのままに書き換えられたコードを検出します

- function chargeCard(amount) { return gateway.charge(amount); }
+ function chargeCard(amount) { return gateway.charge(amount * 100); }

名前は同じ。呼び出し先も同じ。グラフの形も同じです。名前とトポロジーを比較するだけでは何も見つかりません。Verisは正規化した本体をハッシュ化するため、これはmodifiedNodeとして検出されます。一方、以前はドリフト率100％に見えていたディレクトリ名の変更は、今では正しく差分なしとして扱われます。

---

エージェントが尋ねること

veris: analyze_pr_behavior with baseRef=origin/main
veris: list_workflows, then analyze_workflow for the highest-risk one
veris: generate_adversarial_probes, then allocate_budget minutes=15
veris: detect_drift
veris: what_if_revert nodeIds=[...]

プローブは具体的なテストであり、単なる促しではありません。

決済／冪等性 — 同じ冪等性キーを使って、500 ms以内に請求を2回送信します。 不変条件： 台帳エントリーは1件だけで、2回目の呼び出しは最初の結果を返します。

---

Webhook／リプレイ — 24時間前の署名済みペイロードを、元の署名を付けて再送します。 不変条件： 署名が有効でも、タイムスタンプの許容範囲外のため拒否されます。

そのほかの機能

セマンティックなワークフロー	25 のドメイン — 認証、決済、チェックアウト、Webhook、キュー、キャッシュなど。つまり、単位は GraphModels.ts ではなく、「チェックアウトの信頼性」です。
リスクモデル	結合の大きさ、被結合の優位性、実行時の重要度 — 異なるものを測定する 3 つの入力です。すべての重みは data/risk-config.json に記載され、理由も平易な言葉で添えられています。
ドリフト検出	実行ごとのフィンガープリントです。気づかれない書き換え、表層的な変更、振動するリファクタリング、削除を検出します。
予算の割り当て	N 分が与えられた場合、実際に実行すべき、最も効果の高いサブセットを選びます。
反実仮想	what_if_revert — これを取り除くと、何が回復しますか？
オンボーディング用エクスポート	コードベースに不慣れな新しいエンジニアや新しいエージェント向けに、ワークフローを優先した Markdown を出力します。
ダッシュボード	スタンドアロンの HTML です。ワークフローをクリックすると、すべてが絞り込まれます。クリックしてディレクティブをコピーできます。

---

正直な制限事項

誰も後から困ることのないよう、率直に説明します。

• ワークフローはラベルであり、パスではありません。 ディレクトリ名、インポート、シンボル名に対する重み付きキーワード投票で分類します。呼び出しグラフはたどりません。Redis をインポートするレート制限コードは、キャッシュに分類されます。ワークフローを実際のパスにすることが、ロードマップの最優先事項です。
• カバレッジは保証ではありません。 計画された検証のうち、どの程度がエビデンスに裏付けられているかを測定します。実際のインシデントに照らして調整されておらず、コードが正しい確率を推定するものでもありません。
• リスクはヒューリスティックです。 最初に確認すべき対象の順位付けには有用ですが、欠陥を予測するものではありません。裏付けとなる正解データはありません。
• プローブは厳選されたライブラリです — 実際の障害モードを手作業で記述し、ドメインごとに選定しています。コードから生成されるものではありません。
• 対応言語は TypeScript と JavaScript のみです。 Python と Go はロードマップに含まれています。
• 解決できない呼び出しもあります。 動的ディスパッチと型付けされていない JS はチェッカーで処理できません。その場合、エッジは生成されず、その件数は出力に含まれます。

2.x からアップグレードしますか？ 3.0 には実際の破壊的変更があります。詳しくは UPGRADING.md をご覧ください。

---

プライバシーとセキュリティ

• ローカルファーストです。 すべての分析はお使いのマシン上で実行されます。テレメトリーは一切ありません。 コードに関する情報がマシンの外部に送信されることはありません。
• ゼロ保持モード — VERIS_STATE_DISABLED=1。
• アナライザーにネットワークソケットはありません。 stdio とファイルシステムのみを使用します。

Veris は通常、作成者ではないリポジトリに対して実行されるため、リポジトリの内容は信頼できない入力として扱います。プラグインは分析対象のリポジトリのコードを実行するため、デフォルトでは無効です — --allow-plugins で有効にすると、実行前に各プラグインのパスと SHA-256 が表示されます。サンドボックスはなく、SECURITY.md ではその点を曖昧にせず明記しています。

---

ドキュメント

MCP ツール	推奨フローと、全 17 種類のツール
アーキテクチャ	設計上の不変条件と、それぞれが置き換えた欠陥
監査トラッカー	エビデンス付きの全 55 件の指摘
アップグレード	2.x → 3.0
セキュリティ	脅威モデルと報告方法
ロードマップ	次に予定されていること — そして決して開発しないもの
プラグイン	分類とリスクの拡張

---

コントリビューション

特に大きな効果があるのは、次の5つです。

1. ご存じのフレームワークのエントリーポイント検出 — ルート、ハンドラー、キューのコンシューマーです。これによって、ワークフローは単なるラベルではなく、経路になります。
2. 分類ベンチマーク用のラベル付きリポジトリ。精度を主張するには、ルールを増やすのではなく、正解データが必要です。
3. プローブの出典。同梱のプローブは優れていますが、出典が明記されていません。公開された事後分析に裏付けられたもの1つは、そうでないもの10個分の価値があります。
4. 言語アダプター — Python、Go。
5. キャリブレーションデータ — Veris が検出して実際に問題となったものと、見逃したものです。後者のほうが価値があります。

CONTRIBUTING.mdをご覧ください。オープンソースで、スポンサーの支援を受けています。有料プランも、制限付き機能も、オープンコアを装った誘いもありません。

_{MIT — LICENSEをご覧ください}