first commit

2026-03-09 16:31:42 +08:00
commit 4a9c444b10
486 changed files with 52479 additions and 0 deletions
@@ -0,0 +1,93 @@
+# 状态机形式化说明（与代码一致）
+
+## 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` 并跳过
+
+## 3. 事件到代码映射
+
+### bootstrap
+- `E01`：`engine/events.py::e01_bootstrap()`
+
+### bind
+- `E10`：`engine/events.py::e10_bind_core()`
+- `E15`：`engine/events.py::e15_bind_dependency()`
+- `E16`：`engine/events.py::e16_bind_auto()`（自动绑定判定；`ZERO+create_enabled=true` 时进入 `S13`，等待创建副作用提交）
+
+### create/update prepare
+- `E20`：`engine/events.py::e20_create_prepare()`（spawn 成功从 `S13` 提交到 `S01`；失败保持 `S13`）
+- `E21`：`engine/events.py::e21_create_prepare()`
+- `E30`：`engine/events.py::e30_update_prepare()`
+
+### sync execute
+- `E40C_START/E40C`：CREATE 执行入口与结果回写
+- `E40U_START/E40U`：UPDATE 执行入口与结果回写
+- `E40D_START/E40D`：DELETE 执行入口与结果回写
+
+## 4. strategy 调用链（当前）
+- bind 主入口：`sync_system/strategy.py::DefaultSyncStrategy.bind()` -> `strategy_ops/bind_ops.py::run_bind()`
+- create 主入口：`sync_system/strategy.py::DefaultSyncStrategy.create()` -> `strategy_ops/create_ops.py::run_create()`
+- update 主入口：`sync_system/strategy.py::DefaultSyncStrategy.update()` -> `strategy_ops/update_ops.py::run_update()`
+- reset 主入口：`sync_system/strategy.py::BaseSyncStrategy.run_reset()` -> `strategy_ops/reset_ops.py::run_phase2_cleanup()`
+
+## 5. context 字段（以 YAML 为准）
+
+### bind 相关
+- `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 负责业务语义计算（如依赖是否满足、自动绑定结果、差异检测）。
+- 状态机只负责迁移判定与不变量校验，不直接访问数据源。
+
+## 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（不再是图示别名）。