@fx-data/ai-diagnostics 0.1.20261026070913 → 0.1.20261107142011

package/content/knowledge/update/topics/events-execution.md

@@ -0,0 +1,136 @@
+# 更新事件：消费、重排队与合并
+
+主队列消息被消费，到因租户限流、拿不到锁而重新排队，再到巡检和死信队列的恢复，以及同一节点多次请求的合并。整体流程见[一次更新怎么走完](lifecycle.md)，事件之间的关联见[关联边与性能片段](correlations.md)。
+
+## 目录
+
+- [attempt-consumed](#attempt-consumed)
+- [capacity-deferred](#capacity-deferred)
+- [lock-requeued](#lock-requeued)
+- [ready-recovery](#ready-recovery)
+- [init-recovery](#init-recovery)
+- [dlx-recovery](#dlx-recovery)
+- [merge-decision](#merge-decision)
+
+## attempt-consumed
+
+主队列每投递一次消息，就是一次“尝试”。消费者先看租户并发额度，拿到额度才继续去加锁、合并、执行。
+
+- 计数单位：`execution-attempt`（没有尝试 ID；同一条执行明细被重复投递，就是多次尝试）
+- 队列 span：`node-task-queue receive`
+- span：`update`
+- 属性：`corpId`、`tableId`
+- 日志 signature：`handle nodeTaskId {}, executeId {}`
+- 其他日志：`nodeTaskKey {} has been executed`、`exec fail, nodeTaskId {}, chainId {}, id {}，do not callback children node `（ERROR）、`handle msg error`（ERROR）、`send execute info to dlx, nodeTaskId {}, id {}, chainId {}`、`ignore execute info, nodeTaskId {}, executeId {}, chainId {}`（ERROR）
+- 什么时候出现：
+  - 每投递一次，先有队列 span `node-task-queue receive`（Consumer），它在发布这条消息的那条 trace 里，例如提交时挂在 `dispatch_submit` 下；这个 span 总带 `corpId` 和 `tableId`。
+  - 随后消费者另开一条 trace，根 span 是 `update`（Consumer），用链接（link）指回队列 span，所以执行细节在 `update` 这条 trace 里，要靠链接才能找到。
+  - `update` 上的 `corpId`、`tableId`、`dagId` 等属性只有节点真正执行后才写入。没有这些属性的 `update` 多半是只做了限流转发、重新排队或被判定已执行，没有走到执行，不能当作缺数据。
+  - `handle nodeTaskId` 在拿到额度之前就打，所以它出现不代表节点真的执行了。
+- 分支（按消费结果）：
+  - 没有租户额度：转到慢队列（[capacity-deferred](#capacity-deferred)）。
+  - 拿不到节点运行锁：抛重排队异常，消息重新发回主队列（[lock-requeued](#lock-requeued)）。
+  - 同一链、同一节点本轮已执行过（1 小时内的标记）：打 `nodeTaskKey {} has been executed`，删除这条明细，不再执行。
+  - 引擎主节点不可用（节点失败后的存活检查没通过），或依赖来源（血缘）不可用：打 `send execute info to dlx`，清掉“已执行”标记，消息拒收并进死信队列（[dlx-recovery](#dlx-recovery)）。
+  - 普通业务失败：节点内部消化成 FAIL 结果，不往外抛，所以队列层看不到失败；见[节点主结果](events-outcome.md#primary-node-result)。
+  - 其他未预期异常：打 `handle msg error` 和 `ignore execute info`，这条消息被丢弃，没有自动重试。重排队和被丢弃这两种情况，都会在当前的 `update` span 上记录异常并置为 ERROR，所以 `update` 报错不一定是节点业务失败。
+- 不能说明：没有尝试序号，同一明细多次投递只能按时间排序；`corpId`、`tableId` 写在队列 span 上，查询前先确认它们实际落在哪个 span。
+
+## capacity-deferred
+
+租户的并发额度用完后，这条消息转到慢队列等待，不在主队列里执行。
+
+- 计数单位：`requeue`
+- 队列 span：`slow-node-task-queue receive`
+- span：无
+- 属性：无
+- 日志 signature：`Tenant limit exceeded: tenant {}, nodeTaskId {}, executeId {}`
+- 其他日志：`receive executeInfo at slow queue, nodeTaskId = {}, executeId = {}, chainId = {}`、`reject because of shutdownSignalException`（ERROR）、`sth other error happened, msg = {}`（ERROR）
+- 什么时候出现：
+  - 只有配置了租户并发上限（大于 0）才会限流；没有配置时所有消息都有额度，不会出现这类日志。
+  - 超限时先把消息发到慢队列，再打 `Tenant limit exceeded`。
+  - 租户额度按租约发放，默认 20 秒、每 10 秒续约，持有额度的消费者异常退出后额度自动回收。
+  - 慢队列只有一个消费者，每收到一条打 `receive executeInfo at slow queue`；额度可用就发回主队列，仍不可用就再发回慢队列，如此循环，所以一条消息在慢队列里可能出现很多次。
+  - 慢队列消费不开 `update` trace，也没有 `corpId`、`tableId`。
+- 分支：收到关闭信号时把消息重新发回慢队列；其他异常只记 ERROR，不重发。
+- 不能说明：慢队列每转一圈是一次重排队，不是一次执行尝试；日志条数多只说明等得久，不说明有多少个不同节点。
+
+## lock-requeued
+
+同一个节点同一时间只能被一个消费者处理；等锁超时的消息被重新发回主队列。
+
+- 计数单位：`requeue`
+- span：无
+- 属性：无
+- 日志 signature：`resend execute info, nodeTaskId {}, id {}, chainId {}`
+- 其他日志：`handle msg error`（ERROR，紧挨着出现）
+- 什么时候出现：
+  - 节点运行锁等待超过 30 秒（默认，配置项 `waitTime`）、或节点的“计算来源”被别人占着、或拿锁后发现计算来源变了，都会走这里。
+  - 重新发回主队列后，之后的投递是新的一次尝试。
+- 不能说明：`update` 上的 `requeue` 属性不由这个分支设置，现行路径里基本恒为 `false`，不能用它判断是否发生过重排队；没有重排队序号，只能按明细 ID 加时间排。
+
+## ready-recovery
+
+根节点明细落库后消息没发出去（发布失败或进程在发布前退出），由定时巡检补发。
+
+- 计数单位：`requeue`
+- span：无
+- 属性：无
+- 日志 signature：`[inspect ready] send nodeTaskId {} , executeId {}`
+- 其他日志：`find ready execute size {}`、`[inspect ready] error`（ERROR）
+- 什么时候出现：
+  - 服务启动时跑一次，之后每 30 分钟跑一次（固定间隔）；每次先打 `find ready execute size N`，N 为 0 说明没有需要补发的明细（巡检日志没有 trace）。
+  - 只处理“就绪且待发送”的明细（根节点落库时的状态）；找到后加锁、补发、把标记改成已发送。
+- 分支：检查时明细已变化或消失，就跳过。
+- 不能说明：只覆盖根节点；子节点创建时就是“已发送”，发布失败后不会被这个巡检补上。没有补发 ID，也没有 broker 确认。
+
+## init-recovery
+
+子节点自己的父表都完成了，但还在等其他链合并，这类明细状态是“等待”（INIT）；巡检会重新判断并放行。
+
+- 计数单位：`requeue`
+- span：无
+- 属性：无
+- 日志 signature：`send nodeTaskId {} , executeId {}`
+- 其他日志：`find init execute size {}`、`inspectInit error`（ERROR）
+- 什么时候出现：
+  - 只在服务启动时跑一次，且只处理“昨天 0 点到今天 0 点之间”创建的等待明细；跑完之后不会定时重复。
+  - 重新判断为就绪才补发，补发时打 `send nodeTaskId ...`，和提交后的正常发布日志是同一个模板。
+- 分支：父表仍有未完成的，明细保持等待，等下一次启动或其他链的释放。
+- 不能说明：同一个日志模板既可能是正常发布，也可能是等待恢复，必须结合前后事件区分；今天创建的等待明细在今天内不会被巡检捞起。
+
+## dlx-recovery
+
+引擎、依赖来源不可用时，消息被拒收进死信队列；死信队列的消费者等条件恢复后再发回主队列。
+
+- 计数单位：`requeue`
+- 队列 span：`node-task-queue_dlx_queue receive`
+- span：无
+- 属性：无
+- 日志 signature：`receive msg at dlx queue, msgId = {}`、`send execute info to fast, msgId = {}`
+- 什么时候出现：
+  - 死信队列只有一个消费者；每收到一条先检查执行条件，不满足就每分钟重试一次、没有次数上限；满足后发回主队列。
+  - 它会开自己的 `update` trace，没有节点执行属性。
+  - 队列名带死信后缀；在配置了队列前缀的环境里 span 名也会带前缀。
+- 分支：检查或重发出错，只记 ERROR，这条消息不会再被处理。
+- 不能说明：`msgId` 就是执行明细 ID，不是死信的重试序号；只在基础设施不可用时才走这里，普通业务失败不会进死信队列。
+
+## merge-decision
+
+同一节点在不同请求里重复提交时，只执行一次，把几条明细合并成一个任务。
+
+- 计数单位：`merge-decision`
+- span：无
+- 属性：`merge_count`、`merge_round_count`、`wait_merge_time`
+- 日志 signature：`merge isolationMode {}, executeId {} nodeTaskId: {}, merge mergeExecuteIds {} chainIds {}`
+- 其他日志：`nodeTaskId {}, merge chainIds {}`、`nodeTaskId {}, id {}, already merged by other task`
+- 什么时候出现：
+  - 拿到节点运行锁、没有被转发或重排队之后，每次都要做一次合并判断，打 `merge isolationMode ...`。日志里的 `mergeExecuteIds`、`chainIds` 是这次合并的成员。
+  - 场景允许合并（`ALLOW_MERGE`，或在动态配置里放开），才会把同节点其他明细一并纳入；否则只处理自己这一条。
+  - 合并了不止一个明细时，才会打 `nodeTaskId {}, merge chainIds {}`，并在 `update` span 上写 `merge_count`（合并的链数）、`merge_round_count`（合并轮次）、`wait_merge_time`（最早成员等待的毫秒数；只有跨链合并才大于 0）。
+  - 绝大多数 `update` 没有 `merge_count`：只有真正合并了多条明细的才会有。
+- 分支：
+  - 这条明细已被其他任务合并执行：打 `already merged by other task`，这次不执行节点，成员由执行它们的任务清理。
+  - 合并轮次达到上限（默认 5 轮）：本来要等其他链的子节点直接放行，不再跨链等待。
+  - 跨链合并等待窗口默认 15 分钟：窗口内其他链的祖先还没完成，子节点以“等待”状态保存，之后由就绪投递或[等待恢复](#init-recovery)放行。
+- 不能说明：合并不等于一次请求、一条链或一次物理加载；单成员的合并没有这些属性，不能因为属性缺失就判断没有发生合并判断。

package/content/knowledge/update/topics/events-intake.md

@@ -0,0 +1,102 @@
+# 更新事件：受理与入队
+
+从业务模块提交更新，到根节点落库、消息发布到队列。整体流程见[一次更新怎么走完](lifecycle.md)，事件之间的关联见[关联边与性能片段](correlations.md)。
+
+## 目录
+
+- [intent-accepted](#intent-accepted)
+- [candidate-root-filter](#candidate-root-filter)
+- [effective-root-selection](#effective-root-selection)
+- [logical-dependency-expansion](#logical-dependency-expansion)
+- [execution-frontier-persisted](#execution-frontier-persisted)
+- [after-commit-delivery](#after-commit-delivery)
+
+## intent-accepted
+
+受理一次更新请求：业务模块带着一批候选表和更新场景（`updateScene`）调用调度入口，调度生成一条更新链并返回链 ID（即 `dagId`）。
+
+- 计数单位：`update-request`（没有请求 ID；受理后生成的 `dagId` 标识这条链）
+- span：`dispatch_submit`
+- 属性：`dagId`、`totalSize`、`updateScene`
+- 日志 signature：`dispatch receive request, chainId {},  root size {},`、`submit root task success, chain {} root size {}, cost {}`
+- 其他日志：`dispatch request rootIds is empty`（WARN）、`transaction is active `（WARN，带堆栈）
+- 什么时候出现：
+  - 受理日志在候选不为空时先打；`dispatch_submit` 的三个属性和“success”日志只在提交流程正常走完后才有。
+  - `totalSize` 是这条链涉及的表总数：请求的根表加上它们的全部下游。
+  - `cost` 是提交流程本身的耗时（毫秒），不含后续排队和执行。
+- 分支：
+  - 候选为空：只打 `dispatch request rootIds is empty`，不生成明细，也不会有 `dispatch_submit`；调用方仍拿到一个链 ID。
+  - 提交时外层已有数据库事务：打 `transaction is active ` 警告，说明业务方把提交包进了事务（不符合规范，会影响消息发布时机）。
+  - 提交中途失败：没有 `dagId` / `totalSize` 属性，也没有“success”日志。
+- 真实 trace 里的样子：`dispatch_submit` 下面挂着 `dispatch_get_descendants`（查全部下游）、每个监听器一个 `trigger_listener_<名称>`（`onStart`，各一次）；队列消费 span `node-task-queue receive` 也挂在它下面。
+- 不能说明：请求里有多少表真的会被更新（后面还有过滤和合并）；没有请求 ID，不能仅凭 `dagId` 还原“是谁在什么时候发起的”。
+
+## candidate-root-filter
+
+入口先过滤候选表：不需要更新的表、库里已经不存在的表直接丢掉。
+
+- 计数单位：`candidate-root`
+- span：无
+- 属性：无
+- 日志 signature：`table don't need update, tableId = {}, tenantId = {}`、`table is not exist in db, can't update, tableId = {}, tenantId = {}`
+- 什么时候出现：只有走公共入口过滤的调用才会过滤；被保留的候选没有日志，所以日志条数不是候选数。
+- 分支：判断“是否需要更新”本身出错时，保守地当作需要更新，继续调度。
+- 不能说明：日志里的 `tableId`、`tenantId` 只是占位参数，表和租户相同不代表属于同一次请求。
+
+## effective-root-selection
+
+从候选表里挑出真正的根：如果某张候选表的祖先也在候选里，它就不是根，由祖先更新完成后再释放。
+
+- 计数单位：`effective-root`
+- span：`dispatch_gen_roots`
+- 属性：无
+- 日志 signature：无
+- 其他日志：`no root task, check lineage {} `（ERROR）
+- 什么时候出现：
+  - 候选加上共享计算来源后只有一张表时，直接把它当根，不产生 `dispatch_gen_roots`；所以 `dispatch_submit` 的次数比这个 span 多。
+  - 有多张表时，`dispatch_gen_roots` 内部会调用一次批量祖先查询（`dispatch_get_ancestors_batch`）。
+- 分支：候选非空却没有选出根（血缘异常）时，打 ERROR 日志，退回“全部候选都当根”，提交继续。
+- 不能说明：span 不带候选表和根表的 ID，不能用它数根的个数；选根也不保证这些表最终都会执行。
+
+## logical-dependency-expansion
+
+查依赖：向上查祖先（用来判断父表是否已完成）、向下查子孙（用来算 `totalSize` 和释放子节点）。
+
+- 计数单位：`logical-dag-edge`
+- span：`dispatch_get_ancestors`、`dispatch_get_ancestors_batch`、`dispatch_get_descendants`
+- 属性：无
+- 日志 signature：`getAncestors error {}`、`getDescendants error {}`
+- 什么时候出现：每次向依赖来源（血缘）发起查询就产生一个对应 span。提交时查子孙（`dispatch_get_descendants`），选根和释放子节点时批量查祖先（`dispatch_get_ancestors_batch`）；单表祖先查询（`dispatch_get_ancestors`）只在 INIT 巡检里用到，平时几乎看不到。
+- 分支：依赖来源不可用时打 ERROR 日志并按“依赖不可用”处理，当前阶段未知，消息可能转入死信队列恢复（见 [dlx-recovery](events-execution.md#dlx-recovery)）。
+- 不能说明：span 不带父子表对、链范围或结果数量；血缘是每次现查的，不是历史快照，不能用现在的血缘还原当时的依赖。
+
+## execution-frontier-persisted
+
+根节点的执行明细落库。明细是“待执行的节点”的临时记录：执行完进入下一步后会被删除，不是历史台账。
+
+- 计数单位：`execution-detail`
+- span：无
+- 属性：无
+- 日志 signature：无
+- 什么时候出现：没有专门的信号标记“明细已写入”；`dispatch_submit` 覆盖了落库、监听器启动和发布调度，空根列表时也会出现，不能当作落库证明。
+- 分支：明细事务失败，则没有明细、也不会发布消息，调用方可以稍后重新提交。
+- 不能说明：明细表里的状态只是当前进度，不能当作更新历史。
+
+## after-commit-delivery
+
+明细提交成功后，把消息发布到主队列。
+
+- 计数单位：`queue-publication`
+- span：无
+- 属性：无
+- 日志 signature：`send nodeTaskId {} , executeId {}`
+- 什么时候出现：
+  - 外层有事务时，发布动作等事务提交后再执行；没有事务就立即执行。
+  - 发布后，如果这条明细在落库时标记为“待发送”（`PENDING_SENT`），会把标记更新为“已发送”（`SENT`）。
+  - 每发布一条消息打一行日志。
+- 分支：
+  - 发布线程池拒绝、发布失败：打 ERROR 日志（`[DispatchAfterCommitSubmitExecutor] submit rejected` / `submit failed`、`[DispatchAfterCommitAction] after commit action failed`），根节点仍是“待发送”，由 [ready-recovery](events-execution.md#ready-recovery) 补发。
+  - 发布成功但更新“已发送”标记失败：消息可能已投递而明细仍是“待发送”，之后可能重复补发，靠消费端去重。
+  - 子节点发布失败：子节点创建时就是“已发送”，补发巡检不会再管它，当前没有对应的自动补发路径。
+- 不能说明：日志只说明“发布调用返回了”，不代表消息被 broker 确认或被消费；发布次数不是尝试次数，补发和重复投递都会增加它。
+- 同一行日志模板还会出现在 [init-recovery](events-execution.md#init-recovery) 里，不能只靠文本区分两者，要结合前后事件。

package/content/knowledge/update/topics/events-outcome.md

@@ -0,0 +1,163 @@
+# 更新事件：load、引擎与结果
+
+节点真正执行时的几个环节：决定要不要加载数据、提交给引擎写入、得出节点结果、通知监听器，再释放下游子节点。整体流程见[一次更新怎么走完](lifecycle.md)，事件之间的关联见[关联边与性能片段](correlations.md)。
+
+## 目录
+
+- [load-decision](#load-decision)
+- [load-operation](#load-operation)
+- [result-publish](#result-publish)
+- [engine-handoff](#engine-handoff)
+- [primary-node-result](#primary-node-result)
+- [listener-invocation](#listener-invocation)
+- [child-release](#child-release)
+- [listener-derived-chain](#listener-derived-chain)
+
+## load-decision
+
+节点执行时先决定这次要不要真的把数据写进引擎：失败、直通、跳过、复用已有结果、不需要加载，或者调用加载。
+
+- 计数单位：`load-decision`
+- span：无
+- 属性：`active`、`loadData`、`execution.mode`、`loadDataSkipReason`、`skip`、`dataModify`
+- 日志 signature：无
+- 什么时候出现：这些属性在节点执行结束时统一写到 `update` span 上，是“结果”，不是决定发生时的实时信号。
+  - `execution.mode`：这次结果怎么落。`WRITE` 是自己算并写进引擎，包括引用失败后回退来写；`REF` 是不写数据、直接指向已有结果，见 [result-publish](#result-publish)；空字符串是进了准备、但没走到这一步（主动不加载、不需要加载或之前就失败）；没有这个属性是连准备都没进。
+  - `loadData`：是否完成加载或结果复用。`true` 包括实际写入、引用成功和数据未变而跳过写入；`false` 表示不加载或执行失败，不代表没有发起引擎写入。
+  - `loadDataSkipReason`：主动不加载的原因，只在 `loadData=false` 且有明确原因时出现。`INACTIVE` 表不活跃，`ASSET_AUTH_UNCHANGED` 资产权限没变化，`PASS_THROUGH` 直通表，`MIGRATION_TARGET_ABSENT`、`MIGRATION_SOURCE_SCHEMA_ABSENT`、`MIGRATION_SOURCE_TABLE_ABSENT` 是迁移场景里目标或来源不存在。
+  - `skip`：引擎写入时发现数据没变，没有真的写，对应日志 `reason: skip write (parent data unchanged)`。REF 时总是 `false`。
+  - `dataModify`：`1` 变了，`0` 没变，`-1` 无法判断。主动不加载记 `0`；REF 时读的位置或版本换了记 `1`，没换又缺少变化依据记 `-1`。
+  - `active`：这张表当前是不是活跃表。
+- 读法：`loadData=false` 时，先看 `loadDataSkipReason`；没有原因时，结合错误和加载日志区分不需要加载与执行失败，不能据此判断失败阶段。实际写入结合 `execution.mode`、`skip` 和写入统计判断；REF 的 `dataModify=1` 只说明换了读的版本。
+- 分支：
+  - 同一合并链里有父节点失败：当前节点直接判失败，不加载，见 [primary-node-result](#primary-node-result)。
+  - 语法检查或加载前校验失败：记业务失败，不加载。
+  - 直通、不活跃、权限没变、复用已有结果、物理上已可用：可能成功，但没有写入，也没有引擎任务。
+- 不能说明：`loadData=true` 不代表写了新数据，要看 `execution.mode`、`skip` 和 `dataModify`。
+
+## load-operation
+
+决定要加载之后，调用对应表类型的加载逻辑，把数据写进引擎。这一步有稳定的“开始/结束”日志，可以用来圈定一次加载。
+
+- 计数单位：`load-operation`
+- span：无
+- 属性：`execution.mode`
+- 日志 signature：`table load start`、`table load success`、`table load fail`
+- 其他日志：`Full Load:id = {}, transferName = {}, executionMode={}, computeFromTableId={}`
+- 什么时候出现：
+  - 加载日志是一块多行文本，标题行形如 `*************** table load start ***************`，后面依次是 `table:`（节点表 ID，和 `exec nodeTaskId` 里的一致）、`tenantId:`、`transferName:`，成功时还有 `cost: N ms`。这条日志带 `trace_id` 和 `span_id`，`span_id` 就是 `dispatch_node_task_exec`，可以直接对回执行 trace。
+  - 正常加载：先 `table load start`，结束时 `table load success` 并带 `cost`（毫秒，即这次加载耗时）。
+  - 失败：节点失败时打 `table load fail`，没有 `cost`。
+  - 成功日志也会出现在没有物理写入的情况，靠 `cost:` 或 `reason:` 那一行区分：`cost: don't need update polars` 表示不需要更新引擎；`cost: don't active` 表示表不活跃；`reason: skip write (parent data unchanged)` 表示父表数据没变、跳过写入；`reason: skip write (SHARED_RESULT)` 表示数据门户复制的表复用来源结果（见 [result-publish](#result-publish)），其他 REF 打的是普通的 `cost: N ms`；同时给出 `computeFromTableId`、`engineId`、`schema`、`version`。
+  - `Full Load:id = ...` 在判断是否需要加载之前就打了，带 `executionMode` 和 `computeFromTableId`，不能单独当作物理加载的证明。
+- 分支：
+  - 加载失败：节点得到 FAIL 结果；如果失败属于“引擎主节点或依赖来源不可用”，则走死信队列而不是节点失败，见 [attempt-consumed](events-execution.md#attempt-consumed)。
+- 不能说明：`table load success` 不等于有数据写入，要同时看 `cost:` / `reason:` 行和 `execution.mode`；`update.load_data` 这类汇总指标没有表、链、尝试标识，圈不出某一次加载。关系（relation）加载另有 `relation load start/success/fail` 日志，和这里不是同一类。
+
+## result-publish
+
+REF 不写数据，而是选定来源的一个版本，给它打保护 tag，再把本表的读取位置提交过去；提交成功后释放旧版本的 tag，旧物理表没人读了才删。WRITE 后读取位置变了（比如从引用改回自己算）也走这里的提交和释放。
+
+- 计数单位：`result-publish`
+- span：`result.binding.commit`、`result.snapshot.retain_selected`、`result.snapshot.tag.<操作>`、`result.snapshot.release`、`result.snapshot.discard_unused`
+- 属性：`result.binding.committed`、`result.writer.table_id`、`result.tag.name`（都在上面这些结果 span 上，`update` span 上没有）
+- 日志 signature：`[ResultBinding] event=COMMIT_RESULT committed={}`、`[ResultBinding] event=COMMIT_REJECTED reason=SOURCE_CHANGED`、`[Snapshot tag {}]`、`[ResultRetention] event=RELEASE_REQUESTED`、`[ResultRetention] event=RELEASED`、`[ResultRetention] event=ORPHAN_CLEANUP_REQUESTED`
+- 其他日志：`[ResultBinding] event=WRITE_DECISION`、`[ResultRetention] event=COPIED`
+- 什么时候出现：日志都带 `trace_id`，按本表 ID、物理表 ID、版本号或 tag 名搜。
+  - 走 REF 的表：只选了上游字段（最多改名）、没有其他步骤的分析表，原样引用上游结果，配置 `update.materialization.always-materialize=true` 时改为照常写入；数据门户复制出的表和来源共享计算，直接复用来源结果，加载日志是 `reason: skip write (SHARED_RESULT)`，共享失效后按自己的配置重算；镜像表和企业数据表指向来源结果；云 JDBC 数据源的隐藏表直接引用同步下来的数据。
+  - tag：湖存储的结果按 `reference-<本表ID>-<版本号>` 打 tag，一张引用表的一个版本一个，防止这个版本被引擎回收。`[Snapshot tag ...]` 记请求和成功或失败；失败那条是 WARN，引擎可能已经执行，tag 状态不确定。NAS 存储没有 tag，改为复制一份副本（`event=COPIED`）。
+  - 提交：`COMMIT_RESULT committed=true` 是本表读取位置真的换了，日志里有前后绑定；`committed=false` 或 `COMMIT_REJECTED reason=SOURCE_CHANGED` 是加载期间来源或本表变了、拒绝提交，不是引擎故障，本表继续读旧版本。
+  - 释放：`RELEASE_REQUESTED` 带原因，常见的是 `RESULT_COMMITTED`（提交成功，释放旧版本）和 `BINDING_UNCOMMITTED`（没提交成功，释放这次新打的 tag），另有 `TABLE_DELETED` 等。`RELEASED` 是 tag 已删，`ORPHAN_CLEANUP_REQUESTED` 是旧物理表已发起删除，都不代表引擎已回收快照。
+  - 统计：REF 不在本节点计算，没有本节点的引擎任务，不查 Metric。行数取来源的统计（数据源直引时现数一次）；峰值内存在原样引用和数据源直引时记 0，门户共享时继承来源。
+- 分支：
+  - 选定版本已不存在：最多重选 3 次；仍不行、且来源还是最初的最新版本时，回退照常写入（`execution.mode` 变成 `WRITE`）。来源已变、校验失败或其他引擎错误不回退，节点失败，旧绑定和旧 tag 保留。
+- 不能说明：tag 成功不等于本表已切换，要看 `COMMIT_RESULT committed=true`；`RELEASED` 不等于快照已被回收。同一 trace 里的这些日志可能来自 DAG 里的多张表，按 tableId 对。
+
+## engine-handoff
+
+写入走 Polars 引擎时，服务端把写任务交给引擎事务，提交后拿回写入结果。
+
+- 计数单位：`engine-task`
+- span：`DataFlowExecutor`、`execute`
+- 属性：`write_metric`、`metric`、`polarsNode`、`compute.retry.pipeline_parallelism_reduced`
+- 日志 signature：`table {} load fail!`、`table {} load success.`
+- 什么时候出现：
+  - `DataFlowExecutor` 是 `dispatch_node_task_exec` 的子 span，`execute` 是它的子 span；`execute` 这个名字在别处也有，要看它的父 span 是不是 `DataFlowExecutor` 才算引擎写入。
+  - 写入完成后，`write_metric` 记录引擎返回的写入统计；`polarsNode` 记录执行的引擎节点名。
+  - 结果里的 `taskId` 会写进节点结果埋点。
+- 分支：
+  - 可重试的引擎失败：服务端可以重试，每次重试产生新的引擎任务 ID，成功结果只暴露最后返回的那个。
+  - 数据源湖（MPP）写入遇到引擎任务内存不足：允许重试一次，并把流水线并行度降为 1，同时写 `compute.retry.pipeline_parallelism_reduced`。这只针对这一类写入，不是所有 OOM 的通用重试策略。
+  - 引擎写入失败：事务回滚，服务端加载失败；要继续追查，需要具体的引擎任务或请求标识，否则停在服务端边界。
+- 不能说明：直通、不活跃、不需要加载等没有引擎任务；失败或重试过的任务不会都留下标识，引擎内部细节不在这里。
+
+## primary-node-result
+
+节点执行得出的主结果：成功或失败。这一步之后才会通知监听器、释放子节点。
+
+- 计数单位：`node-primary-result`
+- span：`dispatch_node_task_exec`
+- 属性：`dagId`、`tableId`、`tableName`、`userId`、`rowCount`、`updateType`、`requeue`、`active`、`rootErrorId`、`dispatchConsumed`、`businessConsumed`
+- 日志 signature：`finish to exec task, nodeTaskId = {}, chainId = {}, cost = {}ms`、`task exec error, nodeTaskId {}, chainIds {}, {}`
+- 其他日志：`begin to exec task, nodeTaskId = {}, chainId = {}`、`exec nodeTaskId {}, executeIds {}`、`execute task error, msg = {}`（ERROR，带异常堆栈）、`Task is failed by its parent failed, curId {}, fail parent {}, chainId {}`（ERROR）、`exec fail, nodeTaskId {}, chainId {}, id {}，do not callback children node `（ERROR）
+- 什么时候出现：
+  - `dispatch_node_task_exec` 是节点真正执行的 span，在 `update` 这条 trace 里，里面有语法检查、加载、引擎写入和监听器 span；整次尝试的 `update` 总耗时一般略大于它。
+  - 上面列的属性都写在 `update` span 上，而不是 `dispatch_node_task_exec` 上，并且按进度逐步写入：`loadData` 等在完成回调里无条件写；`dagId`、`tableName`、`userId`、`rowCount`、`updateType`、`requeue`、`active`、`rootErrorId` 要先取得这张表的更新配置才写；`dispatchConsumed`、`businessConsumed` 要走到成功或失败回调才写。节点在准备阶段就失败（例如表已失效）时，`update` 上只有 `loadData`。各属性含义：`updateType` 是更新场景名（如 `ACTIVE`、`SCHEDU`），`rowCount` 成功时是行数、失败时是 -1，`dispatchConsumed` 是整个消费线程的耗时、`businessConsumed` 是节点业务执行的耗时（毫秒），`rootErrorId` 只在失败时有，是导致失败的根表。
+  - 执行入口先打 `exec nodeTaskId ... executeIds [...]`（`executeIds` 是被合并的所有明细），再打 `begin to exec task`，成功后打 `finish to exec task`（`cost` 是节点耗时，毫秒）。
+  - 失败时打两条 ERROR：一条 `execute task error, msg = ...` 带堆栈（SigNoZ 里有 `exception.type`、`exception.message`、`exception.stacktrace`），一条 `task exec error, ...` 只有摘要。
+  - 节点结果还会生成一条 XS03 埋点，字段包括 `dagId`、`tableId`、`status`、`rows`、`actualWrite`、`dataModify`、`errorMsg`、`requeue`、`triggerId`、`tenantId`、`dispatchConsumed`、`businessConsumed`、`polarsConsumed`。埋点是否能在 SigNoZ 里查到没有核实，不要当作首查依据。
+- 分支：
+  - 父节点（同一合并链内）失败：当前节点直接失败，打 `Task is failed by its parent failed`，并把根因表写进 `rootErrorId`。
+  - 普通业务失败：转成 FAIL 结果，不再往队列层抛，所以消费者看不到异常。
+  - 停止工作（引擎主节点不可用）：不当作节点结果，异常继续向上抛，消息进死信队列；这种情况没有 XS03 埋点。
+- 不能说明：节点成功不代表整条链完成、数据真的变化、监听器成功或有引擎任务；`status` 只区分成功和失败，监听器结果另算。
+
+## listener-invocation
+
+节点结果之后，按固定顺序依次触发一组监听器，各自处理自己的后续工作（刷新配置、推送状态、触发工作流、写指标等）。
+
+- 计数单位：`listener-invocation`
+- span：`trigger_listener_<监听器名>`
+- 属性：无
+- 日志 signature：无
+- 什么时候出现：
+  - 每次触发一个监听器就产生一个 `trigger_listener_<名称>` span，例如 `trigger_listener_UPDATE_METRIC`、`trigger_listener_WORK_FLOW`、`trigger_listener_CORP_SETTING`。
+  - 一次更新链的提交（`dispatch_submit`）里每个监听器各触发一次（开始），一个被执行的节点里每个监听器各触发三次（执行前、成功或失败、完成）。所以一个节点的 `update` trace 里同名监听器 span 通常有 3 个。
+  - 默认的 9 个监听器：`ANALYSIS_CONF_SYNCHRONIZED`、`COMPUTE_TABLE_FIELD_RENAME`、`COMPUTE_RED_MARK`、`CUSTOM_TABLE_STATUS_EVENT`（或 `TASK_STATUS_EVENT`）、`CORP_SETTING`、`UPDATE_WEB_SOCKET_SEND`、`WORK_FLOW`、`UPDATE_METRIC`、`ANALYSIS_CONFIG_ROUNDTRIP_CHECK`。副本、迁移等场景用不同的组合，所以不是每条链都有全部监听器。
+  - span 名只带监听器名，不带是“开始/执行前/成功/失败/完成”哪个阶段，要靠时间顺序和父 span 区分。
+- 分支：
+  - 某个监听器抛异常：记 ERROR 日志，继续下一个监听器，节点主结果不变。
+  - `onComplete` 只表示这个节点的回调走完，不是整条链完成。
+- 不能说明：监听器自己的异步工作、应用日志都不在这个 span 里；`WORK_FLOW` 监听器只在满足条件（基础表更新、符合条件的工作流）时才会真正启动工作流，不能因为有 `trigger_listener_WORK_FLOW` 就认为启动了工作流。
+
+## child-release
+
+节点执行完，把它的下游子节点放出来：删除父节点明细，判断每个子节点能不能执行，保存子节点明细并发布。
+
+- 计数单位：`execution-detail`
+- span：`dispatch_callback_children`、`evaluator_child`
+- 属性：无
+- 日志 signature：`dispatch callback children, nodeTaskId {}, executeId {}, chainId {}, children size {},`
+- 其他日志：`exist circle, parent {}, cyclicIds {}`（WARN）、`evaluator error, nodeTaskId {}`（ERROR）、`evaluator error`（ERROR）
+- 什么时候出现：
+  - `dispatch_callback_children` 在 `update` trace 里；其中判断子节点是否可执行的步骤是 `evaluator_child`；没有子节点的只删除明细，不做判断，所以 `evaluator_child` 比 `dispatch_callback_children` 少。
+  - 日志 `children size` 是这次保存的子节点明细数；它只有数量，没有子节点 ID，也没有发布确认。
+  - 子节点的状态：自己的所有祖先都完成了才会保存，并直接就绪；祖先还有没完成的就不保存，等祖先完成时再放。如果允许合并，且还有别的链里的祖先在等，就保存成“等待”（INIT），之后由其他链释放或启动巡检放行（见 [init-recovery](events-execution.md#init-recovery)）。
+  - 配置里出现父子循环依赖（子节点是自己或父节点）时，打 WARN 并排除这些节点。
+- 分支：
+  - 没有子节点：只删除父节点明细，不打 `dispatch callback children` 日志。
+  - 子节点事务失败：父节点明细保留，没有更强的自动恢复保证。
+  - 判断子节点时出错：记 ERROR 后异常上抛。
+- 不能说明：子节点明细是逐步生成的，不是完整的逻辑依赖图，也不是历史尝试；没有子节点和事务/发布失败要分别解读。
+
+## listener-derived-chain
+
+监听器处理时主动再提交一批更新，生成新的更新链。目前确认的是企业设置监听器触发的“权限变更”链。
+
+- 计数单位：`update-chain`
+- span：无
+- 属性：`authChangeDagId`、`authChangeRootCount`
+- 日志 signature：`update corp success , update {}`
+- 什么时候出现：监听器调用调度入口提交权限变更的更新并拿到新链 ID 之后，把新链 ID 和根数量写到源节点所在的 `update` span 上，并打日志。
+- 分支：派生提交失败，监听器记自己的失败日志，源节点的主结果仍是成功，不自动回滚。
+- 不能说明：派生链的上下文里不保存源链 ID，没有“源链—监听器—派生链”的持久关联，只有这条进程内的调用能证明关系；这只覆盖企业设置监听器，不代表所有监听器。

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

@@ -0,0 +1,58 @@
+# 一次更新怎么走完
+
+把分析表更新从“业务模块提交”到“下游全部跑完”的过程串成一条线，标出每一步在 SigNoZ 里留下的 span 和日志。各事件的细节在[受理与入队](events-intake.md)、[消费、重排队与合并](events-execution.md)、[load、引擎与结果](events-outcome.md)；事件之间怎么关联见[关联边与性能片段](correlations.md)。
+
+## 目录
+
+- [先记住的几个概念](#先记住的几个概念)
+- [过程总览](#过程总览)
+- [一次执行的 span 结构](#一次执行的-span-结构)
+
+## 先记住的几个概念
+
+- **链**：一次受理的更新请求生成一条链，链 ID 就是 `dagId`。链里有若干张表（节点）。
+- **明细**：一个节点在一条链里的待执行记录，写在库里，执行完就删除。明细 ID 就是日志里的 `executeId`（队列消息里叫 `id`、死信日志里叫 `msgId`）。
+- **节点表 ID**：就是日志里的 `nodeTaskId`，和 `update` span 上的 `tableId`、加载日志里的 `table:` 是同一个值。
+- **根节点与子节点**：请求里没有祖先在候选里的表是根，先执行；它们执行完再放出直接下游，一层层往下。
+- **更新场景**：`updateScene`，也叫更新“tag”，见[更新场景表](../concepts.md#更新场景updatescene)。
+
+## 过程总览
+
+| 步骤 | 发生什么 | SigNoZ 里的信号 | 事件 |
+|---|---|---|---|
+| 1 受理 | 业务模块提交候选表，调度生成链、过滤候选、选根、查下游 | `dispatch_submit`（属性 `dagId`、`totalSize`、`updateScene`），其下有 `dispatch_gen_roots`、`dispatch_get_descendants`；日志 `dispatch receive request` / `submit root task success` | [intent-accepted](events-intake.md#intent-accepted)、[effective-root-selection](events-intake.md#effective-root-selection)、[logical-dependency-expansion](events-intake.md#logical-dependency-expansion) |
+| 2 落库与监听器启动 | 根节点明细写库；各监听器收到“开始” | `dispatch_submit` 下的 `trigger_listener_<名称>` | [execution-frontier-persisted](events-intake.md#execution-frontier-persisted)、[listener-invocation](events-outcome.md#listener-invocation) |
+| 3 发布消息 | 明细提交后，把消息发到主队列 | 日志 `send nodeTaskId ... executeId ...` | [after-commit-delivery](events-intake.md#after-commit-delivery) |
+| 4 消费 | 主队列投递一次，就是一次尝试 | 发布所在 trace 里的 `node-task-queue receive`，另开一条 trace，根 span 是 `update`；日志 `handle nodeTaskId ...` | [attempt-consumed](events-execution.md#attempt-consumed) |
+| 4a 限流 | 租户并发超限，消息转到慢队列，额度够了再回主队列 | 日志 `Tenant limit exceeded`；`slow-node-task-queue receive` | [capacity-deferred](events-execution.md#capacity-deferred) |
+| 4b 拿锁失败 | 同一节点正被别人处理，等锁超时后重新排队 | 日志 `resend execute info` | [lock-requeued](events-execution.md#lock-requeued) |
+| 5 合并 | 把同一节点的多条明细合成一次执行 | 日志 `merge isolationMode ...`；多链合并时 `update` 上有 `merge_count` | [merge-decision](events-execution.md#merge-decision) |
+| 6 执行节点 | 语法检查、决定是否加载、写入引擎 | `dispatch_node_task_exec`，里面有 `grammarCheck`、`DataFlowExecutor` / `execute`；日志 `table load start` / `table load success` | [load-decision](events-outcome.md#load-decision)、[load-operation](events-outcome.md#load-operation)、[engine-handoff](events-outcome.md#engine-handoff) |
+| 7 节点结果 | 得出成功或失败，写 `update` 上的结果属性 | `update` 的 `updateType`、`loadData`、`rowCount`、`dispatchConsumed`、`businessConsumed`；日志 `finish to exec task` / `task exec error` | [primary-node-result](events-outcome.md#primary-node-result) |
+| 8 监听器 | 执行前、成功/失败、完成三次回调 | `dispatch_node_task_exec` 下每个监听器 3 个 `trigger_listener_<名称>` | [listener-invocation](events-outcome.md#listener-invocation) |
+| 9 释放子节点 | 删除本节点明细，判断并保存可执行的子节点，再发布 | `dispatch_callback_children`、`evaluator_child`；日志 `dispatch callback children ... children size` | [child-release](events-outcome.md#child-release) |
+| 回到 3 | 子节点的消息再走 3 至 9，直到没有下游 | 每个子节点各有一条 `update` trace，`linked` 指向放出它的上一个节点所在的 trace | — |
+
+没有走到执行的投递（限流转发、拿锁失败、判定已执行、被合并掉）也会各有一个 `update` span，但没有 `updateType`、`rowCount` 这些结果属性。
+
+## 一次执行的 span 结构
+
+一次真实的节点执行（`update` trace，已脱敏简化）：
+
+```text
+update                                  根 span，Consumer；linked = 放出它的上游所在 trace
+├─ dispatch_node_task_exec              节点真正执行的区间
+│  ├─ trigger_listener_<名称> × 9       执行前（每个监听器 1 个）
+│  ├─ grammarCheck                      语法检查
+│  ├─ DataFlowExecutor                  引擎写入（有物理写入时）
+│  │  └─ execute
+│  ├─ trigger_listener_<名称> × 9       成功或失败
+│  └─ trigger_listener_<名称> × 9       完成
+└─ dispatch_callback_children           释放子节点
+   └─ evaluator_child                   判断子节点可否执行（有子节点时）
+```
+
+要点：
+
+- `dispatch_node_task_exec` 是 `update` 的子 span，监听器、语法检查和引擎写入都挂在它下面；`dispatch_callback_children` 挂在 `update` 下，不在 `dispatch_node_task_exec` 里面。
+- 加载日志（`table load start` / `table load success`）带 `span_id`，等于 `dispatch_node_task_exec` 的 span ID，可以直接对回这个区间。