项目接续文件：L4-PYTHON-REMAP OPFS/WASM runtime milestone 执行计划

生成时间：2026-06-19 CST

本文件接替 `text24.txt`，整理当前完成情况，并明确下一步：

```text
剩余 hard block 先做 L4-PYTHON-REMAP；
L4-USER-M-PROCESS 放在 Python remap lifecycle proof 之后。
```

重要边界：

```text
本文件是单独 hard-block runtime milestone 的执行计划。
不是 virtual HAL 新功能计划，也不是直接批量 promotion 计划。

当前禁止事项：
- 不用 JavaScript 重写 Python remap / prolog / epilog CNC 语义；
- 不把 Python runtime 可 import 当成 remap pass；
- 不把 NGC-only subroutine asset 当 standalone main program；
- 不一次性解锁全部 53 个 L4-PYTHON-REMAP rows；
- 不因为 native probe 通过就自动改 promotion_allowed；
- L4-USER-M-PROCESS 仍不做 arbitrary external process execution。
```

一、当前完成情况快照

1. virtual HAL 已接入 Web 数控仿真。

已通过真实 browser simulation smoke：

```bash
SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
```

输出：

```text
browser_real_simulation_page_smoke=ok
```

当前 virtual HAL 覆盖范围：

- browser HAL pin/signal/param state；
- virtual `halcmd` command workflow；
- ESTOP / power / home / jog / spindle / coolant state；
- motion controller matrix；
- virtual HAL session save/restore；
- browser diagnostics / release evidence。

边界不变：

- G-code / interpreter / planner / canonical motion 语义仍来自 LinuxCNC-backed WASM；
- virtual HAL 不提供 Linux kernel hard-realtime ABI；
- virtual HAL 不提供外部硬件驱动 ABI 或 native HAL module ABI；
- virtual HAL 不解锁 Python remap、external user-M process。

2. L4-TOOL-DB proof 已完成接入，但仍要按 promotion lock 规则处理。

已通过聚合 proof：

```bash
wasm-port/tests/host/verify_tool_db_process_proof.sh
```

输出：

```text
tool_db_process_port_sdk=ok
tool_db_store_opfs=ok
tool_db_process_port_wasm=ok
browser_tool_db_process_smoke=ok
tool_db_process_proof=ok
```

已通过 native opt-in DB_PROGRAM protocol probe：

```bash
ENABLE_TOOL_DB_RUNTIME_PROBE=1 wasm-port/tests/native/probe_tool_db_runtime.sh
```

关键输出：

```text
tool_db_protocol_version=v2.1
tool_db_get_all_count=10
tool_db_put_tool_update_state_ok=1
tool_db_load_spindle_state_ok=1
tool_db_unload_spindle_state_ok=1
tool_db_persistence_state_ok=1
tool_db_runtime_probe_status=runtime_protocol_probe_passed
```

结论：

```text
L4-TOOL-DB 的 native / SDK / OPFS / WASM / browser proof chain 已经成立。
后续不应再把主要精力放在 Tool DB runtime substrate 上，除非是 promotion lock
收尾或 gate drift 修复。
```

3. 当前 sim-config inventory 快照。

当前 `wasm-port/build/wasm/sim-configs-inventory/summary.tsv` 统计：

```text
total=159
pass=29
skip=130
fail=0
```

当前 `skip-summary.tsv`：

```text
ASSET-ONLY=65
L4-PYTHON-REMAP=53
L4-USER-M-PROCESS=1
NON_MAIN_CLASS=10
UPSTREAM-DEMO=1
```

注意：

```text
这里已经不是 text24.txt 中的旧 baseline：
executed=28 passed=28 skipped=131 unexpected_fail=0。

当前可见 generated inventory 已是：
PASS=29 SKIP=130 FAIL=0。
后续文件和 gate 必须以当前 artifact 为准，不能沿用过期 baseline。
```

4. 当前剩余 hard block。

主要剩余：

```text
L4-PYTHON-REMAP: 53
L4-USER-M-PROCESS: 1
```

推荐顺序：

```text
1. L4-PYTHON-REMAP
2. L4-USER-M-PROCESS
```

理由：

- `L4-PYTHON-REMAP` 覆盖面最大，解决后可复用到 53 个 rows；
- Tool DB milestone 已经建立 Python/WASM Worker、runtime port、browser proof、OPFS/diagnostics 的可复用模式；
- `L4-USER-M-PROCESS` 只有 1 个 row，且浏览器不能支持 arbitrary external process，只能做受控 state-transition proof；
- 先做 Python remap lifecycle substrate，能为后续 user-M 的受控 runtime proof 提供更成熟的边界模型。

二、L4-PYTHON-REMAP 当前已有基础

已有 machine-readable artifacts：

```text
wasm-port/build/wasm/sim-configs-inventory/python-remap-boundary-summary.tsv
wasm-port/build/wasm/sim-configs-inventory/python-remap-family-summary.tsv
wasm-port/build/wasm/sim-configs-inventory/python-remap-runtime-contract.tsv
wasm-port/build/wasm/sim-configs-inventory/python-remap-runtime-gates.tsv
wasm-port/build/wasm/sim-configs-inventory/python-remap-native-runtime-alignment.tsv
wasm-port/build/wasm/sim-configs-inventory/python-remap-native-runtime-readiness.tsv
wasm-port/build/wasm/sim-configs-inventory/python-remap-native-runtime-state-plan.tsv
wasm-port/build/wasm/sim-configs-inventory/python-remap-native-runtime-fixture-plan.tsv
wasm-port/build/wasm/sim-configs-inventory/python-remap-native-runtime-probe-gate.tsv
```

当前选定最小 fixture：

```text
family=axis/remap/stop-lookahead/nc_files
fixture_id=stop_lookahead_python_runtime_lifecycle
fixture_scope=no_python_callables_no_ngc_only_subpaths
```

原因：

- 适合作为 Python runtime lifecycle proof；
- 范围比 tool-change、five-axis、完整 remap family 更窄；
- 已有 source/runtime readiness artifacts；
- 可先证明 Python path、toplevel、module import、callable lookup、generator lifecycle、
  remap phase dispatch 等生命周期边界。

当前 fixture modules：

```text
axis/remap/stop-lookahead/python/remap.py
axis/remap/stop-lookahead/python/toplevel.py
```

当前 runtime phases：

```text
initialize_python
apply_ini_python_path
execute_toplevel
callable_lookup
pycall_dispatch
callable_invoke
remap_phase_dispatch
generator_finish
execute_python_runtime
reload_on_change
```

三、当前 native probe 状态

默认 probe：

```bash
wasm-port/tests/native/probe_python_remap_runtime.sh
```

关键输出：

```text
python_remap_runtime_fixture_family=axis/remap/stop-lookahead/nc_files
python_remap_runtime_fixture_id=stop_lookahead_python_runtime_lifecycle
python_remap_runtime_requirements=python3:1,linuxcnc:1
python_remap_missing_requirements=-
python_remap_source_proof_ready=1
python_remap_runtime_ready=1
python_remap_execution_enabled=0
python_remap_promotion_allowed=0
python_remap_runtime_probe_status=ready_disabled_by_default
```

显式 opt-in native lifecycle probe：

```bash
ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 wasm-port/tests/native/probe_python_remap_runtime.sh
```

关键输出：

```text
python_remap_lifecycle_execute_finish_source_value=2
python_remap_lifecycle_ini_path_prepend=python
python_remap_lifecycle_ini_toplevel=python/toplevel.py
python_remap_lifecycle_interpreter_sentinel_ok=1
python_remap_lifecycle_toplevel_imported=1
python_remap_lifecycle_remap_imported=1
python_remap_lifecycle_callable_lookup_ok=1
python_remap_lifecycle_generator_returned=1
python_remap_lifecycle_generator_first_yield=2
python_remap_lifecycle_generator_finish_ok=1
python_remap_runtime_lifecycle_probe_ok=1
python_remap_runtime_probe_status=runtime_lifecycle_probe_passed
```

结论：

```text
L4-PYTHON-REMAP 已不是“从零设计”。
native stop-lookahead lifecycle proof 已能通过；
下一步是把这个 native pass evidence 接入 WASM/Worker proof、browser diagnostics、
release artifact 和 promotion lock 后置 gate。
```

四、目标

本 milestone 的目标不是直接让 53 个 `L4-PYTHON-REMAP` rows 全部 PASS。

目标是证明：

```text
LinuxCNC-owned Python remap lifecycle + configured Python modules +
interpreter state binding 可以在 native / WASM / browser proof chain 中成立。
```

第一目标 fixture：

```text
axis/remap/stop-lookahead/nc_files
ini=axis/remap/stop-lookahead/demo.ini
blocked=L4-PYTHON-REMAP
modules=python/remap.py,python/toplevel.py
```

必须证明：

- INI `[PYTHON]PATH_PREPEND=python` 被执行；
- INI `[PYTHON]TOPLEVEL=python/toplevel.py` 被执行；
- configured Python module 可 import；
- callable lookup 来自 LinuxCNC Python remap lifecycle；
- generator remap lifecycle 可开始、yield、finish；
- interpreter sentinel / state binding 可观测；
- diagnostics 明确 `promotion_allowed=0`，直到完整 native + WASM + browser + manual lock review 完成。

五、Phase 1：把 native lifecycle pass evidence 接入 artifacts

当前 native opt-in probe 已通过，但 generated artifact 里仍有历史状态：

```text
python-remap-native-runtime-probe-gate.tsv
gate_status=ready_to_implement_lifecycle_probe
proof_status=pending
promotion_allowed=0
```

下一批应先做：

1. 让 inventory/report layer 可读取 native probe stdout：

```text
wasm-port/build/native/python-remap-runtime/python_lifecycle.stdout.log
```

2. 生成 native pass evidence contract：

```text
python_remap_runtime_probe_status=runtime_lifecycle_probe_passed
python_remap_lifecycle_toplevel_imported=1
python_remap_lifecycle_remap_imported=1
python_remap_lifecycle_callable_lookup_ok=1
python_remap_lifecycle_generator_finish_ok=1
python_remap_runtime_lifecycle_probe_ok=1
```

3. 更新/新增 machine-readable artifacts：

```text
python-remap-native-runtime-probe-gate.tsv
runtime-boundary-native-evidence-acceptance-gate.tsv
runtime-boundary-post-native-pass-gates.tsv
native-runtime-probe-pass-evidence-contract.tsv
runtime-probe-gate-alignment.tsv
```

4. 仍保持：

```text
execution_enabled=0
promotion_allowed=0
manual_lock_update_required=1
```

验收命令：

```bash
ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 wasm-port/tests/native/probe_python_remap_runtime.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_interp_browser.sh
```

六、Phase 2：定义 PythonRemapRuntimePort

建议新增：

```text
wasm-port/runtime/sdk/src/python-remap-runtime-port.js
wasm-port/runtime/sdk/src/python-remap-browser-worker-adapter.js
wasm-port/runtime/workers/python-remap-worker.js
wasm-port/tests/sdk/node/verify_python_remap_runtime_port.mjs
wasm-port/tests/wasm/node/verify_python_remap_runtime_port_wasm.mjs
wasm-port/tests/browser/verify_python_remap_runtime_browser.sh
wasm-port/tests/browser/python_remap_runtime_browser_smoke.html
```

建议 API：

```text
createLinuxCncPythonRemapRuntimePort({
  fixtureFamily,
  iniPath,
  pythonPathPrepend,
  topLevelPath,
  sourceFiles,
  runtimeMode,
  runtimeAdapter,
})

start()
applyIniPythonPath()
executeTopLevel()
importModule(modulePath)
lookupCallable(callableName)
invokeGenerator(callableName, args)
runLifecyclePlan(plan)
exportTranscript()
exportDiagnostics()
close()
```

最小 lifecycle plan：

```text
1. initialize_python
2. apply_ini_python_path
3. execute_toplevel
4. import python/remap.py
5. lookup configured callable
6. invoke generator
7. observe first yield
8. finish generator
9. export interpreter sentinel/state
10. export diagnostics
```

必须保持：

```text
executionEnabled=false
promotionAllowed=false
bulkPromotionAllowed=false
```

不允许：

- JS 直接实现 remap callable 结果；
- JS 构造 interpreter state 假装 Python remap pass；
- 只用 fixture transcript 假装 runtime pass；
- 跳过 `toplevel.py`；
- 跳过 configured Python module import；
- 把 Python module import success 当作 full remap lifecycle success。

七、Phase 3：WASM/Worker runtime

推荐复用 Tool DB milestone 的 runtime pattern：

```text
Browser/Node worker + Python/WASM provider + LinuxCNC-specific lifecycle shim
```

Worker 职责：

- 加载 Python runtime provider；
- 设置 INI 声明的 Python path；
- 执行 `python/toplevel.py`；
- import `python/remap.py`；
- 通过受控 adapter 调用 lifecycle fixture；
- 记录 transcript；
- 导出 diagnostics。

允许的 shim：

```text
minimal LinuxCNC Python remap integration shim
```

shim 只能覆盖 stop-lookahead fixture 必需的 integration surface，例如：

- interpreter sentinel；
- callable lookup bridge；
- generator invocation bridge；
- remap phase observations；
- diagnostics state capture。

shim 不允许承载：

- generic interpreter semantics；
- G-code parsing；
- planner / canonical motion；
- full tool-change semantics；
- arbitrary Python UI process；
- arbitrary external process。

八、Phase 4：browser diagnostics proof

新增 browser diagnostics 字段建议：

```text
python_remap_runtime_mode=browser-python-wasm-worker
fixture_family=axis/remap/stop-lookahead/nc_files
ini_path=axis/remap/stop-lookahead/demo.ini
python_path_prepend=python
toplevel=python/toplevel.py
modules=python/remap.py,python/toplevel.py
lifecycle_transcript_ready=true
callable_lookup_ready=true
generator_lifecycle_ready=true
interpreter_state_binding_ready=true
ngc_only_subroutine_promoted=false
bulk_family_promotion_allowed=false
promotion_allowed=0
```

browser gate 必须证明：

- 页面/API 可读取 Python remap lifecycle diagnostics；
- diagnostics 来源绑定 LinuxCNC config/source；
- diagnostics 明确不是 JS-owned CNC semantics；
- saved artifact 可进入 release URL / ini-panel workflow；
- `L4-PYTHON-REMAP` 仍在 manual promotion lock 下。

建议命令：

```bash
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_python_remap_runtime_browser.sh
```

九、Phase 5：release artifact / promotion lock

在 native + WASM + browser proof 全部通过前，release artifact 只能显示：

```text
L4-PYTHON-REMAP locked
python_remap_native_lifecycle_ready=<0|1>
python_remap_wasm_lifecycle_ready=<0|1>
python_remap_browser_lifecycle_ready=<0|1>
promotion_allowed=0
```

三层 proof 都 ready 后，仍不能自动批量解锁 53 rows。

下一步只能考虑单独 review：

```text
axis/remap/stop-lookahead/nc_files: SKIP L4-PYTHON-REMAP -> PASS
```

并且必须证明：

- 对应 row 不是 NGC-only subroutine；
- 对应 INI / Python modules / remap declarations 都已 vendored；
- native pass 与 WASM/browser lifecycle proof 对齐；
- Python runtime 没有绕过 LinuxCNC interpreter lifecycle；
- `promotion_allowed` 的变更是显式人工 review，不是 gate 自动推断。

十、L4-USER-M-PROCESS 暂缓原则

`L4-USER-M-PROCESS` 当前代表 row：

```text
axis/vismach/millturn/example.ngc
```

核心阻塞：

```text
M128 / M129 Tcl scripts
HAL pin state updates
kinstype guard
ini.[xyz].* soft-limit state transitions
```

暂缓原因：

- 浏览器不能支持 arbitrary executable spawn；
- 浏览器不能通用执行 native Tcl process；
- 不能模拟 host HAL daemon unrestricted side effects；
- 成功只覆盖 1 个 row；
- 更适合在 Python remap lifecycle / runtime diagnostics pattern 稳定后，做受控 state-transition proof。

后续做法只允许：

```text
LinuxCNC-owned user-M state transition boundary
```

不允许：

```text
browser arbitrary external process execution
```

十一、下一批最小执行建议

优先做一批小而可验收的改动：

1. 固化 native Python remap lifecycle pass evidence。

```bash
ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 wasm-port/tests/native/probe_python_remap_runtime.sh
```

2. 让 generated inventory / release artifact 能识别：

```text
python_remap_runtime_probe_status=runtime_lifecycle_probe_passed
```

3. 新增 `PythonRemapRuntimePort` contract-only SDK 层。

4. 新增 Node contract test：

```text
wasm-port/tests/sdk/node/verify_python_remap_runtime_port.mjs
```

5. 暂不改 baseline，不改 53 rows。

首批验收命令：

```bash
git diff --check
ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 wasm-port/tests/native/probe_python_remap_runtime.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
wasm-port/tests/sdk/node/verify_sdk_surface.sh
wasm-port/tests/sdk/node/verify_project_release_gate_manifest.sh
```

十二、结论

当前状态可以概括为：

```text
virtual HAL 已接入 Web 仿真；
L4-TOOL-DB proof chain 已成立；
当前 generated inventory 为 PASS=29 / SKIP=130 / FAIL=0；
剩余主要 hard block 是 L4-PYTHON-REMAP=53 和 L4-USER-M-PROCESS=1；
下一步先做 L4-PYTHON-REMAP；
首个 fixture 是 axis/remap/stop-lookahead/nc_files；
native opt-in lifecycle probe 已通过；
下一批应把 native pass evidence 接入 artifacts，并建立 PythonRemapRuntimePort
的 WASM/browser proof chain；
promotion_allowed 继续保持 0，直到完整 proof + manual lock review。
```

十三、2026-06-19 接续执行记录：L4-PYTHON-REMAP 仿真系统接入收尾

本轮结论：

```text
L4-PYTHON-REMAP 的 native / SDK / WASM / browser proof chain 已接入；
真实数控仿真页 runtime/ui/simulation 现在也暴露 Python remap runtime 状态；
release artifact / URL workflow 能识别 python-remap-runtime-proof=ready；
53 个 L4-PYTHON-REMAP inventory rows 仍保持 SKIP/manual promotion lock，
不做批量 PASS，不启用 execution，不允许 promotion_allowed。
```

新增/补齐的仿真接入点：

```text
wasm-port/runtime/ui/simulation/simulation-app.js
- createPythonRemapSimulationRuntimeStatus()
- renderPythonRemapRuntimeStatus()
- runRealBrowserSimulation() state.pythonRemapRuntime

wasm-port/runtime/ui/simulation/index.html
- Machine State 面板显示 L4-PYTHON-REMAP fixture/runtime/lifecycle/promotion 状态
- window.linuxCncRealSimulationApi.getPythonRemapRuntimeStatus()
- exportDiagnosticsArtifact().pythonRemapRuntime

wasm-port/tests/browser/real_simulation_page_smoke.html
- 验证 DOM / API / diagnostics artifact 的 Python remap runtime 状态
```

本轮验证：

```bash
wasm-port/tests/native/probe_python_remap_runtime.sh
ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 wasm-port/tests/native/probe_python_remap_runtime.sh
wasm-port/tests/sdk/node/verify_python_remap_runtime_port.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_python_remap_runtime_port_wasm.sh
wasm-port/tests/browser/verify_python_remap_runtime_browser.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_real_simulation_browser.sh
wasm-port/tests/browser/verify_release_artifact_url_workflow_browser.sh
wasm-port/tests/sdk/node/verify_sdk_surface.sh
wasm-port/tests/sdk/node/verify_project_release_gate_manifest.sh
wasm-port/tests/sdk/node/verify_project_release_artifact_url_workflow.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
wasm-port/tools/verify_no_standalone_cnc_semantics.sh
git diff --check
```

关键验证结果：

```text
python_remap_runtime_probe_status=ready_disabled_by_default
python_remap_runtime_probe_status=runtime_lifecycle_probe_passed
python_remap_runtime_lifecycle_probe_ok=1
python_remap_lifecycle_generator_first_yield=2
python_remap_execution_enabled=0
python_remap_promotion_allowed=0
browser_python_remap_runtime_smoke=ok
browser_real_simulation_page_smoke=ok
browser_release_artifact_url_workflow_smoke=ok
sim_configs_wasm_node_inventory_executed=29
sim_configs_wasm_node_inventory_passed=29
sim_configs_wasm_node_inventory_skipped=130
sim_configs_wasm_node_inventory_skip_L4_PYTHON_REMAP=53
sim_configs_wasm_node_inventory_unexpected_fail=0
standalone CNC semantics guard complete
```

仍保持的边界：

```text
executionEnabled=false
promotionAllowed=false
bulkPromotionAllowed=false
ngcOnlySubroutinePromoted=false
jsCncSemantics=false
```