wasm-simulator/docs/linuxcnc-source-policy.md

# LinuxCNC Source Policy

The simulator must not grow independently designed functional behavior.
Functional behavior must come from LinuxCNC source code.

Hard rules:

- Port-first: prefer direct LinuxCNC source porting, trimming, wrapping, or
  platform adaptation over project-authored replacements.
- Do not write project-owned functional CNC behavior.
- Functional CNC behavior must be ported, trimmed, wrapped, or routed from
  LinuxCNC source code.
- Any G/M-code interpretation, motion behavior, kinematics, coordinate
  handling, cutter compensation, canned cycle, parameter expression, modal
  state, tool data, remap behavior, or RTCP behavior must first be traced to
  LinuxCNC source before implementation.
- Browser-side wasm filesystem behavior must use OPFS-backed storage. Do not
  add browser filesystem paths that bypass OPFS.
- Browser app and wasm bridge code must not persist CNC programs, LinuxCNC
  parameter files, or mirrored workspace files through non-OPFS browser storage
  APIs such as Local Storage, IndexedDB, File Picker writes, WebKit filesystem
  APIs, or FileReader-backed import paths.

Allowed project code:

- LinuxCNC source porting, trimming, wrappers, and platform adaptation.
- Thin adapters between LinuxCNC source code and the simulator C API.
- Platform shims needed to compile LinuxCNC code for native tests or wasm.
- Event serialization, test fixtures, build scripts, and documentation.
- Temporary smoke scaffolding only when it is explicitly marked as temporary.

Not allowed as final behavior:

- Hand-written G-code interpretation semantics.
- Hand-derived kinematics, RTCP, coordinate transform, cutter compensation, canned cycle, modal, parameter, or expression behavior.
- Behavior copied from documentation, controller intuition, or examples without checking the LinuxCNC implementation.

Required workflow for every functional change:

1. Identify the LinuxCNC source file and function that defines the behavior.
2. Add or update a test that demonstrates the LinuxCNC behavior.
3. Port, wrap, or route to that LinuxCNC implementation.
4. Record the source file/function in code comments or nearby documentation when the mapping is not obvious.
5. Keep the change inside one active workstream context unless a dependency is
   unavoidable and explicitly named in the final report.
6. Run `./test-native.sh` and `./test-linuxcnc-source-link.sh`.
7. For source-manifest, build, or build-policy changes, also run the aggregate
   and guardrail checks: `./test-all-native.sh`,
   `./test-linuxcnc-source-syntax.sh`, and
   `./test-linuxcnc-wasm-cmake-safe-probe.sh`.
   When `./test-native.sh` and `./test-linuxcnc-source-link.sh` have already
   been run in the same pass, use
   `CNC_SIM_ALL_NATIVE_GUARDRAILS_ONLY=1 ./test-all-native.sh` for the
   aggregate guardrail pass instead of recompiling the same native/source-link
   targets again.
8. Keep `./test-linuxcnc-wasm-cmake-safe-probe.sh` focused on the actual CMake
   probe by default. Run
   `CNC_SIM_WASM_CMAKE_SAFE_PROBE_SELF_CHECKS=1 ./test-linuxcnc-wasm-cmake-safe-probe.sh`
   only when changing its meta-guardrails or the surrounding build-wasm policy.

Efficiency rules:

- Each pass should advance one reasonable, reviewable context. Do not use a
  nearby failing smoke assertion, broad fixture, or convenient touched file as
  permission to expand the pass into another workstream.
- Do not add a smoke-only behavior path when the LinuxCNC-backed route already
  exists; add coverage to the source-backed route instead.
- Keep browser filesystem guardrails negative as well as positive: require the
  OPFS bridge and reject browser app/wasm storage APIs that could bypass it.
- Smoke tests are verification guardrails. They must not be expanded with new
  functional CNC behavior unless that behavior is directly routed to, copied
  from, or checked against the relevant LinuxCNC source in the same narrow
  context.
- Do not mix generator/table work, manifests, OPFS/browser work, and build
  policy cleanup in the same pass unless the files directly depend on each
  other.
- Prefer tightening an existing probe or manifest over adding another broad
  end-to-end smoke case.
- Do not run the full native aggregate after already running its expensive
  native/source-link children in the same pass; use the explicit guardrails-only
  aggregate mode for build-policy cleanup.
- Keep meta-guardrails out of hot build paths. The wasm-safe CMake probe may
  run extended self-checks with `CNC_SIM_WASM_CMAKE_SAFE_PROBE_SELF_CHECKS=1`,
  and the source syntax probe may run extended self-checks with
  `CNC_SIM_SOURCE_SYNTAX_SELF_CHECKS=1`. The wasm blocker probe may run
  analyzer failure-path self-checks with `CNC_SIM_WASM_BLOCKERS_SELF_CHECKS=1`.
  The default actual CMake, syntax, and blocker probe paths remain fast.
- Keep `test-linuxcnc-wasm-source-syntax.sh` on the same persistent incremental
  build pattern as the native syntax probe. It must use
  `build/wasm-source-syntax-test` by default, dependency files, a signature,
  `make --output-sync=target`, and `CNC_SIM_BUILD_JOBS:-8`.
- Reuse source preflight results in persistent build directories through
  `check-linuxcnc-inputs-cached.sh`; its signature must include the LinuxCNC
  root, manifest content, source file size and nanosecond mtime stats, the check
  mode, the cached wrapper script hash, and the checker script hash. Cache
  updates must be serialized with a lock inside the cache directory and must
  write next signatures through unique temporary files.
  Root-only source, flag, and link helper scripts must also use this cached
  preflight, defaulting to `build/linuxcnc-helper-preflight-cache` when a caller
  has not supplied `CNC_SIM_PREFLIGHT_CACHE_DIR`.
  `build-wasm.sh` must pass its preflight cache into nested build probes such as
  `test-linuxcnc-wasm-blockers.sh` and
  `test-linuxcnc-wasm-cmake-safe-probe.sh` instead of forcing a second cache
  walk in the same pass.
- Cache wasm blocker analyzer output in `test-linuxcnc-wasm-blockers.sh`. Its
  signature must include the blocker wrapper script, analyzer script, manifest
  content, LinuxCNC source size and nanosecond mtime stats, shim lister script,
  and shim source hashes. The cache must be locked and may be overridden with
  `CNC_SIM_WASM_BLOCKERS_CACHE_DIR`.
- Reuse switchkins/remap table check results in the same persistent cache with
  `check-linuxcnc-switchkins-remap-table-cached.sh`; its signature must include
  the cached wrapper script, checker script, generator script, manifest input
  checker scripts, the kinematics manifest, referenced LinuxCNC source size and
  nanosecond mtime stats, tracked generated table/case outputs, and the thin API/web bridge files that pass
  switchkins config aliases. Native, source-link, and build-wasm entry points
  must run this cached check before consuming those aliases.
- The switchkins/remap generator must treat LinuxCNC `[EMCIO] TOOL_TABLE`
  entries as source coverage only. Resolvable tool tables referenced by
  M428/M429/M430 INI files must be present as `tooldata` manifest entries and
  must not become new generated API aliases or browser cases.
- The kinematics manifest lister must preserve every allowed manifest group
  used by switchkins and RTCP coverage, including `asset`, `tooldata`, and
  `generated`, and must reject unknown filters or output modes for those groups.
- Reuse wasm probe objects across the wasm source object probe,
  `rs274ngc_pre` blocker/link probes, and the runtime link probe through
  `build-linuxcnc-wasm-probe-objects.sh`. Its mode-specific object caches must
  be keyed by compiler, LinuxCNC root, manifest, flags, and source list, and
  must include make dependency files so repeated build-wasm passes and the
  paired `rs274ngc_pre` probes do not recompile unchanged LinuxCNC core files,
  shims, or kinematics adapters.
- Reuse standalone wasm probe objects and binaries for the tooldata link,
  tooldata_common link, `interp_base` link, python_plugin link, and
  `rs274ngc_pre` object probes through
  `build-linuxcnc-wasm-standalone-probe.sh`. Its mode-specific caches must keep
  compiler, LinuxCNC root, flags, source list, dependency files, and a lock so
  repeated build-wasm passes do not rebuild unchanged probe inputs.
- Reuse wasm final link probes for `rs274ngc_pre` and runtime link checks
  through `build-linuxcnc-wasm-link-probe.sh`. It must consume
  `build-linuxcnc-wasm-probe-objects.sh`, cache probe main objects and linked
  executables with dependency files and a lock, and keep runtime symbol checks
  in `test-linuxcnc-wasm-runtime-link.sh`.
- Cache the runtime link probe symbol table in `test-linuxcnc-wasm-runtime-link.sh`
  using the probe binary size and mtime plus an explicit `SYMBOL_RULE_VERSION`,
  so repeated build-wasm passes do not rerun `nm -C` on an unchanged probe.
- Cache the `rs274ngc_pre` pre-link undefined-symbol scan in
  `test-linuxcnc-wasm-rs274ngc-pre-link-blockers.sh`. Its signature must
  include the LinuxCNC root, manifest, object list, object size and mtime stats,
  and an explicit `FILTER_RULE_VERSION`, with a lock and
  `CNC_SIM_WASM_RS274NGC_PRE_LINK_BLOCKERS_CACHE_DIR` override.
- Keep `test-linuxcnc-wasm-python-c-api-symbols.sh` persistent for repeated
  build-wasm passes. It must use `build/wasm-python-c-api-symbols`,
  dependency files, a build signature, cached source token and object symbol
  signatures, `make --output-sync=target`, and `CNC_SIM_BUILD_JOBS:-8` while
  still deriving required Python C API symbols from LinuxCNC RS274 Python/remap
  sources.
- Keep `test-linuxcnc-wasm-interp-find-link.sh` persistent for repeated
  build-wasm passes. It must use `build/wasm-interp-find-link`, dependency
  files, a signature, `make --output-sync=target`, and `CNC_SIM_BUILD_JOBS:-8`
  while still linking LinuxCNC `interp_find.cc` with the wasm-safe tooldata and
  RTAPI shims.
- Keep tooldata symbol probes persistent for repeated build-wasm passes.
  `test-linuxcnc-wasm-tooldata-mmap-symbols.sh` must use
  `build/wasm-tooldata-mmap-symbols`, and
  `test-linuxcnc-wasm-tooldata-runtime-symbols.sh` must use
  `build/wasm-tooldata-runtime-symbols`; both must use dependency files,
  build signatures, cached `nm --defined-only` symbol export signatures,
  `make --output-sync=target`, and `CNC_SIM_BUILD_JOBS:-8` while comparing wasm
  shim exports against LinuxCNC tooldata sources.
- Default native, source-link, build-wasm, and wasm-safe CMake probe
  parallelism to `CNC_SIM_BUILD_JOBS:-8`; raise it only by explicit
  positive-integer environment override.
- Persistent object/stamp signatures must not include `CNC_SIM_BUILD_JOBS`.
  Parallelism affects scheduling only; changing it must not invalidate otherwise
  unchanged LinuxCNC source, shim, syntax, or CMake probe build outputs.
- Persistent native, source-object, source-link, source-syntax, RS274 native,
  bridge native, API native, shared bridge-object, wasm source-syntax,
  wasm probe-object, wasm link-probe, wasm standalone-probe, wasm Python C API,
  wasm interp_find, and wasm tooldata symbol signatures must include an explicit
  `BUILD_RULE_VERSION` instead of hashing the whole probe script. Bump that
  version when generated compile or link rule semantics change; ordinary
  guardrail and smoke assertion edits must not invalidate unchanged LinuxCNC
  source, shim, or project objects.
- The LinuxCNC canon bridge native smoke probe must use persistent
  `build/bridge-native-test` objects, dependency files, a build-rule signature,
  `make --output-sync=target`, and `CNC_SIM_BUILD_JOBS:-8`; it must not compile
  all bridge sources in a throwaway temporary directory on every aggregate pass.
  Its 41 LinuxCNC bridge/project objects must be built through the shared
  `build-linuxcnc-native-bridge-objects.sh` cache so the RS274 API native smoke
  probe can link the same objects instead of recompiling them.
- The LinuxCNC RS274 API native smoke probe must use persistent
  `build/api-native-test` objects, dependency files, a build-rule signature,
  `make --output-sync=target`, and `CNC_SIM_BUILD_JOBS:-8`; it must keep
  resetting its RS274 parameter file from LinuxCNC `tests/halui/jogging/sim.var`
  before running the smoke executable. It must reuse the shared bridge object
  cache and compile only its extra API/backend sources locally. Its LinuxCNC
  RS274 backend compile define must be applied only to source files that use
  that define, currently `core/src/gcode_backend.cpp`, so unrelated bridge and
  kinematics adapter objects are not rebuilt by backend-specific rule changes.
- When `ccache` is available and `CXX` is unset, native, source-link,
  source-syntax, and wasm build paths should enable compiler caching
  automatically rather than requiring a manual wrapper, including the
  wasm-safe CMake probe.
- Persistent native, source-link, source-syntax, and wasm-safe CMake probe
  build directories, plus the wasm source-syntax, Python C API, and interp_find
  probe build directories, tooldata symbol probe build directories, and wasm
  standalone/link probe cache directories may be overridden for local workflows,
  but must not point at the filesystem root.
- Build policy knobs are intentionally narrow:
  `CNC_SIM_BUILD_JOBS`, `CNC_SIM_NATIVE_BUILD_DIR`,
  `CNC_SIM_SOURCE_LINK_BUILD_DIR`, `CNC_SIM_SOURCE_SYNTAX_BUILD_DIR`,
  `CNC_SIM_SOURCE_OBJECTS_BUILD_DIR`, `CNC_SIM_BRIDGE_NATIVE_BUILD_DIR`,
  `CNC_SIM_API_NATIVE_BUILD_DIR`, `CNC_SIM_NATIVE_BRIDGE_OBJECT_CACHE_DIR`, and
  `CNC_SIM_RS274_NATIVE_BUILD_DIR`, and
  `CNC_SIM_WASM_CMAKE_SAFE_PROBE_BUILD_DIR`. The wasm source-syntax probe also
  accepts `CNC_SIM_WASM_SOURCE_SYNTAX_BUILD_DIR` because it owns a persistent
  incremental cache. The wasm Python C API probe accepts
  `CNC_SIM_WASM_PYTHON_C_API_BUILD_DIR` for the same reason, and the
  wasm interp_find probe accepts `CNC_SIM_WASM_INTERP_FIND_BUILD_DIR`.
  Tooldata symbol probes accept
  `CNC_SIM_WASM_TOOLDATA_MMAP_SYMBOLS_BUILD_DIR` and
  `CNC_SIM_WASM_TOOLDATA_RUNTIME_SYMBOLS_BUILD_DIR`.
  Standalone wasm probes accept `CNC_SIM_WASM_STANDALONE_PROBE_CACHE_DIR`.
  Final wasm link probes accept `CNC_SIM_WASM_LINK_PROBE_CACHE_DIR`.
  Build directory overrides must stay non-empty, whitespace-free, and outside
  the filesystem root.
- `build-wasm.sh` keeps fixed artifact paths: CMake writes `build/wasm`, then
  the script copies and byte-compares `cnc_sim.js` and `cnc_sim.wasm` under
  `web/public` before running Node and browser smoke checks.

Build and source-link guardrails:

- `CNC_SIM_BUILD_JOBS` must be a positive integer and defaults to `8`.
- `test-native.sh` uses persistent `build/native-test` objects, dependency
  files, and `native-build.signature`.
- `test-linuxcnc-source-link.sh` uses persistent `build/source-link-test`
  objects, dependency files, and `source-link-build.signature`.
- `test-linuxcnc-source-syntax.sh` uses persistent
  `build/source-syntax-test` stamps, dependency files, and
  `source-syntax.signature`.
- `test-linuxcnc-source-objects.sh` uses persistent
  `build/source-objects-test` objects, dependency files, and
  `source-objects.signature`.
- `test-linuxcnc-rs274-native.sh` uses persistent
  `build/rs274-native-test` objects, dependency files, and
  `rs274-native.signature`.
- `test-linuxcnc-wasm-cmake-safe-probe.sh` uses persistent
  `build/wasm-cmake-safe-probe` and `wasm-cmake-safe-probe.signature`; signature
  changes must reconfigure in place, its signature must include an explicit
  `CONFIGURE_RULE_VERSION`, and its two probe executables must be built with one
  combined `cmake --build` invocation.
- `test-linuxcnc-wasm-source-syntax.sh` uses persistent
  `build/wasm-source-syntax-test` stamps, dependency files, and
  `wasm-source-syntax.signature`.
- `test-linuxcnc-wasm-python-c-api-symbols.sh` uses persistent
  `build/wasm-python-c-api-symbols` objects, dependency files, and
  `python-c-api.signature`.
- `test-linuxcnc-wasm-interp-find-link.sh` uses persistent
  `build/wasm-interp-find-link` objects, dependency files, and
  `interp-find.signature`.
- `test-linuxcnc-wasm-tooldata-mmap-symbols.sh` uses persistent
  `build/wasm-tooldata-mmap-symbols` objects, dependency files, and
  `tooldata-mmap-symbols.signature`.
- `test-linuxcnc-wasm-tooldata-runtime-symbols.sh` uses persistent
  `build/wasm-tooldata-runtime-symbols` objects, dependency files, and
  `tooldata-runtime-symbols.signature`.
- Native, source-link, source-syntax, wasm-safe CMake probe, and build-wasm
  paths must reject empty, whitespace-containing, or filesystem-root build
  directory overrides before doing destructive cleanup.
- Native, source-link, source-syntax, and build-wasm entry points must serialize
  shared non-concurrency-safe paths with lock files before writing fixed
  outputs.
- `CNC_SIM_ALL_NATIVE_GUARDRAILS_ONLY=1 ./test-all-native.sh` must run the
  aggregate guardrail and failure-path assertions without invoking the expensive
  child native/source-link compile and smoke scripts.
- Native, source-object, source-link, RS274 native, and syntax probes must build
  from generated makefiles with `-MMD -MP` dependency tracking and
  `make --output-sync=target`.
- `build-wasm.sh` must run blocker, syntax, object, CMake, tooldata,
  `interp_*`, Python, `rs274ngc_pre`, and runtime link probes before copying
  browser artifacts.
- Independent tooldata, `interp_*`, Python, and `rs274ngc_pre` object probes in
  `build-wasm.sh` may run in parallel, but their logs must be replayed in a
  deterministic order and the script must wait for all of them before
  `rs274ngc_pre` link checks.
- `build-wasm.sh` must check `cmake`, `emcmake`, `emcc`, and `node` before the
  Emscripten configure step.
- `build-wasm.sh` must reuse a persistent `build/wasm` configure signature
  keyed by manifest, `core/CMakeLists.txt`, an explicit
  `CONFIGURE_RULE_VERSION`, LinuxCNC root, and compiler launcher. The signature
  must not include `CNC_SIM_BUILD_JOBS`, and signature changes must reconfigure
  the existing build tree in place instead of deleting compiled objects.
- `build-wasm.sh` must build `cnc_sim_wasm_runtime_probe` before
  `cnc_sim_wasm`, using one combined `cmake --build` invocation for both
  targets.
- `build-wasm.sh` must copy `build/wasm/cnc_sim.js` and
  `build/wasm/cnc_sim.wasm` exactly once each.
- `build-wasm.sh` must compare copied artifacts with `cmp -s` before running
  Node or browser smoke tests.
- `build-wasm.sh` must run `test-web-wasm-node-smoke.sh` before the browser
  smoke so the Node prerequisite, syntax, and minimum-step checks are enforced.
- The default wasm manifest partition must remain explicitly checked for 26
  wasm-safe core sources and 9 blocked sources.
- Manifest source listers must reject malformed lines, absolute source paths,
  unknown groups, unknown filters, unknown output modes, and duplicate source
  entries.
- Native link flags must include the built LinuxCNC `lib` path and rpath.
- Common CXX flag helpers must surface helper failures instead of hiding them
  behind process substitution or `read`.
- Temporary probe reports must be cleaned on failure and preserved only after a
  successful report path explicitly opts in.
- Documentation-only build policy edits should still update the guardrail
  checks that enforce the relevant script and artifact ordering.

Current temporary exceptions:

- The smoke parser exists only to exercise the public API and UI around remaining fallback paths; native, source-linked, and wasm smoke coverage now route LinuxCNC RS274 behavior through the LinuxCNC-backed interpreter.
- RTCP pivot behavior is limited to LinuxCNC source-backed switchkins paths; unsupported switchkins types must not fall back to hand-derived geometry.

Both exceptions should shrink over time. New functional behavior should not be added to them unless it is directly copied from, or routed to, LinuxCNC source code.