feat(net)!: bootstrap static Bus service connections

docs/reference/bus.md

@@ -38,9 +38,9 @@ config = "bus.plugin.toml"
 ```
 
 The application must also load Net and Utility as required by the existing module
-dependencies. This snippet does not establish cross-plugin initialization order
-or start a listener. The TOML schema, required fields, defaults of public value
-types, validation diagnostics and message serialization/routing are unchanged.
+dependencies. Net queues configured outgoing SS connections during `post_init()`;
+the application still starts its listeners explicitly. The public value types and
+message serialization interfaces remain unchanged.
 
 `check-bus-plugin`, included in application-enabled `check-core`, loads actual
 Bus/Net/Utility DSOs and verifies both public interface keys, TOML queries,
@@ -113,7 +113,11 @@ check_interval = "10s"
 check_timeout = "3s"
 ```
 
-This is a Bus configuration example, not a complete two-process launch configuration. Applications must also load Bus, Net and their dependencies, set each process's Bus ID, start listeners and initiate connections. `relations` supplies target types; reading a relationship does not automatically create a connection.
+Applications load Bus, Net and Utility, set a deployment-assigned Bus ID, and start listeners with `create_server()`. During Net `post_init()`, each directed relation selects configured target processes of that type in the local channel and zone. Self is excluded, and each target Bus ID is queued once through the existing SS client service. A relation with no eligible process records queues nothing. Bus queries retain their existing semantics; `get_other_proc(type, list)` itself does not filter channel or zone.
+
+The selected target's `intranet_endpoint` must contain a dialable TCP or UDP host, a nonzero port and no path. Missing endpoints, unsupported transports and wildcard dial addresses (`0.0.0.0`, `::`) fail Net startup with the target Bus ID and field in the diagnostic. Hostnames remain supported. Wildcard addresses remain valid for listening: where a wildcard bind is needed, use `server_endpoint` for that listener and a reachable `intranet_endpoint` for SS traffic. `intranet_endpoint` currently serves both as the SS listener address and the advertised dial target; there is no separate bind/advertise field.
+
+Connection requests run on subsequent manager updates; successful startup does not mean the target is connected. Targets can start later or restart at the same configured identity and endpoint. The existing client state machine, SS registration and heartbeat handle the connection lifecycle. Configuration is a startup snapshot: it does not support hot reload, dynamic membership, automatic ID assignment or global uniqueness enforcement. Deployments, including Kubernetes, must assign stable Bus IDs and reachable endpoints; no Kubernetes API integration is implied.
 
 Configuring `bus.registry` does not enable dynamic registration or discovery. The Consul registration and health-based discovery paths in the current network service manager remain commented out. This configuration alone cannot discover target processes.
 
@@ -135,7 +139,9 @@ All four sections and their fields are required. Arrays may be empty (`applicati
 
 Bus IDs require exactly four decimal components in `0..255`. Nonempty endpoints require a supported protocol and `protocol://host:port` (optional path), with port `0..65535`. Hostnames are retained without DNS lookup. IPv6 literals use brackets, for example `tcp://[::1]:9011`; their numeric syntax is validated locally, and the stored host is `::1` without brackets for arknet. The public endpoint formatter is unchanged. An empty endpoint remains allowed and disables that listener. Both endpoints are validated independently. Registry interval and timeout strings are passed through without interpreting their duration grammar.
 
-The public `app_config`, `proc_config` and `reg_center` fields and query methods remain unchanged. Application maps and other-process maps keep their first entry for a duplicate key; the last matching self-process entry wins, and relations retain input order and duplicates. A missing self-process entry remains unconfigured. These settings do not enable discovery or create network connections. The private schema validator uses the shared compiled `ark::config` file/TOML reader; toml++ stays private to configuration and plugin implementation targets.
+The public `app_config`, `proc_config` and `reg_center` fields and query methods remain unchanged. Duplicate application names, application types, directed relations and process Bus IDs now fail Bus initialization with the file, array index and field. A missing self-process entry remains unconfigured. The private schema validator uses the shared compiled `ark::config` file/TOML reader; toml++ stays private to configuration and plugin implementation targets.
+
+**Upgrade:** remove duplicate records and provide a reachable `intranet_endpoint` for every same-channel, same-zone process selected by an outgoing relation before starting Net. Configurations that previously loaded duplicate or empty selected-target records now fail startup. Relations now initiate outgoing connections automatically; remove relations that should not initiate traffic. The shipped general-purpose configuration includes historical entries and is not a complete deployment inventory; review its relations and endpoints for the chosen process identity.
 
 ## Query local and target processes
 
@@ -185,9 +191,9 @@ std::vector<ark::proc_config> configured_targets(ark::plugin_manager& manager) {
 | `get_other_proc(id, proc)` | Copies the configuration and returns `true` when found; otherwise returns `false` |
 | `combine_bus_id(type, instance)` | Combines the local channel and zone with the supplied type and instance |
 
-## Establish a TCP connection
+## Explicit TCP connections
 
-The target process first starts its listeners with `net_service_manager_module::create_server()`. The following function reads the target's configured intranet endpoint and queues a TCP connection through the network service manager.
+The target process starts its listeners with `net_service_manager_module::create_server()`. Normal relation-selected targets are queued automatically. For application-managed targets outside that bootstrap policy, the following function queues an explicit TCP connection through the existing interface.
 
 ```cpp
 #include "ark/bus/bus_module.hpp"
@@ -221,7 +227,7 @@ bool queue_tcp_connection(ark::plugin_manager& manager, ark::bus_id_t target_id)
 
 `true` means the connection request was queued in the client service and will be processed by subsequent `update()` calls. It does not mean the connection has succeeded. Observe connection events with the client service's `reg_net_event_callback()` and register message handlers with `reg_msg_callback()`. The receiver registers handlers on the corresponding server service.
 
-The current client service handles reconnection through its connection state machine, with a 30-second retry interval in the implementation. This is not a configurable backoff policy in the XML file. Reconnection does not replay application messages whose earlier send failed.
+The current client service handles reconnection through its connection state machine, with a 30-second retry interval in the implementation. This is not a configurable backoff policy in the TOML file. Reconnection does not replay application messages whose earlier send failed.
 
 ## Send and receive messages
 
@@ -250,9 +256,9 @@ The receive flow is: the network service extracts a `net_msg` → invokes the ha
 
 ## Coverage and planned work
 
-These examples cover configuration queries, an explicit TCP connection request and sending through an existing connection. They are not an accepted multi-process deployment example, and do not imply that every protocol is integrated with the service manager. See the [Net plugin](network.md) for transport integration.
+`check-static-services` (Unix, application-enabled `check-core`) launches two separately owned processes with the actual Bus/Net/Utility dynamic libraries on a private loopback TCP endpoint. It verifies type/channel/zone eligibility and self exclusion, selected-target endpoint diagnostics, SS registration/session mapping, Protobuf request/response, failed sends while disconnected, and a target restart followed by another round trip through the existing 30-second service retry policy. Both processes stop normally; the controller retains raw child logs locally. Run it with `cmake --build build --target check-static-services --parallel 1` after configuring application and core tests.
 
-TODO: provide a standalone two-process example and tests covering connection setup, message round trips, process restarts, reconnection and cross-host routing. Implement and validate dynamic registration / discovery separately.
+This is bounded local functional acceptance, not cross-host routing, UDP integration, Windows process-controller acceptance, capacity or a deployment guarantee. See the [Net plugin](network.md) for transport integration. TODO: provide a standalone deployment example and validate cross-host routing and dynamic registration/discovery separately.
 
 ## API sources
 

docs/reference/bus_CN.md

@@ -27,8 +27,8 @@ name = "ark_bus_plugin"
 config = "bus.plugin.toml"
 ```
 
-应用还需按原有模块依赖加载 Net 与 Utility。该片段不规定跨插件初始化顺序，也不会启动监听。
-TOML 结构、必需字段、公开值类型的默认值、校验诊断、消息序列化与路由均保持不变。
+应用还需按原有模块依赖加载 Net 与 Utility。Net 在 `post_init()` 中加入配置指定的 SS 出站连接，
+应用仍须显式启动监听。公开值类型和消息序列化接口保持不变。
 
 启用应用构建时，`check-core` 包含的 `check-bus-plugin` 加载真实 Bus／Net／Utility 动态库，
 验证两个公开接口键、TOML 查询、通过记录型 Net 连接传递的 Protobuf 消息头与正文、发送失败及正常重复停服。
@@ -98,7 +98,11 @@ check_interval = "10s"
 check_timeout = "3s"
 ```
 
-这是 Bus 配置示例，不是完整的双进程启动配置。应用还需加载 Bus、Net 及其依赖插件，设置各自的 Bus ID，启动监听并发起连接。`relations` 只提供目标类型列表；读取关系本身不会自动建立连接。
+应用加载 Bus、Net 和 Utility，设置部署分配的 Bus ID，并通过 `create_server()` 启动监听。Net 在 `post_init()` 中按有向关系选择目标类型，并仅连接与本进程渠道和区域相同的静态进程。排除自身后，每个目标 Bus ID 只加入一次既有 SS 客户端服务。关系没有匹配的进程记录时，不加入连接。Bus 查询语义不变；`get_other_proc(type, list)` 本身不筛选渠道或区域。
+
+选中目标的 `intranet_endpoint` 必须包含可拨号的 TCP 或 UDP 主机地址、非零端口，且不能带路径。端点缺失、传输协议不受支持或拨号地址为通配地址（`0.0.0.0`、`::`）时，Net 启动失败，诊断包含目标 Bus ID 和字段。支持主机名。监听仍可使用通配地址：需要通配绑定时，用 `server_endpoint` 监听，并为 SS 流量配置可达的 `intranet_endpoint`。目前 `intranet_endpoint` 同时用于 SS 监听和对外提供的拨号地址，没有独立的绑定地址与通告地址字段。
+
+连接请求在后续管理器更新中处理；启动成功不代表目标已经连接。目标可以稍后启动，也可以沿用相同身份和端点重启。连接生命周期继续使用既有客户端状态机、SS 注册和心跳。配置是启动时的快照，不支持热重载、动态成员管理、自动分配 ID 或全局唯一性校验。包括 Kubernetes 在内的部署环境须分配稳定的 Bus ID 和可达端点；这不表示已接入 Kubernetes API。
 
 `bus.registry` 有配置项不等于已启用动态注册或发现。当前网络服务管理模块中的 Consul 注册 / 健康检查发现路径仍为注释，不能依靠这份配置自动获得目标进程。
 
@@ -120,7 +124,9 @@ Bus 运行设置现在要求 TOML 内容，不能只修改旧 XML 文件的扩
 
 Bus ID 必须恰好包含四个 `0..255` 的十进制分量。非空端点必须使用受支持的协议和 `protocol://host:port` 格式（可附加路径），端口为 `0..65535`。主机名原样保留，不进行 DNS 查询。IPv6 字面量必须加方括号，例如 `tcp://[::1]:9011`；解析器仅在本地校验其数值语法，保存供 arknet 使用的无方括号主机名 `::1`。公共端点格式化方法保持不变。端点仍可为空，表示禁用对应监听；两个端点分别校验。注册中心的检查间隔和超时字符串原样传递，不解释时长语法。
 
-公共 `app_config`、`proc_config`、`reg_center` 字段及查询方法不变。应用映射和其他进程映射中的重复键保留首条，本进程配置取最后一条匹配项；关系保留输入顺序及重复项。本进程未配置时仍保持未配置状态。这些设置不会启用服务发现或创建网络连接。私有结构校验使用 `ark::config` 编译目标提供的共享文件／TOML 读取器；toml++ 仅由配置和插件实现目标内部使用，不进入公开接口。
+公共 `app_config`、`proc_config`、`reg_center` 字段及查询方法不变。应用名称、应用类型、有向关系或进程 Bus ID 重复时，Bus 初始化失败，诊断包含文件、数组下标和字段。本进程未配置时仍保持未配置状态。私有结构校验使用 `ark::config` 编译目标提供的共享文件／TOML 读取器；toml++ 仅由配置和插件实现目标内部使用，不进入公开接口。
+
+**升级：**启动 Net 前，删除重复记录，并为出站关系选中的同渠道、同区域进程提供可达的 `intranet_endpoint`。此前可加载的重复记录或选中目标的空端点现在会导致启动失败。关系现在会自动发起出站连接；不应发起流量的关系须删除。随仓库提供的通用配置含历史记录，不是完整的部署清单；应按所选进程身份核对关系及端点。
 
 ## 查询本进程与目标进程
 
@@ -170,9 +176,9 @@ std::vector<ark::proc_config> configured_targets(ark::plugin_manager& manager) {
 | `get_other_proc(id, proc)` | 找到时复制配置并返回 `true`；未找到返回 `false` |
 | `combine_bus_id(type, instance)` | 沿用本进程的渠道和区域，组合指定类型与实例的 ID |
 
-## 建立 TCP 连接
+## 显式 TCP 连接
 
-目标进程应先通过 `net_service_manager_module::create_server()` 启动监听。下面从静态配置取目标的内网端点，并将 TCP 连接请求交给网络服务管理模块。
+目标进程通过 `net_service_manager_module::create_server()` 启动监听。关系选中的常规目标会自动加入连接；对于应用在该启动策略之外自行管理的目标，可通过以下既有接口显式加入 TCP 连接。
 
 ```cpp
 #include "ark/bus/bus_module.hpp"
@@ -235,9 +241,9 @@ bool send_to_process(ark::msg_module& messages, ark::bus_id_t target_id, ark::ms
 
 ## 覆盖范围与后续工作
 
-本页示例覆盖配置查询、显式 TCP 连接请求和已有连接上的消息发送。它不构成经过验收的多进程部署示例，也不保证所有协议在服务管理层均已接入。底层传输能力见 [Net 插件](network_CN.md)。
+`check-static-services`（Unix，启用应用构建时纳入 `check-core`）在私有回环 TCP 端点上启动两个独立持有的进程，加载真实 Bus／Net／Utility 动态库。测试覆盖类型／渠道／区域筛选与自身排除、选中目标的端点诊断、SS 注册与 Session 映射、Protobuf 请求响应、断连期间发送失败，以及目标重启后按既有 30 秒服务重试策略完成第二次往返。两个进程正常停服，控制进程将原始子进程日志保留在本地。启用应用和核心测试后，运行 `cmake --build build --target check-static-services --parallel 1`。
 
-TODO：提供独立的双进程示例与测试，覆盖连接建立、消息往返、进程重启、重连和跨机器路由；动态注册 / 发现另行实现和验证。
+这是有界的本地功能验收，不构成跨机器路由、UDP 集成、Windows 进程控制器、容量或部署保证。底层传输能力见 [Net 插件](network_CN.md)。TODO：提供独立部署示例；跨机器路由、动态注册／发现另行实现和验证。
 
 ## API 来源
 

docs/reference/network.md

@@ -75,7 +75,10 @@ bool connect_tcp(ark::plugin_manager& manager, const ark::bus_addr& target,
 
 Connection requests retain their existing asynchronous behavior. Continue calling
 `manager.update(timestamp)` on the owner thread; keep callback receivers alive
-until delivery stops. See [Bus](bus.md) for identity and endpoint configuration.
+until delivery stops. Net also queues outgoing SS connections from Bus relations
+at startup, restricted to configured target types in the same channel and zone.
+Applications still start listeners explicitly. See [Bus](bus.md) for endpoint
+validation, migration requirements and the bounded two-process restart test.
 
 `check-net-plugin`, included in application-enabled `check-core`, loads actual
 Bus/Utility/Net DSOs, checks both interface keys, TCP message and HTTP callbacks

docs/reference/network_CN.md

@@ -63,7 +63,9 @@ bool connect_tcp(ark::plugin_manager& manager, const ark::bus_addr& target,
 ```
 
 连接请求保持既有异步语义。继续在所属线程调用 `manager.update(timestamp)`，
-并在回调停止前保持接收者有效。进程身份与端点配置见 [Bus](bus_CN.md)。
+并在回调停止前保持接收者有效。Net 也会在启动时根据 Bus 关系加入 SS 出站连接，
+仅选择同渠道、同区域的指定目标类型。应用仍须显式启动监听。
+端点校验、迁移要求和有界双进程重启测试见 [Bus](bus_CN.md)。
 
 启用应用构建时，`check-core` 包含的 `check-net-plugin` 加载真实 Bus／Utility／Net 动态库，
 验证两个接口键、管理器线程上的 TCP 消息与 HTTP 回调、无需管理器更新即可完成的 future、