ecm_sync_system/docs/state_machine.md

状态机形式化说明（与代码一致）

1. 真源与执行入口

• 配置真源：sync_state_machine/config/node_state_machine.yaml
• 事件入口：sync_state_machine/engine/events.py
• 状态落地：sync_state_machine/engine/state_apply.py
• 不变量校验：events._apply_decision() 内调用 runtime.check_invariants()

2. 状态集合（Sxx）

• S00：bind 起点（UNCHECKED/NONE/PENDING）
• S01：NORMAL，待后续 create/update 判定
• S02：MISSING，待依赖检查/自动绑定/create
• S03：ABNORMAL，阻断
• S04：WARNING，阻断
• S05：DEPENDENCY_ERROR，阻断
• S06：CREATE 待执行（目标节点）
• S07：UPDATE 待执行（action=UPDATE,status=PENDING）
• S08：UPDATE 前置失败（action=UPDATE,status=PRECONDITION_FAILED）
• S10C/S10U/S10D：按动作拆分的执行中状态
• S11C/S11U/S11D：按动作拆分的执行成功状态
• S12C/S12U/S12D：按动作拆分的执行失败状态
• S13：对侧创建等待态（PEER_CREATING/NONE/PENDING）
• S14：UPDATE 运行时降级为 NONE 并跳过
• S17：bootstrap 加载异常隔离（存在绑定，但 datasource refresh 未返回最新节点）

3. 事件到代码映射

bootstrap

• E01：sync_state_machine/engine/events.py::e01_bootstrap()

bind

• E10：sync_state_machine/engine/events.py::e10_bind_core()
• E15：sync_state_machine/engine/events.py::e15_bind_dependency()
• E16：sync_state_machine/engine/events.py::e16_bind_auto()（自动绑定判定；ZERO+create_enabled=true 时进入 S13，等待创建副作用提交）

create/update prepare

• E20：sync_state_machine/engine/events.py::e20_create_prepare()（spawn 成功从 S13 提交到 S01；失败保持 S13）
• E21：sync_state_machine/engine/events.py::e21_create_prepare()
• E30：sync_state_machine/engine/events.py::e30_update_prepare()

sync execute

• E40C_START/E40C：CREATE 执行入口与结果回写
• E40U_START/E40U：UPDATE 执行入口与结果回写
• E40D_START/E40D：DELETE 执行入口与结果回写

4. strategy 调用链（当前）

• bind 主入口：sync_state_machine/sync_system/strategy.py::DefaultSyncStrategy.bind()
• create 主入口：sync_state_machine/sync_system/strategy.py::DefaultSyncStrategy.create()
• update 主入口：sync_state_machine/sync_system/strategy.py::DefaultSyncStrategy.update()
• reset 主入口：sync_state_machine/pipeline/full_sync_pipeline.py::_load_persistence_state() -> sync_state_machine/sync_system/strategy_ops/reset_ops.py::run_phase2_cleanup()

5. context 字段（以 YAML 为准）

bind 相关

• bootstrap_source_present
• has_binding_record
• core_binding_result / peer_core_binding_result (NORMAL|WARNING|ABNORMAL)
• data_present
• has_depend_fields
• dep_satisfied
• auto_bind_enabled
• auto_bind_outcome (ONE_TO_ONE|AMBIGUOUS|ZERO|KEY_MISSING|KEY_ID_RESOLVE_FAIL|DATA_MISSING)

create/update 相关

• create_enabled
• create_id_resolve_ok
• spawn_success
• update_enabled
• target_has_data_id
• update_id_resolve_ok
• has_diff

execute 相关

• handler_result (SUCCESS|FAILED|SKIPPED|IN_PROGRESS)
• poll_timeout

6. 语义边界

• strategy 负责业务语义计算（如依赖是否满足、自动绑定结果、差异检测）。
• 状态机只负责迁移判定与不变量校验，不直接访问数据源。
• bootstrap 阶段的数据源刷新由 pipeline 完成，状态机只消费 bootstrap_source_present / has_binding_record / is_create_zombie 这些已计算上下文。

7. 不变量

• INV-1_UNCHECKED_ACTION_NONE
• INV-2_BLOCKING_NO_ACTION
• INV-3_PRECOND_IMPLIES_UPDATE

当状态落地后违反 invariant，运行时会直接抛错。

8. 校验与出图

1. python tools/validate_config.py --config sync_state_machine/config/node_state_machine.yaml
2. python tools/render_graph.py --config sync_state_machine/config/node_state_machine.yaml --format mermaid --out docs/state_machine.mmd

9. 事件意图命名（图示层）

• 为了让流程意图更直观，图示可使用 E01.reset.* / E10.core.* / E20.create.* / E30.update.* / E40<action>.* / E41.create.* 这类别名。
• 别名仅用于图标签；运行时事件 ID 仍以 YAML 中 E01/E10/E15/E16/E20/E21/E30/E40C_START/E40C/E40U_START/E40U/E40D_START/E40D/E41 为准。
• S10C/S10U/S10D 与 S11C/S11U/S11D 现已是配置中的真实状态 ID（不再是图示别名）。