linuxcncWebWASM/doc-rtcp/xyzac-trt-full-tp-parity-plan.md

XYZAC TRT 完整 TP/前瞻数值对标任务轨道

状态：TP-PARITY-00 已 verified，完整 LinuxCNC 数值对标尚未完成。

当前 oracle 证据：coverage/xyzac-native-tick-trace.report.json 已由源 run-5axis-rtcp.sh 产生连续 task-heartbeat tick；源 Python NML 扩展暴露 task_heartbeat，并记录 XYZAC pose/joints、queue、current-line、速度和加速度。 干净 checkout 使用 scripts/build_linuxcnc_native_oracle.sh 应用并编译同一源 patch。 scripts/compare_xyzac_native_wasm_tick_trace.py 已接入同一 case 的 WASM trace， 当前首个差异保留为 $.rows[1].exec_state，因此不得把 TP-PARITY-01..08 写成 数值 parity verified。

目标不是证明页面能绘制一条曲线，而是对同一 xyzac-trt.ini、同一 G-code、同一初始状态，比较 native LinuxCNC 与 WASM Worker 的每个运动 tick：

source G-code
  -> LinuxCNC RS-274 canonical output
  -> LinuxCNC TP/lookahead/blend
  -> motion/kinematics
  -> pose/joints/velocity/active motion/queue/current line

Web 端只有在该链路和 native trace 逐字段一致后，才能声明 PARITY_VERIFIED。Three.js、React 和浏览器时间不能作为运动数据来源。

任务分解

TP-PARITY-00：Native LinuxCNC 逐 tick oracle

来源：

• run-5axis-rtcp.sh
• linuxcnc/src/emc/usr_intf/axis/extensions/emcmodule.cc
• linuxcnc/src/emc/task/taskintf.cc
• linuxcnc/src/emc/motion/motion.h
• linuxcnc/src/emc/tp/tp_debug.h
• linuxcnc/src/emc/tp/tp.c
• linuxcnc/src/emc/tp/tcq.c
• linuxcnc/src/emc/tp/tc.c

交付：

• scripts/run_xyzac_native_tick_trace.py
• coverage/xyzac-native-tick-trace.report.json
• native trace JSONL，包含 tick/taskbeat、task/interpreter/exec state、current/motion/read line、actual/commanded pose、joint actual pose、velocity、acceleration、queue、active queue、queue full、motion id、feed/rapid override 和 G-code source hash。

验收：

• 必须由 ./run-5axis-rtcp.sh 启动 native LinuxCNC。
• 使用 linuxcnc.stat() 读取状态，不能从 GUI 截图推断运动值。
• trace 必须保留重复 tick、空 queue tick 和程序结束排空阶段。
• motion_id 映射为 native active motion identifier；若 native API 不提供 segment geometry，必须显式记录 active_segment_geometry: unavailable，不能伪造。

TP-PARITY-01：锁定 LinuxCNC TP 数据模型和 C ABI

状态：in_progress。native tick oracle 已可用；当前 comparator 显示现有 WASM queue 与源 TP 的执行顺序/速度尚未一致。

来源：linuxcnc/src/emc/tp/{tp.c,tp.h,tp_types.h,tc.c,tcq.c,tc_types.h,blendmath.c,blendmath.h,spherical_arc.c}。

工作：

• 逐项登记 TP_STRUCT、TC_STRUCT、termination condition、queue depth、active depth、current velocity、acceleration、jerk、tolerance 和 motion id。
• 决定采用源码等价移植还是直接编译可移植 LinuxCNC TP 源码到 WASM；优先保留原始 C 算法和数据布局，避免再写第二套近似 planner。
• 为每个 ABI 增加 native/WASM size、endianness、state hash 和 checkpoint restore 测试。

退出条件：native 和 WASM 对同一静态 TC 队列的 enqueue、activate、step、pop 逐字段一致。

TP-PARITY-02：G64/G61/G61.1 完整路径控制

状态：in_progress，WASM interpreter 侧已闭合指令模式和容差状态，numeric blend 仍待 TP port 和 comparator 通过。

来源：

• linuxcnc/src/emc/rs274ngc/interp_convert.cc 的 G64/G61 处理
• linuxcnc/src/emc/rs274ngc/interp_internal.hh 的 tolerance/naivecam_tolerance
• linuxcnc/src/emc/tp/tp.c 的 tpSetTermCond 和 termination condition

工作：

• G61：exact path；G61.1：exact stop；G64：blend；G64 P... Q...：路径和 naive-cam tolerance。
• 保存 modal 状态、每个 canonical motion 的 termination condition 和 tolerance。
• 增加直线-直线、直线-圆弧、圆弧-直线、圆弧-圆弧、急转角、短段、零容差和非法 P/Q 样本。

当前 WASM C interpreter 已输出三种模式及 P/Q 容差到 sim_program.v1，Worker 在入队前应用对应 queue profile；LinuxCNC exact-path 与 exact-stop 的细微 差别、P/Q 驱动的 corner blend 仍由 TP-PARITY-03/06 的 native tick comparator 验证，尚未标记完成。

退出条件：native/WASM 每条 TC 的 termination mode、tolerance、blend point、速度和完成 tick 一致。

TP-PARITY-03：Lookahead、corner blending、acceleration/jerk

来源：

• linuxcnc/src/emc/tp/tp.c：target/final velocity、activate、queue starvation、periodic update
• linuxcnc/src/emc/tp/blendmath.c：cornering speed、blend geometry、acceleration/jerk bound
• linuxcnc/src/emc/tp/tc.c：segment acceleration and interpolation
• linuxcnc/src/emc/motion/control.c：trajectory period and current velocity

工作：

• 移除当前 lookahead=1 的最小近似，复用或等价移植 LinuxCNC 的完整 active-depth/lookahead。
• 按 LinuxCNC 的 blend geometry 计算 corner speed 和 transition segment。
• 保持 queue starvation、pause、abort、feed hold、queue drain 的真实语义。
• acceleration、jerk、cycle time、velocity limit 从 INI/TRAJ 配置进入同一 planner。

退出条件：至少覆盖 2、4、8、32 段 lookahead，连续/精确路径，短段和速度突变；逐 tick pose/velocity/acceleration/queue 一致。

TP-PARITY-04：XYZAC rotary velocity semantics 和 RTCP

来源：

• linuxcnc/src/emc/task/emccanon.cc
• linuxcnc/src/emc/kinematics/{xyzac-trt-kins.c,trtfuncs.c,switchkins.c,kins_util.c}
• linuxcnc/src/emc/motion/control.c

工作：

• 统一线性轴 mm、旋转轴 deg 的速度单位和合成路径长度。
• 验证 A/C 单独运动、XYZ+AC 同时运动、G93 inverse time、G94 units/min、RTCP pivot/tool offset。
• native trace 同时导出 Cartesian actual/commanded pose 和五 joint actual/commanded pose。
• 将 M428/M429/M430 的切换点纳入 planner queue 和 trace，而不是只比较最终姿态。

退出条件：同一切换点前后 pose 连续、joint 速度/路径长度/active motion id 与 native 一致。

TP-PARITY-05：WASM Worker 真实 planner 接入

工作：

• WasmProgramRuntime 输出 LinuxCNC canonical motion/termination 条件。
• Worker 只调用 WASM TP/kinematics/motion ABI；删除 selected-case 中的简化 sim_motion_queue 速度决策。
• React 继续只消费 snapshot/delta，不参与 tick、前瞻、姿态补偿或路径重建。
• Feed/rapid override、pause/resume、abort、restart、checkpoint 都必须落到同一 WASM planner state。

退出条件：Worker trace 与 WASM C trace byte-identical，且不会回退到 AuthoritativeRuntime 或 ProgramRunner 的 authority path。

TP-PARITY-06：Native/WASM 逐 tick comparator

交付：

• scripts/compare_xyzac_native_wasm_tick_trace.py
• coverage/xyzac-native-wasm-tick-parity.report.json

比较字段：

tick
task_state/mode/interp_state/exec_state
current_line/motion_line/read_line
actual_pose/commanded_pose
joint_actual/joint_commanded
velocity/acceleration
queue/active_queue/queue_full
motion_id/active_segment
feed_override/rapid_override
kinematics_mode/RTCP offsets
state_hash

比较规则：

• 浮点使用固定绝对/相对容差，并记录原始值和差异值。
• 列表长度、字段缺失、状态顺序不允许静默忽略。
• 保存 first_divergent_tick、difference_path、native/WASM 两侧样本。

已提供可重复入口：

• scripts/run_xyzac_wasm_tick_trace.mjs
• scripts/compare_xyzac_native_wasm_tick_trace.py
• coverage/xyzac-native-wasm-tick-parity.report.json
• 最终坐标相同但中间 tick 不同必须判定为 diverged。

TP-PARITY-07：预览和实际执行一致性

工作：

• 预览使用同一 canonical/TP 输入生成 planned path，不使用独立的几何近似。
• 实时路径使用同一 planner 的 actual motion trace。
• 对比 planned TC、executed TC、active segment 和完成后的 endpoint；明确 rapid、blend、exact-stop 的颜色/线型只属于显示层。

退出条件：预览不改变 planner state；执行 trace 的 segment/source line 可回指预览 TC；同一程序重复运行 preview hash 稳定。

TP-PARITY-08：最终门禁

必须通过：

• native run-5axis-rtcp.sh trace
• native CTest 和 WASM CTest
• Worker trace
• native/WASM 逐 tick comparator
• XYZAC M428/M429/M430、G64/G61/G61.1、G93/G94、短段、拐角、queue full、pause/abort/restart/recovery
• Chromium 浏览器只读显示验证

只有 first_divergent_tick: null、所有字段状态 hash 通过、所有输入和报告自哈希一致，才允许将状态写为 PARITY_VERIFIED。否则保持 TP-PARITY-* 对应任务的 blocked 或 diverged。

当前明确边界

• 当前 coverage/xyzac-trt-trace-parity.report.json 证明的是项目内 native C/WASM C/Worker 实现之间的 selected-case 一致，不是 native LinuxCNC TP oracle 对标。
• 当前 wasm-program-runtime.mjs 的 preview 是 WASM interpreter canonical segments；完整 LinuxCNC TP 前瞻和 G64 corner blend 尚未接入。
• 当前 sim_motion_queue.c 的 lookahead/blend 是简化实现，不能作为真实 LinuxCNC TP 数值等价证明。
• run-5axis-rtcp.sh 当前只启动 native AXIS；TP-PARITY-00 必须补齐 linuxcnc.stat() trace 导出后，才有资格进行逐 tick comparator。
• Safari、物理断电和真实硬件仍按项目范围排除，不影响本仿真任务的 native/WASM 数值闭环。