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

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。

验收要求

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

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

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