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 只承担外部边界职责。

主要对标文件：

当前 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/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 等旧字段只作为兼容视图。

本阶段要实现或准备实现：

第一阶段必须优先闭合以下字段，原因是它们直接参与 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。

本阶段不做：

阶段完成至少满足：

文档记录 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 的快照。