每轮只推进合理适量的上下文、禁止顺手扩功能 smoke：源码链接构建约束

docs/linuxcnc-source-policy.md

@@ -44,30 +44,170 @@ Required workflow for every functional change:
    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.
+- 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, 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 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 checker and generator scripts, the kinematics manifest, referenced
+  LinuxCNC source size and nanosecond mtime stats, and tracked generated
+  table/case outputs.
+- 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.
-- 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.
+- 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`, and
-  `CNC_SIM_WASM_CMAKE_SAFE_PROBE_BUILD_DIR`. Build directory overrides must
-  stay non-empty, whitespace-free, and outside the filesystem root.
+  `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.
@@ -82,23 +222,61 @@ Build and source-link guardrails:
 - `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`.
+  `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.
-- Source-link and syntax probes must build from generated makefiles with
-  `-MMD -MP` dependency tracking and `make --output-sync=target`.
+- `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`.
+  `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