From 2474e480200a8dfa260a069730c19c4bb2cbdf8e Mon Sep 17 00:00:00 2001
From: Valentin Popov <valentin@popov.link>
Date: Sat, 18 Jul 2026 13:24:00 +0400
Subject: [PATCH] feat(runtime): trace visual graph sizes

---
 apps/fparkan-game/src/main.rs     |  8 +++++--
 crates/fparkan-assets/src/lib.rs  | 26 +++++++++++++++++++++
 crates/fparkan-runtime/src/lib.rs | 38 ++++++++++++++++++++++++-------
 docs/tomes/05-render.md           |  7 ++++++
 4 files changed, 69 insertions(+), 10 deletions(-)

diff --git a/apps/fparkan-game/src/main.rs b/apps/fparkan-game/src/main.rs
index 465a98a..414ee71 100644
--- a/apps/fparkan-game/src/main.rs
+++ b/apps/fparkan-game/src/main.rs
@@ -1089,14 +1089,18 @@ mod tests {
         write_load_progress(
             &path,
             std::time::Duration::from_millis(34),
-            MissionLoadPhase::GraphVisualMaterialRequests(64),
+            MissionLoadPhase::GraphVisualMaterialRequests {
+                request_count: 64,
+                graph_node_count: 128,
+                graph_edge_count: 192,
+            },
         )?;
         let progress = std::fs::read_to_string(&path).map_err(|err| err.to_string())?;
         std::fs::remove_file(&path).map_err(|err| err.to_string())?;
 
         assert_eq!(
             progress,
-            "Starting\telapsed_ms=0\nGraphVisualMaterials\telapsed_ms=12\nGraphVisualMaterialRequests(64)\telapsed_ms=34\n"
+            "Starting\telapsed_ms=0\nGraphVisualMaterials\telapsed_ms=12\nGraphVisualMaterialRequests { request_count: 64, graph_node_count: 128, graph_edge_count: 192 }\telapsed_ms=34\n"
         );
         Ok(())
     }
diff --git a/crates/fparkan-assets/src/lib.rs b/crates/fparkan-assets/src/lib.rs
index 11e324f..6e3364d 100644
--- a/crates/fparkan-assets/src/lib.rs
+++ b/crates/fparkan-assets/src/lib.rs
@@ -490,6 +490,10 @@ pub struct VisualDependencyProgress {
     pub phase: VisualDependencyPhase,
     /// Number of requests reached in this class during the current expansion.
     pub request_count: usize,
+    /// Resource graph nodes materialized before this request is resolved.
+    pub graph_node_count: usize,
+    /// Resource graph edges materialized before this request is resolved.
+    pub graph_edge_count: usize,
 }
 
 /// Errors raised while preparing CPU-side assets.
@@ -1239,6 +1243,8 @@ pub fn extend_graph_report_with_visual_dependencies_with_progress<R: ResourceRep
             &mut on_progress,
             VisualDependencyPhase::Wear,
             wear_requests,
+            graph.nodes.len(),
+            graph.edges.len(),
         );
         match resolve_wear_table_cached(repository, mesh, &mut wear_validation) {
             Ok(table) => {
@@ -1281,6 +1287,8 @@ pub fn extend_graph_report_with_visual_dependencies_with_progress<R: ResourceRep
                 on_progress(VisualDependencyProgress {
                     phase: VisualDependencyPhase::Material,
                     request_count: material_requests,
+                    graph_node_count: graph.nodes.len(),
+                    graph_edge_count: graph.edges.len(),
                 });
                 for (material_index, _entry) in table.entries.iter().enumerate() {
                     material_requests = material_requests.saturating_add(1);
@@ -1288,6 +1296,8 @@ pub fn extend_graph_report_with_visual_dependencies_with_progress<R: ResourceRep
                         &mut on_progress,
                         VisualDependencyPhase::Material,
                         material_requests,
+                        graph.nodes.len(),
+                        graph.edges.len(),
                     );
                     let Ok(material_index) = u16::try_from(material_index) else {
                         push_visual_failure(
@@ -1339,6 +1349,8 @@ pub fn extend_graph_report_with_visual_dependencies_with_progress<R: ResourceRep
                                     &mut on_progress,
                                     VisualDependencyPhase::Texture,
                                     texture_requests,
+                                    graph.nodes.len(),
+                                    graph.edges.len(),
                                 );
                                 report.texture_request_count += 1;
                                 match resolve_texm_validation_cached(
@@ -1405,6 +1417,8 @@ pub fn extend_graph_report_with_visual_dependencies_with_progress<R: ResourceRep
                         &mut on_progress,
                         VisualDependencyPhase::Texture,
                         texture_requests,
+                        graph.nodes.len(),
+                        graph.edges.len(),
                     );
                     report.lightmap_request_count += 1;
                     match resolve_texm_validation_cached(
@@ -1472,11 +1486,15 @@ fn report_visual_dependency_progress(
     on_progress: &mut impl FnMut(VisualDependencyProgress),
     phase: VisualDependencyPhase,
     request_count: usize,
+    graph_node_count: usize,
+    graph_edge_count: usize,
 ) {
     if request_count == 1 || request_count.is_multiple_of(VISUAL_DEPENDENCY_PROGRESS_INTERVAL) {
         on_progress(VisualDependencyProgress {
             phase,
             request_count,
+            graph_node_count,
+            graph_edge_count,
         });
     }
 }
@@ -2320,6 +2338,8 @@ mod tests {
                 &mut |event| progress.push(event),
                 VisualDependencyPhase::Texture,
                 request_count,
+                37,
+                41,
             );
         }
 
@@ -2329,14 +2349,20 @@ mod tests {
                 VisualDependencyProgress {
                     phase: VisualDependencyPhase::Texture,
                     request_count: 1,
+                    graph_node_count: 37,
+                    graph_edge_count: 41,
                 },
                 VisualDependencyProgress {
                     phase: VisualDependencyPhase::Texture,
                     request_count: 64,
+                    graph_node_count: 37,
+                    graph_edge_count: 41,
                 },
                 VisualDependencyProgress {
                     phase: VisualDependencyPhase::Texture,
                     request_count: 128,
+                    graph_node_count: 37,
+                    graph_edge_count: 41,
                 },
             ]
         );
diff --git a/crates/fparkan-runtime/src/lib.rs b/crates/fparkan-runtime/src/lib.rs
index 42b3eda..1ab8e38 100644
--- a/crates/fparkan-runtime/src/lib.rs
+++ b/crates/fparkan-runtime/src/lib.rs
@@ -126,11 +126,25 @@ pub enum MissionLoadPhase {
     /// Resolve MAT0 documents while expanding visual dependencies.
     GraphVisualMaterials,
     /// Progress marker emitted after each 64 MAT0 validation requests.
-    GraphVisualMaterialRequests(usize),
+    GraphVisualMaterialRequests {
+        /// Number of MAT0 validation requests started.
+        request_count: usize,
+        /// Graph nodes materialized before the request.
+        graph_node_count: usize,
+        /// Graph edges materialized before the request.
+        graph_edge_count: usize,
+    },
     /// Validate TEXM documents while expanding visual dependencies.
     GraphVisualTextures,
     /// Progress marker emitted after each 64 TEXM validation requests.
-    GraphVisualTextureRequests(usize),
+    GraphVisualTextureRequests {
+        /// Number of TEXM validation requests started.
+        request_count: usize,
+        /// Graph nodes materialized before the request.
+        graph_node_count: usize,
+        /// Graph edges materialized before the request.
+        graph_edge_count: usize,
+    },
     /// Prepare all reachable visual/resource dependencies.
     Assets,
     /// Decode and validate MSH model meshes.
@@ -728,12 +742,20 @@ fn load_mission_with_options_and_progress(
             if progress.request_count > 1 {
                 let request_phase = match progress.phase {
                     VisualDependencyPhase::Wear => None,
-                    VisualDependencyPhase::Material => Some(
-                        MissionLoadPhase::GraphVisualMaterialRequests(progress.request_count),
-                    ),
-                    VisualDependencyPhase::Texture => Some(
-                        MissionLoadPhase::GraphVisualTextureRequests(progress.request_count),
-                    ),
+                    VisualDependencyPhase::Material => {
+                        Some(MissionLoadPhase::GraphVisualMaterialRequests {
+                            request_count: progress.request_count,
+                            graph_node_count: progress.graph_node_count,
+                            graph_edge_count: progress.graph_edge_count,
+                        })
+                    }
+                    VisualDependencyPhase::Texture => {
+                        Some(MissionLoadPhase::GraphVisualTextureRequests {
+                            request_count: progress.request_count,
+                            graph_node_count: progress.graph_node_count,
+                            graph_edge_count: progress.graph_edge_count,
+                        })
+                    }
                 };
                 if let Some(request_phase) = request_phase {
                     record_load_phase(&mut trace, &mut on_phase, request_phase);
diff --git a/docs/tomes/05-render.md b/docs/tomes/05-render.md
index b647f19..d390a9a 100644
--- a/docs/tomes/05-render.md
+++ b/docs/tomes/05-render.md
@@ -1126,6 +1126,13 @@ termination. It does not preserve the simultaneous TEXM count, so it neither
 identifies a slow individual material nor attributes time to MAT0 parsing; the
 next profiler revision needs one cumulative snapshot of all classes.
 
+Visual MAT0/TEXM request markers now also carry the graph node and edge counts
+materialized immediately before that request resolves. A rebuilt bounded Part 2
+probe recorded MAT0 request 3 at 52 nodes / 51 edges and request 4 at 55 nodes
+/ 54 edges. These are observational snapshots for graph-growth profiling only:
+they do not change traversal order, node or edge identities, provenance,
+validation, cache semantics, or rendering.
+
 `fparkan-game --load-progress` now initializes its file with `Starting` and
 appends each later mission-load event instead of replacing the prior line. A
 bounded probe can therefore retain both MAT0 and TEXM request milestones even