HAL/UI/full-process standalone/browser boundary design and next plan

Generated: 2026-06-10 CST

This plan follows `text3.txt`. The `configs/sim` inventory/matrix work is now
complete for the current definition. This file defines the next boundary before
any previously blocked HAL/UI/full-process family is promoted into standalone,
Node, or browser execution.

Goal

- Preserve LinuxCNC as the CNC semantic source of truth.
- Make HAL/UI/full-process dependencies machine-readable before attempting
  execution.
- Promote only the subpaths that can run through vendored LinuxCNC source plus
  explicit standalone runtime adapters.
- Keep task, HAL process launch, UI driver process launch, linuxcncrsh, Python
  remap, and tool-database process behavior blocked until each has a deliberate
  LinuxCNC-owned runtime boundary.

Non-goals

- Do not implement HAL, task, linuxcncrsh, GUI, Python remap, or tool-database
  semantics in JavaScript.
- Do not make blocked `configs/sim` programs pass by editing upstream G-code,
  changing SDK behavior, or adding project-owned interpreter semantics.
- Do not treat native LinuxCNC GUI code as implementation code for the browser
  UI.

Current implementation added by this batch

1. SDK runtime-boundary classifier

   Added:

   ```text
   wasm-port/runtime/sdk/src/sim-config-staging.js
   analyzeIniRuntimeBoundaries()
   ```

   Exported through:

   ```text
   wasm-port/runtime/sdk/src/index.js
   ```

   The classifier reads INI text, manifest text, source-root metadata, and
   optional execution text. It reports:

   - declared `HAL` process inputs: `HALFILE`, `HALCMD`, `POSTGUI_HALFILE`,
     `HALUI`;
   - declared UI process inputs: `DISPLAY`, `PYVCP`, `GLADEVCP`,
     `EMBED_TAB_COMMAND`;
   - `HALUI` MDI command dependencies;
   - `[EMCIO]DB_PROGRAM` tool-database process dependencies;
   - Python references in UI, DB, `[PYTHON]`, or Python remap declarations;
   - `[RS274NGC]USER_M_PATH` plus whether the current execution text calls
     unstaged external `M100..M199` process codes.

   It returns a policy recommendation for hard Layer 4 blocks:

   - `L4-TOOL-DB` when `[EMCIO]DB_PROGRAM` is present;
   - `L4-USER-M-PROCESS` when the current execution chain calls unstaged
     external user-M process codes;
   - `L4-PYTHON-REMAP` for Python remap runtime declarations;
   - `-` when the dependency is only a declared process dependency already
     represented by a narrower standalone adapter or class representative.

   This is policy/accounting only. It does not execute or emulate HAL, task,
   UI, Python, user-M, or tool-database behavior.

2. Node coverage for the classifier

   Updated:

   ```text
   wasm-port/tests/wasm/node/verify_sim_configs_wasm.mjs
   ```

   Covered cases:

   - synthetic INI with vendored `M123` user-M file remains unblocked;
   - `axis/db_demo/db_nonran.ini` reports `L4-TOOL-DB`;
   - `axis/vismach/millturn/millturn.ini` plus its remap execution chain
     reports `L4-USER-M-PROCESS` because `M428/M429` call unstaged `M128/M129`;
   - `axis/vismach/puma/puma_cube.ini` declares HAL/UI/HALUI process
     dependencies but remains unblocked for the current representative program
     because the promoted execution path does not call unstaged external
     user-M process codes;
   - `axis/gladevcp/gladevcp_panel.ini` declares UI/Python UI process
     dependencies but remains unblocked for the current `probe.ngc`
     representative.

3. Inventory policy guard

   Updated:

   ```text
   wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.mjs
   ```

   The Node inventory now checks vendored INI rows against
   `analyzeIniRuntimeBoundaries()` before execution/skipping:

   - `L4-TOOL-DB` rows must declare `DB_PROGRAM`;
   - `L4-USER-M-PROCESS` rows must be backed by an execution chain that calls
     unstaged external user-M process codes;
   - generated/tracked blocked policy drift fails the inventory.

Boundary model

Layer A: declaration classification

- Input: INI text, manifest text, optional execution text.
- Output: dependency list and recommended blocked kind.
- Owner: SDK host-boundary code.
- Validation: Node unit/smoke assertions and Node inventory policy checks.

Layer B: standalone adapter execution

- Allowed only when a narrow runtime edge already exists and CNC behavior still
  comes from vendored LinuxCNC source.
- Current examples:
  - HAL named-parameter lookup and switchkins M68/M66 synchronization through
    the standalone HAL adapter;
  - deterministic `USER_M_COMMAND` canonical events for already vendored
    M110/M111-style user-M registration;
  - five-axis remap execution through vendored LinuxCNC remap/O-word paths;
  - OPFS/file/parameter/tool-table persistence as host storage boundaries.

Layer C: browser/UI representation

- Browser UI may present standalone simulation state and user controls.
- Browser UI must not execute native LinuxCNC GUI code.
- Browser UI must call SDK/WASM boundaries that are already validated in Node
  or native probes.
- Full LinuxCNC GUI actions remain blocked unless expressed as a deliberate
  standalone command boundary with LinuxCNC-owned behavior underneath.

Layer D: full-process blocked boundary

Keep blocked until explicitly designed:

- LinuxCNC task process lifecycle;
- HAL process/module loading and realtime scheduling;
- HALUI/linuxcncrsh command queues;
- external userspace components;
- native GUI driver processes;
- Python remap/prolog/epilog runtime;
- tool database process startup and protocol/state behavior.

Immediate next implementation batches

Batch 1: make boundary reports durable

- Add a generated machine-readable boundary artifact:

  ```text
  wasm-port/build/wasm/sim-configs-inventory/boundary-summary.tsv
  ```

- Minimum fields:

  ```text
  path
  ini
  blocked
  recommended_blocked
  dependencies
  user_m_execution_codes
  user_m_vendored_count
  db_program
  hal_process
  ui_process
  halui_mdi_process
  python_process
  ```

- The existing Node inventory should fail if `blocked` and
  `recommended_blocked` conflict for hard blocks.

Batch 2: promote only safe HAL/UI representatives

- Keep `axis/gladevcp/probe.ngc`, `woodpecker/on_abort.ngc`,
  `axis/vismach/puma/puma_cube.ngc`, and `axis/vismach/melfa-sim/example.ngc`
  as representative file-execution paths.
- Add browser assertions that these programs remain file/remap execution
  representatives and do not claim full UI/HAL process coverage.
- Do not promote `axis/vismach/millturn/example.ngc` until the user-M process
  boundary is designed, because the remap chain calls M128/M129.

Batch 3: design external user-M process boundary

- Start with `axis/vismach/millturn` because it is the smallest current hard
  blocked row with vendored INI and program context.
- Required design questions:
  - Which LinuxCNC source owns M128/M129 behavior in the native config?
  - Is the behavior expressible as a LinuxCNC-owned deterministic adapter
    boundary, or does it require spawning external process scripts?
  - What canonical/state output proves behavior without adding JS CNC
    semantics?
- Do not mark `millturn` unblocked until native, Node, and browser checks can
  prove the boundary.

Batch 4: design tool DB boundary

- Start with `axis/db_demo/db_nonran.ini`.
- Required design questions:
  - Which LinuxCNC source owns `DB_PROGRAM` startup/protocol semantics?
  - Can a standalone tool database adapter call vendored LinuxCNC tooldata
    source without reimplementing database behavior?
  - What fixture demonstrates tool lookup/update behavior across native and
    WASM?
- Keep `axis/db_demo/base.ngc` as `L4-TOOL-DB` until this exists.

Batch 5: Python remap/full-process family plan

- Do not vendor or execute `gmoccapy`, `axis/laser`, or TWP nutating Layer 4
  paths until Python remap runtime ownership is designed.
- First artifact should be a dependency inventory, not execution:
  - Python modules referenced by INI/remap;
  - prolog/epilog functions;
  - HAL/task/UI assumptions;
  - NGC-only subpaths, if any, that can be separated safely.

Validation gates

Run after each batch:

```bash
wasm-port/tests/wasm/node/verify_sim_configs_wasm.sh
wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
wasm-port/tests/browser/verify_interp_browser.sh
wasm-port/tests/host/verify_host_smokes.sh
wasm-port/tools/verify_vendor_sync.sh
wasm-port/tools/verify_no_standalone_cnc_semantics.sh
```

Completion criteria for this boundary phase

- Every vendored sim-config INI used by Node inventory has a machine-readable
  runtime-boundary report.
- Hard blocked rows have a dependency-backed reason rather than path-only
  classification.
- Safe representatives can declare HAL/UI process dependencies without being
  mislabeled as full-process coverage.
- No blocked family is promoted until a LinuxCNC-owned runtime boundary exists
  and is validated native, Node, and browser where appropriate.
