cnc_wams/完善wasm/working/24-04-HAL-Component-Precompile-Manifest-Truth-Table-Gate落地蓝图.md

24-04 HAL Component Precompile Manifest / Truth-Table Gate 落地蓝图

后续状态：阶段 A 已由 26 完成，阶段 B-D 已由 27 完成。本文保留实施合同；涉及“当前缺失/只记录事件”的段落应结合 27 的最终机器 gate 阅读。

定位

本文件落实 ACC-036/INT-023：在 19-04动态加载与预编译Manifest复核.md 和 21-04-HAL-Component-Precompile-Manifest实现缺口复核.md 已确认边界和缺口后，把 and2、or2、not、mux2、scale 的源码同步、预编译 manifest、实例化、线程执行和 truth-table/formula evidence 收敛为可直接实施的合同。

覆盖 04 条目：

• 4.7 and2 组件
• 4.8 or2 组件
• 4.9 not 组件
• 4.10 mux2 组件
• 4.11 scale 组件
• 4.16 loadrt 加载组件

严格口径：不得在 JS/TS 或项目自有 C/C++ 中手写五个组件公式后宣称 LinuxCNC 源码复用。组件实现必须直接编译 LinuxCNC .comp 的生成物，或由可复现工具从 vendored .comp 生成最窄适配层；manifest、生成物和 WASM 必须绑定同一上游源码哈希。

本轮实物复核结论

检查项	当前事实	严格结论
上游源码	五个 .comp 均存在于 linuxcnc/src/hal/components/	P0 来源已确定
vendored 源码	五个 .comp 已抽取到 wasm-port/vendor/linuxcnc/src/hal/components	专项 P1 同步已完成，见 26
source manifest	两个 manifest 已登记五个 .comp，专项 commit/字节/hash gate 已通过	1 个非上游 generated fallback 已由独立 manifest 锁定，全量 vendor/overlay gate 通过
WASM 构建	build_task_hal_wasm.sh 只编译 task subset、HAL runtime、motion runtime 和 task-HAL wrapper	五个组件没有进入 WASM object/link
导出符号	EXPORTED_FUNCTIONS 不含组件实例化或执行入口	无真实 WASM component symbol proof
loadrt	linuxcnc_hal_runtime.cpp 仅追加 loadrt:<name> event 并返回成功	不是实例化证据
addf	当前只把函数名登记到 thread	未绑定可调用函数指针/组件实例
servo step	lchal_step_threads() 只追加 call:<thread>:<function> event	未执行组件公式、未更新输出 pin
Web evidence	代表配置有原生 loadrt mux2/scale 和 addf 文本	只能证明 LinuxCNC 原生配置使用组件

因此，4.7-4.11 仍是“待实现预编译执行 gate”，4.16 只能保持“预编译 allowlist 条件通过/任意动态加载 Blocked”。

LinuxCNC 源码与哈希基线

上游基线 commit：

60597ee0718873d2449058c824262a275e5e4bad

组件	上游源码	SHA-256	LinuxCNC 函数语义
and2	src/hal/components/and2.comp	29f02d1342bae24d138bbb1387b006b97f592967b8688ccb1c6c0af451cae419	out = in0 && in1
or2	src/hal/components/or2.comp	c27663ce45f9562d7a5dc1b542da50ec2cc60802ef591ee729222002083a3c08	`out = in0
not	src/hal/components/not.comp	9fd9522627db9926d037dc0c116badce7dc880f190c6f8b85c690cbb8b638332	out = !in
mux2	src/hal/components/mux2.comp	b75e3eeb74297d09d13052e812de53a38613ea8287522c371cc2fdaf76be3284	sel ? in1 : in0
scale	src/hal/components/scale.comp	d6830d74fd3462c7b7285a9e0b37cbcd2c53d2243007a198e3f19bfed9817f4f	out = in * gain + offset

五个组件都声明 function _ 和 option period no。LinuxCNC 原生名称规则、names=/count= 实例化以及函数注册由 halcompile 生成代码负责；Web/WASM 适配不得改变 pin 方向、类型、默认值、实例命名或函数语义。

实施顺序

阶段 A：P1 源码同步闭合

必须先把以下路径加入可复现同步清单：

src/hal/components/and2.comp
src/hal/components/or2.comp
src/hal/components/not.comp
src/hal/components/mux2.comp
src/hal/components/scale.comp

目标文件必须位于：

wasm-port/vendor/linuxcnc/src/hal/components/

最低 gate：

cd wasm-port
./tools/extract_sources.sh
./tools/verify_vendor_sync.sh
sha256sum vendor/linuxcnc/src/hal/components/{and2,or2,not,mux2,scale}.comp

要求：五个 vendored 文件与上游逐字节一致；任何 source hash 变化必须让 manifest gate 失败，不能自动接受新公式。

阶段 B：LinuxCNC 派生生成物

推荐构建路径：使用与锁定基线一致的 LinuxCNC halcompile --preprocess 生成 C，再通过最窄 RTAPI/HAL shim 编译到 task-HAL WASM。若源树中只有 halcompile.g 而没有可执行的生成器，必须先在构建工具链中生成/定位 LinuxCNC halcompile，不能用正则截取 FUNCTION(_) 或人工复制公式替代。

建议产物：

wasm-port/build/generated/hal-components/and2.c
wasm-port/build/generated/hal-components/or2.c
wasm-port/build/generated/hal-components/not.c
wasm-port/build/generated/hal-components/mux2.c
wasm-port/build/generated/hal-components/scale.c
wasm-port/build/generated/hal-components/generation-report.json

generation-report.json 最少包含：

字段	要求
upstreamCommit	固定为锁定 commit
generator	LinuxCNC halcompile 路径/版本
sourcePath	vendored .comp 路径
sourceSha256	必须等于本文件基线
generatedPath	生成 C 路径
generatedSha256	用于增量构建和漂移检查
commandFingerprint	生成命令和参数摘要

生成过程必须增量执行：源码哈希、生成器哈希和命令指纹未变化时不得无条件重生成或重编译。

阶段 C：预编译 Manifest

建议文件：

wasm-port/runtime/manifests/hal_component_precompile_manifest.json

顶层最小字段：

字段	规则
apiName	固定为 hal_component_precompile_manifest
schemaVersion	固定为 1
upstreamCommit	与 tools/upstream-baseline.txt 一致
dynamicLoadrtSupported	固定为 false
unknownComponentPolicy	固定为 blocked
components[]	必须恰好覆盖当前 allowlist

components[] 每项最小字段：

字段	规则
component	and2、or2、not、mux2、scale
linuxcncSource	vendored .comp 相对路径
sourceSha256	与 P0/P1 基线一致
generatedSource	LinuxCNC halcompile 派生 C
wasmFactorySymbol	创建 names=/count= 实例的 C ABI
wasmStepSymbol	组件函数执行入口，或绑定到 runtime function registry 的 symbol
pins[]	名称、方向、HAL type、默认值
functions[]	LinuxCNC HAL function 名、usesFp、period policy
loadrtArgs	明确支持的 names=、count= 子集和互斥规则
tests[]	manifest、truth-table/formula、thread/net gate 路径

阶段 D：loadrt / addf / servo-step 执行链

运行时必须形成以下调用链：

HAL text loadrt
  -> allowlist lookup
  -> parse names=/count=
  -> call precompiled factory
  -> create LinuxCNC-compatible pins/functions
  -> register callable function entry
HAL text addf
  -> resolve registered function
  -> attach callable entry to virtual thread
lchal_step_threads
  -> invoke callable entry in thread order
  -> update output pins
  -> propagate connected signals
  -> emit execution evidence

失败规则：

• 未知组件：返回 blocked，不得仅记录 event 后成功。
• manifest 中有组件但 WASM symbol 缺失：启动失败。
• names= 与 count= 同时出现：按 LinuxCNC 行为拒绝。
• 重复实例名、pin 名冲突、未知 addf function：返回错误。
• thread step 只写 call: event 但没有实际输出变化：gate 失败。

Truth-Table / Formula Evidence

建议 evidence：

wasm-port/build/evidence/hal-component-truth-table-evidence.json

顶层最小字段：

字段	规则
apiName	hal_component_truth_table_evidence
schemaVersion	1
upstreamCommit	锁定基线
manifestSha256	绑定实际 manifest
runtimeSource	linuxcnc-derived-precompiled-hal-component
components[]	五个组件全部出现
integrity.complete	所有向量、thread/net 和 blocked case 通过时为 true

每个测试向量必须记录 instance、inputs、expected、actual、threadCycle、outputPin、connectedSignal、passed。最小向量：

组件	最小覆盖
and2	4 组 bit 组合
or2	4 组 bit 组合
not	2 组 bit 输入
mux2	sel=false、sel=true，并使用不相等 float 输入
scale	至少 3 组，覆盖正 gain、负 gain、非零 offset，误差容限显式记录

每个组件至少一个向量必须通过真实 loadrt -> setp/net -> addf -> lchal_step_threads -> snapshot 路径，不能只直接调用测试 helper。

建议 Gate

wasm-port

建议新增：

wasm-port/tools/generate_hal_component_sources.sh
wasm-port/tools/verify_hal_component_source_sync.sh
wasm-port/tests/wasm/node/verify_hal_component_precompile_manifest.mjs
wasm-port/tests/wasm/node/verify_hal_component_truth_tables.mjs
wasm-port/tests/wasm/node/verify_hal_component_thread_net_execution.mjs

命令和通过输出：

cd wasm-port
./tools/verify_hal_component_source_sync.sh
node tests/wasm/node/verify_hal_component_precompile_manifest.mjs
node tests/wasm/node/verify_hal_component_truth_tables.mjs
node tests/wasm/node/verify_hal_component_thread_net_execution.mjs

hal_component_source_sync=ok
hal_component_precompile_manifest=ok
hal_component_truth_tables=ok
hal_component_thread_net_execution=ok
unknown_loadrt_component_blocked=ok

web-rtcp-5axis-xyzbc-trt-sim-plan

目标 Web 项目不应再实现一套组件公式。它应消费 wasm-port task-HAL runtime 输出，并在 evidence 中引用：

halComponentManifest
halComponentExecution
halComponentBlockedCases

代表 profile 至少要证明 xyzac-trt_cmds.hal 中 mux2 和 scale 的实例名、pin、addf 顺序和输出来自相同 WASM runtime。compare-xyzbc-trt-evidence.json 需记录 native HAL 配置声明与 Web/WASM 组件实例/执行结果的对应关系，但不能用配置文本相等替代运行结果。

04 严格状态与晋级条件

04 项	当前状态	晋级条件
4.7 and2	P1 已完成，预编译执行 gate 待补	manifest、WASM symbol、4 组 truth table、thread/net proof
4.8 or2	P1 已完成，预编译执行 gate 待补	manifest、WASM symbol、4 组 truth table、thread/net proof
4.9 not	P1 已完成，预编译执行 gate 待补	manifest、WASM symbol、2 组 truth table、thread/net proof
4.10 mux2	P1 已完成，预编译执行 gate 待补	sel 两路、names= 实例化、代表 XYZAC HAL 配置、thread/net proof
4.11 scale	P1 已完成，预编译执行 gate 待补	公式向量、浮点容差、代表 rpm_rps 实例、thread/net proof
4.16 loadrt	预编译 allowlist 条件通过/动态加载 Blocked	allowlist 组件真实实例化；未知组件 blocked；仍不得宣称任意 .so 动态加载

与现有文件的关系

• 19-04动态加载与预编译Manifest复核.md：定义动态加载和预编译边界。
• 21-04-HAL-Component-Precompile-Manifest实现缺口复核.md：确认当前实现缺口。
• 本文件：补充 source sync、哈希、生成物、manifest、runtime 调用链、evidence 和 gate 的落地合同。
• 26-04-HAL-Component-P1源码同步与哈希Gate实施记录.md：记录阶段 A 已实施、专项 gate 已通过以及严格 upstream/生成 overlay 分层。
• 实际实现完成后，必须把运行输出回填到 05-验收证据.md，再更新 14 中 4.7-4.11/4.16 的状态。

结论

ACC-036/INT-023 已把 HAL component precompile 从“需要 manifest/truth-table”细化为可执行实施合同；ACC-038/INT-025 已完成五个 .comp 的专项 P1 同步/hash 和全量 vendor/overlay gate。后续仍须完成 LinuxCNC 派生生成、预编译 symbol、真实 loadrt/addf/servo-step 调用和结构化 truth-table/formula evidence，04 的 4.7-4.11 才能晋级；任意运行时动态 loadrt 仍保持 Blocked。

后续状态

剩余实施合同已由 ACC-039/INT-026 闭合，五组件具备可复现生成、manifest、真实预编译 factory/thread/net 执行和结构化 truth-table/formula evidence。当前状态见 27-04-HAL-Component-Precompile-Runtime-Gate实施记录.md；固定 allowlist 条件通过，任意运行时动态 loadrt 继续 Blocked。