chore: close wasm status contract work

wasm-port/working/11-WASM核心状态机边界与后续完善路线.md

@@ -0,0 +1,82 @@
+# 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. JSON 字段可以兼容旧 SDK/UI，但必须从核心结构体导出，不能成为新的事实源。
+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`。
+
+## 代码修改检查清单
+
+每次按本路线改 WASM runtime 时，至少检查：
+
+- 新状态是否有 C/C++ 结构体字段，而不是只新增 JSON 字段。
+- 新 command 是否先入队，再由 `lctask_run_cycles()` 消费。
+- 新 status JSON 字段是否从 `StandaloneEmcStatus` 或明确的 C/C++ status buffer 导出。
+- JS/SDK 是否只做边界包装和兼容 API。
+- 是否新增或更新 `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。