chore: close wasm status contract work

wasm-port/working/04-任务矩阵.md

@@ -0,0 +1,72 @@
+# 04-任务矩阵
+
+## 状态说明
+
+- `待办`：尚未开始。
+- `进行中`：已有修改但未验收闭合。
+- `完成`：代码/文档/测试/证据均已闭合。
+- `阻塞`：需要外部文件、上游能力或明确决策后才能继续。
+
+## 任务列表
+
+| 编号 | 任务 | 状态 | 验收标准 |
+| --- | --- | --- | --- |
+| T-001 | 创建 `wasm-port/working` 推进文档 | 完成 | README、01-06 文档存在；任务矩阵、台账、验收证据、决策记录具备初始内容。 |
+| T-002 | 固定当前 task/motion/HAL 基线证据 | 完成 | `verify_task_hal_source_manifest.sh`、`verify_motion_hal_sync.sh`、`verify_task_hal_wasm.sh`、`verify_task_hal_sdk.sh` 结果写入 `05-验收证据.md`。 |
+| T-003 | 设计 task 周期内 motion snapshot C ABI | 完成 | 有设计记录；避免 task 周期内解析 JSON；明确字段映射到 `EMC_STAT.motion` 等价结构。 |
+| T-004 | 实现 minimal motion snapshot 结构化读取 | 完成 | `linuxcnc_motion_runtime.c` 提供结构化 snapshot 读取；现有 motion smoke 不回退。 |
+| T-005 | 在 `lctask_run_cycles()` 每个 task 周期读取 motion snapshot | 完成 | 新测试证明 task status 来自周期 snapshot；status API 不再是 task motion 事实源。 |
+| T-006 | 重排 `lctask_run_cycles()` 为 LinuxCNC 式周期骨架 | 完成 | 代码中有 command read、plan、execute、motion update、subordinate sync、task update、status write 的清晰阶段；现有 smoke 通过。 |
+| T-007 | 建立 `EMC_STAT` 等价状态容器 | 完成 | task/motion/io 必需字段集中管理；JSON status 从该状态导出。 |
+| T-008 | 迁移 wait-for-motion 和 queueFull 语义 | 完成 | `WAITING_FOR_MOTION`、`WAITING_FOR_MOTION_QUEUE` 依赖周期 motion snapshot；新增覆盖测试。 |
+| T-009 | 迁移 motion/io error 和 abort cleanup 语义 | 完成 | motion error/io error 能驱动 task abort/error；测试覆盖不回退。 |
+| T-010 | 迁移 pause/resume/step 到 snapshot 驱动 | 完成 | `pause_freezes_motion_queue`、`resume_restores_interp_resume_state`、`step_returns_to_paused` 继续通过，并新增周期 snapshot 断言。 |
+| T-011 | 收缩 JSON command 自有状态机 | 完成 | JSON 只作为 C ABI host 边界；task 语义转入 LinuxCNC 式 plan/execute 层。 |
+| T-012 | 引入 vendored/upstream `emctask.cc` 可编译子集 | 完成 | build 脚本纳入对应源或 shim；新增 source reuse 验证。 |
+| T-013 | 引入 vendored/upstream `taskintf.cc` 可编译子集 | 完成 | motion command issuing 更接近上游；adapter 边界有文档说明。 |
+| T-014 | 引入 vendored/upstream `emccanon.cc` 可编译子集 | 完成 | canonical task/motion command 生成减少自有语义；测试通过。 |
+| T-015 | 修正 readiness 文档和实现口径 | 完成 | `nativeTaskReady`、`nativeHalSyncReady`、`fullLinuxCncProgramExecutionReady` 与实际能力一致；`docs/source-reuse-map.md` 不再与代码矛盾。 |
+| T-016 | 处理 `verify_task_hal_phase0.sh` native probe 阻塞 | 完成 | 缺失 `xyzac-trt_cmds.hal` 问题有明确来源修复或任务降级决策；phase0 gate 口径稳定。 |
+| T-017 | 建立 `emctaskmain.cc` 周期对标蓝图 | 完成 | `07-emctaskmain周期对标蓝图.md` 存在，包含上游代码锚点、WASM 周期骨架、字段映射、command/plan/execute/motion update/status write 对标要求。 |
+| T-018 | 定义 `LcmotStatusSnapshot` 结构 | 完成 | header 中有结构化 snapshot 类型；字段覆盖 queue、inpos、paused、motion id、axis/joint、velocity、switchkins；不解析 JSON。 |
+| T-019 | 实现 `lcmot_read_status_snapshot()` | 完成 | 函数只复制 motion runtime 状态，不 step servo、不消费队列；新增 low-level 单测。 |
+| T-020 | 实现 `wasm_emcMotionUpdate()` 映射层 | 完成 | `LcmotStatusSnapshot` 映射到 `EMC_STAT.motion` 或 `StandaloneEmcStatus.motion`；字段映射有测试。 |
+| T-021 | 建立 task status buffer 等价物 | 完成 | `lctask_read_status_json()` 只导出最后一次 task status write，不直接读取/同步 motion runtime。 |
+| T-022 | 建立 command buffer/slot | 完成 | `lctask_send_command_json()` 入队 command；不调用 `runCycles()` 时 task 语义状态不变化。 |
+| T-023 | 拆分 `lctask_run_cycles()` 周期函数 | 完成 | 内部函数覆盖 cycle begin、command read、plan、execute、motion update、subordinate sync、task update、top-level status、status write。 |
+| T-024 | 迁移当前 state/mode/home/run gate 到 plan 阶段 | 完成 | 现有 state matrix 通过；command 语义由 `runCycles()` 触发。 |
+| T-025 | 迁移 MDI/JOG/HOME motion issue 到 execute 阶段 | 完成 | MDI/JOG/HOME 不在 send command 时直接 forward motion；现有 smoke 通过。 |
+| T-026 | 新增 task 周期 snapshot 行为测试 | 完成 | 覆盖 status read 不推进、不同步；low-level motion step 后 task status 等待下一 task cycle 才更新。 |
+| T-027 | 新增 motion error/soft-limit 注入测试 | 完成 | motion ERROR 和 soft-limit 能通过 subordinate sync 改变 task/top-level status。 |
+| T-028 | 对齐 top-level `RCS_STATUS` 聚合 | 完成 | task/motion/io 三方 DONE/EXEC/ERROR 聚合逻辑与 `emctaskmain.cc` 对齐；JSON status 反映聚合值。 |
+| T-029 | 评估 vendored `emc_nml.hh` 直接复用可行性 | 完成 | 形成记录：直接 include、窄 shim、或分阶段 typedef 的选择和依赖清单。 |
+| T-030 | 更新 source reuse map 与 drift 文档 | 完成 | `docs/source-reuse-map.md`、drift/compatibility 文档反映 task 主循环迁移阶段和 readiness 真实状态。 |
+| T-031 | 建立上游 task 源码替换分解文档 | 完成 | `08-上游task源码替换分解.md` 存在，覆盖 `emctask.cc`、`taskintf.cc`、`emccanon.cc` 的函数族、shim、验收和批次。 |
+| T-032 | `taskintf.cc` usrmot shim 设计 | 完成 | 明确 `usrmot*` 到 `lcmot_*` 的映射，包含 command write、status read、config read、error read。 |
+| T-033 | `taskintf.cc` motion init/update/abort 子集 | 完成 | `emcMotionInit()`、`emcMotionUpdate()`、`emcMotionAbort()` 通过 WASM bridge 工作；task cycle snapshot 测试通过。 |
+| T-034 | `taskintf.cc` traj control 子集 | 完成 | `emcTrajEnable/Disable/Abort/Pause/Step/Resume/SetMotionId` 接入 `lcmot`，现有 pause/step/resume smoke 不回退。 |
+| T-035 | `taskintf.cc` linear move issue 子集 | 完成 | `emcTrajLinearMove()` 替换 task JSON linear move 拼接；G0/G1 smoke 通过。 |
+| T-036 | `taskintf.cc` jog/home/switchkins 子集 | 完成 | `emcJogIncr()`、`emcJointHome/Unhome()`、`emcMotionSetAout()` 接入；Home/Jog/M428-M430 验收通过。 |
+| T-037 | `emctask.cc` abort/state/mode 子集 | 完成 | `emcTaskAbort()`、`emcTaskSetMode()`、`emcTaskSetState()` 替换当前自有逻辑；语义由 task cycle 触发。 |
+| T-038 | `emctask.cc` determine/update 子集 | 完成 | `determineMode()`、`determineState()`、`emcTaskUpdate()` 从 motion/io snapshot 推导 task status。 |
+| T-039 | `emctask.cc` plan wait/synch/open/close 子集 | 完成 | `PlanSetWait/IsWait/ClearWait/Synch/Open/Close/Reset` 接入 vendored interpreter 和 staged FS。 |
+| T-040 | `emctask.cc` plan read/execute 子集 | 完成 | `PlanRead/Execute/Line/Level/Command` 驱动 `interp_list`；不依赖 JSON motion plan。 |
+| T-041 | `emccanon.cc` canon init/finish/unit 子集 | 完成 | `INIT_CANON()`、`ON_RESET()`、`FINISH()`、单位/endpoint getter 接入 `EMC_STAT`。 |
+| T-042 | `emccanon.cc` straight traverse/feed 子集 | 完成 | `STRAIGHT_TRAVERSE()`、`STRAIGHT_FEED()` 生成 LinuxCNC `EMC_TRAJ_LINEAR_MOVE` 到 `interp_list`。 |
+| T-043 | `emccanon.cc` dwell/path-control 子集 | 完成 | `DWELL()` 和 `SET_MOTION_CONTROL_MODE()` 进入 task delay/path mode 语义。 |
+| T-044 | `emccanon.cc` spindle/tool command 子集 | 完成 | spindle/tool commands append 到 `interp_list`，runtime boundary 和 readiness 保守记录。 |
+| T-045 | `emccanon.cc` motion output/switchkins 子集 | 完成 | M62-M68/M428-M430 通过 canon motion output 到 `emcMotionSetAout()`，移除字符串 special-case。 |
+| T-046 | 移除主路径 JSON motion plan 依赖 | 完成 | RUN 文件主路径由 `Interp::open/read/execute` + `emccanon.cc` + `interp_list` + `emcTaskExecute()` 驱动；`loadProgramMotionPlan()` 降为调试/兼容入口或删除。 |
+| T-047 | 收口 working 索引与闭合 gate | 完成 | README、功能内容、NML 评估和矩阵闭合口径与 T-007/T-046 当前实现一致；有 gate 验证无待办/进行中/阻塞任务。 |
+| T-048 | 将 working closure gate 纳入全局文档一致性验证 | 完成 | `source-reuse-map.md`、`compatibility-validation.md` 和 `verify_task_source_reuse_drift_docs.sh` 均记录并检查 `verify_task_working_closure.sh`。 |
+| T-049 | 建立 task-HAL 全量闭合验证入口 | 完成 | `tools/verify_task_full_closure.sh` 一次性执行 build、WASM smoke、SDK、state matrix、motion sync、T-007/T-046/T-047/T-048/docs/readiness gates。 |
+| T-050 | 建立 status JSON LinuxCNC 对标方案 | 完成 | `12-status-json-LinuxCNC对标方案.md` 存在；README、功能内容、开发步骤、台账、证据和决策记录均记录 `StandaloneEmcStatus -> status JSON` 方案；working closure gate 不回退。 |
+| T-051 | SJ-1 规范 `emcStatus.motion.traj` | 完成 | `emcStatus.motion.traj` 导出 enabled/inpos/queue/activeQueue/queueFull/id/paused/singleStepping/position/actualPosition/currentVel；WASM/SDK/state matrix 和 status JSON contract gate 断言其与兼容 `motionStatus` 同源。 |
+| T-052 | SJ-2 规范 task line 和 interpreter 字段 | 完成 | `StandaloneEmcTaskStatus` 集中 currentLine/readLine/motionLine/callLevel；`task` 兼容视图和 `emcStatus.task` 同源；staged RUN 后 contract gate 验证 line 字段。 |
+| T-053 | SJ-3 规范 `emcStatus.motion.axis[]` 和 `joint[]` | 完成 | `StandaloneEmcMotionStatus` 保存 axis command/feedback 与 joint command/feedback 数组；`emcStatus.motion.axis[]`、`joint[]` 导出至少 6 轴/关节，旧 `motionStatus.axis`、`joint0` 与新数组一致。 |
+| T-054 | SJ-4 规范 IO/aux/tool/coolant 边界 | 完成 | `emcStatus.io` 导出 status/error/fault/reason/aux.estop；tool/coolant 以 `supported=false` 和 shim reason 显式标记未接 native IO；readiness 仍为 false。 |
+| T-055 | SJ-5 引入 status JSON contract gate | 完成 | 新增 `tools/verify_task_status_json_contract.sh` 和 Node contract 测试；检查 `statusSource=StandaloneEmcStatus`、`lctask_read_status_json()` 不调用 motion JSON、SDK 不实现 task/motion 语义；该 gate 纳入 full closure。 |
+
+## 当前推进指针
+
+下一条优先任务：无。任务矩阵当前已闭合；`11-WASM核心状态机边界与后续完善路线.md` 和 `12-status-json-LinuxCNC对标方案.md` 中 SJ-1 到 SJ-5 已补入 T-051 到 T-055 并闭合。后续新增对标项需先补入本矩阵。