@fx-data/ai-diagnostics 0.1.20261026070913 → 0.1.20261107142011

package/content/knowledge/engine/metric-semantics.md

@@ -1,172 +0,0 @@
-# 引擎 Metric 解读知识
-
-## 作用与适用范围
-
-本文说明完整 Polars Metric 中执行结构、耗时、内存和数据规模信号的含义，供 `$analyze-engine-metric` 及场景诊断 Skill 按需读取。
-
-它不负责定位 Metric 日志；获取链路见 [Metric 获取方法](metric-retrieval.md)。SigNoZ MetricOuts 只有任务级摘要和 analyzed plan 时，不能套用本文的 pipeline/operator 规则。
-
-不同引擎版本可能增删或改变 Metric 字段。只解释本次证据中出现的字段，不补造数值或执行关系。具体异常查[常见性能问题](performance-patterns.md)中的相关条目；产物格式和复用规则见[事实产物](metric-artifacts.md)。
-
-## 执行结构
-
-完整 Metric 通常同时包含几层信息：
-
-```text
-Analyzed / Optimized Plan
-  -> SubPlan / PhysicalNode
-  -> Stage / Task
-  -> Pipeline
-  -> Operator
-```
-
-- Plan 描述计算关系，PhysicalNode 描述优化后的物理实现；
-- SubPlan 是分布式执行片段，Stage/Task 是本次运行实例；
-- Pipeline 是可以流水执行的一段物理链路；
-- Operator 是 Pipeline 内的 source、process 或 sink 节点；
-- Operator 行末的 `[plan id]` 可用于关联同 ID 的 PhysicalNode，但不等同于业务 UI 的步骤 ID。
-
-同一物理节点可能拆成多个 Pipeline，例如 Join 的建表与探测、排序的收集与输出。不同 Task 也可能执行同一物理节点。先按 Stage、Task、Pipeline 区分运行实例，再用物理计划确认依赖；仅凭相同的 Operator 名称或 plan id 无法确认是同一实例，文本相邻也不能证明数据直连。
-
-`sourceFragmentId`、`sinkFragmentId` 和明确的 remote input 可以关联跨片段交换；SubPlan 的父子层级本身不能说明每条输入来自哪里。并行 Pipeline 的时间会重叠，没有运行时间线时不能将耗时排名当作串行关键路径。
-
-先定位异常任务和 Pipeline，再查看其中的 Operator、物理节点和数据条件。不要因为某个 Operator 名称看起来昂贵，就跳过本次运行指标直接判定根因。
-
-## 时间信号
-
-### 任务与 Pipeline
-
-- Job/summary 的 elapsed、execution、queue、optimizer 等字段用于区分排队、优化、分发和实际执行阶段；
-- 在 `Job:StandardTask[..., TaskStateTime[...]]` 格式中，`queue_time`、`wait_resource_time`、`plan_time`、`start_time`、`run_time`、`finish_time` 都是对应任务状态阶段的耗时，单位为毫秒。`start_time` 是启动阶段耗时，不是 Unix 时间戳；`null` 表示该阶段尚无已结束的测量，不能填成 0。`plan_time` 只统计状态机的规划阶段，不包含所有计划转换或优化工作。例如 `Slow constant folding` 的 `elapsedMs` 是独立专项测量，应单独核对；即使 `plan_time` 很短，也不能排除规划工作慢；
-- `pipeline_wall_time` 表示 Pipeline 的墙钟时间，适合找本次执行中的慢链路；
-- `morsel_blocked_time` 表示执行单元等待，可能来自上游、IO、交换、背压或异步任务，不能直接描述成 CPU 计算耗时；
-- `{max, min, sum, avg, count}` 是该字段统计对象的聚合值。判断尾延迟看 `max`，判断总工作量看 `sum`，判断平均值看 `avg`，不能不说明统计对象和口径就互相替代。
-
-各时间字段的计时范围如下：
-
-| 字段 | 记录什么 | 怎样使用 |
-|---|---|---|
-| `pipeline_wall_time_ms` | Pipeline 从调度到统计收尾时的墙钟时间 | 包含执行、依赖等待等链路作用，不是纯 CPU 时间 |
-| `morsel_pending_time` | 每个 Pipeline 执行单元累计的调度等待 | 大值支持检查调度压力，不能直接证明机器 CPU 已满 |
-| `morsel_blocked_time` | 执行单元因依赖未就绪而阻塞、直到唤醒的累计时间 | 结合 Source、Sink、Exchange 的专项等待确认对象 |
-| `morsel_active_wall_time` | 执行单元实际运行执行代码的累计墙钟时间 | 可能包含同步等待；不是整个 Pipeline 的 elapsed |
-| `morsel_active_cpu_time` | 上述执行代码的累计线程 CPU 时间 | 与同范围 active wall 对照，不能当作整机 CPU 利用率 |
-| `pipeline_task_open_time`、`pipeline_task_close_time` | 执行单元打开、关闭阶段的计时 | active 不高但 Pipeline 慢时，检查初始化与收尾 |
-| `compile_wall_time`、`compile_cost_wall_time` | 对应 JIT 后端的编译墙钟时间 | 不等于所有优化或查询执行时间，不与重叠阶段相加 |
-
-Pipeline 层的 morsel 统计先累计每个执行单元的多次运行，再汇总这些单元。这里的 `count` 是参与聚合的单元数量，不是调度次数或输入块数。算子专项统计的 `count` 可能统计列读取、分区等其他对象，应按字段确认。编译后端中的同名 `morsel_active_*` 只覆盖该后端运行的部分，与 Pipeline 汇总分别解释。
-
-比较 active CPU 与 active wall 时，先确认范围和聚合口径相同。CPU 较高时检查计算工作量；active wall 明显大于 CPU 时，检查同步 IO、锁等待或线程被抢占的专项信号。
-
-blocked、pending 的 `sum` 可能因并发超过 Pipeline 墙钟时间，不能用 `sum / pipeline_wall_time` 当作等待占比，各项最大值相加也无法还原总耗时。blocked 比例不包含事件顺序，无法说明等待发生在内存触顶之前还是之后。
-
-CPU 的 max 与 wall 的 max 可能来自不同执行单元，缺少实例对应时不能算某个单元的 CPU 占比。跨 Task 对照也须先确认同一物理工作及分布条件；只出现一个代表 Task 时不推断全体实例的差异。
-
-`Task execution timeout after ... ms (limit: ... ms)` 日志由优化器计时保护产生，预算可来自优化器配置或某段独立优化过程。应结合明确阶段及同 task 的 `Slow constant folding`、原始 limit 解释，不能仅凭错误文字就归为查询总运行时限、排队超时或算子执行耗时。两种计时可能包含同一段工作，不能相加；本次配置也不能从默认值推断。调整优化预算与调整查询超时需分别核对依据。
-
-### `next` 与 `pre`（仅在字段存在时）
-
-旧式逐节点取数记录中的 `next:sum` 统计取数调用的累计时间，包含调用内部读取子节点的时间，不能当作该 Operator 的独占时间。估算局部开销时，须确认记录来自同一次执行，同步单子链完整、直接父子关系和计时范围明确，且没有并发重叠。满足这些条件后，才可用父节点减直接子节点估算；多输入节点不套用这一差值。
-
-`pre()` 应按该份记录明确的阶段含义解读。名称本身不足以确认计时范围，不能统一解释为异步预取或独占工作，也不能与 `next` 简单相加。
-
-旧式 `stage[...]` / `rows=...` 文本与当前 Pipeline/Operator 格式不同。现有解析器不自动建立这类节点的统计树；保留原文与未识别范围，不把格式未解析当作指标为零，也不把上述估算写成解析器已验证的算子耗时。
-
-## 内存信号
-
-- `peakUserMemory`、`query_peak_memory` 与 `query_memory_limit` 用于确认任务峰值和资源边界；
-- `query_peak_memory_when_pipeline_closed` 是 Pipeline 关闭时观察到的查询级峰值快照，不等于该 Pipeline 或最后一个 Operator 独占的内存；
-- `store_tuple_arena_logical/physical`、`hash_table_arena_logical/physical` 等 Operator 专项 arena 信号比查询级快照更接近具体排序、缓存或 Hash 状态；存在时优先报告它们，但 logical、physical、allocated 和 peak 仍不能混为同一口径；
-- current、allocated、deallocated、peak 表达的生命周期不同，不能只取最大数字混为“算子内存”；
-- OOM 只证明资源边界被触发。完整解释还要连接具体计算、物理状态和本次数据条件。
-
-当前原生 Metric 的可读容量通常保留两位小数，`8.00 GiB` 等显示值存在舍入。单位转换保留原文和这一精度，不能从显示值还原精确字节；判断临界资源申请时优先核对同 task 错误中的整数字节值。Java 任务摘要、原生 query、arena 与错误申请记录的范围也分别保留。
-
-查询级快照的统计范围还可能随内存跟踪模式变化。核对 `use_memory_tracking_v2` 及已经出现的 `query_peak_memory_v1_when_pipeline_closed`、`query_peak_memory_tracked_when_pipeline_closed` 等伴随信号，不将不同跟踪范围的值相加；对照两次执行时，同名字段和相同单位不足以证明口径一致。缺少模式或版本依据时保留这项比较限制。
-
-不同内存字段对应不同物理状态：
-
-| 字段 | 状态含义 | 判断限制 |
-|---|---|---|
-| `store_tuple_arena_*` | 排序或窗口等保存中间行的 arena | 算子类型及字段所在节点决定用途，不统一命名为排序内存 |
-| `hash_table_arena_*` | Hash Join、聚合等保存键、行或聚合状态的 arena | 不一定覆盖整个 Hash 表及所有附属结构 |
-| `arena_*_allocated` | 预聚合等局部状态的 arena | 与其他名称的 arena 分开保留 |
-| `main_arena_*_allocated`、`secondary_arena_*_allocated` | 最终聚合中的主状态与其他局部状态 | main 不表示峰值，secondary 不表示增量；不能据名称计算差值 |
-| `partition_allocated_*`、`partition_arena_allocated_*` | 窗口或连接分区保存的状态 | 先核对对应算子及聚合对象 |
-| `query_current_memory`、`query_peak_memory` | 查询当前值及已观测峰值 | 结束后的 current 降低不证明运行中内存低 |
-| `query_memory_limit`、`global_memory_limit` | 查询与全局资源限制 | 哪个限制触发须由同 task 的错误确认 |
-| `spill_write_io_bytes`、`spill_write_disk_bytes` | 溢写产生的 IO 或落盘数据量 | 不属于驻留内存，不能进入算子内存排名 |
-
-这些 arena 的 logical 通常记录实际请求的数据空间，physical 记录分配的内存块。块内余量、对齐和复用会使两者不同，两者均不是进程 RSS。收集时的 arena 值也不能直接当作运行全过程的峰值。
-
-分析内存时优先寻找 hash table、分组状态、排序缓存、窗口状态、中间结果、spill 和输入放大等直接信号。只有总行数时，不能进一步推断高基数、倾斜或 N:N 放大。
-
-## 数据规模与 Operator 信号
-
-常用信号包括：
-
-- 扫描：`scanned_rows_num`、`scanned_columns_num`、`scan_task_file_bytes`、读取耗时；
-- 输出：`output_rows_num`、`output_cols_num`；
-- Hash：`hash_table_size` 及构建、探测相关计时；
-- 分组/排序/窗口：分组数、排序行数、缓存、spill、输入输出变化；
-- 并行：parallelism、各实例的 max/avg/sum 和任务间差异。
-
-这些值应和 Operator、PhysicalNode 及本次业务上下文一起解释。输入输出行数显著增长可以证明中间结果放大，但在没有连接条件和分支基数时，不能直接把它命名为 N:N Join。
-
-分析数据规模时，检查所有带行数信号的 Operator，包括 Top Pipeline 之外的节点。自身耗时或峰值内存不高的 Operator，也可能扩大中间结果并影响下游。原始行数和聚合口径是直接证据；据此计算的差值、输出/输入倍数和两次执行变化是可复算的派生证据，两类证据都应保留来源并分别说明。
-
-V1 查询埋点的 `rowCount` 与 Operator 的 `output_rows_num` 是不同口径。普通取数的前者可为默认 0，count 路径的前者表示 count 值，而物理 count 结果可能只输出一行；两者不能直接相除或作为对方缺失时的替代值。查询埋点的 `queryCount` 也是尝试序号，不是本次业务请求总数，详见[V1 查询边界](metric-retrieval.md#v1-查询埋点与完成边界)。
-
-比较两次执行时，优先按稳定 plan id 对齐同名 Operator，其次使用唯一物理签名；仅有唯一名称仍不足以自动对齐。同名候选不唯一时保留歧义，不按出现顺序强行配对。
-
-计数字段中的负值不是合法的数据规模。`-1` 等值应保留为原始哨兵并解释为该阶段未产出或指标不可用，不能参与差值、比例或“减少了一行”的计算。失败尾节点没有有效输出时，仍要继续读取此前已经完成的 Operator；例如下游 Sink 未产出，不会使上游 Scan、Aggregate、Unnest 或 Join 的已观测行数失效。
-
-`Unnest` 在执行层只表示把集合或数组元素展开为多行。只有本次 PhysicalNode、表达式或受控业务配置明确显示日期序列生成时，才能进一步解释为日期补全；否则保留“集合展开/行数放大”的通用语义，不能把一次案例中的业务操作固化为全局映射。
-
-当前原生 Metric 会在 Pipeline 之前记录 `jsy_cpp_task_name`、`resultRows`、`query_peak_memory`、`query_current_memory` 与 `query_memory_limit`。这些是任务级直接事实，但不包含任务状态时不能根据 `query_peak_memory == query_memory_limit` 反推执行失败；失败仍需同 task 的错误日志或显式状态证明。
-
-部分 Operator 只记录输出行数。解析器保留缺失输入，不用邻接 Operator 输出或扫描行数补造输入；只有同一 Operator 明确提供输入与输出、单位及聚合口径一致时，才计算差值和比例。缺失、无效、未产出和零分母分别保留原因，不能由诊断层手算绕过这些限制。
-
-两次 Metric 的 Operator 对比只说明已稳定对齐部分的变化。存在未匹配节点或多候选歧义时，比较只覆盖已对齐的部分；同向的数据规模与内存变化可以提升为贡献因素，但不能单独证明唯一原因，也不能把某个 Pipeline 关闭时的查询级快照描述成整个任务的最终峰值。
-
-## 变化原因与失败原因
-
-用户问“为什么这次失败、之前却成功”时，需要把不同层次分开：
-
-1. 本次变化：相较成功执行或历史基线，进入某个 Operator 的数据、输出规模或放大倍数发生了什么变化；
-2. 膨胀位置：哪个无歧义 Operator 在本次执行中把输入局部放大为更大的中间结果；
-3. 资源压力位置：哪些 Pipeline 或 Operator 状态承接了本次工作量并形成内存、排序、窗口或 Hash 压力；
-4. 直接失败条件：同 task 错误日志确认的内存上限、超时、结果限制等最终边界；
-5. 根因层次：当前是否只形成执行层原因链，还是已经通过场景配置把它映射为具体业务计算。
-
-单份失败 Metric 可以说明第 2～4 项中的观测事实，但不能证明第 1 项。只有成功/失败两侧 Metric 都完整，并且同 Operator 能稳定对齐时，才能把输入和输出变化提升为本次触发因素。例如“输入增加，经 Unnest 放大后多产生一批中间行，本次查询又达到内存边界”可以作为执行层贡献原因链；在业务配置缺失或仍有未匹配 Operator 时，不能继续宣称唯一业务根因。
-
-资源阈值是原因链末端，Operator 放大是执行机制，两者都不应单独命名为完整根因。场景诊断应依据 metric comparison 的数值变化与对齐范围组织解释，并由同 task 错误日志确认失败状态。
-
-| Operator 类别 | 常见候选机制 | 至少需要的本次证据 |
-|---|---|---|
-| Source / Scan | IO 慢、文件过多、读取放大、上游等待 | 扫描行列/字节、读取 wall time、任务分布 |
-| Filter / Project / Expression | 表达式计算量、列宽、无法下推 | 输入输出规模、表达式或 PhysicalNode、CPU/专项计时 |
-| Aggregate | 高分组基数、状态膨胀、spill | 输入输出行数、分组/hash 状态、内存或 spill |
-| Join | build 侧过大、输出放大、分支不均 | 两侧规模、hash table、输出规模、连接语义 |
-| Sort / TopN / Window | 排序或窗口状态随数据增长 | 输入规模、排序/窗口配置、内存或 spill |
-| Union / Exchange / Sink | 多分支慢源、网络交换、下游背压 | 所有输入分支、blocked/网络/输出信号 |
-
-表中的机制用于选择检查方向，不能按 Operator 名称直接匹配根因，仍需本次证据确认。例如 Union 本身可能开销很小，也可能暴露某个慢输入或交换等待，不能据此断言“Union 不会成为瓶颈”。
-
-## 推荐分析顺序
-
-1. 确认输入是完整 Metric 还是摘要，先报告任务状态和阶段边界；
-2. 找出少量异常 Pipeline，并区分 wall、blocked、内存的口径；
-3. 读取 Pipeline 中的 Operator 数据规模和专项指标；
-4. 用 plan id 关联 PhysicalNode，说明当前物理计算类型和 Operator 位置；
-5. 将热点与本次数据条件、资源上限和用户现象连接；
-6. 将“已观测事实”“关联判断”和“仍待验证的候选机制”分开表达。
-
-Top N 只用于控制调查优先级，不代表排名靠前的节点已经被证明是根因。
-
-## 如何使用解析结果
-
-先读取紧凑摘要的执行概况与内存排名，再沿报告指针查看相关 Task、Pipeline、Operator 或 JIT 后端。摘要总数与返回数不同，表示展示范围有限；没有进入 Top N 的节点仍可能制造大量中间结果或持有内存。
-
-算子输入输出事实及可复算比例使用 `data_scale_transitions`；缺少输入、单位或匹配依据时，标明不可计算。完整原文保留未知字段与未识别行，解读时须另行确认其含义。字段归属、版本与旧产物复用见[事实产物](metric-artifacts.md)。

package/content/knowledge/engine/performance-patterns.md

@@ -1,86 +0,0 @@
-# 常见引擎性能问题
-
-取得对应执行的材料后，按当前现象查阅相关条目；字段口径见[Metric 解读知识](metric-semantics.md)。本次是否存在这些机制，要用同一执行的记录确认。提出优化建议前，核对业务语义和配置条件；不自动修改资源或重跑任务。
-
-## 调度等待长，执行工作量并不高
-
-查询或 Pipeline 很慢，active CPU 和实际处理量却不高时，先区分在哪一层等待。
-
-核对任务级 queue / wait_resource、Pipeline 的 `morsel_pending_time`、`morsel_blocked_time` 及 open/close。pending 是执行单元等待调度；blocked 是依赖未就绪；任务级资源准入等待又是另一层。只有明确 `not submitted, skip finish` 等记录时，才能说明尚未进入计算。
-
-同口径 pending 较大，支持“调度等待贡献了耗时”的判断，可进一步检查并发提交和资源准入。它无法单独证明 CPU 满载或某个租户抢占资源。提交前失败不套用算子优化。
-
-## 扫描很多，最终只返回少量数据
-
-查看 Scan 的扫描行列、`read_io_file_bytes`、`read_block_time`、`fetch_block_meta_time`、`io_task_pending_time`，再核对 Filter 的输出与本次条件。返回少量结果，也可能先扫描大量数据。
-
-在对应 VFS 读取格式中，read_block_time 记录一批列读取任务从发出到完成的等待，期间还可能获取下一块元信息，因此不能当作纯磁盘时间。io_task_pending_time 记录列读取任务开始运行前的等待，fetch_block_meta_time 记录获取块元信息的计时。这些工作可能重叠，计时不能相加解释总耗时。
-
-计划和实际读取均显示条件在扫描后处理时，可检查过滤下推、裁剪读取列或缩小业务允许的数据范围。已有过滤条件却扫描很多，还需要核对缓存、文件布局和条件选择性，不能直接判定下推失效。
-
-## 表达式或本地计算耗时高
-
-比较同一范围的 active CPU 与 active wall，并核对处理行列数、PhysicalNode 中的表达式及已有专项计时。active CPU 较高说明执行代码消耗了 CPU，具体由哪个 Project 或 Filter 消耗，仍需同一 Pipeline 内的专项证据。
-
-定位到具体表达式及重复计算后，才考虑提前过滤、减少重复表达式或缩小参与计算的列。CPU 不高但 active wall 高时，继续检查同步读取、锁等待和调度干扰；缺少专项计时则保留算子归属未知，不凭名称推荐改写。
-
-## Join 建表状态大或输出放大
-
-通过物理计划确认建表侧、探测侧及各自来源。两侧可能分属不同 Pipeline，不能用页面上的左右表位置判断物理建表/探测方向。
-
-分别查看输入规模、`hash_table_size`、Hash arena、探测输出及连接条件。建表侧状态大时，即使输出很少，也可能消耗大量内存；连接输出增多则可能增加下游排序或窗口压力。hash_table_size 统计具体 Hash 实现的状态项，不能统一当作原表总行数或唯一业务键数。
-
-解释局部放大前，确认同一 Join 的输入输出可比，且连接语义明确。缺少一侧规模或键重复证据时，不命名为 N:N Join。业务允许时，可检查过滤、列裁剪或预聚合，但须保留连接类型、重复键和空值语义。
-
-## 聚合结果少，Hash 状态仍很大
-
-查看具体聚合函数、分组键、`hash_table_size` / capacity、arena，以及预聚合与最终聚合的 main/secondary 状态。即使最终结果行数少，局部状态、可变长键和聚合内容仍可能占用较多空间。
-
-有 `hash_table_size_by_slot` 或 `hash_table_size_by_partition` 时，可以检查同口径状态分布。多个局部 Hash 表中的状态数量不能直接当成全局唯一分组数。只凭总输入行数不能断言高基数。
-
-确认压力来自某组键或聚合状态后，再核对业务是否允许减少分组维度、先过滤或缩小聚合内容。跨层预聚合需验证聚合函数和重复值语义，不能承诺一定减少内存。
-
-## 排序或窗口保存大量中间行
-
-核对排序/窗口的实际输入、保留列、排序键、分区规则、`store_tuple_arena_*` 或 `partition_allocated_*`，以及上游是否产生了更多行。收集状态与输出可以分属不同 Pipeline，最终输出少也可能先保存大量数据。
-
-说明哪个状态持有多少数据，并核对其明确的上游输入。判断某个窗口分区是否较大，需要分区分布证据；窗口总行数不能说明单个分区的大小。
-
-业务和计算语义允许时，可提前执行等价筛选、裁剪状态中不需要的列；确实只需有限结果时，可检查是否适合有限排序。窗口边界、分区、排序和筛选位置的变化都可能改变结果，建议须写清适用前提。
-
-## Spill 降低内存压力，但增加读写成本
-
-Spill 是将可溢写状态转移到临时存储，并在后续读取或合并。排序、聚合、Join、窗口可能提供不同的 spill 字段；按当前 Operator 实际字段解读，不要求每份记录都具备同一组字段。
-
-核对 `spill_hits_count`、`spill_task_count`、`spill_write_io_bytes`、`spill_write_io_cost_time`、读取/合并计时及对应内存状态。写出字节不等于内存峰值；出现 spill 不证明任务失败；spill 为零或字段缺失也不证明系统没有内存压力。
-
-同一执行的 spill 读写及长耗时，可以支持“溢写贡献了工作量”的判断；端到端耗时占比仍需时间线。优化时先检查哪些数据与计算使状态变大，调整 spill 或资源参数则需另有适用依据。
-
-## Exchange 等待或多个 Task 完成不均
-
-按 Stage、Task 和明确的片段关联找到生产端与消费端，查看 `queue_total_wait_time`、`local_queue_total_wait_time`、`finish_total_wait_time`、`wait_another_astro_task_cost`，以及序列化/压缩字节和计时。
-
-发送队列、对端就绪或结束确认的等待，可能由消费慢、其他 Task 晚启动或传输条件引起。判断传输瓶颈需要通信专项记录，不能把这些等待都称为网络慢。
-
-确认 Task 执行同一物理工作、分布条件相同后，比较行数、CPU、pending、blocked 和分区状态。max 明显高于 avg，说明记录中的对象存在差异；是否数据倾斜，还需其他证据。总数相同时，差异仍可能来自调度或机器条件。完整 Metric 文本也可能只包含 Top Stage / 每个 Stage 的代表 Task，应先确认打印覆盖范围，再做全局判断。
-
-确认分区工作量不均后才检查分布键或并行方式；确认消费端慢后优先看消费端状态。提高并行度可能增加局部状态与交换成本，不能作为通用提速建议。
-
-## 优化或编译慢，执行指标却不高
-
-核对任务阶段、`optimizer1_cost` / `optimizer2_cost`、同 task 的 `Slow constant folding`，以及各 `jit_backend[...]` 的 compile 和执行计时。Pipeline 的 build AST、编译、实际执行是不同工作，不能因为 active CPU 低就排除准备阶段慢。
-
-不同后端可能先后执行同一 Pipeline 的部分工作，后端编译与其他执行也可能重叠。llvm_predict_compile_time 是预测值，不能当作已发生的编译耗时。后端字段与 Pipeline 汇总分别查看，不互相覆盖，也不相加成查询总时长。
-
-确认耗时来自昂贵表达式、常量展开或编译后，再检查能否做语义等价的简化，并查看可取得的缓存证据。优化器保护、资源等待时限和业务查询超时需分别解释；增加超时只延长允许等待的时间，不能证明计算会更快。
-
-## 简化示例怎样下结论
-
-以下数字只用于说明判断方式，不作为通用阈值：
-
-| 已有材料 | 可以说明 | 仍不能说明 |
-|---|---|---|
-| Pipeline 墙钟 1 秒；pending 的 max 800 毫秒、sum 6 秒、count 8 | 所记录执行单元存在调度等待，累计量受到并发影响 | 等待占查询耗时 600%，或机器 CPU 已满 |
-| Scan 输出 1400 万行，Filter 输出 9 行，读取字节和读取计时较高 | 本次读取规模远大于最终输出，读取是待核对贡献环节 | 过滤未下推已经被证明，或任意两节点可直接算局部放大率 |
-| 排序收集节点 arena 为 4 GiB，最终只返回 100 行 | 排序相关保存状态仍可能很大，应核对实际输入与列宽 | 可以直接把 LIMIT 提前且结果不变 |
-| Join 输出增多，下游窗口状态增大，同 task 报内存超限 | 有证据支持从数据规模到下游状态与失败边界的执行层解释 | 仅凭这些指标就确认唯一业务根因 |

package/content/knowledge/update/diagnostic/manifest.json

@@ -1,209 +0,0 @@
-{
-  "snapshot": {
-    "id": "analysis-table-update-runtime-v3",
-    "schema_version": "2.0",
-    "purpose": "Interpret version-matched analysis-table update evidence for the no-source frontline consumer through hashed repository-native knowledge indexes."
-  },
-  "publication_state": "published",
-  "artifacts": [
-    {
-      "kind": "analysis-update-scene-inventory",
-      "path": "knowledge/update/diagnostic/scene-index.json",
-      "schema_version": "2.0",
-      "sha256": "9cebf882e0841c9ec618d558ba75574ea1152f483955bf157590eff7b660db56"
-    },
-    {
-      "kind": "analysis-update-observability-lookup",
-      "path": "knowledge/update/diagnostic/observability-index.json",
-      "schema_version": "2.0",
-      "sha256": "8880074f874efac5e9527efdfee98c8098a90b0fe66a19defd77fc20e1e80216"
-    },
-    {
-      "kind": "analysis-update-query-recipes",
-      "path": "knowledge/update/diagnostic/recipe-index.json",
-      "schema_version": "2.0",
-      "sha256": "f40e1eb7c5eb1be674cdbfe9265d706878ae7ca8d75a777cca305e40dcab6c7e"
-    }
-  ],
-  "consumer": {
-    "id": "frontline-no-source-diagnosis",
-    "user_requestable_use_case": "Explain scoped analysis-table update runtime evidence without a product-source checkout."
-  },
-  "source_repository_roles": [
-    {
-      "role": "main-server",
-      "exact_revision_anchor": "git:7b2ad75cc70b6b1ef6db40e73413b9389b784e48",
-      "exact_build_anchor": "gradle-root-version:3.0.0"
-    }
-  ],
-  "deployment_environment_scope": {
-    "environment": "runtime-matched",
-    "service_scope": [
-      "main-server"
-    ],
-    "deployment_scope": "main-server analysis-update dispatch",
-    "scope_limits": "Only a deployment exposing the declared service, source, build, runtime revision, and selected physical evidence contract applies."
-  },
-  "runtime_version_anchors": [
-    {
-      "component": "main-server-dispatch",
-      "version_anchor": "git:7b2ad75cc70b6b1ef6db40e73413b9389b784e48",
-      "evidence_field": "runtime_revision"
-    }
-  ],
-  "captured_at": "2026-09-06T05:50:14Z",
-  "answer_boundaries": {
-    "direct_answer": [
-      "Classify supplied scoped evidence by the published update, chain, node, attempt, load, listener, and engine-task semantics.",
-      "Explain why declared counting units or explicitly verified correlation keys do or do not reconcile."
-    ],
-    "direct_requirements": [
-      "The manifest schema, supported versions, publication state, artifact integrity, consumer, use case, environment, service, deployment scope, and source/build/runtime anchors must match.",
-      "Every selected required physical field must be present, no invalidator may be active, and supplied evidence must prove each requested correlation edge."
-    ],
-    "needs_revalidation": [
-      "Use needs_revalidation for a known unsupported schema or artifact version, a known runtime version mismatch, or confirmed semantic drift of a required field, span, or log signature."
-    ],
-    "unknown": [
-      "Keep unknown when the source, build, runtime version, scope, required evidence, or correlation cannot be confirmed. Directly observed times, identifiers, states, and errors remain reportable; version-dependent behavior and missing relations remain unverified."
-    ],
-    "unsupported": [
-      "Do not infer an asynchronous link, duplicate physical update, or engine task from time proximity, shared tenant, display name, table name, or equal count.",
-      "Do not assert a historical execution, successful physical commit, complete update chain, or root cause from this bundle alone."
-    ]
-  },
-  "observability_evidence_contract": {
-    "required_evidence_fields": [
-      "runtime_revision",
-      "event_timestamp",
-      "event_kind",
-      "update_chain_id",
-      "node_or_execute_id"
-    ],
-    "log_contract": "Current evidence must map the required logical fields and every selected recipe's required physical span, attribute, structured-field, or bounded log signature before interpretation.",
-    "identity_contract": "A chain-to-node relation requires explicit chain and node or execution identity; every asynchronous hop requires a native trace relation or supplied, semantically validated business or execution keys declared by the selected recipe.",
-    "coverage_limits": "The contract does not prove undeclared producer hops, current backend ingestion, complete telemetry coverage, historical execution, physical commit, or root cause."
-  },
-  "permitted_inferences": [
-    "Classify a supplied record with all selected required fields into the declared logical event and counting unit.",
-    "Confirm a scoped relation only when the selected recipe allows the edge and supplied evidence verifies its declared correlation semantics.",
-    "State that units are not comparable when no verified conversion or mapping has been supplied."
-  ],
-  "forbidden_inferences": [
-    "Do not infer causal or asynchronous correlation from nearby time, shared tenant, same name, same table, similar count, or trace adjacency alone.",
-    "Do not infer that request, logical DAG, frontier, attempt, load, listener, engine task, or physical successful commit are the same count.",
-    "Do not infer current backend ingestion, a historical execution, physical commit, complete chain, or incident root cause from this versioned bundle."
-  ],
-  "invalidators": [
-    {
-      "kind": "revision-change",
-      "event": "The declared source revision or build anchor no longer identifies the requested service scope.",
-      "effect": "unknown"
-    },
-    {
-      "kind": "configuration-change",
-      "event": "Effective merge, retry, routing, listener, loading, or observability configuration changes a declared decision boundary.",
-      "effect": "unknown"
-    },
-    {
-      "kind": "evidence-contract-drift",
-      "event": "A required physical signal no longer has the declared production condition or correlation semantics.",
-      "effect": "unknown"
-    },
-    {
-      "kind": "scope-change",
-      "event": "The request targets another consumer, use case, environment, service, deployment, source, or build scope.",
-      "effect": "unknown"
-    }
-  ],
-  "minimal_refresh_recipe": [
-    {
-      "step": "Review the observed behavior, applicable product information and evidence limits.",
-      "current_evidence": "Sanitized examples and confirmed operating conditions."
-    },
-    {
-      "step": "Update affected descriptions and meaningful evidence-processing examples.",
-      "current_evidence": "Entry meanings, field interpretations, correlation boundaries and counterexamples."
-    },
-    {
-      "step": "Validate the complete knowledge set before using it to interpret supplied evidence.",
-      "current_evidence": "Integrity checks and application tests; no automatic promotion of runtime verification."
-    }
-  ],
-  "lineage": {
-    "supersedes": [
-      "analysis-table-update-runtime-v1",
-      "analysis-table-update-runtime-v2"
-    ],
-    "compatibility": "schema-compatible-runtime-revalidation-required"
-  },
-  "evidence_provenance": [
-    {
-      "kind": "source",
-      "artifact_type": "bounded scene inventory and publication evidence anchors",
-      "coverage_limit": "Source validates possible semantics and producer accounting, not a historical runtime execution."
-    },
-    {
-      "kind": "build",
-      "artifact_type": "frozen Gradle root build descriptor",
-      "coverage_limit": "The build anchor identifies the source contract; deployment and runtime identity still require supplied current evidence."
-    },
-    {
-      "kind": "observability",
-      "artifact_type": "source-confirmed physical lookup and backend-neutral query recipes",
-      "coverage_limit": "No SigNoz or other runtime ingestion verification was performed; generated plans remain candidates until current discovery and execution."
-    }
-  ],
-  "safety": {
-    "derived_diagnostic": true,
-    "not_product_authority": true
-  },
-  "source_publication": {
-    "manifest_semantic_digest": "7223b4b4939b850877fcc5760b7aafab906566685204ec4ad755773cb64b6e32",
-    "artifacts": [
-      {
-        "kind": "analysis-update-scene-inventory",
-        "schema_version": "1.0",
-        "sha256": "104603044e639eb18fe5add5b7d143ee849ee90442b6bbb81c7af6e53b82c716"
-      },
-      {
-        "kind": "analysis-update-observability-lookup",
-        "schema_version": "1.0",
-        "sha256": "066096ff5fd6bf26db914c0d6e212881e124a930e10dd69b348bea9dddb812d9"
-      },
-      {
-        "kind": "analysis-update-query-recipes",
-        "schema_version": "1.0",
-        "sha256": "9081e7e889ac13a13d1c2d528f1bfb73dab697fc2ed3cfc7a5f2f61b233d7d8b"
-      }
-    ],
-    "representation": "Validated diagnostic records are stored in small indexed files. These descriptions explain supplied evidence; they do not prove historical execution or runtime ingestion.",
-    "identity_basis": {
-      "revision": "git:7b2ad75cc70b6b1ef6db40e73413b9389b784e48",
-      "build": "gradle-root-version:3.0.0",
-      "artifacts": [
-        {
-          "kind": "analysis-update-scene-inventory",
-          "schema_version": "1.0",
-          "sha256": "104603044e639eb18fe5add5b7d143ee849ee90442b6bbb81c7af6e53b82c716"
-        },
-        {
-          "kind": "analysis-update-observability-lookup",
-          "schema_version": "1.0",
-          "sha256": "066096ff5fd6bf26db914c0d6e212881e124a930e10dd69b348bea9dddb812d9"
-        },
-        {
-          "kind": "analysis-update-query-recipes",
-          "schema_version": "1.0",
-          "sha256": "9081e7e889ac13a13d1c2d528f1bfb73dab697fc2ed3cfc7a5f2f61b233d7d8b"
-        }
-      ],
-      "guide_scope": "analysis-table-update-records"
-    },
-    "previous_publication": {
-      "snapshot_id": "analysis-table-update-runtime-v2",
-      "source_manifest_semantic_digest": "c51a3ff27c1b0a996457dbbcf359c686b7db9bc0dc88789d4a709de13b40c482",
-      "source_revision": "git:3eff76b49c86e4cabf6ce4ac5f670f8c568b7d56"
-    }
-  }
-}

package/content/knowledge/update/diagnostic/observability/edges/edge-attempt-to-capacity-deferral.json

@@ -1,17 +0,0 @@
-{
-  "edge_id": "edge-attempt-to-capacity-deferral",
-  "graph_kind": "execution",
-  "from_lookup_id": "analysis-update-attempt-consumed",
-  "to_lookup_id": "analysis-update-capacity-deferred",
-  "from_unit": "execution-attempt",
-  "to_unit": "requeue",
-  "semantics": "An attempt that cannot obtain a tenant permit publishes the same detail to the slow route before node work.",
-  "correlation_keys": [
-    "execution detail ID",
-    "tenant ID"
-  ],
-  "correlation_status": "source-confirmed-payload",
-  "durability": "message-lifetime",
-  "asynchronous": true,
-  "coverage_limit": "The deferral has no independent requeue ID."
-}

package/content/knowledge/update/diagnostic/observability/edges/edge-attempt-to-lock-requeue.json

@@ -1,18 +0,0 @@
-{
-  "edge_id": "edge-attempt-to-lock-requeue",
-  "graph_kind": "execution",
-  "from_lookup_id": "analysis-update-attempt-consumed",
-  "to_lookup_id": "analysis-update-lock-requeued",
-  "from_unit": "execution-attempt",
-  "to_unit": "requeue",
-  "semantics": "A node-running lock timeout republishes the same execution detail to the main queue.",
-  "correlation_keys": [
-    "execution detail ID",
-    "node table ID",
-    "update chain ID"
-  ],
-  "correlation_status": "source-confirmed-payload",
-  "durability": "message-lifetime",
-  "asynchronous": true,
-  "coverage_limit": "No attempt or requeue ID is added."
-}

package/content/knowledge/update/diagnostic/observability/edges/edge-attempt-to-merge.json

@@ -1,17 +0,0 @@
-{
-  "edge_id": "edge-attempt-to-merge",
-  "graph_kind": "execution",
-  "from_lookup_id": "analysis-update-attempt-consumed",
-  "to_lookup_id": "analysis-update-merge-decision",
-  "from_unit": "execution-attempt",
-  "to_unit": "merge-decision",
-  "semantics": "An attempt holding the node lock queries eligible same-node frontier details and selects a merge result.",
-  "correlation_keys": [
-    "execution detail ID",
-    "node table ID"
-  ],
-  "correlation_status": "source-confirmed-in-process",
-  "durability": "execution-scope",
-  "asynchronous": false,
-  "coverage_limit": "No merge-decision ID is persisted."
-}

package/content/knowledge/update/diagnostic/observability/edges/edge-candidate-to-effective-root.json

@@ -1,16 +0,0 @@
-{
-  "edge_id": "edge-candidate-to-effective-root",
-  "graph_kind": "logical",
-  "from_lookup_id": "analysis-update-candidate-root-filter",
-  "to_lookup_id": "analysis-update-effective-root-selection",
-  "from_unit": "candidate-root",
-  "to_unit": "effective-root",
-  "semantics": "Entry eligibility and ancestor reduction determine whether a candidate remains an effective root.",
-  "correlation_keys": [
-    "table ID within the same dispatch invocation"
-  ],
-  "correlation_status": "source-confirmed-in-process",
-  "durability": "not-durable",
-  "asynchronous": false,
-  "coverage_limit": "Filtered candidates are not stored as a durable ledger."
-}

package/content/knowledge/update/diagnostic/observability/edges/edge-capacity-deferral-to-attempt.json

@@ -1,16 +0,0 @@
-{
-  "edge_id": "edge-capacity-deferral-to-attempt",
-  "graph_kind": "execution",
-  "from_lookup_id": "analysis-update-capacity-deferred",
-  "to_lookup_id": "analysis-update-attempt-consumed",
-  "from_unit": "requeue",
-  "to_unit": "execution-attempt",
-  "semantics": "When capacity is available, the slow consumer republishes the same detail to the main queue for a later attempt.",
-  "correlation_keys": [
-    "execution detail ID"
-  ],
-  "correlation_status": "source-confirmed-payload",
-  "durability": "message-lifetime",
-  "asynchronous": true,
-  "coverage_limit": "Intermediate slow-queue cycles are requeues, not main-consumer attempts."
-}

package/content/knowledge/update/diagnostic/observability/edges/edge-chain-node-to-execution-detail.json

@@ -1,18 +0,0 @@
-{
-  "edge_id": "edge-chain-node-to-execution-detail",
-  "graph_kind": "logical-to-execution",
-  "from_lookup_id": "analysis-update-effective-root-selection",
-  "to_lookup_id": "analysis-update-execution-frontier-persisted",
-  "from_unit": "dag-node",
-  "to_unit": "execution-detail",
-  "semantics": "Each effective root is materialized as one transient frontier detail for its chain context.",
-  "correlation_keys": [
-    "update chain ID",
-    "node table ID",
-    "execution detail ID"
-  ],
-  "correlation_status": "source-confirmed-durable",
-  "durability": "frontier-lifetime",
-  "asynchronous": false,
-  "coverage_limit": "Details are later deleted and do not form a permanent node history."
-}

package/content/knowledge/update/diagnostic/observability/edges/edge-dlx-recovery-to-attempt.json

@@ -1,16 +0,0 @@
-{
-  "edge_id": "edge-dlx-recovery-to-attempt",
-  "graph_kind": "execution",
-  "from_lookup_id": "analysis-update-dlx-recovery",
-  "to_lookup_id": "analysis-update-attempt-consumed",
-  "from_unit": "requeue",
-  "to_unit": "execution-attempt",
-  "semantics": "Dead-letter recovery republishes the same detail to the main queue after execution availability returns.",
-  "correlation_keys": [
-    "execution detail ID"
-  ],
-  "correlation_status": "source-confirmed-payload",
-  "durability": "message-lifetime",
-  "asynchronous": true,
-  "coverage_limit": "The recovery cycles and later attempt have no independent IDs."
-}

package/content/knowledge/update/diagnostic/observability/edges/edge-effective-execution-to-listener-before.json

@@ -1,21 +0,0 @@
-{
-  "edge_id": "edge-effective-execution-to-listener-before",
-  "graph_kind": "side-effect",
-  "from_lookup_id": "analysis-update-merge-decision",
-  "to_lookup_id": "analysis-update-listener-invocation",
-  "from_unit": "dag-node",
-  "to_unit": "listener-invocation",
-  "callback_phases": [
-    "onBefore"
-  ],
-  "semantics": "After merge selects an effective node task, each selected named listener receives onBefore before parent-failure evaluation and node work; no primary node result exists yet.",
-  "correlation_keys": [
-    "update chain or merged-chain context",
-    "node table ID",
-    "listener name and onBefore phase"
-  ],
-  "correlation_status": "source-confirmed-in-process",
-  "durability": "listener-specific",
-  "asynchronous": false,
-  "coverage_limit": "This edge does not carry a node-primary-result and does not prove that later node work succeeds."
-}