feat(terrain): index surface queries with bvh

1 files changed, 21 insertions, 0 deletions

diff --git a/docs/tomes/04-world.md b/docs/tomes/04-world.md
index 82d9e47..9961a49 100644
--- a/docs/tomes/04-world.md
+++ b/docs/tomes/04-world.md
@@ -555,6 +555,27 @@ candidate areas, затем выполняется точная геометри
 Если область не найдена, caller получает явный miss и решает, допустим ли
 fallback к ближайшей области.
 
+### Индекс поверхности
+
+`TerrainWorld` хранит отдельный deterministic BVH по валидированным
+`TerrainFace28` triangles. Он не заменяет `Land.map` grid: BVH отвечает за
+низкоуровневые surface queries (`height_at` и `raycast`), тогда как grid и
+areal graph остаются навигационным контрактом.
+
+При построении индекс делит triangles по centroid вдоль самой протяжённой оси;
+в leaf остаётся не более восьми face indices. XY query проходит только листья,
+чьи AABB покрывают точку, а raycast — только AABB, пересечённые лучом. После
+выбора кандидатов raycast сортирует их по исходному face index, поэтому при
+равной дистанции сохраняется прежний deterministic tie-break; `height_at`
+по-прежнему выбирает максимальную высоту среди действительно покрывающих
+точку triangles. Индекс меняет стоимость запроса, но не геометрическую
+семантику.
+
+Synthetic test проверяет сокращение candidate set и прежние height/raycast
+results. Licensed run проходит все 33 `Land.msh` Части 1 и 32 файла Части 2:
+для каждого mesh с числом faces выше leaf limit query у центра первого face
+включает этот face и использует меньше кандидатов, чем полный mesh.
+
 ### Маршрут
 
 После определения начальной и целевой областей маршрут строится по графу