Implement real shutdown pipeline

- Route ShutdownTree through cancellable child attempts and ordered drain

- Return per-child shutdown reports with reconciliation and idempotent caching

- Record shutdown metrics, audit facts, documentation, and regression tests

Author: developerworks

Cargo.toml

@@ -108,6 +108,10 @@ path = "src/tests/supervisor_runtime_lifecycle_test.rs"
 name = "supervisor_shutdown_test"
 path = "src/tests/supervisor_shutdown_test.rs"
 
+[[test]]
+name = "supervisor_real_shutdown_pipeline_test"
+path = "src/tests/supervisor_real_shutdown_pipeline_test.rs"
+
 [[test]]
 name = "supervisor_event_shape_test"
 path = "src/tests/supervisor_event_shape_test.rs"

README.zh.md

@@ -20,7 +20,7 @@
 - 配置必须通过 rust-config-tree(集中配置树) v0.1.9 加载 YAML(数据序列化格式), 运行时可调常量不得散落到模块内部.
 - `SupervisorConfig`(监督器配置) 是公开 root configuration struct(根配置结构体), 它同时支持 `confique::Config`(配置派生), `schemars::JsonSchema`(结构模式生成特征), `Serialize`(序列化) 和 `Deserialize`(反序列化).
 - dashboard IPC(看板进程间通信) 只属于 target process(目标进程) 本机入口. 当前仓库只实现 Unix domain socket(Unix 域套接字), snapshot(快照), event record(事件记录), log record(日志记录), command mapping(命令映射) 和 shared contract(共享契约).
-- shutdown(关闭) 必须执行 request stop(请求停止), graceful drain(优雅排空), abort stragglers(强制终止拖尾任务) 和 reconcile(状态对账).
+- shutdown(关闭) 必须执行 request stop(请求停止), graceful drain(优雅排空), abort stragglers(强制中止滞留任务) 和 reconcile(状态对账). `ShutdownTree`(关闭监督树) 会向运行中的 child task(子任务) 发送 `CancellationToken`(取消令牌), 按 shutdown order(关闭顺序) 等待任务返回, 超时后使用 `AbortHandle`(强制中止句柄) 终止滞留任务, 并在 `ShutdownResult`(关闭结果) 中返回 per-child outcome(逐子任务结果) 和 reconcile report(对账报告).
 - 关闭术语统一使用 Shutdown Without Orphaned Tasks(关闭后不留下孤儿任务).
 
 ## Capability Boundary(能力边界)
@@ -31,6 +31,7 @@
 - 从 typed failure(类型化失败), backoff(退避), jitter(抖动), fuse rule(熔断规则) 和 policy engine(策略引擎) 生成 `RestartDecision`(重启决策).
 - 通过 `SupervisorHandle`(监督器句柄) 控制运行中的树, 包括 `add_child`, `remove_child`, `restart_child`, `pause_child`, `resume_child`, `quarantine_child`, `shutdown_tree`, `current_state`, `subscribe_events`, `is_alive`, `health`, `join` 和 `shutdown`.
 - 控制命令必须携带非空 `requested_by`(请求者) 和 `reason`(原因), 公共控制入口和 runtime control loop(运行时控制循环) 都会在执行前校验审计字段.
+- `shutdown_tree`(关闭监督树) 返回完成后的 `ShutdownPipelineReport`(关闭流水线报告), 其中包含 `ChildShutdownStatus`(子任务关闭状态), `ShutdownReconcileReport`(关闭对账报告) 和 socket status(套接字状态). 核心 runtime(运行时) 不拥有 dashboard IPC socket(看板进程间通信套接字) 时, socket status(套接字状态) 会记录为 `NotOwned`(非运行时拥有).
 - `is_alive`(是否存活) 和 `health`(健康报告) 暴露 runtime control plane(运行时控制面)状态. `join`(等待结束) 可以重复读取同一个最终 `RuntimeExitReport`(运行时退出报告). `shutdown`(关闭) 只关闭控制面, 不替代 `shutdown_tree`(监督树关闭).
 - 从 `examples/config/supervisor.yaml` 加载主 YAML(数据序列化格式) 配置.
 - 复用 `rust_supervisor::config::configurable::SupervisorConfig` 完成 YAML(数据序列化格式) 加载, template generation(模板生成) 和 JSON Schema(JSON 结构模式) 生成.

manual/zh/observability.md

@@ -24,6 +24,14 @@ observability pipeline(可观测性管线)把同一事实同步为这些信号:
 
 metrics label(指标标签)必须保持低基数. 可以使用 supervisor path(监督器路径), child id(子任务标识), state(状态), decision(决定)和 failure category(失败类别). 不应该使用错误全文, 用户输入或无界动态值.
 
+## 真实关闭流水线
+
+`ShutdownTree`(关闭监督树) 执行真实 shutdown pipeline(关闭流水线) 后, observability pipeline(可观测性管线) 必须能看到每个阶段的事实. `ChildShutdownCancelDelivered`(子任务取消已送达) 表示 runtime(运行时) 已经向运行中的 child attempt(子任务尝试) 发送 `CancellationToken`(取消令牌). `ChildShutdownGraceful`(子任务优雅完成) 表示 child task(子任务) 在 graceful drain(优雅排空) 时间预算内返回. `ChildShutdownAborted`(子任务已强制中止) 表示 runtime(运行时) 已经对滞留任务请求 `abort`(强制中止). `ChildShutdownLateReport`(子任务迟到报告) 表示 child task(子任务) 在正常关闭核算窗口之后才返回. `ShutdownCompleted`(关闭完成) 表示 pipeline(流水线) 已经输出最终 reconcile report(对账报告).
+
+metrics(指标) 使用低基数标签记录关闭事实. `supervisor_shutdown_duration_seconds`(监督器关闭耗时秒数) 记录完整 pipeline(流水线) 耗时. `supervisor_shutdown_child_outcomes_total`(监督器子任务关闭结果总数) 按 status(状态) 和 phase(阶段) 计数, 不把 `child_id`(子任务标识) 写入指标标签. `supervisor_shutdown_abort_total`(监督器关闭强制中止总数) 按 bounded reason(有界原因) 计数. `supervisor_shutdown_late_reports_total`(监督器关闭迟到报告总数) 按 phase(阶段) 计数.
+
+audit event(审计事件) 会记录 cancel delivered(取消已送达), graceful outcome(优雅结果), abort outcome(强制中止结果), late report(迟到报告) 和 completed reconcile(完成对账). 核心 runtime(运行时) 不拥有 dashboard IPC socket(看板进程间通信套接字) 时, reconcile report(对账报告) 会把 socket status(套接字状态) 写成 `NotOwned`(非运行时拥有).
+
 ## 诊断回放
 
 event journal(事件日志缓冲区)保存固定容量的最近事件. `RunSummary`(运行摘要)从事件日志, current state(当前状态)和策略决定生成诊断摘要, 用于解释 meltdown(熔断), 关闭超时或父级升级.