# 27-04 HAL Component Precompile Runtime Gate 实施记录

## 定位

本文件落实 `ACC-039/INT-026`，承接 `24` 的阶段 B-D 和 `26` 的 P1 源码同步结果，把 `and2`、`or2`、`not`、`mux2`、`scale` 从“源码已同步”推进到 LinuxCNC `halcompile` 派生、预编译 manifest、WASM 实例化、线程回调、net 传播和代表 Web 配置消费均有机器 gate 的状态。

严格边界：本轮只晋级 Web/WASM 虚拟 HAL 仿真运行时。`dynamicLoadrtSupported=false`，未知组件必须 blocked；宿主 RTAPI 实时内核、共享内存、内核模块、硬件驱动和任意动态模块加载没有晋级。

## LinuxCNC 派生链

生成入口：

```text
wasm-port/tools/generate_hal_component_sources.sh
wasm-port/tools/generate_hal_component_sources.mjs
```

生成器固定为锁定源码树中的 `../linuxcnc/bin/halcompile --preprocess`。脚本校验 LinuxCNC HEAD 与 `tools/upstream-baseline.txt`，从五个 vendored `.comp` 生成 `build/generated/hal-components/*.c`，仅规范化生成时间行并附加最窄的 start/reset C ABI。`generation-report.json` 逐组件记录 source、generator、command fingerprint 和 generated SHA-256。

生成 C 不进入上游 vendor manifest，也不冒充 LinuxCNC 原始源码；其上游语义仍由 `26` 的 P0/P1 字节和固定哈希 gate 约束。

## 预编译 Manifest

新增 `wasm-port/runtime/manifests/hal_component_precompile_manifest.json`，固定：

- `upstreamCommit=60597ee0718873d2449058c824262a275e5e4bad`；
- allowlist 恰好为 `and2/or2/not/mux2/scale`；
- 每个组件的 `.comp` 路径、source SHA-256、generated path、factory/step symbol、pin 和 `count/names` 参数；
- `dynamicLoadrtSupported=false`；
- `unknownComponentPolicy=blocked`。

`verify_hal_component_precompile_manifest.mjs` 同时复算 source/generated hash，并将 manifest、generation report 和实际文件闭合。

## 真实执行链

`linuxcnc_hal_runtime.cpp` 现按以下路径执行 allowlist 组件：

```text
loadrt + names/count
  -> allowlist/factory
  -> halcompile 生成的 pin 与 hal_export_funct
  -> addf 绑定 callback/instance
  -> lchal_step_threads 调用生成公式
  -> HAL_OUT 更新 signal
  -> net 传播到下游 pin
```

运行时同时补齐：

- `names=` 与 `count=` 互斥和非法参数 blocked；
- 未知 `loadrt` 返回 blocked，不再只记成功事件；
- LinuxCNC HAL `net` 行的 `=>`、`<=`、`<=>` 方向标记解析；
- 同一 WASM 模块重新初始化 HAL session 时清空生成组件实例链；
- 保留 `trivkins` 既有 legacy boundary，避免回退既有 Task/Motion gate。

## 专项证据

```bash
cd wasm-port
./tools/build_task_hal_wasm.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
```

实际输出：

```text
hal_component_generation=ok
linuxcnc_task_hal_wasm_build=ok
hal_component_precompile_manifest=ok
hal_component_truth_tables=ok
hal_component_thread_net_execution=ok
unknown_loadrt_component_blocked=ok
hal_component_session_reset=ok
```

truth-table gate 覆盖 `and2/or2` 各 4 组、`not` 2 组、`mux2` 两路选择和 `scale` 三组正负 gain/offset 浮点公式，输出 `build/evidence/hal-component-truth-table-evidence.json`。thread/net gate 证明生成函数真实执行、输出 signal 传播、非法参数阻断和第二 HAL session 重建。

## Web 代表配置消费

目标 Web 项目新增 `tests/node/verify_hal_component_runtime_evidence.mjs` 并挂入 `smoke:node`。gate 读取 vendored `xyzac-trt_cmds.hal` 中：

```text
loadrt mux2 names=J0_mux,J1_mux,J2_mux,J3_mux,J4_mux
loadrt scale names=rpm_rps
addf J0_mux servo-thread
addf rpm_rps servo-thread
```

随后用同一 task-HAL WASM 实例化并执行 `J0_mux` 和 `rpm_rps`，验证 `J0_mux.out=37.25`、`rpm_rps.out=20`，同时阻断 `web-local-formula` 未知组件。Web 项目没有复制五个组件公式。

## 回归结果

以下既有 gate 全部通过：

- `verify_hal_component_source_sync.sh`、`verify_vendor_sync.sh`；
- `verify_hal_runtime.sh`、`verify_task_hal_wasm.sh`；
- 目标 Web `smoke:node`；
- `verify_linuxcnc_task_hal_runtime.mjs`。

补充执行的 `build_native_probes.sh` 已通过。全量 `verify_native_probes.sh` 后续在组件范围外的 `xyzac_switchkins_test_3.ngc` 出现 Bus error；该 INI 引用锁定源码树中不存在的 `xyzac.var`，汇总产生 1 个 unexpected fail。本轮没有将其伪装为 expected-fail，因此不把全量 native 包列入上述通过清单。

后续状态：该历史失败已在 `ACC-045/INT-032` 中由当前 source/vendor 资产和串行全量复验解除。最终结果为 sim-config `159 total / 151 pass / 8 expected_fail / 0 unexpected_fail`、nc_files `107 total / 101 pass / 6 expected_fail / 0 unexpected_fail`，详见 `33-Native全量回归最终收口.md`。

系统 `/usr/bin/emcc` 与 `wasm-opt` 版本不匹配，因此 `wasm_incremental_build_lib.sh` 现优先加载仓库机器已有 EMSDK；最终构建使用 EMSDK 6.0.2 并通过。

## 04 状态

| 04 项 | 本轮后状态 |
| --- | --- |
| `4.7-4.11` | L3 条件通过：LinuxCNC 派生预编译 Web/WASM 仿真运行时、truth-table/formula、thread/net 和 Web 代表配置 gate 通过 |
| `4.16` | 条件通过/Blocked：allowlist `loadrt` 可实例化执行；未知组件和任意运行时动态模块加载仍 blocked |

## 下一步

优先落实 `23` 的 HAL Meter/Scope JSON evidence，或 `25` 的 host runtime evidence/release-promotion 分离 gate。不得从本轮组件仿真证据继承宿主 realtime 或 hardware promotion。

## 结论

`ACC-039/INT-026` 已闭合五个基础 HAL component 的 LinuxCNC 派生预编译运行时证据。04 的 `4.7-4.11` 可在 Web/WASM simulation 边界内晋级，`4.16` 仅对固定 allowlist 条件通过；动态模块加载仍不支持。