cnc_wams/完善wasm/working/06-决策记录.md

06-决策记录

本文件记录关键技术决策。后续如需变更，必须新增记录说明原因、影响和替代方案，不直接覆盖旧决策。

记录模板

## ADR-XXX 标题

日期：
状态：
背景：
决策：
理由：
影响：
变更条件：

ADR-011 严格上游清单与生成 Vendor Overlay 分离

日期：2026-07-10 状态：生效

背景：

verify_vendor_sync.sh 原来要求 vendor 树中的所有文件都来自 source-manifest.txt 并与锁定上游逐字节一致。前序 native TRT phase0 probe 又按 D-013 在 vendor 树保留了由 LinuxCNC basic_sim.tcl 生成、但不在锁定 commit 中的 xyzac-trt_cmds.hal fallback，导致严格上游同步 gate 与已登记的运行目录 overlay 需求冲突。

决策：

tools/source-manifest.txt 继续只登记锁定 LinuxCNC commit 中可逐字节比较的上游文件。非上游生成 fallback 必须登记到独立 tools/vendor-overlay-manifest.tsv，至少绑定相对路径、固定 SHA-256 和 provenance。verify_vendor_sync.sh 必须拒绝未登记额外文件、source/overlay 路径重叠、重复 overlay、无效哈希、缺失 provenance 和哈希漂移。

理由：

这样既不删除 native phase0 所需的既有生成输入，也不把生成文件伪装成 LinuxCNC commit 内的上游源码。严格上游字节一致与少量显式生成 overlay 可以在同一 gate 中分别验证。

影响：

• 当前只允许一个 xyzac-trt_cmds.hal generated overlay，固定哈希为 d12f6c737000aba518c0a1502943f3aef17bbd5d54b4b8ae45a11f9f236a4ab3。
• vendor sync validation complete 表示所有 upstream manifest 文件一致，且所有额外文件均通过 overlay manifest；不表示 overlay 文件存在于上游 commit。
• 新增 overlay 必须经过单独 provenance 审查，不能为了让 gate 通过而自动收录未知文件。

变更条件：

当 xyzac-trt_cmds.hal 可由锁定工具链在构建期确定性生成并迁出 vendor 树，或上游 commit 正式包含等价文件时，可以新增 ADR 调整或删除该 overlay 行。

ADR-008 Full-process promotion 仅限 Web/WASM simulation runtime

日期：2026-07-10 状态：生效

背景：

04基于Web的LinuxCNC兼容数控仿真平台.txt 将 Task、Motion、HAL servo-thread、五轴联动和 full-process 相关能力写为通过；web-rtcp-5axis-xyzbc-trt-sim-plan 也已具备 full-execution-boundary.js、task/HAL runtime、native readiness audit 等 Web/WASM 仿真运行时证据。但浏览器环境仍不是 LinuxCNC 原生实时内核，也没有运行真实硬件驱动、完整 native NML/process topology 或任意宿主 User-M/Tool DB 外部进程。

决策：

完善wasm/working 将 full-process promotion 限定为 linuxcnc_task_motion_hal_wasm_simulation_runtime。当 kinematics、interpreter、planner、machine-file staging、task/motion/HAL runtime、Tool DB Web simulation 和 controlled User-M Web simulation 全部通过时，可以声明 Web/WASM 仿真运行时晋级；同时必须保留 hardwareDrive=false、hostRealtimeKernel=false、hostExternalUserMProcessReady=false、hostToolDbProcessReady=false 和 promotion_scope=web_simulation_only。

理由：

这样可以承认可复验的 Web/WASM task-motion-HAL 运行时进展，同时避免把仿真运行时误写成 LinuxCNC 原生实时系统、硬件控制系统或任意宿主外部进程执行环境。

影响：

• 新增 22-04-Full-Process-Realtime-Runtime-Proof实现缺口复核.md。
• ACC-034/INT-021 可按实现缺口复核完成。
• 14-04-125项逐项源码证据绑定表.md 中 full-process/realtime 项改为指向 22；Web/WASM simulation proof 与 host/hardware/realtime false 必须同时记录。
• verify_native_task_hal_audit.mjs 生成的 readiness artifact 是 Web simulation boundary 证据，不是宿主实时/硬件 promotion 证据。

变更条件：

只有新增并通过显式 opt-in 的 host realtime、硬件、完整 native process topology 或宿主外部进程 gate 后，才允许新增 ADR 扩大 promotion 范围。

ADR-009 HAL 基础组件必须由 vendored .comp 可复现派生

日期：2026-07-10 状态：生效

背景：

04 将 and2、or2、not、mux2、scale 写为 HAL 已通过组件，但当前五个 .comp 只存在于上游 linuxcnc/src/hal/components，没有进入 wasm-port/vendor/linuxcnc 或 source manifest；现有 HAL runtime 的 loadrt、addf 和 servo step 也只记录事件，不执行组件函数。

决策：

HAL 基础组件的 Web/WASM 实现必须先逐字节同步 vendored .comp 并锁定 SHA-256，再使用 LinuxCNC halcompile 或能够证明由该 .comp 可复现派生的生成链产生预编译实现。禁止在 JS/TS 或项目自有 C/C++ 中手写等价公式后标记为 LinuxCNC 源码复用。loadrt 必须实例化 allowlist 组件，addf 必须绑定可调用函数，servo step 必须真实更新输出 pin/signal；未知组件保持 blocked。

理由：

五个公式虽然简单，但手写副本会建立第二套 HAL 语义来源，并绕过 source manifest、上游漂移和 LinuxCNC 生成命名规则。把 P1 同步、生成器 provenance、WASM symbol 和执行 evidence 串成一条链，才能证明组件行为来自锁定的 LinuxCNC 源码。

影响：

• 新增 24-04-HAL-Component-Precompile-Manifest-Truth-Table-Gate落地蓝图.md。
• 4.7-4.11 在五个 .comp 进入 vendor/source manifest 前不得晋级。
• 4.16 仅允许预编译 allowlist 条件通过，任意运行时动态模块加载继续 Blocked。
• truth-table/formula 测试必须经过真实 loadrt -> addf -> servo-step -> pin/signal 路径，不能只直接调用测试 helper。

变更条件：

只有验收标准明确允许非 LinuxCNC 派生的独立 HAL 扩展时，才可新增单独的“产品扩展”路径；该路径仍不得计入 LinuxCNC 对标完成率。

ADR-010 Project release readiness 与 host runtime promotion 必须分离

日期：2026-07-10 状态：生效

背景：

当前 wasm-port/build/project-release-readiness.json 可以同时出现 ready=true、release gate 通过和非空 blockedRuntimeFamilies。Host readiness TSV 也可显示三个 opt-in probe 均可 dispatch，但仍明确 execution_enabled=0、promotion_allowed=0；Python stop-lookahead 单 fixture 已接受 native evidence，manual promotion lock 仍生效。

决策：

项目发布 readiness 与宿主能力 promotion 使用两套独立状态。ready=true、host ready、dispatch allowed、ready_disabled_by_default、native pass、evidence accepted、Node/Browser complete、manual unlock 和 promotion 不得合并或跳级。任何 probe 脚本不得直接写 promotion_allowed=1；只有独立人工审查 artifact 可以解除对应 fixture/family 的 promotion lock。User-M/Tool DB/Python process probe 不授权 Linux realtime kernel 或硬件驱动。

理由：

发布 gate 回答“当前已声明范围是否可发布”，host promotion 回答“某项宿主 LinuxCNC 能力是否有完整运行证据并获准开放”。如果共用一个 ready 字段，会把默认禁用、单 fixture pass 或 Web simulation proof 误写成外部进程、实时内核或硬件已经完成。

影响：

• 新增 25-04-Host-Runtime-Opt-In-Promotion-Evidence-Gate落地蓝图.md。
• 后续增加 host_runtime_opt_in_evidence、promotion state machine 和 release/promotion separation gate。
• Python stop-lookahead 只能按 fixture 记录；不能批量晋级全部 Python remap rows。
• hostRealtimeKernel=false、hardwareDrive=false 只能由独立 realtime/hardware 安全任务解除。

变更条件：

只有总验收标准改为要求宿主原生 LinuxCNC 部署且配套安全/人工审查流程已经实现时，才允许调整两套状态的组织方式；仍不得取消逐 family/fixture 证据。

ADR-006 双项目总控采用“核心移植 + 代表应用”口径

日期：2026-07-10 状态：生效

背景：

用户要求 /home/mes123456/cnc_wams/wasm-port 和 /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan 完全对标 LinuxCNC 源程序，并在 完善wasm/working 中创建相关文件。两个目录职责不同：wasm-port 是 LinuxCNC 源码到 Native/WASM/Browser/OPFS/SDK 的核心移植层；web-rtcp-5axis-xyzbc-trt-sim-plan 是 xyzbc-trt.ini 的 Web 代表应用和 UI/evidence 闭环。

决策：

完善wasm/working 采用“核心移植 + 代表应用”的总控口径：wasm-port 证明 CNC 核心语义来自 LinuxCNC 源码；web-rtcp-5axis-xyzbc-trt-sim-plan 证明这些语义能在真实 Web 应用中通过 OPFS、Worker、UI、3D 和 native/Web JSON 对比呈现。二者共用同一 LinuxCNC commit、同一 source reuse 约束和同一条件边界规则。

理由：

这能避免把 Web UI 工程误当成 LinuxCNC 核心移植，也能避免只看 wasm-port 命令全绿却缺少真实代表应用证据。双项目总控必须同时保留源码级证据和用户可见应用证据。

影响：

• 新增 07 到 12 作为跨项目总控文件。
• 09-联合任务矩阵.md 管理跨项目任务；原 04-任务矩阵.md 继续管理 wasm-port 核心验收。
• 04基于Web的LinuxCNC兼容数控仿真平台.txt 在 ADR-006 创建时为空；补齐后已由 ADR-007 和 13-04验收文档任务对标矩阵.md 重新纳入任务体系。
• xyzbc-trt 的完成结论必须继续由 smoke、evidence JSON 和 compare JSON 复验，不因文档登记自动通过。

变更条件：

如果后续出现新的 Web 代表应用、04基于Web...txt 补齐为正式需求，或 wasm-port 与 Web 应用职责边界改变，必须新增 ADR 更新总控口径。

ADR-005 当前验收闭合采用“命令全绿 + 条件边界显式锁定”口径

日期：2026-07-09 状态：生效

背景：

本轮已让上游基线、vendor 同步、Native/WASM/Browser/OPFS/UI/Host 聚合命令通过，但 Python remap、User M 外部进程、硬件驱动和实时内核天然涉及浏览器沙箱、外部进程或实时环境限制，不能因为 smoke 全绿就宣称无条件 LinuxCNC full-process 支持。

决策：

ACC-001 到 ACC-023 的当前闭合采用“可执行命令包全绿 + 条件边界显式锁定”口径：能由 LinuxCNC 源码、Native probe、WASM Node、真实浏览器和 UI/OPFS gate 证明的部分标为完成；Python remap、User M、硬件/实时等仍保留 manual_promotion_lock、Blocked 或条件通过说明。

理由：

这样既满足当前发布前命令包 unexpected_fail=0 的可复验证据，又避免把浏览器环境无法直接承载的 LinuxCNC 外部进程/实时能力误报为已经完整实现。

影响：

• 04-任务矩阵.md 中相关任务可以闭合，但状态使用“条件通过”而不是无条件“完成”。
• 05-验收证据.md 必须保留 inventory 29/29/130/0、skip/block 分类和 Python remap manual lock 说明。
• 后续如果要解除条件边界，必须新增 ACC 任务、源码归属、runtime owner、fixture 和验收 gate。

变更条件：

只有当对应 runtime 或安全边界真正实现，并且 Native/WASM/Browser/UI 证据同时通过后，才能把条件通过项升级为无条件完成。

ADR-007 04 验收文档的“通过/100%”表述必须降解为待核验任务

日期：2026-07-10 状态：生效

背景：

完善wasm/04基于Web的LinuxCNC兼容数控仿真平台.txt 已补齐，文档中声明基于 Web/WASM/OPFS 的 LinuxCNC 兼容仿真平台 10 个模块、125 个功能项总体 97.6%，核心模块 100%，并给出多项“通过”结论。但该文件本身不是命令输出、不是 LinuxCNC 源码、不是 Native/WASM/Browser evidence。

决策：

04 文档中的模块和功能项必须进入 13-04验收文档任务对标矩阵.md，作为待验证任务和目标声明处理。任何“通过/100%/超越”表述都不能自动成为 working 的最终验收结论；必须由 LinuxCNC 源码归属、wasm-port gate、目标 Web 应用 gate 和 evidence JSON 共同证明。

理由：

这与 03完全对标LinuxCNC的可执行验收标准.txt 的一票否决规则一致，可以避免把总结性文档当成可复验证据，也能防止 full-process、实时内核、动态加载、多通道、HAL Scope/Meter 等边界被静默标绿。

影响：

• INT-010 改为“04 参考说明纳入任务体系”。
• 新增 INT-013 负责 04 的 125 项逐行 evidence 绑定。
• 04 的受限项继续保留条件通过或 Blocked 口径。

变更条件：

只有当 04 每个功能项都绑定到源码、测试、命令输出和 evidence，并且 unexpected_fail=0，才能把对应 W04 任务升级为完成。

ADR-001 以 LinuxCNC 源码和测试资产作为唯一数控语义基准

日期：2026-07-09 状态：生效

背景：

验收标准明确要求“完全对标 LinuxCNC”必须证明核心数控语义来自 LinuxCNC 源码、测试资产和运行规则，而不是界面相似或项目自研近似实现。

决策：

wasm-port 的 G 代码解释、刀补、参数、remap、刀具、轨迹规划、运动学、Task/HAL/Motion 等 CNC 语义只能来自 LinuxCNC 源码复用、vendored 同步或明确的薄封装。JS/TS、浏览器 UI 和项目自有 C/C++ 只能承担文件、调度、展示、持久化、C ABI 和边界桥接职责。

理由：

这能避免 Web 端逐渐形成第二套状态真相，也能让上游测试迁移、Native/WASM/Browser 对比和 blocked table 具备共同基准。

影响：

• 新功能必须先找到 LinuxCNC 源码归属。
• 找不到归属的功能不能宣称为 LinuxCNC 对标功能。
• 疑似自研 CNC 语义必须通过 verify_no_standalone_cnc_semantics.sh 或人工审查解释清楚。

变更条件：

只有验收标准更新并允许某类非 LinuxCNC 语义作为产品扩展时，才能改变此决策；即使变更，也必须与 LinuxCNC 对标功能分开标识。

ADR-002 采用 L0-L5 加 Blocked 的晋级模型

日期：2026-07-09 状态：生效

背景：

只写“完成”无法区分源码已同步、Native 通过、WASM 通过、浏览器通过和 UI 发布，也容易把 full-process 或硬件依赖降级为解释器通过。

决策：

所有任务使用 L0 已盘点、L1 已同步、L2 Native 通过、L3 WASM 通过、L4 Browser 通过、L5 UI 发布、Blocked 表达真实进度。

理由：

该模型与验收标准的分层证据体系一致，可以防止跳级宣称，也方便后续按证据缺口继续推进。

影响：

• 任务矩阵必须记录晋级目标。
• 浏览器/UI 功能不能只凭 Native 或 WASM 结果标为 L5。
• Python remap、动态 loadrt、硬件驱动、实时内核等未闭合项应标 Blocked 或条件通过。

变更条件：

如果新增运行层级或验收标准调整证据层级，需要补充状态定义。

ADR-003 把 完善wasm/working 作为总验收推进入口

日期：2026-07-09 状态：生效

背景：

wasm-port/working 已存在 task/status JSON 等局部推进文档，并显示当前 task-HAL 工作已闭合。新的验收标准覆盖整个 LinuxCNC 功能树，需要一个更高层的总入口。

决策：

完善wasm/working 作为完整 LinuxCNC 对标推进入口，维护总任务矩阵、验收证据和决策记录；wasm-port/working 继续作为 wasm-port 内部具体阶段文档和历史证据来源。

理由：

这样可以避免把某个已闭合子方向误认为整体验收完成，同时保留既有工作成果。

影响：

• 后续总体验收先看 完善wasm/working/README.md 和 04-任务矩阵.md。
• 涉及具体实现时，再跳转到 wasm-port/docs、wasm-port/working 和对应测试。

变更条件：

如果后续决定把总入口迁入 wasm-port/working，必须同步迁移任务编号、证据和决策记录，避免两套矩阵并行。

ADR-004 截图和 UI smoke 只能作为补充证据

日期：2026-07-09 状态：生效

背景：

验收标准明确浏览器测试不能只验证页面元素存在，UI 的坐标、模态、刀具、主轴、程序状态必须与底层 LinuxCNC 状态快照一致。

决策：

截图、录屏、DOM smoke 和页面存在性检查只作为 P5 证据。任何核心语义、OPFS、Worker、UI 状态发布都必须有 C ABI、状态 JSON、OPFS 文件或底层快照证据支撑。

理由：

UI 可以显示正确外观但底层状态错误；P4/P5 分离可以防止验收被外观证据污染。

影响：

• UI 任务必须绑定底层状态断言。
• 真实浏览器 smoke 需要检查运行结果、错误、文件或快照，而不是只检查按钮。

变更条件：

无底层状态可取的纯视觉展示功能可用截图验收，但不得宣称 LinuxCNC 核心语义通过。