chore: close wasm status contract work

wasm-port/working/01-项目功能内容.md

@@ -0,0 +1,122 @@
+# 01-项目功能内容
+
+## 项目目标
+
+将 `wasm-port` 的 task/motion/HAL 运行时从当前 minimal adapter 推进到尽可能贴近 LinuxCNC 原生 `emctaskmain.cc` 的 task 主循环结构。
+
+核心要求：
+
+- 每个 task 周期都建立 LinuxCNC 式 motion 状态快照。
+- task 状态机使用该 motion 快照驱动等待、错误、estop、abort、queueFull、in-position、program line 等行为。
+- 周期顺序对标上游 `emctaskmain.cc`：command read -> plan -> execute -> motion update -> subordinate sync -> task update -> status write。
+- 当前 JSON 自有状态机逐步收缩为 host/runtime 边界，CNC/task 语义优先来自 LinuxCNC 源码。
+- 后续 WASM 程序定位为核心状态机实现的运行载体：task/motion 状态机、周期调度、状态聚合、命令执行位于 C/C++ WASM 侧；JS/SDK 和 JSON 只承担外部边界职责。
+
+## 对标源
+
+主要对标文件：
+
+- `/home/mes123456/cnc_wams/linuxcnc/src/emc/task/emctaskmain.cc`
+- `/home/mes123456/cnc_wams/linuxcnc/src/emc/task/emctask.cc`
+- `/home/mes123456/cnc_wams/linuxcnc/src/emc/task/taskintf.cc`
+- `/home/mes123456/cnc_wams/linuxcnc/src/emc/task/emccanon.cc`
+- `/home/mes123456/cnc_wams/linuxcnc/src/emc/task/task.hh`
+- `/home/mes123456/cnc_wams/linuxcnc/src/emc/nml_intf/emc.hh`
+- `/home/mes123456/cnc_wams/linuxcnc/src/emc/nml_intf/emc_nml.hh`
+- `/home/mes123456/cnc_wams/linuxcnc/src/emc/motion/usrmotintf.h`
+- `/home/mes123456/cnc_wams/linuxcnc/src/emc/motion/motion.h`
+
+当前 WASM 侧入口：
+
+- `/home/mes123456/cnc_wams/wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp`
+- `/home/mes123456/cnc_wams/wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c`
+- `/home/mes123456/cnc_wams/wasm-port/runtime/sdk/src/linuxcnc-task-hal.js`
+
+## 当前闭合状态
+
+当前 `wasm-port` 已有：
+
+- `lctask_*` C ABI。
+- `lcmot_*` minimal motion runtime。
+- HAL pin/snapshot runtime。
+- Node WASM task/motion/HAL smoke。
+- LinuxCNC 式 task 周期骨架：command read -> plan -> execute -> motion update -> subordinate sync -> task update -> status write。
+- 周期内 `LcmotStatusSnapshot` 到 `StandaloneEmcStatus.motion` 的映射。
+- `StandaloneEmcStatus` 作为当前阶段 `EMC_STAT` 等价容器，集中导出 task/motion/io/top status。
+- RUN 文件主路径通过 staged program plan read/command/execute、`emccanon.cc` command envelope 和 `taskintf.cc` motion issue 工作，不依赖 host JSON motion plan。
+- task 状态、模式、pause/resume/step/home/run gate、wait-for-motion、queueFull、motion error、soft-limit、IO error、RCS 聚合和 no-JSON RUN path 的 WASM/SDK/state-matrix 覆盖。
+
+当前保守边界：
+
+- 当前 shim `runtime/core/shims/nml_intf/emc.hh` 只暴露 `motion.traj.linearUnits`，远小于上游 `emc_nml.hh` 中 `EMC_STAT`、`EMC_TASK_STAT`、`EMC_MOTION_STAT`、`EMC_TRAJ_STAT` 的字段范围。
+- task-HAL WASM 构建接入的是 `emctask.cc`、`taskintf.cc`、`emccanon.cc` 的窄 source-anchored subset，不是完整上游 process/NML topology。
+- `tools/task-hal-source-manifest.txt` 仍是 Phase 0 references，`task_hal_runtime_promoted=0`。
+- `nativeTaskReady=false`、`nativeHalSyncReady=false`、`fullLinuxCncProgramExecutionReady=false` 仍是当前 readiness contract。
+
+## WASM核心状态机边界
+
+后续完善时按以下职责划分：
+
+| 层 | 职责 |
+| --- | --- |
+| WASM/C++ | 核心状态机、LinuxCNC 语义复用、task cycle、motion snapshot、`StandaloneEmcStatus`、command read/plan/execute、RCS 聚合。 |
+| JS/SDK | 加载 WASM、传命令、读状态、管理 Emscripten FS/OPFS 和浏览器/Node 边界。 |
+| JSON | 作为外部通信格式，例如 command JSON 和 status JSON；不得作为核心状态机事实源。 |
+
+因此，新增状态应优先进入 C/C++ 结构体、枚举、队列和周期函数；status JSON 只能从最后一次 status write 或 `StandaloneEmcStatus` 导出。
+
+`status JSON` 的具体 LinuxCNC 对标方案详见 `12-status-json-LinuxCNC对标方案.md`。该方案要求 `emcStatus` 成为新增 LinuxCNC 对标字段的主对象，`task`、`motionStatus` 等旧字段只作为兼容视图。
+
+## 功能范围
+
+本阶段要实现或准备实现：
+
+1. 在 WASM task runtime 内建立 `EMC_STAT` 等价状态容器。
+2. 将 minimal motion runtime 的状态导入 `EMC_STAT.motion` 等价快照。
+3. 重排 `lctask_run_cycles()`，使每个 task 周期符合上游主循环顺序。
+4. 把 wait-for-motion、motion queue、pause/step/resume、abort/error 逻辑改为依赖 motion 快照。
+5. 增加测试证明 task 周期内读取 motion，而不是只在 status API 读取时拼接 motion。
+6. 分阶段引入 vendored/upstream task 源码，减少自有状态机语义。
+
+## 最小字段闭环
+
+第一阶段必须优先闭合以下字段，原因是它们直接参与 `emctaskmain.cc` 主循环、`emcTaskExecute()` 或顶层 status 聚合：
+
+| 领域 | 字段 | 用途 |
+| --- | --- | --- |
+| task | `state`、`mode` | state/mode gate、power/home/run 前置 |
+| task | `execState`、`interpState` | `emcTaskPlan()` 和 `emcTaskExecute()` 状态机 |
+| task | `currentLine`、`readLine`、`motionLine` | interpreter/motion line 对齐 |
+| task | `task_paused` | pause/resume/step |
+| motion | `status` | wait-for-motion、error、top-level status |
+| motion.traj | `enabled`、`inpos`、`queue`、`activeQueue`、`queueFull` | motion wait、queue gate、disable edge |
+| motion.traj | `id`、`paused`、`single_stepping` | stepping、motion id、pause |
+| motion.traj | `position`、`actualPosition`、`current_vel` | UI/status、interpreter sync |
+| motion | `on_soft_limit` | soft-limit error path |
+| io | `status`、`aux.estop` | subordinate sync、top-level status |
+
+完整字段映射详见 `07-emctaskmain周期对标蓝图.md`。
+
+后续 WASM 核心状态机完善路线详见 `11-WASM核心状态机边界与后续完善路线.md`。
+
+## 非目标
+
+本阶段不做：
+
+- 驱动真实硬件。
+- 浏览器内复刻 LinuxCNC 原生多进程拓扑。
+- 移植 native GUI。
+- 用 JavaScript 重写 CNC/task/motion 语义。
+- 一次性完整移植 realtime motion controller。
+
+## 完成定义
+
+阶段完成至少满足：
+
+- 文档记录 task 主循环对标范围、步骤、任务矩阵和验收证据。
+- 新增测试能区分“task 周期读取 motion”和“status API 拼接 motion”。
+- `lctask_run_cycles()` 内存在清晰的 LinuxCNC 式周期结构。
+- `nativeTaskReady`、`nativeHalSyncReady`、`fullLinuxCncProgramExecutionReady` 等 readiness 字段与真实能力一致。
+- 现有 WASM task/motion/HAL smoke 不回退。
+- `lctask_send_command_json()` 不再直接产生 LinuxCNC task 语义变化；语义变化必须由后续 `lctask_run_cycles()` 的 command read/plan/execute 阶段产生。
+- `lctask_read_status_json()` 不推进、不同步、不重新读取 motion；它只导出最后一次 status write 的快照。