Enhance documentation, update dependencies, and improve build processes

Makefile

@@ -395,7 +395,7 @@ docs-clean:
 
 clean:
 	rm -rf dist docs/site probing/server/web-assets web/dist web/target
-	rm -rf python/probing/libs python/probing/shim/hccl
+	rm -rf python/probing/bundled_web python/probing/libs python/probing/shim/hccl
 	rm -rf .pytest_cache .coverage coverage.xml coverage.lcov
 	cargo clean
 	rm -f coverage.lcov coverage.json

docs/src/design/federation.md

@@ -233,17 +233,20 @@ flowchart LR
     RW --> EX[Execute shards]
     EX --> TG[Inject federation tags]
     TG --> MG[Merge / re-aggregate]
-    MG --> OUT[DataFrame + FanoutMeta]
+    MG --> OUT[QueryOutcome DataFrame + QueryQuality]
 ```
 
 **Conventions**
 
 | Item | Semantics |
 |------|-----------|
-| Response | `dataframe` + `meta.nodes_queried` + `meta.nodes_failed` |
+| Core result | `QueryOutcome<T>` always carries `data` and typed `QueryQuality`; partialness is not a task-local side channel |
+| HTTP response | `dataframe` + `meta.nodes_queried` + `meta.nodes_failed` |
 | Peer set | Snapshot of `cluster.nodes`, **excluding** coordinator listen addrs |
 | Peer execution | Always `probe.*`; peers must not fan-out again |
-| Concurrency | Parallel peer requests; latency ≈ slowest peer + coordinator merge |
+| Execution | SQL, extension capture, node discovery, and heartbeat HTTP share one async `FanoutService` |
+| Isolation | Peer network I/O runs on a dedicated Tokio runtime (`PROBING_FANOUT_WORKER_THREADS`), separate from Axum/DataFusion caller workers |
+| Concurrency | Shared bounded peer requests; latency ≈ slowest peer + coordinator merge |
 | Timeout | Failed peer → `nodes_failed`; default **30s** (`PROBING_REMOTE_QUERY_TIMEOUT_SECS`) |
 | Strict fan-out | `PROBING_FANOUT_STRICT=1` fails query on any `nodes_failed` or `peer_batches_dropped` (no partial merge) |
 | Partial HTTP | Cluster/fan-out APIs return **503** with partial `dataframe` when `meta.partial=true` (non-strict only) |

docs/src/design/federation.zh.md

@@ -240,17 +240,20 @@ flowchart LR
     RW --> EX[各分片执行]
     EX --> TG[注入联邦标签]
     TG --> MG[合并 / 二次聚合]
-    MG --> OUT[DataFrame + FanoutMeta]
+    MG --> OUT[QueryOutcome DataFrame + QueryQuality]
 ```
 
 **统一约定**
 
 | 项 | 语义 |
 |----|------|
-| 响应体 | `dataframe` + `meta.nodes_queried` + `meta.nodes_failed` |
+| Core 返回值 | `QueryOutcome<T>` 始终同时携带 `data` 与类型化 `QueryQuality`；partial 不再是 task-local 旁路状态 |
+| HTTP 响应体 | `dataframe` + `meta.nodes_queried` + `meta.nodes_failed` |
 | Peer 集合 | `cluster.nodes` 快照，**排除** coordinator 自身 listen addr |
 | Peer 执行 | 永远 `probe.*`；禁止 peer 再 fan-out（防递归） |
-| 并发 | 各 peer 并行请求；总延迟 ≈ 最慢 peer + coordinator 合并 |
+| 统一执行 | SQL、Extension 采集、节点发现和心跳 HTTP 共用一个异步 `FanoutService` |
+| 资源隔离 | Peer 网络 I/O 使用独立 Tokio runtime（`PROBING_FANOUT_WORKER_THREADS`），不占用 Axum/DataFusion 调用线程 |
+| 并发 | 共用有界并发；总延迟 ≈ 最慢 peer + coordinator 合并 |
 | 超时 | 失败 peer → `nodes_failed`；默认 **30s**（`PROBING_REMOTE_QUERY_TIMEOUT_SECS`） |
 | 严格 fan-out | `PROBING_FANOUT_STRICT=1`：任一 `nodes_failed` 或 `peer_batches_dropped` 则整查失败（无 partial merge） |
 | Partial HTTP | 集群/fan-out API 在 `meta.partial=true` 时返回 **503** 及 partial `dataframe`（非 strict 模式） |

docs/src/design/modularity.md

@@ -156,20 +156,22 @@ New work should extend **one** of these contracts instead of adding cross-module
   `global.<schema>.<table>`.
 - Do **not** query other collectors from inside `scan()`; join at SQL layer.
 
-### 3.2 `ProbeExtension` — config + imperative HTTP
+### 3.2 `ProbeExtension` — typed config + HTTP contracts
 
 **Where:** `probing/core/src/core/probe_extension.rs`
 **Derive:** `#[derive(ProbeExtension)]` in `probing-macros`
 
 | Capability | Mechanism |
 |------------|-----------|
-| Config keys | `probing.<namespace>.<option>` via `set` / `get` / `options` |
+| Identity | `ProbeExtension::name` supplies the registration namespace |
+| Config keys | `ProbeExtensionConfig` publishes typed key/alias specs and implements `set` / `get` / `options` |
 | Side effects | Background sampler start/stop in `set_*` handlers |
-| HTTP | `ProbeExtensionCall::call` → `/apis/<name>/...` fallback |
+| HTTP | `ProbeExtensionCall::routes` registers method/content-type/CORS/readiness contracts; `call` executes them |
 
 **Rules:**
 
 - Extension name = URL segment (`pythonext`, `rdmaextension`, …).
+- Registration validates names, duplicate routes, and config key/alias collisions before engine publication.
 - Prefer **tables for data**, extension for **control** (start/stop, eval, flamegraph render).
 - Never `todo!()` in default trait methods — return `EngineError`.
 

docs/src/design/modularity.zh.md

@@ -145,17 +145,18 @@ HTTP 契约：`probing/server/API.md` + `tests/regression/spec/api_spec.json`。
 
 **规则：** schema/scan 在采集 crate 内；跨信号用 SQL JOIN，不在 `scan()` 里调别的采集器。
 
-### 3.2 `ProbeExtension` — 配置 + 命令式 HTTP
+### 3.2 `ProbeExtension` — 类型化配置与 HTTP 契约
 
 **定义：** `probing/core/src/core/probe_extension.rs`
 
 | 能力 | 机制 |
 |------|------|
-| 配置 | `probing.<ns>.<option>` |
+| 身份 | `ProbeExtension::name` 定义注册命名空间 |
+| 配置 | `ProbeExtensionConfig` 声明 key/alias 并实现 `set` / `get` / `options` |
 | 副作用 | `set_*` 里启停采样线程 |
-| HTTP | `/apis/<name>/...` |
+| HTTP | `ProbeExtensionCall::routes` 声明 method/content-type/CORS/readiness，`call` 负责执行 |
 
-**规则：** 数据走表，控制走 Extension；trait 默认实现禁止 `todo!()`。
+**规则：** 注册阶段校验扩展名、重复 route、配置 key/alias 冲突；数据走表，控制走 Extension；trait 默认实现禁止 `todo!()`。
 
 ### 3.3 Python `@table` — 应用数据插件
 

docs/src/reference/env-vars.md

@@ -215,8 +215,8 @@ Hierarchical side-channel registration when `WORLD_SIZE > 1`. See [torchrun clus
 | `PROBING_CLUSTER_FANOUT_HIERARCHICAL` | `1` | Hierarchical cluster query fan-out (coordinator → local0 → leaves). `0` = flat fan-out to every peer. See [Hierarchical fan-out](../design/hierarchical-fanout.md). |
 | `PROBING_REMOTE_QUERY_TIMEOUT_SECS` | `30` | Per-peer timeout for remote federated / cluster queries (seconds). |
 | `PROBING_FANOUT_CONCURRENCY` | `128` | Max concurrent in-flight remote fan-out HTTP requests per query. |
+| `PROBING_FANOUT_WORKER_THREADS` | `4` | Worker threads in the isolated async fan-out runtime shared by distributed SQL, extension capture, discovery, and heartbeat requests. |
 | `PROBING_FANOUT_STRICT` | unset | When `1` or `true`, any federated peer failure or dropped batch fails the whole query instead of returning partial results. |
-| `PROBING_STACK_FANOUT_CONCURRENCY` | `32` | Max concurrent peer captures for Distributed stacks. |
 | `PROBING_STACK_FANOUT_DEADLINE_SEC` | `15` | Overall Distributed stacks fan-out deadline. Completed peers are returned as a partial flamegraph when the deadline expires. |
 | `PROBING_NCCL_CHUNK_BYTES` | `65536` | NCCL profiler mmap ring chunk size (bytes). |
 | `PROBING_NCCL_NUM_CHUNKS` | `64` | NCCL profiler mmap ring chunk count (~4 MiB total per table at defaults). |

docs/src/reference/env-vars.zh.md

@@ -27,7 +27,7 @@ Probing 读取的全部 `PROBING_*` 环境变量参考（按子系统分组）
 | `PROBING_CLUSTER_FANOUT_HIERARCHICAL` | `1` | 分层集群查询 fan-out；`0` = 扁平 fan-out 到所有 peer。 |
 | `PROBING_REMOTE_QUERY_TIMEOUT_SECS` | `30` | 远程联邦 / 集群查询的单 peer 超时（秒）。 |
 | `PROBING_FANOUT_CONCURRENCY` | `128` | 单次 cluster fan-out 的最大并发远程 HTTP 请求数。 |
-| `PROBING_STACK_FANOUT_CONCURRENCY` | `32` | Distributed stacks 同时采集的最大 peer 数。 |
+| `PROBING_FANOUT_WORKER_THREADS` | `4` | 分布式 SQL、Extension 采集、节点发现和心跳共用的独立异步 fan-out runtime 线程数。 |
 | `PROBING_STACK_FANOUT_DEADLINE_SEC` | `15` | Distributed stacks 的整体 fan-out 截止时间；超时后返回已完成 peer 的部分火焰图并列出失败 peer。 |
 | `PROBING_ADVERTISE_ADDR` | `MASTER_ADDR`，否则 hostname | wildcard bind 时向 peer 发布的地址；支持 `host`、`host:port`、IPv6 或 `{port}` 占位符。多网卡环境或 `MASTER_ADDR` 不是当前节点的 peer 可达地址时必须显式设置。 |
 | `PROBING_NODE_HOST` | 操作系统 hostname | cluster heartbeat 中上报的显式 host 标签。用于容器身份和本地逻辑节点 fixture；不会改变向 peer 发布的网络地址。 |

probing/cli/src/cli/ctrl.rs

@@ -152,19 +152,14 @@ impl ProbeEndpoint {
         let q_str = serde_json::to_string(&request)?;
         let reply_str = self.send_request("/query", &q_str).await?; // Renamed reply variable
         let msg = serde_json::from_str::<Message<QueryDataFormat>>(&reply_str)?;
-        if let Some(meta) = &msg.meta {
-            if meta
-                .get("fanout")
-                .and_then(|f| f.get("partial"))
-                .and_then(|v| v.as_bool())
-                .unwrap_or(false)
-            {
+        if let Some(quality) = msg.meta.as_ref().and_then(|meta| meta.fanout.as_ref()) {
+            if quality.is_partial() {
                 if fanout_strict_enabled() {
                     return Err(anyhow::anyhow!(
-                        "federated fan-out strict mode: query returned partial data: {meta}"
+                        "federated fan-out strict mode: query returned partial data: {quality:?}"
                     ));
                 }
-                eprintln!("warning: federated query returned partial data: {meta}");
+                eprintln!("warning: federated query returned partial data: {quality:?}");
             }
         }
         let reply = msg.payload;

probing/core/src/config.rs

@@ -124,7 +124,10 @@ pub async fn write(key: &str, value: &str) -> Result<(), EngineError> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::core::{ProbeExtension, ProbeExtensionCall, ProbeExtensionOption};
+    use crate::core::{
+        ExtensionConfigSpec, ProbeExtension, ProbeExtensionCall, ProbeExtensionConfig,
+        ProbeExtensionOption,
+    };
     use crate::{create_engine, initialize_engine};
 
     async fn setup_test() -> tokio::sync::MutexGuard<'static, ()> {
@@ -156,6 +159,16 @@ mod tests {
         fn name(&self) -> String {
             "test".to_string()
         }
+    }
+
+    impl ProbeExtensionConfig for TestExtension {
+        fn config_specs(&self) -> &'static [ExtensionConfigSpec] {
+            &[ExtensionConfigSpec {
+                key: "option",
+                aliases: &[],
+                help: "Test option",
+            }]
+        }
 
         fn set(&mut self, key: &str, value: &str) -> Result<String, EngineError> {
             match key {