@fx-data/ai-diagnostics 0.1.20261026070913 → 0.1.20261107142011

package/content/knowledge/signal-index.md

@@ -0,0 +1,117 @@
+# 信号索引
+
+按名称找到 span、属性、日志或报错的含义在哪一节，只读那一节。只收常用的；没收录的直接在 `knowledge/` 里搜。同名信号在多个场景出现时各列一行。
+
+## 目录
+
+- [常见报错](#常见报错)
+- [更新](#更新)
+- [分析表](#分析表)
+- [组件](#组件)
+- [仪表板](#仪表板)
+- [引擎](#引擎)
+- [通用](#通用)
+
+## 常见报错
+
+报错只说明撞上了什么，不等于根因：查完回到这次请求所在场景的 `workflow.md` 找业务原因。
+
+| 名称 | 是什么 | 说明在哪 |
+|---|---|---|
+| `MemoryLimitExceeded`、`MemInsufficientException` | 引擎内存撞到上限，是失败条件，不是根因 | [按现象决定先查什么](common/topics/start-and-anchors.md#按现象决定先查什么)、[内存信号](engine/signals.md#内存信号)、[取数结果与失败](component/signals.md#取数结果与失败) |
+| `polars query timeout`、`QueryTimeOutException` | 业务层等引擎查询超时；先找回这次的 task 再看 Metric | [易错点](common/workflow.md#易错点)、[取数结果与失败](component/signals.md#取数结果与失败) |
+| `Task execution timeout after` | 引擎优化阶段超时，业务层随后报 `polars query timeout`；多半是查询太大，回场景找是什么让它变大 | [任务与 Pipeline](engine/signals.md#任务与-pipeline)、[查询规模信号](engine/signals.md#查询规模信号) |
+| `not submitted, skip finish` | 提交前就失败或取消了，引擎没开始算 | [易错点](common/workflow.md#易错点) |
+| `TaskCancelledException`、`TableInvalidException`、`NoSuchEntryInfoException` | 任务被取消、表暂不可用、表不存在，和计算快慢无关 | [取数结果与失败](component/signals.md#取数结果与失败) |
+| `is invalid`、`propagate red mark`、`TableRedMarkPreLoadValidator` | 更新时报某张表 invalid：上游表自己出错，本表被连带标红，没进入计算 | [上游出错连带失败](update/signals.md#上游出错连带失败) |
+| `col size over limit`、`column_size_over` | 分析表某一步输出的列数超过上限（目前 400 列），更新在检查阶段就失败并被标红，下游跟着连带失败；配置问题，要减少字段或拆表 | [上游出错连带失败](update/signals.md#上游出错连带失败) |
+| `formulaStr {} has error` | 公式校验不通过，常见是引用的字段或参数已不存在、改了名；配置问题 | [上游出错连带失败](update/signals.md#上游出错连带失败) |
+| `select operator not found parentTable` | 选字段步骤配的上游表找不到了（被删除或已不可见），这一步按原字段名当文本字段继续，不一定导致失败；同一张表反复出现时，查这张上游表的状态 | [步骤类型对照](dataset/topics/steps.md#步骤类型对照) |
+| `AggregateSignature not found` | 对文本、日期等字段做了引擎不支持的聚合（如求和），是配置问题 | [常见引擎报错](engine/signals.md#常见引擎报错) |
+| `TABLE_VERSION_NOT_FOUND` | 要读的表版本在引擎里已经没有了，查这张表出错前后的更新 | [常见引擎报错](engine/signals.md#常见引擎报错) |
+| `dax parse too slow`、`end get parent` | 日志正文：查询语句多长、牵涉多少张表，判断查询是不是被展开得过大 | [查询规模信号](engine/signals.md#查询规模信号) |
+| `retry executor:QueryExecutor` | 引擎查询失败后自动重试，最多 3 次、间隔 5 秒；总耗时长可能全是重试等待 | [查询失败重试](engine/signals.md#查询失败重试) |
+| `NoFieldFoundException`、`NoParameterFoundException`、`IllegalTableMarkedException` | 字段或参数已不存在、表被标红，属于配置问题 | [取数结果与失败](component/signals.md#取数结果与失败) |
+| `JoinN2NException` | 关联出现多对多 | [取数结果与失败](component/signals.md#取数结果与失败) |
+| `updating` | 组件取数时底层表正在更新，没返回结果 | [取数结果与失败](component/signals.md#取数结果与失败) |
+| `task exec error`、`table load fail` | 更新节点失败、加载失败 | [primary-node-result](update/topics/events-outcome.md#primary-node-result)、[load-operation](update/topics/events-outcome.md#load-operation) |
+| `Task is failed by its parent failed`、`dependence failed` | 同一条链里上游节点失败，本节点没执行就跟着失败；沿 `fail parent` 往上找第一张自己报错的表 | [上游出错连带失败](update/signals.md#上游出错连带失败) |
+| `record failed`、`peakMem` | 更新失败后记到表上的指标：`peakMem-3` 是内存超限失败，`-1` 是其他错误 | [上游出错连带失败](update/signals.md#上游出错连带失败) |
+| `Tenant limit exceeded`、`resend execute info` | 租户额度用完转慢队列、等锁超时重派；都不是最终失败 | [capacity-deferred](update/topics/events-execution.md#capacity-deferred)、[lock-requeued](update/topics/events-execution.md#lock-requeued) |
+
+## 更新
+
+| 名称 | 是什么 | 说明在哪 |
+|---|---|---|
+| `dispatch_submit` | 受理一次更新请求，属性 `dagId`、`totalSize`、`updateScene` | [intent-accepted](update/topics/events-intake.md#intent-accepted) |
+| `dispatch_gen_roots` | 选根，候选多于 1 张时才有 | [effective-root-selection](update/topics/events-intake.md#effective-root-selection) |
+| `dispatch_get_ancestors`、`dispatch_get_descendants` | 查祖先、查下游 | [logical-dependency-expansion](update/topics/events-intake.md#logical-dependency-expansion) |
+| `node-task-queue receive` | 主队列投递一次，就是一次消费尝试 | [attempt-consumed](update/topics/events-execution.md#attempt-consumed) |
+| `update` | 消费一次投递的根 span，另开独立 trace；节点结果属性写在它上面 | [attempt-consumed](update/topics/events-execution.md#attempt-consumed)、[primary-node-result](update/topics/events-outcome.md#primary-node-result) |
+| `slow-node-task-queue receive` | 租户并发超限，消息转到慢队列 | [capacity-deferred](update/topics/events-execution.md#capacity-deferred) |
+| `dispatch_node_task_exec` | 节点真正执行的区间，加载日志的 `span_id` 指向它 | [一次执行的 span 结构](update/topics/lifecycle.md#一次执行的-span-结构) |
+| `trigger_listener_<监听器名>` | 监听器回调，一个节点里同名出现 3 次 | [listener-invocation](update/topics/events-outcome.md#listener-invocation) |
+| `dispatch_callback_children`、`evaluator_child` | 释放子节点、判断子节点能否执行 | [child-release](update/topics/events-outcome.md#child-release) |
+| `DataFlowExecutor` | 引擎写入（更新的物理写入），其下是 `execute` | [engine-handoff](update/topics/events-outcome.md#engine-handoff) |
+| `dagId` | 更新链 ID | [先记住的几个概念](update/topics/lifecycle.md#先记住的几个概念) |
+| `loadData`、`loadDataSkipReason`、`dataModify`、`execution.mode` | 这次有没有加载、为什么没加载、数据是否变化、写入方式 | [load-decision](update/topics/events-outcome.md#load-decision) |
+| `rowCount`、`updateType`、`rootErrorId`、`dispatchConsumed`、`businessConsumed` | 节点结果属性（行数、更新场景、失败根表、两段耗时） | [primary-node-result](update/topics/events-outcome.md#primary-node-result) |
+| `merge_count`、`wait_merge_time` | 合并了多条明细时才有 | [merge-decision](update/topics/events-execution.md#merge-decision) |
+| `corpId` | 企业 ID，队列 span 总有，`update` 上只有执行过的才有 | [attempt-consumed](update/topics/events-execution.md#attempt-consumed) |
+| `linked` | `update` 上保存放出它的上游 trace ID | [独立 Trace 的显式链接](common/topics/linked-traces.md#独立-trace-的显式链接) |
+| `handle nodeTaskId` | 日志：主队列消费一条消息，在拿额度之前就打 | [attempt-consumed](update/topics/events-execution.md#attempt-consumed) |
+| `Tenant limit exceeded` | 日志：租户额度用完，转慢队列 | [capacity-deferred](update/topics/events-execution.md#capacity-deferred) |
+| `resend execute info` | 日志：等锁超时，重新发回主队列 | [lock-requeued](update/topics/events-execution.md#lock-requeued) |
+| `merge isolationMode` | 日志：每次拿锁后的合并判断 | [merge-decision](update/topics/events-execution.md#merge-decision) |
+| `table load start`、`table load success`、`table load fail` | 日志：一次加载的开始、结束与耗时 | [load-operation](update/topics/events-outcome.md#load-operation) |
+| `[ResultBinding]`、`[Snapshot tag`、`[ResultRetention]`、`skip write (SHARED_RESULT)` | 日志：引用已有结果（REF）时的提交、保护 tag 和旧版本释放 | [result-publish](update/topics/events-outcome.md#result-publish) |
+| `finish to exec task`、`task exec error` | 日志：节点成功、失败 | [primary-node-result](update/topics/events-outcome.md#primary-node-result) |
+| `dispatch callback children` | 日志：这次保存的子节点明细数 | [child-release](update/topics/events-outcome.md#child-release) |
+
+## 分析表
+
+| 名称 | 是什么 | 说明在哪 |
+|---|---|---|
+| `operatorsPage`、`analysis.operatorsFields`、`analysis.operatorsPageCount`、`stepPage.stepDataPreview` | 预览分页、字段、行数、按稳定 stepId 预览 | [场景识别](dataset/signals.md#场景识别) |
+| `tableId`、`tableName`、`selectIndex`、`subselectIndex`、`operatorType` | 预览关联的表、选中的步骤和步骤类型 | [信号含义](dataset/signals.md#信号含义)、[步骤类型对照](dataset/topics/steps.md#步骤类型对照) |
+| `grammarCheck`、`dataModel`、`createCacheTable`、`tryGetRowCount` | 预览各阶段：语法检查、取数主体、写缓存表、取行数 | [预览的阶段](dataset/signals.md#预览的阶段) |
+| `optimizeUsingCache`、`hit_operator_type`、`hit_operator_index`、`used_cache_table` | 是否命中已缓存的步骤结果，命中的步骤 | [预览的阶段](dataset/signals.md#预览的阶段) |
+| `checkUpdatePolars`、`markActive`、`activeScene`、`updateRoots` | 引擎查询前的活跃检查，必要时触发 `ACTIVE` 更新 | [活跃检查](dataset/signals.md#活跃检查) |
+
+## 组件
+
+| 名称 | 是什么 | 说明在哪 |
+|---|---|---|
+| `editComponent`、`previewComponent`、`queryData`、`getComponentMatrixData` | 图表编辑时的取数、仪表板组件预览的组件计算、通用查询、矩阵取数 | [场景识别](component/signals.md#场景识别) |
+| `data.endpoint`、`data.request_context`、`component.id`、`component.type`、`component.query.table_id` | 入口类型、请求来源（仪表板，或仪表板以外的图表预览）、组件与绑定表 | [场景识别](component/signals.md#场景识别)、[仪表板组件预览入口](common/signals.md#仪表板组件预览入口) |
+| `data.component.checkPublishedTableStatus`、`data.component.buildControlContext`、`data.component.analyzeControlContext`、`data.component.executeRequest` | 组件计算的阶段 | [组件计算的阶段](component/signals.md#组件计算的阶段) |
+| `result.status`、`error.class` | 取数结果（success、empty、updating、error）与失败的根因类名 | [取数结果与失败](component/signals.md#取数结果与失败) |
+
+## 仪表板
+
+| 名称 | 是什么 | 说明在哪 |
+|---|---|---|
+| `dashboard.controlData`、`data.control.calculateOptions`、`data.control.engineExecute`、`data.control.validateSourceTables` | 筛选器候选值的 span 结构 | [场景识别](dashboard/signals.md#场景识别) |
+| `FilterConditionsBuilder.build` | 构建筛选条件树 | [场景识别](dashboard/signals.md#场景识别)、[筛选树还原与交付](dashboard/topics/filter-tree.md) |
+| `control.query.mode`、`control.query.unbounded`、`control.query.fetch_limit`、`control.query.output_rows`、`control.option_source.truncated` | 候选值取数方式、是否无上限、实际返回量 | [筛选器候选值请求的属性](dashboard/signals.md#筛选器候选值请求的属性) |
+| `controls.effect_count`、`controls.valued_effect_count`、`calculation_context.has_auto_linkage`、`component.linkage.depth`、`component.query_count` | 仪表板内组件请求带入的筛选器、联动、权限上下文 | [信号含义](dashboard/signals.md#信号含义) |
+| `tree_summary` | 最终筛选树的摘要 | [筛选树还原与交付](dashboard/topics/filter-tree.md) |
+| `controls.binding_info`、`dynamic_field_count` | 筛选器绑定摘要、动态字段覆盖计数 | [动态字段覆盖与上游展开](dashboard/topics/dynamic-fields.md) |
+
+## 引擎
+
+| 名称 | 是什么 | 说明在哪 |
+|---|---|---|
+| `taskName`、`metric`、`polars.taskId`、`QueryExecutor`、`v2.execute.query` | trace 上的引擎任务标识与统计链接 | [已有 trace 时取哪些字段](engine/queries.md#已有-trace-时取哪些字段) |
+| `elapsed_time`、`optimizer_cost`、`query_memory_limit`、`morsel_blocked_time`、`scanned_rows_num`、`table_scan_cache_result_queue_size` | MPP Metric 各层字段：任务总耗时、优化耗时、内存上限、执行单元挂起、读表行数、读表瓶颈 | [Metric 字段速查](engine/topics/metric-fields.md) |
+| `MetricOuts` | 引擎统计日志的 logger，按 task 和时间窗取 | [Metric 链接与任务日志](engine/queries.md#metric-链接与任务日志) |
+| `queryCount`、`rowCount`（查询埋点） | V1 查询埋点：尝试序号、返回行数的口径 | [V1 查询埋点与完成边界](engine/queries.md#v1-查询埋点与完成边界) |
+| `compute.retry.pipeline_parallelism_reduced` | 数据源湖写入内存不足后降并行度重试 | [更新 Write 链路](engine/queries.md#更新-write-链路) |
+
+## 通用
+
+| 名称 | 是什么 | 说明在哪 |
+|---|---|---|
+| `http.route` | HTTP 入口；SigNoZ 里带部署上下文路径，如 `/decision` | [识别方法](common/signals.md#识别方法) |
+| `scope_name`、`logger.name`、`exception.type`、`severity_text` | 日志字段：业务服务的类名、引擎的类名、异常类型、级别 | [查日志](common/queries.md#查日志) |
+| `service.name` | 查询时优先下推的服务过滤；各环境的取值 | [后端子环境](common/concepts.md#fx-data-server-后端子环境)、[查询约束](common/queries.md#查询约束) |

package/content/knowledge/update/README.md

@@ -0,0 +1,39 @@
+# 更新知识
+
+分析表更新（dispatch）：`UpdateScene` 场景标签、调度链路上的逻辑事件与信号、允许的关联边，以及取证配方。
+
+## 槽位
+
+每个知识域都按同样的槽位组织。按要做的事选槽位，只读命中的章节。
+
+| 要做什么 | 读 | 包含 |
+|---|---|---|
+| 这类问题从哪里入手 | [workflow.md](workflow.md) | 更新排查入口：解释更新记录、更新性能排查、常见现象的候选假设 |
+| 弄清概念是什么、怎么关联 | [concepts.md](concepts.md) | 计数单位与身份（request、chain、节点、尝试…）；`UpdateScene` 全部场景及其行为影响 |
+| 认出入口，看懂 span、attribute、日志和字段 | [signals.md](signals.md) | 认出更新入口；使用规则；20 个逻辑事件的索引 |
+| 看完日志和 trace，能下什么结论 | [conclusions.md](conclusions.md) | 知识的适用范围；关联、计数与返回规则 |
+| 写查询、选取证路径 | [queries.md](queries.md) | SigNoZ 查询线索，以及五个取证配方（scene-origin、table-history、table-in-chain、dag-chain、performance-window） |
+
+## 选配方
+
+按已有输入（场景、表、链、dagId）选取证配方，见 [queries.md · 选哪个配方](queries.md#选哪个配方)。
+
+已有 trace 时直接按精确 trace/必要 span 和服务补当前字段；只有对象/链时先用已确认时间和公共默认范围寻找有限候选。时间规则、企业更新、DAG 回退与查询预算见[公共规则](../common/queries.md)。查询意图、字段和范围明确后，由助手按当前 MCP 工具声明执行。
+
+## 展开明细
+
+| 文件 | 何时读 | 内容 |
+|---|---|---|
+| [topics/lifecycle.md](topics/lifecycle.md) | 想先弄清一次更新怎么走完、每一步在 SigNoZ 里是什么样时 | 过程总览、span 结构、读 trace 的常见坑 |
+| [topics/scene-producers.md](topics/scene-producers.md) | 已知场景、要找触发入口时 | 按场景列出的触发入口明细 |
+| [topics/events-intake.md](topics/events-intake.md) | 查受理、选根、依赖展开、明细落库、提交后发布的信号时 | 受理与入队阶段的 6 个事件 |
+| [topics/events-execution.md](topics/events-execution.md) | 查消费尝试、限流与锁超时重排队、恢复、合并判断的信号时 | 消费、重排队与合并阶段的 7 个事件 |
+| [topics/events-outcome.md](topics/events-outcome.md) | 查 load、引擎交接、节点主结果、监听器、子节点释放的信号时 | load、引擎与结果阶段的 7 个事件 |
+| [topics/discover-executions.md](topics/discover-executions.md) | 只有企业 ID 或 dagId、还没定位到更新执行，或要确定企业、dagId 的检索时间窗时 | 从企业或 DAG 定位更新执行；检索时间 |
+| [topics/correlations.md](topics/correlations.md) | 核对异步关联或拆分耗时时 | 允许的关联边与 12 个性能片段 |
+
+## 关联
+
+- 相关知识域：[引擎](../engine/README.md)：更新写入阶段的 Metric
+- 相关知识域：[分析表](../dataset/README.md)：预览读取更新产物时
+- 相关知识域：[通用](../common/README.md)：企业更新与 dagId 的默认值

package/content/knowledge/update/concepts.md

@@ -0,0 +1,93 @@
+# 更新 · 概念与关联
+
+回答“这是什么、彼此怎么关联”。包括更新请求、chain、节点、尝试等计数单位，以及 `UpdateScene` 场景标签。
+
+## 计数单位与身份
+
+不同单位不可互相换算；报告计数时先声明单位。“原生 ID”是系统里真实存在的标识，“无”表示没有，只能靠时间、明细 ID 等间接推断。
+
+| 单位 | 原生 ID | 指什么 | 怎么数 | 不能当作 |
+|---|---|---|---|---|
+| `update-request` | 无 | 业务模块一次“请求更新”的调用 | 按调用次数数，包括没有产生任何明细的调用 | 更新链 ID、触发 ID、trace ID |
+| `candidate-root` | 表 ID | 一次请求里提交的一张候选表（过滤和合并之前） | 过滤前按候选表逐张数 | 有效根的个数、逻辑节点的个数 |
+| `effective-root` | 链 ID、表 ID | 一条链选出的根表（祖先不在候选里的才是根） | 过滤并选根之后的个数 | 候选根的个数、执行明细的个数 |
+| `update-chain` | 链 ID（`dagId`） | 受理一次请求后生成的更新链 | 数不同的链 ID；没有产生明细的链也算 | 请求 ID、尝试 ID |
+| `dag-node` | 表 ID，加链 ID（或合并链集合） | 一条链（或合并后的链）里的一张逻辑表节点 | 按不同的逻辑表节点数，与明细和尝试分开 | 明细 ID、引擎任务 ID |
+| `logical-dag-edge` | 无 | 一条链里当前的一对父子依赖 | 按“父表—子表”对数，现查的血缘不能代表历史 | 不带链范围的表对、明细 ID |
+| `execution-detail` | 明细 ID | 一个节点在一条链里的待执行记录 | 数创建的明细行；执行完会删除，不是历史台账 | 尝试 ID、加载 ID |
+| `queue-publication` | 无 | 向队列发布一条消息的操作 | 根节点、子节点、重排队、巡检、死信补发都各算一次，与 broker 投递分开 | 明细 ID、尝试 ID |
+| `execution-attempt` | 无 | 主队列对某条明细的一次投递（被消费者处理） | 数主队列投递次数；同一明细重复投递是多次尝试，不是新明细 | 明细 ID、链 ID、节点 ID |
+| `requeue` | 无 | 因限流、锁超时、补发巡检、等待恢复或死信恢复而发生的一次重新发布 | 按分支分别数，不要当作完成了的节点尝试 | 明细 ID、尝试次数 |
+| `merge-decision` | 无 | 一次尝试拿到节点锁之后做的同节点合并判断 | 每次判断算一次，无论选中 0 个、1 个还是多个成员 | 链 ID、明细 ID、加载 ID |
+| `load-decision` | 无 | 一次有效节点执行选择“失败、直通、跳过、复用、不加载或调用加载” | 每个合并后的有效执行算一次，先于任何物理工作 | 尝试 ID、加载 ID、引擎任务 ID |
+| `load-operation` | 无 | 决定加载后，一次进入表类型加载逻辑的调用 | 数发起的加载调用，包括失败的；直通、不活跃、不需要加载的不算 | 节点 ID、引擎任务 ID |
+| `result-publish` | 无 | 一次把本表读取位置换到新结果的提交，含选版本、打 tag、释放旧版本 | 按 `[ResultBinding] event=COMMIT_RESULT` 数，`committed=false` 的也算 | 加载 ID、引擎任务 ID |
+| `engine-task` | 引擎任务 ID | 一次引擎写入尝试创建的 Polars 写任务 | 只数服务端真正创建了写任务的；不加载的结果没有引擎任务 | 加载 ID、明细 ID |
+| `node-primary-result` | 无 | 一次有效节点执行得出的成功或失败主结果（释放子节点之前） | 每个合并后的有效执行算一次，与监听器结果、按表看的最新状态分开 | 链 ID、明细 ID、监听器调用 ID |
+| `listener-invocation` | 无 | 一个监听器在一个节点结果上的一次回调阶段 | 按监听器名加阶段数；`onComplete` 是节点完成，不是整条链完成 | 链 ID、节点 ID |
+
+## 更新场景（UpdateScene）
+
+`UpdateScene` 是每次更新请求携带的来源标签（整数 `type` 随任务序列化，发布后保持稳定）。它决定合并模式，也影响父表就绪检查、权限通知和是否 load。用户说的“活跃”“定时”“手动更新”等，多半就是这个标签。
+
+### 场景会改变什么行为
+
+- **合并模式**：`DEFAULT`、`SCHEDU`、`GLOBAL`、`CORP_LINKED`、`DYNAMIC_TIME` 默认 `ALLOW_MERGE`，同一节点的多次请求可合并为一次执行；其余场景 `FORBIDDEN_MERGE`，每个请求独立执行。
+  怎么认出合并见[merge-decision 事件](topics/events-execution.md#merge-decision)。
+- **父表就绪检查**（`checkParentIsSync`）：`ACTIVE`、`CASE_INSTALL`、`ROLLBACK`、`PARAM_CHANGE` 在刷新当前表配置前检查父表是否就绪。父表未就绪时保留当前的表配置，不能当作已完成刷新。
+- **权限通知**（`requiresPermissionNotification`）：`AUTH_CHANGE`、`CATALOG_DATA_PERMISSION_CHANGE`，客户端需要刷新权限相关展示。
+- **未知 type**：`getUpdateScene` 对不认识的整数回退为 `DEFAULT`，日志里的 type 与枚举对不上时先确认版本。
+- **`NoUpdateIfExist`**：load 只在 Polars 中没有结果时执行，见下表。
+
+### 全部场景
+
+各场景的触发入口见[场景入口明细](topics/scene-producers.md)；其中没有找到触发入口、或仅为兼容旧数据保留的场景也在那里标明。
+
+| type | 场景 | 含义 | 默认合并 |
+|---|---|---|---|
+| 0 | [`DEFAULT`](topics/scene-producers.md#default) | 默认（未细分的强制 / 立即更新） | ALLOW_MERGE |
+| 1 | [`EDIT`](topics/scene-producers.md#edit) | 编辑保存 | FORBIDDEN_MERGE |
+| 2 | [`ACTIVE`](topics/scene-producers.md#active) | 活跃（表激活或预览要求未活跃依赖刷新） | FORBIDDEN_MERGE |
+| 3 | [`SCHEDU`](topics/scene-producers.md#schedu) | 定时 | ALLOW_MERGE |
+| 4 | [`FOLDER_COPY`](topics/scene-producers.md#folder_copy) | 项目复制 | FORBIDDEN_MERGE |
+| 5 | [`CASE_INSTALL`](topics/scene-producers.md#case_install) | 案例应用 | FORBIDDEN_MERGE |
+| 6 | [`CASE_REPLACE`](topics/scene-producers.md#case_replace) | 案例替换 | FORBIDDEN_MERGE |
+| 7 | [`ROLLBACK`](topics/scene-producers.md#rollback) | 回收站恢复 | FORBIDDEN_MERGE |
+| 8 | [`ADD`](topics/scene-producers.md#add) | 添加 / 新建表 | FORBIDDEN_MERGE |
+| 9 | [`EXCEL_SAVE`](topics/scene-producers.md#excel_save) | excel 编辑、追加等 | FORBIDDEN_MERGE |
+| 10 | [`PREVIEW_EXCEPTION`](topics/scene-producers.md#preview_exception) | 预览异常 | FORBIDDEN_MERGE |
+| 11 | [`PARAM_CHANGE`](topics/scene-producers.md#param_change) | 参数改变 | FORBIDDEN_MERGE |
+| 12 | [`POLARS_ERROR`](topics/scene-producers.md#polars_error) | OOM 等编辑进入后自动触发 | FORBIDDEN_MERGE |
+| 13 | [`MANUAL_UPDATE`](topics/scene-producers.md#manual_update) | 手动更新（用户主动触发） | FORBIDDEN_MERGE |
+| 14 | [`GLOBAL`](topics/scene-producers.md#global) | 全局更新 | ALLOW_MERGE |
+| 15 | [`REPLACE`](topics/scene-producers.md#replace) | 替换表 | FORBIDDEN_MERGE |
+| 16 | [`HANDOVER`](topics/scene-producers.md#handover) | 交接 | FORBIDDEN_MERGE |
+| 17 | [`DEL`](topics/scene-producers.md#del) | 删除数据带起的更新 | FORBIDDEN_MERGE |
+| 18 | [`COPY_DATA`](topics/scene-producers.md#copy_data) | 复制数据 | FORBIDDEN_MERGE |
+| 19 | [`CORP_LINKED`](topics/scene-producers.md#corp_linked) | 企业表更新连带的团队表更新 | ALLOW_MERGE |
+| 20 | [`CALL_BACK`](topics/scene-producers.md#call_back) | 数知鸟 / jdy 推送 | FORBIDDEN_MERGE |
+| 21 | [`ARCHIVE`](topics/scene-producers.md#archive) | 存档 | FORBIDDEN_MERGE |
+| 22 | [`AUTH_CHANGE`](topics/scene-producers.md#auth_change) | 权限变更 | FORBIDDEN_MERGE |
+| 23 | [`DYNAMIC_TIME`](topics/scene-producers.md#dynamic_time) | 动态时间 | ALLOW_MERGE |
+| 24 | [`SAVE_AS`](topics/scene-producers.md#save_as) | 另存为 | FORBIDDEN_MERGE |
+| 25 | [`COMPUTE_MODEL`](topics/scene-producers.md#compute_model) | 计算模型 | FORBIDDEN_MERGE |
+| 26 | [`PREVIEW_INVALID`](topics/scene-producers.md#preview_invalid) | 预览主页标红但有数据 | FORBIDDEN_MERGE |
+| 27 | [`CORP_SETTING`](topics/scene-producers.md#corp_setting) | 企业属性配置修改 | FORBIDDEN_MERGE |
+| 28 | [`CORP_SETTING_MEMBER_RENAME`](topics/scene-producers.md#corp_setting_member_rename) | 企业属性（成员重命名） | FORBIDDEN_MERGE |
+| 29 | [`CDC_SCHEDULE`](topics/scene-producers.md#cdc_schedule) | 简道云 CDC | FORBIDDEN_MERGE |
+| 30 | [`EXCEL_APPEND`](topics/scene-producers.md#excel_append) | excel 追加 | FORBIDDEN_MERGE |
+| 31 | [`RE_CHECK`](topics/scene-producers.md#re_check) | 重回队列 | FORBIDDEN_MERGE |
+| 32 | [`CORP_MEMBER_ADD`](topics/scene-producers.md#corp_member_add) | 新增成员（计算自定义字段、添加 holder 成员） | FORBIDDEN_MERGE |
+| 33 | [`CORP_MEMBER_DEL`](topics/scene-producers.md#corp_member_del) | 删除成员（计算自定义字段） | FORBIDDEN_MERGE |
+| 34 | [`CORP_MEMBER_MODIFY`](topics/scene-producers.md#corp_member_modify) | 成员信息修改（如重命名） | FORBIDDEN_MERGE |
+| 35 | [`CORP_MEMBER_SYNC`](topics/scene-producers.md#corp_member_sync) | 钉钉 / 企微同步成员 | FORBIDDEN_MERGE |
+| 36 | [`CROSS_PROJECT_ALLOW`](topics/scene-producers.md#cross_project_allow) | 跨项目引用 | FORBIDDEN_MERGE |
+| 37 | [`HISTORY_HANDLE`](topics/scene-producers.md#history_handle) | 历史 chain 任务处理（仅调度升级） | FORBIDDEN_MERGE |
+| 38 | [`USER_HOLDER_TO_NORMAL`](topics/scene-producers.md#user_holder_to_normal) | 用户从 holder 转正常（用户名由手机号变更，需更新自定义字段） | FORBIDDEN_MERGE |
+| 39 | [`TABLE_MOVE_OTHER_WORKSPACE`](topics/scene-producers.md#table_move_other_workspace) | 表移动到其他空间 | FORBIDDEN_MERGE |
+| 40 | [`AGENT`](topics/scene-producers.md#agent) | Agent 触发的保存 | FORBIDDEN_MERGE |
+| 41 | [`MIGRATION`](topics/scene-producers.md#migration) | 租户迁移触发的更新 | FORBIDDEN_MERGE |
+| 42 | [`PROJECT_EXCEL_MOVE`](topics/scene-producers.md#project_excel_move) | 项目 excel 移动 | FORBIDDEN_MERGE |
+| 43 | [`SPLIT`](topics/scene-producers.md#split) | 拆分分析表 | FORBIDDEN_MERGE |
+| 44 | [`CATALOG_DATA_PERMISSION_CHANGE`](topics/scene-producers.md#catalog_data_permission_change) | 目录行列权限配置变更（含清空规则） | FORBIDDEN_MERGE |
+| 45 | [`NoUpdateIfExist`](topics/scene-producers.md#noupdateifexist) | 诊断复制 / 另存时结果已存在则不更新 | FORBIDDEN_MERGE |

package/content/knowledge/update/conclusions.md

@@ -0,0 +1,59 @@
+# 更新 · 能下什么结论
+
+回答“手上的日志、trace 和 Metric 能说明什么、不能说明什么，结论能下到哪一步”。允许使用的关联边和性能片段见[关联边与性能片段](topics/correlations.md)，计数单位见[概念](concepts.md#计数单位与身份)。
+
+## 目录
+
+- [适用范围](#适用范围)
+- [结果里写什么](#结果里写什么)
+- [计数对账](#计数对账)
+- [判断矩阵](#判断矩阵)
+- [选择运行与阶段测量](#选择运行与阶段测量)
+- [停止规则](#停止规则)
+
+## 适用范围
+
+知识整理自 server 主干代码，说明可能产生哪些记录、能怎么解释，证明不了这次真的发生了。版本、字段含义的处理按[知识适用性](../common/conclusions.md#知识适用性)：对不上标 `needs_revalidation`，确认不了标 `unknown`，记录里直接看到的时间、标识、状态和错误照样可以整理。知识缺失或自相矛盾时按缺口处理。配方只限定参考范围，不要求跑完它的全部查询，只补当前缺的那一项。
+
+## 结果里写什么
+
+写清范围、所有仍可信的候选、选定的运行、计数单位、各阶段测量、已验证的关联、反证、覆盖范围，以及停在哪一步。引擎统计、相近时间和猜的默认值都补不上 `unknown` 的缺口。最终根因和处置排序属于性能排查，不在这里下。
+
+## 计数对账
+
+一次统计只用一种单位。聚合前写清统计的是什么、时间指什么、按什么去重、包含和排除了什么、覆盖多大范围。请求、链、节点、执行尝试、加载、引擎任务和真正写入成功的次数分开数。
+
+| 比较 | 要有什么才能比 | 没有时怎么说 |
+| --- | --- | --- |
+| 请求 → 根表 | 请求到根表的明确对应和过滤范围 | 展开和过滤关系未知 |
+| 根表 → 节点 | 同一条链、同一版本下明确的依赖范围 | 依赖展开未知 |
+| 链 → 执行尝试 | 明确的链或执行标识，以及重试原因 | 只是受理了，不代表执行了几次 |
+| 执行尝试 → 加载 | 尝试和加载结果的明确对应 | 执行了不代表加载了 |
+| 加载 → 引擎任务或写入 | 明确的交接、任务和结果记录 | 不下引擎或写入的结论 |
+| trace / span → 任何业务单位 | 有明确含义的属性和去重规则 | 只能算遥测条数 |
+
+明细数、链数、节点或 `update` span 数、trace 数和真正写入成功的次数不能互换。尝试或 span 重复不代表重复写入；多个请求可能被过滤或合并，一张根表也可能展开成多个节点。
+
+## 判断矩阵
+
+| 问题 | 要有的记录 | 能直接回答 | 没有时 |
+| --- | --- | --- | --- |
+| 请求有没有被受理成更新？ | 明确的请求和链受理记录 | 只说受理情况 | 没有标识：请求到链未知 |
+| 为什么明细比链或节点多？ | 固定的计数单位，以及明确的根表、合并、依赖对应 | 说清测到的过滤、展开或合并 | 没有对应：说明不能比较 |
+| 重复的节点是不是重试？ | 同一节点或尝试，带明确的重排队原因 | 按观察到的重排队分类 | 没有原因：重复不能证明是重试 |
+| 节点有没有写数据？ | 明确的加载结果，见 [load-decision](topics/events-outcome.md#load-decision)、[result-publish](topics/events-outcome.md#result-publish) | 按记录分成写入、引用、跳过、失败 | 没有加载结果：不能说写了 |
+| 引擎有没有写成功？ | 明确的交接、引擎任务和结果 | 在记录范围内说引擎结果 | 没有明确关联：停在服务端 |
+| 权限或成员变动有没有引起更新？ | 明确的来源、受理和链标识 | 说已证实的那几段 | 只有时间挨着、同租户或同名：留作候选并停下 |
+
+## 选择运行与阶段测量
+
+- 可信的候选运行都留着，按用户操作和明确关系选目标，不悄悄挑最新、最慢或有链接的那次。失败、重试成功、其他查询和正常基线分开放。
+- 每段耗时保留原始的开始、结束、字段口径和覆盖范围。异步阶段和并发分支可能重叠，父子或并发的耗时不能加成端到端时间。
+- 加载或监听器成功不等于整条链都写成功，一次尝试成功也不代表整条链成功。恢复和重试只报告实际看到的分支。
+- 分页、截断、超出保留期、字段缺失和关联缺口分开说。有限样本代替不了总体；一次完整查询已经回答了计数就直接整理，不重复聚合。要和历史比，另找可比的基线，时间范围和记录单独取。
+
+## 停止规则
+
+有已生效的失效条件（包括配置变了）、范围对不上、属于别的服务、缺必要的身份关联、分页没读完或要的记录取不到时，标 `unknown`。不为了凑关联扩大时间窗。
+
+在说好的范围里查到了要分类的记录、必要的关联断了，或者下一步要研发确认产品行为、补采集或分析因果时，就停下。说清下一步最少要查什么，不给猜测的结论；还要验证哪项产品行为，交给研发继续。

package/content/knowledge/update/queries.md

@@ -0,0 +1,103 @@
+# 更新 · 查询方法
+
+回答“怎样取证、怎样查询”。
+
+## 目录
+
+- [SigNoZ 查询线索](#signoz-查询线索)
+- [公共约定](#公共约定)
+- [选哪个配方](#选哪个配方)
+- [scene-origin：从场景入口开始](#scene-origin从场景入口开始)
+- [table-history：一张表在窗口内的全部运行](#table-history一张表在窗口内的全部运行)
+- [table-in-chain：一条链里的一张表](#table-in-chain一条链里的一张表)
+- [dag-chain：一条链的依赖图与执行时间线](#dag-chain一条链的依赖图与执行时间线)
+- [performance-window：性能片段](#performance-window性能片段)
+
+## SigNoZ 查询线索
+
+从企业或 dagId 开始时不用先要 trace 或时间，窗口按[公共查询规则](../common/queries.md#默认值速查)。在业务 `service.name` 下组合 `dispatch_*` / `update` span 与 tableId、dagId、updateId；进入引擎后按 task 取 Metric，不套用业务服务过滤。
+
+常用的过滤条件（环境与 `service.name` 的对应见[环境识别](../common/concepts.md)）：
+
+| 想找什么 | 在哪个信号上过滤 | 备注 |
+|---|---|---|
+| 一条链的受理和各节点执行 | `name = 'dispatch_submit' AND dagId = '<链 ID>'`；`name = 'update' AND dagId = '<链 ID>'` | `dagId` 只在 `dispatch_submit` 和已执行的 `update` 上有 |
+| 某张表的消费尝试 | `name = 'node-task-queue receive' AND tableId = '<表 ID>'` | 队列 span 总带 `tableId`、`corpId`，包括限流转发和拿锁失败的投递 |
+| 某张表的节点执行结果 | `name = 'update' AND tableId = '<表 ID>'`，看 `updateType`、`loadData`、`rowCount`、`rootErrorId` | 没有这些属性的 `update` 没走到节点执行 |
+| 某个企业的更新 | 先用 `corpId` 查队列 span 或 `dispatch_submit`，再按 `linked` 找 `update` | `update` 上的 `corpId` 只有执行过的才有，不能用来排除企业 |
+| 从发布方找到执行方（或反过来） | `name = 'update' AND linked = '<发布方 trace ID>'` | `linked` 保存的是发布方 trace ID |
+| 某次加载的起止与耗时 | 日志 `body CONTAINS 'table load success'`（或 `table load start`、`table load fail`），带 `trace_id` | 日志的 `span_id` 等于 `dispatch_node_task_exec` |
+| 某个节点的失败原因 | 日志 `body CONTAINS 'execute task error'`，带 `exception.type`、`exception.message` | 同一次失败还有一条不带堆栈的 `task exec error` |
+| 某张表有没有引用已有结果、tag 和旧版本释放 | `update` 上 `execution.mode = 'REF'`；日志 `body CONTAINS '<表 ID>'` 加 `[ResultBinding]`、`[Snapshot tag`、`[ResultRetention]` | 见 [result-publish](topics/events-outcome.md#result-publish) |
+| 限流和重排队 | 日志 `body CONTAINS 'Tenant limit exceeded'`、`resend execute info` | 慢队列每转一圈打一行，条数不等于节点数 |
+
+按已有输入选一个配方，只补当前缺的那一项。配方只限定参考范围，不证明每个分支都发生，也不要求跑完全部步骤。事件见[事件索引](signals.md#事件索引)，边与片段见[关联边与性能片段](topics/correlations.md)。
+
+## 公共约定
+
+- `update` span 上的真假值是字符串，过滤写 `loadData = 'true'`；`rowCount`、`dataModify` 是数字，写 `rowCount > 1000000`、`dataModify = 1`。旧版本的记录里数字也存成字符串，跨版本查询时两种类型分别取。
+- 输入：环境、时区必填；时间窗用绝对半开区间 `[start, end)`；有 trace_id 就精确锚定。
+- 只用[允许的关联边](topics/correlations.md#关联边)，第一条必要边缺失就停，报告最后证实的边界。缺失的身份或字段保持未知，不补造入口、明细、发布或异步边，也不扩成另一个配方。
+- 从 trace 开始：记下绝对时间和时区，确认 trace 对应哪个事件、有没有显式的 chain 受理 key；有原生关系或已验证的 chain / node / attempt key 才扩到消费 trace，否则只算候选。之后按 merge、requeue、load、engine task 的顺序检查。
+- 从时间窗开始：先定统计对象和计数单位；区间以完整的服务端聚合为准，原始记录只有分页和覆盖核对完整后才代表总体，否则只是样本。request、chain、distinct node、attempt、load、engine task 分开测，少量代表性 trace 只用来解释过程。
+
+## 选哪个配方
+
+| 已有输入 | 配方 | 回答什么 |
+|---|---|---|
+| 已知更新场景（如 `ACTIVE`、`SCHEDU`） | scene-origin | 这个场景的更新由哪类入口触发，是否被受理并落到明细 / 发布 |
+| 表 + 发生时间 | table-history | 这张表在时间窗内的更新运行、尝试、重排队、合并、load 与监听器 |
+| 表 + chain | table-in-chain | 这张表在这条链里的节点时间线 |
+| chain / dagId | dag-chain | 链的逻辑依赖图，以及执行时间线（尝试、重排队、合并、load、监听器、子节点释放） |
+| 已选定一条链，要看耗时 | performance-window | 12 个性能片段各自的耗时 |
+
+## scene-origin：从场景入口开始
+
+范围是某个场景、某类入口、精确锚点内的触发方，没有显式边的上游不算。入口类型决定读哪类上游记录（见[场景入口明细](topics/scene-producers.md)），后续步骤相同：
+
+1. 定位受理的更新意图（`intent-accepted`）。入口类型是“监听器派生链”的，先从 `listener-invocation` / `listener-derived-chain` 找派生来源。
+2. 分类候选根（`candidate-root-filter`）。
+3. 确认有效根（`effective-root-selection`）。
+4. 定位落库的执行明细（`execution-frontier-persisted`）。
+5. 定位提交后的发布（`after-commit-delivery`）。
+
+停止：受理或落库的信号缺失时停；不能用时间、企业、表名或相似数量把上游入口和 dispatch 连起来；chain ID 不是触发方的请求 ID，也不是 attempt ID。
+
+## table-history：一张表在窗口内的全部运行
+
+范围是一张表、一个绝对时间窗、所有显式识别的链。必填：绝对时间窗、表；只有 trace 不行。
+
+1. 定位表的节点结果（`primary-node-result`）。
+2. 枚举尝试（`after-commit-delivery`、`attempt-consumed`）。
+3. 分类重排队与恢复（`capacity-deferred`、`lock-requeued`、`ready-recovery`、`init-recovery`、`dlx-recovery`）。
+4. 分类合并、load 与引擎（`merge-decision`、`load-decision`、`load-operation`、`result-publish`、`engine-handoff`）。
+5. 定位监听器影响（`listener-invocation`、`listener-derived-chain`）。
+
+缺尝试或物理边界时覆盖范围记为未知，不能重建完整历史，也不按明细 ID 去重；不同链的记录不按表名、企业或时间拼接。
+
+## table-in-chain：一条链里的一张表
+
+范围只是这条链里的这张表，别的链不算。必填：表、chain。
+
+1. 明细与发布：`execution-frontier-persisted`、`after-commit-delivery`。
+2. 尝试与重排队时间线：`attempt-consumed` 及各 requeue / recovery 事件。
+3. 合并、load、引擎与节点结果：`merge-decision`、`load-decision`、`load-operation`、`result-publish`、`engine-handoff`、`primary-node-result`。
+4. 监听器与子节点：`listener-invocation`、`child-release`、`listener-derived-chain`。
+
+重复投递记为多次尝试；表或链身份缺失就停，不扩成 table-history。
+
+## dag-chain：一条链的依赖图与执行时间线
+
+范围是一条显式识别的链。逻辑依赖图和执行层（明细、发布、尝试、重排队、副作用）分开统计，答复分“逻辑图”“执行时间线”两节。必填：chain。
+
+1. 展开逻辑依赖：`intent-accepted`、`candidate-root-filter`、`effective-root-selection`、`logical-dependency-expansion`。历史依赖对或链范围在物理记录中不存在时停止，当前血缘不能代表历史。
+2. 定位明细与发布：`execution-frontier-persisted`、`after-commit-delivery`。
+3. 组装尝试与重排队：`attempt-consumed`、`capacity-deferred`、`lock-requeued`、`ready-recovery`、`init-recovery`、`dlx-recovery`。每次主队列投递是一次 attempt，每次 capacity / lock / READY / INIT / DLX 路由是一次 requeue。
+4. 分类合并与 load：`merge-decision`、`load-decision`、`load-operation`、`result-publish`、`engine-handoff`、`primary-node-result`。
+5. 分类监听器、子节点与派生链：`listener-invocation`、`child-release`、`listener-derived-chain`。
+
+只用[关联边](topics/correlations.md#关联边)声明的 27 条边；缺明细落库、load 或监听器信号时在该分支停下并报告缺口。
+
+## performance-window：性能片段
+
+对一条链分别测 12 个独立片段，不合成端到端总耗时。必填：chain。片段定义见[性能片段](topics/correlations.md#性能片段)。12 个都要返回，测不了的停在各自最后证实的边界并说明；没有 engine task 身份时，引擎分支停在 server 边界，不按表或时间推断任务。

package/content/knowledge/update/signals.md

@@ -0,0 +1,57 @@
+# 更新 · 入口与信号
+
+回答“怎样认出入口，各个 span、attribute、日志和字段是什么意思”。
+
+## 使用规则
+
+- 认场景：trace 里有 `dispatch_submit` 等 `dispatch_*` span、`update` span，或 `dagId`、`updateId`，就是更新。只有 `tableId` 或共享的 Query / engine span，分不清是前台查询还是后台更新。
+- 认出后：性能问题按[更新性能排查](workflow.md#更新性能排查)，来源、DAG、计数这类事实问题按[解释更新记录](workflow.md#解释更新记录)。先读[一次更新怎么走完](topics/lifecycle.md)，再按下面的索引读具体事件。
+- 用信号前确认这次记录里真有这个字段；字段缺失只限制依赖它的判断，不证明没发生。异步关联只用[关联边](topics/correlations.md#关联边)声明的边和键。
+- server 版本、合并重试路由监听器等配置、span 属性日志模板、服务边界变了，相关判断标 `needs_revalidation`；版本确认不了标 `unknown`。
+
+## 事件索引
+
+事件按生命周期分在三个文件里（受理与入队、消费与合并、load 与结果），按下表找到要的事件，只读对应文件。重排队与恢复（限流、拿锁失败、补发、等待恢复、死信）从消费环节旁路回到队列。
+
+| 事件 | span | 日志 signature |
+|---|---|---|
+| [`intent-accepted`](topics/events-intake.md#intent-accepted) | `dispatch_submit` | `dispatch receive request, chainId {},  root size {},`、`submit root task success, chain {} root size {}, cost {}` |
+| [`candidate-root-filter`](topics/events-intake.md#candidate-root-filter) | 无 | `table don't need update, tableId = {}, tenantId = {}`、`table is not exist in db, can't update, tableId = {}, tenantId = {}` |
+| [`effective-root-selection`](topics/events-intake.md#effective-root-selection) | `dispatch_gen_roots` | 无 |
+| [`logical-dependency-expansion`](topics/events-intake.md#logical-dependency-expansion) | `dispatch_get_ancestors`、`dispatch_get_ancestors_batch`、`dispatch_get_descendants` | `getAncestors error {}`、`getDescendants error {}` |
+| [`execution-frontier-persisted`](topics/events-intake.md#execution-frontier-persisted) | 无 | 无 |
+| [`after-commit-delivery`](topics/events-intake.md#after-commit-delivery) | 无 | `send nodeTaskId {} , executeId {}` |
+| [`attempt-consumed`](topics/events-execution.md#attempt-consumed) | `node-task-queue receive`、`update` | `handle nodeTaskId {}, executeId {}` |
+| [`capacity-deferred`](topics/events-execution.md#capacity-deferred) | `slow-node-task-queue receive` | `Tenant limit exceeded: tenant {}, nodeTaskId {}, executeId {}` |
+| [`lock-requeued`](topics/events-execution.md#lock-requeued) | 无 | `resend execute info, nodeTaskId {}, id {}, chainId {}` |
+| [`ready-recovery`](topics/events-execution.md#ready-recovery) | 无 | `[inspect ready] send nodeTaskId {} , executeId {}` |
+| [`init-recovery`](topics/events-execution.md#init-recovery) | 无 | `send nodeTaskId {} , executeId {}` |
+| [`dlx-recovery`](topics/events-execution.md#dlx-recovery) | `node-task-queue_dlx_queue receive` | `receive msg at dlx queue, msgId = {}`、`send execute info to fast, msgId = {}` |
+| [`merge-decision`](topics/events-execution.md#merge-decision) | 无 | `merge isolationMode {}, executeId {} nodeTaskId: {}, merge mergeExecuteIds {} chainIds {}` |
+| [`load-decision`](topics/events-outcome.md#load-decision) | 无（`update` 上的 `loadData`、`execution.mode` 等属性） | 无 |
+| [`load-operation`](topics/events-outcome.md#load-operation) | 无 | `table load start`、`table load success`、`table load fail` |
+| [`result-publish`](topics/events-outcome.md#result-publish) | `result.binding.commit`、`result.snapshot.tag.<操作>` | `[ResultBinding] event=COMMIT_RESULT`、`[Snapshot tag {}]`、`[ResultRetention] event=RELEASE_REQUESTED` |
+| [`engine-handoff`](topics/events-outcome.md#engine-handoff) | `DataFlowExecutor`、`execute` | `table {} load fail!`、`table {} load success.` |
+| [`primary-node-result`](topics/events-outcome.md#primary-node-result) | `dispatch_node_task_exec` | `finish to exec task, nodeTaskId = {}, chainId = {}, cost = {}ms`、`task exec error, nodeTaskId {}, chainIds {}, {}` |
+| [`listener-invocation`](topics/events-outcome.md#listener-invocation) | `trigger_listener_<监听器名>` | 无 |
+| [`child-release`](topics/events-outcome.md#child-release) | `dispatch_callback_children`、`evaluator_child` | `dispatch callback children, nodeTaskId {}, executeId {}, chainId {}, children size {},` |
+| [`listener-derived-chain`](topics/events-outcome.md#listener-derived-chain) | 无 | `update corp success , update {}` |
+
+## 上游出错连带失败
+
+更新开始前会先做配置检查，日志 `[TableRedMarkPreLoadValidator] Check table for id {} Is {}`，`Is false` 就是没通过。引用的上游表正处在出错状态时，同一 trace 里会有：
+
+- `[GrammarCheck] referenced table is invalid, propagate red mark: curTable=…, parentTable=…, parentStatus=…`：写明是哪张上游表、它是什么状态。常见的 `parentStatus` 有 `mem_insufficient`（上游自己内存不足失败了）、`parent_error`（上游的上游出错，还要再往上找）；
+- `[RedMarkCheck] analysis table marked red by grammar check`：本表随之被标红；
+- 最后报 `table <表 ID> is invalid`（`TableInvalidException`），这里的表 ID 是上游表，不是用户看到的那张。
+
+同一条链里上游节点这次刚失败时，走的是另一条路，日志是：
+
+- `Task is failed by its parent failed, curId {}, fail parent {}, chainId {}`：`fail parent` 是失败的上游表；
+- 随后报 `Task is failed by its dependence failed <上游的错误原文>`（`DependenceFailedException`）。
+
+两种情况本表都没进入计算，原因在上游。按 `parentTable` 或 `fail parent` 去查那张表自己的失败记录；如果它的错误也是 `dependence failed` 或 `parent_error`，就继续往上找，直到第一张自己报错的表（`task exec error` 里是 `MemoryLimitExceeded` 这类真实错误），把它讲清楚才算回答了用户。同一时间往往有一批依赖它的下游一起失败，不要逐张当成独立问题。
+
+第一张自己报错的表，也可能是本表配置检查没通过，同样没进入计算：`col size over limit 400`（状态 `column_size_over`）是某一步输出的列数超过上限，要减少字段或拆表；`formulaStr {} has error` 是公式校验不通过，常见是引用的字段或参数已经不在了。
+
+更新失败后，日志 `[TableConfRecord] record failed table:tableID<表>, rowCount-1, peakMem<值>` 会把失败记到表上：`peakMem-3` 表示这次是内存超限失败，`peakMem-1` 是其他错误。按时间看一张表的这条日志，就能看出它从什么时候开始因为内存失败、什么时候换成了别的错误。

package/content/knowledge/update/topics/correlations.md

@@ -0,0 +1,63 @@
+# 更新关联边与性能片段
+
+本文件补充[更新可观测知识](../signals.md)：更新事件之间允许用哪些关联键把记录连起来，以及性能分析时把一条链的耗时切成哪些片段。各事件的含义见[受理与入队](events-intake.md)、[消费、重排队与合并](events-execution.md)、[load、引擎与结果](events-outcome.md)；整体流程见[一次更新怎么走完](lifecycle.md)。
+
+## 目录
+
+- [关联边](#关联边)
+- [性能片段](#性能片段)
+
+## 关联边
+
+只允许使用下表声明的边。缺少某条必要的边时停止扩展，只报告最后一条证实的边界；表名、租户、时间相近都不能当作关联依据。trace 的父子关系和 link 只能连接遥测范围，不能单独确认业务关联，业务关联仍要有这条边声明的关联键。
+
+“异步”指两端不在同一个线程或同一条 trace 里，要靠消息或链接才能连起来。
+
+| 边 | 从 → 到 | 关联键 | 异步 | 说明与限制 |
+|---|---|---|---|---|
+| `request-to-candidate-root` | 更新请求 → 候选根 | 同一次调用里的候选集合 | 否 | 没有请求 ID，只在进程内成立。 |
+| `candidate-to-effective-root` | 候选根 → 有效根 | 同一次提交里的表 ID | 否 | 被过滤的候选没有留存。 |
+| `effective-root-to-chain` | 有效根 → 更新链 | 链 ID（`dagId`）、表 ID | 否 | 没有选出任何根时，链 ID 仍会返回，但没有明细。 |
+| `chain-node-to-execution-detail` | 链上的节点 → 执行明细 | 链 ID、节点表 ID、明细 ID | 否 | 明细是临时记录，执行完会删除，不是节点历史。 |
+| `logical-parent-to-child` | 父节点 → 子节点 | 父表 ID、子表 ID、链范围 | 否 | 依赖是现查的当前血缘，不能证明当时的依赖。 |
+| `execution-detail-to-publication` | 执行明细 → 消息发布 | 明细 ID | 是 | 明细提交可见之后才发布；没有独立的发布 ID。 |
+| `publication-to-attempt` | 消息发布 → 一次消费尝试 | 明细 ID；`update` trace 上的 `linked`（发布所在 trace 的 ID）和 span link | 是 | 同一明细被重复投递无法区分第几次。执行 trace 在 `update` 里，要靠 `linked` 或 link 从发布所在的 trace 查到。 |
+| `attempt-to-capacity-deferral` | 尝试 → 限流转发 | 明细 ID、租户 ID | 是 | 没有独立的转发 ID。 |
+| `capacity-deferral-to-attempt` | 限流转发 → 后续尝试 | 明细 ID | 是 | 慢队列里的每一圈是重排队，不是主队列尝试。 |
+| `attempt-to-lock-requeue` | 尝试 → 锁超时重排队 | 明细 ID、节点表 ID、链 ID | 是 | 不增加尝试或重排队 ID。 |
+| `lock-requeue-to-attempt` | 重排队 → 后续尝试 | 明细 ID | 是 | 重复投递的次数没有保留。 |
+| `ready-recovery-to-publication` | 补发巡检 → 消息发布 | 明细 ID | 是 | 只适用于“待发送”的根明细，不适用于子明细。 |
+| `init-recovery-to-publication` | 等待恢复 → 消息发布 | 明细 ID | 是 | 重新判断的是当前依赖，不是当时的历史依赖。 |
+| `dlx-recovery-to-attempt` | 死信恢复 → 后续尝试 | 明细 ID | 是 | 恢复轮次和后续尝试都没有独立 ID。 |
+| `attempt-to-merge` | 尝试 → 合并判断 | 明细 ID、节点表 ID | 否 | 合并判断不留存 ID。 |
+| `merge-member-to-effective-execution` | 被合并的明细 → 实际执行的节点 | 被合并的明细 ID、链 ID、节点表 ID | 否 | 合并成员关系不能证明它们属于同一个请求。 |
+| `merge-to-load-decision` | 合并判断 → load 决定 | 节点表 ID、被合并的链 ID | 否 | load 决定没有独立 ID。 |
+| `effective-execution-to-listener-before` | 实际执行的节点 → 执行前监听器 | 链上下文、节点表 ID、监听器名 | 否 | 此时还没有节点主结果。 |
+| `load-decision-to-load-operation` | load 决定 → 加载 | 同一次执行里的节点对象；加载日志的 `span_id` 等于 `dispatch_node_task_exec` | 否 | 只有通过活跃、可用、执行模式等判断的分支才会调用加载。 |
+| `load-decision-to-result-publish` | load 决定 → 结果提交 | 同一次执行的 `trace_id`，日志里的本表 ID | 否 | 只有 REF 或读取位置变了才有；同一 trace 可能有多张表，按本表 ID 对，不按时间挨着拼。 |
+| `no-load-to-primary-result` | 不加载 → 节点主结果 | 同一次执行里的节点对象 | 否 | 直通、不活跃、跳过或加载前失败，都可以没有引擎任务就得出结果；这种成功不能当作数据变化。 |
+| `load-operation-to-engine-task` | 加载 → 引擎任务 | 服务端调用范围；成功时返回的引擎任务 ID | 否 | 只有进入 Polars 写入才会产生引擎任务；失败和重试过的任务不完整。 |
+| `engine-task-to-primary-result` | 引擎任务 → 节点主结果 | 返回时的引擎任务 ID、服务端执行范围 | 否 | 没有返回任务 ID 时，不能用表名补出任务关系。 |
+| `primary-result-to-listener` | 节点主结果 → 成功/失败/完成监听器 | 链 ID、节点表 ID、监听器名 | 否 | 监听器按固定顺序执行，在释放子节点之前。 |
+| `listener-complete-to-child-release` | 监听器完成 → 释放子节点 | 链 ID、节点表 ID | 否 | 正常走完后才释放子节点；停止工作的情况不会走到这里。 |
+| `primary-result-to-child-frontier` | 节点主结果 → 子节点明细 | 链 ID、节点表 ID、子明细 ID | 否 | 中间隔着监听器，不是相邻步骤，只能作为先后条件。 |
+| `listener-to-derived-chain` | 监听器 → 派生链 | 监听器调用范围里的源链 ID、监听器名、新返回的链 ID | 否 | 派生链的上下文里不保存源链 ID，只有进程内的这次调用能证明关系。 |
+
+## 性能片段
+
+性能分析把一条链的耗时拆成下面 12 个互相独立的片段，每个片段单独计数，不加成端到端总耗时。某个片段缺少度量信号时保留并说明停在哪个已证实的边界。
+
+| 片段 | 起点 → 终点 | 包含 | 不包含 | 度量信号 | 限制 |
+|---|---|---|---|---|---|
+| `control-planning` | 受理 → 根明细落库 | 候选过滤、选根、提交所需的依赖展开、根明细落库 | 外层事务提交等待、队列发布与消费 | `dispatch_submit`、`dispatch_gen_roots`、`dispatch_get_*` 的时长；`submit root task success` 日志里的 `cost` | 没有请求 ID，单凭链 ID 无法还原整个请求群。 |
+| `commit-publication` | 明细落库 → 发布调用返回 | 外层事务提交等待、发布线程调度、根消息发布 | 队列停留、消费 | 日志 `send nodeTaskId` 的时间 | 没有发布 ID；子明细没有根明细的补发保证。 |
+| `main-queue-wait` | 发布被接受 → 主队列开始消费 | 消息在队列里等待的时间 | 慢队列的限流等待、节点锁等待、业务处理 | `send nodeTaskId` 日志、`handle nodeTaskId` 日志、`node-task-queue receive` span、明细 ID | 同一明细的重复投递无法区分。 |
+| `capacity-cycle` | 转到慢队列 → 再次在主队列被消费 | 慢队列里一圈或多圈的额度检查和重发 | 之前的主队列尝试、之后的锁和业务处理 | `Tenant limit exceeded` 日志、`receive executeInfo at slow queue` 日志、`slow-node-task-queue receive` span、明细 ID | 同一明细 ID 被复用，没有轮次序号。 |
+| `lock-cycle` | 锁超时重发 → 再次在主队列被消费 | 从一次锁超时到下一次主队列投递的时间 | 仅限流的慢队列等待、拿锁之后的业务处理 | `resend execute info` 日志、`handle nodeTaskId` 日志、明细 ID | 没有尝试 ID、重排队 ID 或锁等待历史。 |
+| `merge-evaluation` | 拿到节点锁 → 选出合并成员和主上下文 | 同节点明细查询、合并策略判断 | 拿锁前的等待、父节点判断、节点业务 | `merge isolationMode` 日志；多成员合并时 `update` 上的 `merge_count`、`wait_merge_time` | 没有合并判断 ID 或成员台账。 |
+| `parent-dependency-wait` | 子节点以“等待”状态保存 → 之后被某次就绪投递或巡检放行 | 等待状态明细的存续时间 | 保存之前的依赖图年龄、放行后的队列等待 | `child-release` 的 `children size` 日志、`init-recovery` 日志 | 启动巡检只在启动时跑一次，明细消失后无法还原当时的等待时间。 |
+| `business-attempt` | 节点有效执行开始 → 得出成功或失败 | 执行前监听器、父节点失败判断、load 决定和节点工作 | 结果之后的成功/失败/完成监听器、释放子节点 | `update` 上的 `businessConsumed`；XS03 里的同名字段 | 没有尝试 ID，需要别的显式关联。 |
+| `load-operation` | 进入加载 → 加载返回或失败 | 加载内部的服务端准备、下游交接与等待 | 直通、不活跃、复用、不需要加载的分支 | `table load start` / `table load success` 日志（带 `cost`）及其 `span_id` | 没有加载 ID；不同表类型的下游工作不同。 |
+| `engine-task` | 引擎任务创建 → 引擎事务提交或回滚 | 一次引擎执行尝试及其事务 | 创建任务之前的服务端工作、其他任务 ID 的重试 | `DataFlowExecutor`、`execute` span；`write_metric` 属性 | 只暴露最后成功的任务 ID，重试链路不完整。 |
+| `listener-callback` | 一个监听器的一个阶段被调用 → 返回 | 某个监听器的执行前/成功/失败/完成之一 | 其他监听器和阶段、监听器自己的异步工作 | `trigger_listener_<名称>` span 的时长 | 没有调用 ID；span 不区分阶段。 |
+| `child-release` | 释放子节点开始 → 子明细事务和发布调用返回 | 子节点与祖先发现、子节点可执行判断、删除父明细和创建子明细、子节点发布调用 | 释放之前的监听器回调、子节点之后的队列等待 | `dispatch_callback_children`、`evaluator_child` span | 一个结果可能释放多个子明细；发布失败的子节点没有根节点那样的补发巡检。 |

package/content/knowledge/update/topics/discover-executions.md

@@ -0,0 +1,31 @@
+# 从企业或 DAG 定位更新执行
+
+只有企业 ID 或 dagId、还没定位到更新执行时读这里，用来找候选，不重建完整 DAG。企业入口只覆盖更新，其他企业级性能问题回性能总流程确认范围。环境、服务、时间和结果数按[公共查询规则](../../common/queries.md)，已有执行、时间和结果直接复用。
+
+## 检索时间
+
+企业更新和 dagId 的检索窗口只在这里维护。
+
+- **企业**：没给时间或只说“最近”，用当前时间往前 24 小时，说一句“未提供时间，先查看正式环境最近 24 小时的更新，优先检查异常”就直接查，报告里写明范围。用户给的时间、URL 时间、已确认范围优先；“那天”这种明确指向历史的说法不能用最近窗口代替。没结果时先在同范围降级一次，再说明覆盖范围、问更早的时间，不自动扩大企业扫描。
+- **dagId**：就是更新链 ID，一条链里可能有多个节点、尝试和 trace；它不是可以反复运行的表 ID，也不用先问时间。工具必须带时间时，内部先用最近 24 小时，按同环境、服务、精确 dagId 查，再在同范围降级一次；这个窗口只用来发现，命中后按实际记录恢复链的起止，跨出窗口的同链记录不能当无关执行排除。
+- **dagId 两查都空**：核对标识和过滤条件；数据保留期已知、用户没限定时间时，可以再扩一次时间，最多覆盖保留期和最近 30 天的交集，记下新旧边界，不扫描企业、不去掉服务过滤。保留期未知、仍为空或查询失败时，交付实际覆盖范围，再问大致日期，不猜保留期、不循环扩展。
+
+## 企业入口
+
+1. 按 `corpId` 精确查，只限环境、服务和时间，不同时要求 `span=update`、`dagId` 非空或错误状态。`corpId` 在队列 span 上总有，`update` 上只有执行过的才有（见[attempt-consumed](events-execution.md#attempt-consumed)），所以只有 `corpId` 证明不了是一次完整更新，`update` 上没有 `corpId` 也不能排除企业归属。
+2. 记下命中的 trace/span ID、时间、tableId 和实际返回的属性，按[独立 Trace 的显式链接](../../common/topics/linked-traces.md#独立-trace-的显式链接)用实际的 link 或 `linked` 找关联的更新执行，可以批量用已拿到的精确 ID。不按企业或时间相同把没有链接的执行并进来。
+3. 从关联更新取 dagId、tableId、traceId、时间、结果和耗时。“最近更新情况”先交付概况，突出有明确失败、超时、OOM 或有记录支持的等待异常的执行；只是耗时长或缺结束记录不直接判异常。正常的简述即可，不要求用户选一条；多个不同异常、又判断不了要深入哪个时，才列出差异请用户选，不擅自挑最慢的或全部深挖。
+
+## DAG 入口
+
+1. 用 `dagId` attribute 精确过滤，在同服务、确认或内部生成的范围里查提交和节点执行。
+2. 没命中或不能按属性查时，在同范围用 [intent-accepted](events-intake.md#intent-accepted)、[primary-node-result](events-outcome.md#primary-node-result) 里带 chain ID 的日志签名降级一次，精确匹配 chain 值，不只搜 `dag` 字样。提交早期失败的可能还没写 dagId attribute。
+3. 日志命中后取真实的 trace_id（没有就按公共规则补），有了 chain 和绝对窗口就进 `dag-chain` 配方，不要求用户另找 trace。
+
+## 字段与交付边界
+
+- 首查和同范围降级用公共查询预算；只有 dagId 能按上面的规则扩一次时间。拿到执行后只沿精确 ID 补证。没结果时分清是查询为空、字段不能查、权限问题还是本地响应读取失败，不写“企业/DAG 字段未采集”这种笼统结论。
+- XS03 埋点（见 [primary-node-result](events-outcome.md#primary-node-result)）只在已经有可访问的数据源或用户材料时用，不作为首查或必需的回退。
+- 到了 limit、分页没完或窗口不全时，报告“已观察到”的数量和覆盖限制，不说是企业的全部更新；节点成功不代表 DAG 完成，多个 span 不代表多次更新。
+- 发现阶段只解释原生记录和显式链接；选定执行后再按[解释更新记录](../workflow.md#解释更新记录)核对版本、范围、字段和关联边。有精确 task 可以继续取 Metric，但不反过来补造 DAG 关系。
+- 发现完成不等于诊断完成：把候选、排除依据、选中的执行和范围带进下一步，性能问题按[更新性能排查](../workflow.md#更新性能排查)，来源、计数等事实问题按[解释更新记录](../workflow.md#解释更新记录)。