# 11-WASM核心状态机边界与后续完善路线

## 目标

本文件固定后续完善 `wasm-port` 程序时的边界：WASM/C++ 程序作为核心状态机实现的运行载体，JS/SDK 和 JSON 只承担 host/browser 边界职责。

后续新增代码任务前，必须先把对应任务补入 `04-任务矩阵.md`，写明验收标准和 gate，再按本文件推进。

## 分层边界

| 层 | 职责 | 不应承担 |
| --- | --- | --- |
| WASM/C++ | LinuxCNC 语义复用、task/motion 核心状态机、task cycle、motion snapshot、command read/plan/execute、RCS 聚合、`StandaloneEmcStatus` | 浏览器 UI 状态、DOM、OPFS 业务流程、JSON 文本状态机 |
| JS/SDK | 加载 WASM、管理 Emscripten FS/OPFS 边界、传入 command JSON、读取 status JSON、提供测试和 UI 友好 API | G-code 语义、task/motion 状态机、LinuxCNC planner/canon 语义 |
| JSON | host 与 WASM 的输入/输出通信格式，例如 `lctask_send_command_json()` 和 `lctask_read_status_json()` | 保存事实状态、推进 task 周期、执行 motion 语义、替代结构体状态 |

## 核心原则

1. `lctask_run_cycles()` 是 task 状态变化的主入口。
2. `lctask_send_command_json()` 只入队 host command，不直接改变 LinuxCNC task/motion 语义状态。
3. `lctask_read_status_json()` 只导出最后一次 status write，不推进 cycle、不重新读取 motion、不触发 command 执行。
4. 核心状态保存在 C/C++ 结构体、枚举、队列和周期函数中；当前集中容器为 `StandaloneEmcStatus`。
5. motion 状态通过 `LcmotStatusSnapshot` 在 task 周期内读入，再映射到 `StandaloneEmcStatus.motion`。
6. status JSON 只通过 `emcStatus` 暴露 task/motion/io/top 状态；旧顶层状态字段不再作为兼容视图输出。
7. 若 LinuxCNC 上游源码已有对应语义，优先接入 vendored source 或窄 shim，不在 JS/JSON 中重写。

## 当前事实源

当前阶段的事实源如下：

- task cycle skeleton：`linuxcnc_task_hal_wasm.cpp` 中的 command read、plan、execute、motion update、subordinate sync、task update、status write。
- task/motion/io/top status：`StandaloneEmcStatus`。
- motion runtime snapshot：`LcmotStatusSnapshot` 和 `lcmot_read_status_snapshot()`。
- RUN 主路径：staged program -> `emcTaskPlanRead()` -> `emcTaskPlanCommand()` -> `emcTaskPlanExecute()` -> `emccanon.cc` command envelope -> `taskintf.cc` motion issue。
- JSON status：`statusSource=StandaloneEmcStatus` 的外部导出视图。

status JSON 的 LinuxCNC `EMC_STAT` 字段映射、旧字段收口策略和后续 SJ 批次见 `12-status-json-LinuxCNC对标方案.md`。

当前 `12-status-json-LinuxCNC对标方案.md` 中 SJ-1 到 SJ-5 已补入 `04-任务矩阵.md` 的 T-051 到 T-055，并已闭合。后续不得再只用“后续路线”描述实际任务；凡是出现可执行实现项，必须同步进入任务矩阵。

## 后续完善路线

后续 WASM 程序完善应按以下顺序拆成新任务：

1. 扩展 `StandaloneEmcStatus` 字段覆盖，而不是扩展 status JSON 自有字段。
2. 将更多 `TaskRuntime` 分散字段迁移到 task/motion/io/top status 容器。
3. 继续把 plan/execute 分支替换为 vendored `emctask.cc`、`taskintf.cc`、`emccanon.cc` 的 source-anchored 子集。
4. 扩展 `taskintf.cc` usrmot shim，使 motion command/status/config/error 的映射更接近上游。
5. 评估 `emc_nml.hh` 的分阶段 typedef 或窄编译复用，但不得为了 readiness 提前引入完整 native NML/process topology。
6. 将新增状态字段同步补齐 WASM smoke、SDK smoke、state matrix 和 source reuse/drift docs gate。
7. 只有在完整 native task/HAL/runtime 边界被实际采用并验证后，才能提升 `nativeTaskReady`、`nativeHalSyncReady` 或 `fullLinuxCncProgramExecutionReady`。

本轮已闭合的 status JSON 子任务：

- T-051 / SJ-1：`emcStatus.motion.traj`。
- T-052 / SJ-2：task current/read/motion line 和 call level。
- T-053 / SJ-3：`emcStatus.motion.axis[]` 与 `joint[]`。
- T-054 / SJ-4：`emcStatus.io.aux/tool/coolant` 窄边界。
- T-055 / SJ-5：`tools/verify_task_status_json_contract.sh`。
- T-056：源头取消旧 status 字段兼容输出。

## 代码修改检查清单

每次按本路线改 WASM runtime 时，至少检查：

- 新状态是否有 C/C++ 结构体字段，而不是只新增 JSON 字段。
- 新 command 是否先入队，再由 `lctask_run_cycles()` 消费。
- 新 status JSON 字段是否从 `StandaloneEmcStatus` 或明确的 C/C++ status buffer 导出。
- JS/SDK 是否只做边界包装，不重新引入旧 status 字段兼容读取。
- 是否新增或更新 `tools/verify_task_*` gate。
- 是否同步更新 `03-推进台账.md`、`05-验收证据.md`、`06-决策记录.md`。

## 验收要求

后续实现任务完成时，至少运行：

```bash
cd /home/mes123456/cnc_wams/wasm-port
./tools/verify_task_full_closure.sh
git diff --check
```

如任务新增专用 gate，应先运行专用 gate，再运行 full closure gate。