2026-07-28 Source Flow Debugger 実際ソース検索報告書

目的

既存の記録には実際の Godot プロジェクトを 134 個のチャンクに分割して検索し、関連文書が上位結果に含まれていたとだけ書かれていた。この表現だけでは各チャンクで何が返されたのか、返された JSONL が SQLite に実際に存在するのか、より直接的な文書が SQLite にあるのに検索順位で埋もれたのかが分からなかった。

本報告では次の三つの質問を分けて記録する。

1. Source Flow Debugger がチャンクごとにどの JSONL 候補を返したか？
2. 返された候補がコミットされた SQLite の検証済み原文 JSONL と正確に同じか？
3. SQLite 全体で確認した直接根拠が上位に来ているか、あるいは順位改善が必要か？

Qwen エンドポイントは停止中のため、今回は検索と SQLite 照合のみを実行した。Qwen の Godot バージョン分類と候補承認・却下結果は記録せず、検索候補が出たという事実を最終検証成功とはみなさない。

固定入力

• リポジトリ: godotengine/godot-demo-projects
• ライセンス: MIT
• コミット: cae8dc567a56d3e7936f171bcb85f0ccb9634ad0
• プロジェクト: 2d/hexagonal_map
• 入力ファイル: project.godot, map.tscn, tileset.tres, tileset_edit.tscn, troll.gd, troll.tscn
• 入力ファイル数: 6
• 生成チャンク数: 134
• AST チャンク: 3
• 直接チャンク: 131

実行に使用した SQLite は outputs/godot-rag-sqlite/godot-rag.sqlite3 で、実行時に docs_chunks 2,265 件、api_mapping 1,133 件、 label_prototypes 2 件と embedding 3,399 件を含んでいた。

実行状態

段階	状態	今回の実行の意味
SQLite FTS5 + Okapi BM25	実行	134 個チャンクすべて検索した
embedding	未実行	クエリ embedding API キーを設定していない
reranker	未実行	provider API キーを設定していない
Qwen validator	未実行	Qwen エンドポイントが停止中

したがって以下の順位は全体 F 戦略の最終順位ではなく lexical/BM25 段階の結果である。

全体照合結果

項目	結果
チャンク	134
チャンクごとに返された BM25 候補	80
SQLite と照合した返却候補	10,720
重複を除いた候補	844
SQLite で見つからない候補	0
provenance が verified でない候補	0
返却 raw_json と SQLite 原文が異なる候補	0
docs_chunks 返却	10,713
api_mapping 返却	7
label_prototypes 返却	0

返却データの整合性は合っていた。Source Flow Debugger が示したテーブルと ID を SQLite で再検索したところ、10,720 件すべてが存在し、provenance が verified であり、返却されたレコードと保存された raw_json も同じだった。

しかし検索品質まで全部合っていたという意味ではない。134 個のチャンクがすべて候補上限の 80 件を埋めているため、lexical 候補が十分に絞り込まれない状態だ。またファイル名アンカー保護により BM25 スコアが低い文書が 1 位に昇格したチャンクが 9 件あった。

代表チャンク結果

よく検索された事例

チャンク	入力要約	返却結果	SQLite 照合
1	project.godot ファイル形式説明	Manually editing project.godot 1 位	同じ ID と原文を確認
13	TileMapLayer, tile_map_data, TileSet	TileMapLayer 属性 1 位、メソッド 2 位、TileData 3 位	すべて検証済み docs_chunks
42	TileSetAtlasSource, texture region	TileSetAtlasSource 1 位、TileSetSource 2 位	直接クラス根拠を確認
125	_physics_process, Input.get_axis, move_and_slide	Physics process 1 位、2D movement 文書 5~7 位、CharacterBody2D 8 位	移動・物理関連文書が共に存在
130	CharacterBody2D ノード	CharacterBody2D クラス 1 位	直接クラス根拠を確認

チャンク 1 の 1 位文書は BM25 スコアだけで 1 位になったのではなく、project.godot lexical アンカー保護により維持された。この場合ファイル形式説明と直接合致するため、保護が有効だった。

ランキング改善が必要なケース

チャンク 123: extends CharacterBody2D

• 実際 1位: Collision exceptions
• CharacterBody2D クラス文書: 17位
• KinematicBody2D -> CharacterBody2D マッピング: 6位

SQLite には正確な CharacterBody2D クラス文書があったが、広い衝突・移動 文書より後に配置された。データ欠如ではなくランキングの問題だ。短い宣言 チャンクでは完全に一致するクラス名と構造フィールドを一般的な文脈トークンよりも 強く扱う必要がある。

チャンク 124: tan(deg_to_rad(30))

• 実際 1位: Setting up the spring arm and camera
• Evaluating expressions: 2位と 3位

1位の文書にも deg_to_rad の使用例があり全く無関係ではないが、呼び出し 自体を説明する文書より 3D チュートリアルが先行した。直接 API 説明と単純使用 例を区別する再配置が必要である。

Qwen 再検証が必要な構造候補

チャンク 13: PackedByteArray が含まれる map.tscn

PackedByteArray -> byte[] マッピングが 48位に入った。保存された JSONL は C# コレクション マイグレーションを説明しているが、入力は GDScript シーンリソースだ。トークンは一致するが 言語と適用文脈が異なるため、検索段階で最終承認してはならない。

チャンク 130: すでに CharacterBody2D を使用しているノード

KinematicBody2D -> CharacterBody2D マッピングが 3位に入った。このマッピングは バージョン判別には関係があるが、現在のチャンクには旧 API の KinematicBody2D が 存在しない。マイグレーション警告として承認すべき候補ではなく、Qwen が JSONL と元のチャンクを 共に見て Godot 4 根拠または適用不要として分類すべきである。

両ケースの SQLite JSONL 原文は機械読取レポートの reviewCases にそのまま 保存した。

label_prototypes が 0 件である理由

SQLite のプロトタイプは次の 2 件だけである。

• enum PlaneSemanticLabel
• class OpenXRSpatialComponentPlaneSemanticLabelList

hexagonal_map チャンクにはこの 2 つの入力パターンがなかった。したがって今回の実行で label_prototypes が 0 件であるのは欠落ではなく、直接構造根拠フィルタが作動した結果と判断した。

現在の結論

• 返却候補と SQLite 原文間のデータ整合性は確認された。
• 代表的なプロジェクト設定、TileSet、TileMapLayer、移動関数検索は直接 関連文書を上位に含めた。
• すべてのチャンクが候補上限 80 件を埋めているため、候補削減は十分でない。
• 短いクラス宣言と単一関数呼び出しでは、より直接的な文書が後方に押しやられるケースが確認された。
• 構造マッピングは関連トークンだけで候補に入る可能性があるため、Qwen がオフの状態で 承認可否を結論付けることはできない。

次回再実行基準

Qwen エンドポイントが再び利用可能になったら同じコミットと同じ 134 件のチャンクを使用して 次の項目を追加する。

1. 各構造候補の Godot 3、Godot 4、関連なし、根拠不足 分類
2. PackedByteArray -> byte[] のような言語文脈不一致候補の却下可否
3. すでに target API を使用しているチャンクで migration 適用候補を却下するか
4. 関連性のない negative control JSONL の却下可否
5. embedding と reranker 適用前後の直接文書ランキング変化

2026-08-01 F 戦略と Qwen 再検証

同じ外部リポジトリのコミットと 2d/hexagonal_map 原本 6 ファイルを Source Flow Debugger GUI に再度投入した。最新のチャンク基準では全体で 146 件のチャンクが生成された。BM25、embedding、union、reranker を順に 実行した全検索監査で 146 件すべてが完了し、SQLite で欠落した返却レコード、検証されていない provenance、原文と異なる JSONL は存在しなかった。

実際のファイル	チャンク	確認範囲
project.godot	20	全体ハイブリッド検索、全体 Qwen 検証、失敗チャンク個別再検証
map.tscn	6	全体ハイブリッド検索と Qwen 検証
tileset.tres	54	全体検索監査、atlas source と最終リソース代表検証
tileset_edit.tscn	54	全体検索監査、ルートノードと sprite ノード代表検証
troll.gd	3	全体ハイブリッド検索と Qwen 検証
troll.tscn	9	全体ハイブリッド検索と Qwen 検証

検索と検証を分けてみた結果

• CharacterBody2D 宣言とノードはクラス文書と KinematicBody2D -> CharacterBody2D マッピングを返した。Qwen はターゲット API と実際のチャンクが一致するマッピングのみをバージョン根拠として採用し Godot 4 と判定した。
• PackedScene、Node2D、Sprite2D、TileSetAtlasSource などは関連クラス 文書を正常に返したが、該当文書がコードのメジャーバージョン 排他性を証明しないため 根拠不足 のままだった。
• run/main_scene 設定は Setting the main scene 文書と SQLite 原文が 直接一致した。自然言語説明が設定表記をそのまま繰り返さなかったため 初回検証で却下されたが、構造化キーの値と役割を文書が直接説明すれば 関連根拠として扱うよう検証規則を補完した。
• doc_version または godot_version_tags は文書収集バージョンでありコードの バージョン排他性を自動的に証明しない。JSONL 本文がメジャーバージョン 差を直接説明する場合のみバージョンを確定するよう検証規則を補完した。

SQLite 全体対照で確認したデータ空白

次の表現は GUI 上位候補が不正確で SQLite の docs_chunks、 api_mapping、label_prototypes 全体 raw_json を再検索した結果である。正確な 表現を含むレコードはすべて 0 件だった。

• scene resource header
• script external resource declaration
• project format version setting
• untyped declaration warning setting
• window stretch aspect setting
• default clear color setting

これらのケースは正しい JSONL が SQLite に存在するが検索が見逃したのではなく、 現在収集された JSONL に直接根拠がない状態である。したがって検証器が 関連なし を返すことを任意に Godot 3 または Godot 4 に変更しなかった。

検証規則の修正はコミット d504f50、2222634 に分けて反映し、 Source Flow Debugger テスト 33 件をすべて通過した。規則に特定のコード 文法、API 名、設定キーを一覧として入れなかった。

成果物

• 134個のチャンクごとの上位10件の検索結果とSQLite比較記録
• Source Flow Retrieval Reports 形式