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.

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.

Efficiency rules:

• Do not add a smoke-only behavior path when the LinuxCNC-backed route already exists; add coverage to the source-backed route instead.
• 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.
• 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.
• When ccache is available and CXX is unset, native and wasm build paths should enable compiler caching automatically rather than requiring a manual wrapper.
• Persistent native, source-link, and wasm-safe CMake probe build 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, and CNC_SIM_WASM_CMAKE_SAFE_PROBE_BUILD_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-wasm-cmake-safe-probe.sh uses persistent build/wasm-cmake-safe-probe and wasm-cmake-safe-probe.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.
• Source-link 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.
• build-wasm.sh must check cmake, emcmake, emcc, and node before the Emscripten configure step.
• build-wasm.sh must build cnc_sim_wasm_runtime_probe before cnc_sim_wasm.
• 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 the Node smoke before the browser smoke.
• The default wasm manifest partition must remain explicitly checked for 25 wasm-safe core sources and 9 blocked sources.
• Manifest source listers must reject malformed lines, absolute source paths, unknown groups, unknown filters, 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.