wasm-simulator/docs/linuxcnc-wasm-blockers-source-map.md

# LinuxCNC WASM blockers source map

This map records the source basis for the WASM blocker categories used by
`analyze-linuxcnc-wasm-blockers.sh` and `test-linuxcnc-wasm-blockers.sh`. It is
a source-link/build guard only; it does not add CNC behavior and must not become smoke parser behavior.

## LinuxCNC Source Basis

- `src/emc/rs274ngc/gcodemodule.cc`, `canonmodule.cc`, `interpmodule.cc`, and
  `py*.cc` provide the Python and Boost.Python module binding blockers.
- `test-linuxcnc-wasm-python-c-api-symbols.sh` compiles the blocked
  Python/Boost.Python binding sources with inert Python/runtime shims so their
  source surface is covered without enabling Python execution.
- `src/emc/rs274ngc/interp_python.cc`, `interp_remap.cc`,
  `interp_namedparams.cc`, `interp_o_word.cc`, `interp_setup.cc`, and
  `rs274ngc_pre.cc` keep Python/Boost.Python remap paths as shimmed core
  sources.
- `src/emc/rs274ngc/interp_base.cc` is the core source that still carries
  `dlopen` use satisfied by the wasm dlfcn shim.
- `src/emc/tooldata/tooldata_mmap.cc` is the native mmap backend blocker
  replaced by the wasm-safe tooldata mmap backend shim.
- `src/emc/rs274ngc/interp_o_word.cc` uses native directory traversal for
  O-word subroutine lookup; browser persistence remains OPFS-only.
- `src/emc/rs274ngc/rs274ngc_pre.cc` implements LinuxCNC parameter-file replacement through `filename + ".new"`, `filename + ".bak"`, `unlink`, `link`, and `rename`; browser persistence remains OPFS-only.

## Manifest Coverage

| Manifest group | Count | Role |
| --- | ---: | --- |
| `core` | 26 | LinuxCNC RS274/tooldata/INI/NML sources compiled or shim-satisfied by WASM probes. |
| `blocked` | 9 | LinuxCNC Python binding and native tooldata sources tracked but replaced for WASM. |
| `header` | 26 | LinuxCNC headers needed by the WASM-safe source probes and shims. |
| `blocked-header` | 1 | Boost.Python helper header tracked as blocked browser API surface. |
| `metadata` | 15 | LinuxCNC build/source-basis files for shim coverage. |

## Analyzer Coverage

| Analyzer section | Count | Boundary |
| --- | ---: | --- |
| `python` | 8 | Blocked Python/Boost.Python module sources. |
| `python-compile-covered` | 8 | Blocked Python/Boost.Python module sources compiled by the inert Python C API symbol probe while remaining blockers. |
| `dlopen` | 0 | blocked `dlopen` and blocked tooldata-users remain empty. |
| `tooldata` | 1 | Native tooldata mmap blocker. |
| `tooldata-users` | 0 | Blocked tooldata user sources remain empty. |
| `native-backend` | 1 | Native backend source excluded from browser linking. |
| `native-fs` | 1 | Native filesystem blocker excluded from browser linking. |
| `blocked-replacements` | 9 | Blocked LinuxCNC sources mapped to wasm-safe shim files. |
| `core-python-shimmed` | 6 | Core LinuxCNC Python/remap users compiled with Python/Boost.Python shims. |
| `core-dlopen-shimmed` | 1 | Core LinuxCNC `dlopen` user compiled with dlfcn shim. |
| `core-tooldata-shimmed` | 1 | Core LinuxCNC tooldata source compiled with wasm tooldata shims. |
| `core-tooldata-users-shimmed` | 2 | Core RS274/NML users of tooldata declarations. |
| `core-native-fs-shimmed` | 16 | Core sources with native filesystem includes or calls covered by WASM shims, including O-word lookup and parameter-file replacement. |

Required replacement set:

- `src/emc/rs274ngc/canonmodule.cc -> core/wasm_shims/linuxcnc_runtime_shim.cc`
- `src/emc/rs274ngc/gcodemodule.cc -> core/wasm_shims/linuxcnc_runtime_shim.cc`
- `src/emc/rs274ngc/interpmodule.cc -> core/wasm_shims/linuxcnc_runtime_shim.cc`
- `src/emc/rs274ngc/pyarrays.cc -> core/wasm_shims/python_c_api_shim.cc`
- `src/emc/rs274ngc/pyblock.cc -> core/wasm_shims/python_c_api_shim.cc`
- `src/emc/rs274ngc/pyemctypes.cc -> core/wasm_shims/python_c_api_shim.cc`
- `src/emc/rs274ngc/pyinterp1.cc -> core/wasm_shims/python_c_api_shim.cc`
- `src/emc/rs274ngc/pyparamclass.cc -> core/wasm_shims/python_c_api_shim.cc`
- `src/emc/tooldata/tooldata_mmap.cc -> core/wasm_shims/tooldata/tooldata_mmap_backend.cc`

Required tracked core examples:

- `src/emc/rs274ngc/interp_base.cc -> core/wasm_shims/dlfcn.cc`
- `src/emc/rs274ngc/gcodemodule.cc`
- `src/emc/rs274ngc/interpmodule.cc`
- `src/emc/tooldata/tooldata_mmap.cc`
- `src/emc/rs274ngc/interp_base.cc`
- `src/emc/rs274ngc/interp_o_word.cc`
- `src/emc/rs274ngc/rs274ngc_pre.cc`

## Boundaries

- `test-native.sh`, `test-linuxcnc-source-link.sh`, and `build-wasm.sh` must
  run `./check-linuxcnc-wasm-blockers-source-map.sh` before consuming blocker
  analyzer output, source-linked LinuxCNC objects, or browser artifacts.
- `test-native.sh` and `test-linuxcnc-source-link.sh` must run
  `test-linuxcnc-wasm-blockers.sh` with `CNC_SIM_WASM_BLOCKERS_SELF_CHECKS=1`
  so bad manifests, missing LinuxCNC roots, duplicate entries, and missing
  blocked-source replacements stay executable failures.
- The WASM blockers source-map guard validates LinuxCNC source/blocker
  ownership and manifest drift only; it does not interpret G-code.
- Python/Boost.Python blockers are compile-covered by the inert Python C API probe,
  but they remain tracked blockers until Python/remap execution is ported,
  wrapped, or replaced by a source-backed browser-safe LinuxCNC adaptation.

## Checks

Run:

```bash
./check-linuxcnc-wasm-blockers-source-map.sh
./test-linuxcnc-wasm-blockers.sh linuxcnc-rs274-wasm-source-files.txt
./test-native.sh
./test-linuxcnc-source-link.sh
./build-wasm.sh
```

`check-linuxcnc-wasm-blockers-source-map.sh` keeps this document, the
RS274/WASM manifest, LinuxCNC source anchors, analyzer output, and wasm-safe
shim replacement set synchronized. Python/Boost.Python remap paths remain tracked blockers until they are ported, wrapped, or replaced by source-backed browser-safe LinuxCNC adaptations.