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

## 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`：`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()` -> `sync_state_machine/sync_system/strategy_ops/bind_ops.py::run_bind()`
- create 主入口：`sync_state_machine/sync_system/strategy.py::DefaultSyncStrategy.create()` -> `sync_state_machine/sync_system/strategy_ops/create_ops.py::run_create()`
- update 主入口：`sync_state_machine/sync_system/strategy.py::DefaultSyncStrategy.update()` -> `sync_state_machine/sync_system/strategy_ops/update_ops.py::run_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 相关
- `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（不再是图示别名）。