The Z envelope survives a settings write

The Z soft limit belongs to the driver, not to $20. glowforge_homing.c
owns sys.work_envelope, sys.homed and sys.soft_limits for Z, because Z is
always referenced, to the lens hall edge or to where the lens stands, and
the core knows neither. The core recomputes both masks from the settings
and drops Z when it does: $20 clears the soft-limit mask inside its
setter, and a $13x write clears the homed bit for the axis as well.

z_envelope_test.py drives the null-sink controller over TCP and holds the
rule. It checks that an unreferenced Z is collapsed to where the lens
stands and refuses a move each way, that X and Y stay free so the
reassert is Z's alone, and that neither write frees Z. It restores $132.

The harness runs in the grblHAL repo's CI, next to the laser stream and
lifecycle harnesses.

scripts/bench/README.md

@@ -32,6 +32,7 @@ page's takeover does that; from a host, stop them first.
 | `gate_a_kernel_drills.py` | Kernel laser-safety drills (run on the board with forgectrl stopped so the pulse device is free): `K1` controlled-stop deceleration floor, `K2` resume waypoint honors the locked latch, `K3` a mid-ramp latch unlock never re-arms the FIRE drive. Software witnesses (`cnc/state`, `laser_enable`, `laser_on`, `laser_on_sampled`, interlock bit 3) plus the PSU-connector LASER_ON scope point; K3 refuses to run if HV reports good. |
 | `laser_stream_test.py` | Host-side laser pulse-stream emission harness: runs the native null-sink controller with `GFSINK_DUMP`, drives small laser jobs over TCP, and checks the dumped bytes against the kernel feeder contract (leading power byte, no back-to-back power bytes, FIRE only inside cutting moves, every stream ends FIRE-clear, no FIRE on a stepless gap, no FIRE leak across cycle churn, the rapids after an M5 executed at idle ship dark, and the next job in the same process fires at the level the previous one ended at). Runs in the grblHAL repo's CI. |
 | `laser_lifecycle_test.py` | Host-side operator-armed-window lifecycle harness (null-sink controller): arm once per job with M5/M3 persistence, the M2 close, sender-change re-consent, the disarm grace counting down in Hold, and arm refusal under a blocking cooling verdict. Runs in the grblHAL repo's CI. |
+| `z_envelope_test.py` | Host-side Z envelope harness (null-sink controller): the Z soft limit belongs to the driver, not to `$20`, so the driver re-applies `sys.work_envelope`, `sys.homed` and `sys.soft_limits` for Z from the settings-changed chain. Checks that an unreferenced Z is collapsed to where the lens stands and blocks a move each way, that X and Y stay free, and that neither a `$20` write (the core clears the soft-limit mask in the setter) nor a `$132` write (which un-homes the axis as well) frees Z. Runs in the grblHAL repo's CI. |
 | `live_fire_drills.py` | **LIVE LASER** drills, on the board (the bench page) or from a LAN host (`GF_HOST`): `live_fire_drills.py <drill> [S] [F]` - `witness` (emission witness, lid-IR peaks vs the ambient baseline, HV current, job-based disarm on M2), `hold` (disarm grace in Hold), `faultpos` (armed job refuses a stale origin after an underrun), `ircut` (lid-IR characterization cut at S/F), `pthresh` (laser power-threshold ladder: 13 constant-power rungs from 2 % to 30 % of full on scrap; the lowest rung that marks is the tube's striking threshold and reads directly as the `$35` value - requires `$35` = 0 for the run), `dladder` (density ladder at a chosen base period), `pcurve` (laser performance-curve ladder: one 100 mm line per level at 10 mm/s under M3, the laser off between rungs and a mid-ladder rung repeated at the end; reads `pic/hv_current` and the head thermopile `head/beam_detect_analog` (a scatter detector in the beam path upstream of the final mirror, so it sees the beam, not the material) from sysfs at ~25 Hz on the board, brackets each rung on the controller's Run/Idle states, and reports per rung the current with a clipped-at-1023 flag, the thermopile delta over its laser-off baseline and in-line drift, then the normalized curve, monotonicity, a line fit with its threshold intercept and the repeat-rung drift; JSON record with the raw trace in the bench data directory; rungs follow `laser_power_model`, a comma list overrides; a curve measurement wants `$35` = 0), `dpatch [F] [pitch] [length]` (depth witness for the density dose curve: two rows of small serpentine-filled patches, row A CW at feeds giving relative doses 1.0 to 0.25 of the reference feed, row B at the reference feed at 100/80/60/45/30 % density; the operator matches each row-B patch to the row-A patch of equal depth, which reads the density's light fraction off the material beside the thermopile's prediction; JSON record), `m4feeds [S] [F1] [F2]` (the density time base across feeds: one out-and-back line pair per feed at the same S under M4 density, one armed run; the operator reads within-line evenness and reversal darkness at both feeds - M4's velocity scaling is what holds dose per mm through the accel), `m4corner [S] [F]` (M4 velocity-scaled power into corners: a corner-heavy vector pattern at 30 % under M4 density, one armed run; the operator confirms every commanded segment marks - the floor makes a dropout unreachable - and the drill asserts the arm report, one discharge window and dark after), `m5dark` (the rapids after an M5 ship dark: one 20 mm line at M3 S400, M5, dwell, rapid back, dwell, rapid forward; PASS when the 25 Hz current trace shows one discharge segment and reads dark after the M5 and `laser_on_sampled` never re-lights; the catalog's `laser.m5-rapid-dark` is its port), `flowload` (cooling under laser load, one armed run per invocation, the conf keys it writes put back at the end, the pump never commanded off: `t1` reproduces the flow-check trip with the check on at its defaults and two 30 x 4 mm CW fills at F1500 starting on the press with no dark dwell, and reports the engine's rise/dT verdict beside the 25 Hz trace of both coolant sensors, the current, the digital witness and the heater output in 5 s bins across the window, with the shape at fire start; `t2 <secs> [pct]` runs with the check off and one fill of about `secs` lit seconds at CW or at `pct` density, and reports the lag to each sensor, the rise per raw-second of `hv_current` and what a full 50 s window would add against the 1.6 C margin; `fit` fits rise against dose over every t2 record; JSON records), `expstop` (armed kill on the expected-stop path; needs the panel token - `GF_TOKEN`, or the board's token file) and `ctrlstart` (the separate controller restart after it). Every drill waits for the operator's physical arm press; eye protection, fire watch, extinguisher, and exhaust are mandatory. |
 | `pacing_test.py` | Protocol-loop pacing check (runs on the board, dry motion): idle and parked-in-Hold states are coarse-paced, active motion is tight-paced, and a feed-hold/resume mid-move preserves position with no feeder starve. |
 | `gfbench.py` | Not a tool: the helper the board/host tools share - `HOST`/`LOCAL` from `GF_HOST`, `board(cmd)` (local `sh -c` or ssh), the factory coolant conversion `degc()`, `data_path()` (`FORGETEST_BENCH_DATA` or next to the tool), forgectrl's HTTP API with the panel token, `setting(key)` (from forgectrl, or from `/data/forgefirm.conf` on the board while forgectrl is stopped). |

scripts/bench/z_envelope_test.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Host-side verification that the Z envelope survives a settings write.
+
+The Z soft limit belongs to the driver, not to $20. glowforge_homing.c
+owns sys.work_envelope, sys.homed and sys.soft_limits for Z: Z is always
+referenced, to the lens hall edge or to where the lens stands, and the
+core knows neither. The core recomputes both masks from the settings and
+drops Z when it does, so driver.c re-applies the envelope from the
+settings-changed chain, after the rest of the chain has run.
+
+The core drops Z in two places this harness drives:
+
+  $20  clears sys.soft_limits for every axis in the setter
+  $13x clears sys.homed for the axis as well, when the value changes
+
+Runs the native grblHAL_glowforge binary in null-sink mode (no hardware,
+no root) and drives it over TCP:
+
+  1. the envelope is in force from boot, with $20 off: an unreferenced Z
+     is collapsed to where the lens stands, so a Z move alarms
+  2. it is collapsed, not merely present: a move each way alarms
+  3. it is Z alone: X and Y follow $20 as the core intends, and stay free
+  4. $20=0, soft limits off for every axis, does not free Z
+  5. a $132 write, which un-homes Z and clears the mask in the setter,
+     does not free Z either
+  6. X and Y are still free after both writes
+
+The binary keeps its settings in EEPROM.DAT in the working directory, so
+each run starts from defaults in a temporary directory and leaves
+nothing behind.
+
+Usage: z_envelope_test.py [path-to-binary]
+       (default ./build-native/grblHAL_glowforge)
+"""
+import os
+import re
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+
+BIN = os.path.abspath(sys.argv[1] if len(sys.argv) > 1 else "build-native/grblHAL_glowforge")
+PORT = 2400
+
+ALARM_SOFT_LIMIT = "ALARM:2"
+
+
+def fail(msg):
+    print("FAIL: %s" % msg)
+    sys.exit(1)
+
+
+class Session:
+    """One null-sink controller process with its own settings store."""
+
+    def __init__(self):
+        self.workdir = tempfile.mkdtemp(prefix="z-envelope-")
+        env = dict(os.environ, GF_STATE_DIR=self.workdir, FFLOG_STDERR="1")
+        for key in ("GFSINK", "GF_SWITCH_FILE", "GF_VERDICT_FILE"):
+            env.pop(key, None)
+        self.proc = subprocess.Popen([BIN, "-p", str(PORT)],
+                                     cwd=self.workdir, env=env,
+                                     stdout=subprocess.DEVNULL,
+                                     stderr=subprocess.PIPE)
+        self.sock = self.connect()
+        self.read(1.0)                  # banner and any boot messages
+
+    def connect(self):
+        for _ in range(50):
+            try:
+                return socket.create_connection(("127.0.0.1", PORT), timeout=1)
+            except OSError:
+                time.sleep(0.1)
+        err = b""
+        if self.proc.poll() is not None:
+            err = self.proc.stderr.read() or b""
+        fail("cannot connect to the controller (exit=%s)\n%s"
+             % (self.proc.poll(), err.decode(errors="replace")))
+
+    def read(self, timeout=0.8):
+        out = b""
+        end = time.time() + timeout
+        while time.time() < end:
+            self.sock.settimeout(max(0.05, end - time.time()))
+            try:
+                data = self.sock.recv(4096)
+            except (socket.timeout, OSError):
+                break
+            if not data:
+                break
+            out += data
+        return out.decode(errors="replace")
+
+    def send(self, line, timeout=1.0):
+        self.sock.sendall(b"?" if line == "?" else (line + "\n").encode())
+        return self.read(timeout)
+
+    def setting(self, key):
+        reply = self.send(key)
+        m = re.search(r"^%s=(\S+)" % re.escape(key), reply, re.M)
+        if not m:
+            fail("no value reported for %s: %r" % (key, reply))
+        return m.group(1)
+
+    def write_setting(self, assignment):
+        reply = self.send(assignment)
+        if "ok" not in reply:
+            fail("settings write %r refused: %r" % (assignment, reply))
+
+    def state(self):
+        m = re.search(r"<(\w+)", self.send("?"))
+        return m.group(1) if m else "?"
+
+    def move(self, gcode):
+        """Run one move. Returns True when the soft limit blocked it.
+        An alarm needs a reset and an unlock before the next move."""
+        reply = self.send(gcode, 1.5)
+        if ALARM_SOFT_LIMIT in reply:
+            self.recover()
+            return True
+        if "ok" not in reply:
+            fail("unexpected reply to %r: %r" % (gcode, reply))
+        return False
+
+    def recover(self):
+        self.sock.sendall(b"\x18")
+        self.read(1.0)
+        self.send("$X")
+        if self.state() != "Idle":
+            fail("controller did not return to Idle after an alarm")
+
+    def close(self):
+        try:
+            self.sock.close()
+        except OSError:
+            pass
+        self.proc.terminate()
+        try:
+            self.proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            self.proc.kill()
+        shutil.rmtree(self.workdir, ignore_errors=True)
+
+
+def check(ok, ok_msg, fail_msg):
+    if not ok:
+        fail(fail_msg)
+    print("ok   %s" % ok_msg)
+
+
+def blocked_both_ways(s, when):
+    check(s.move("G0 Z1"), "Z+ blocked %s" % when, "a Z+ move ran %s" % when)
+    check(s.move("G0 Z-1"), "Z- blocked %s" % when, "a Z- move ran %s" % when)
+
+
+def free_in_xy(s, when):
+    ran = not s.move("G0 X1") and not s.move("G0 Y1")
+    check(ran, "X and Y free %s" % when, "an X or Y move was blocked %s" % when)
+
+
+def main():
+    if not os.path.isfile(BIN):
+        fail("no controller binary at %s" % BIN)
+    s = Session()
+    try:
+        soft = s.setting("$20")
+        check(soft == "0", "$20=0 at boot, so the Z envelope is the driver's alone",
+              "$20 is %s, not 0: this harness needs the default" % soft)
+
+        blocked_both_ways(s, "at boot")
+        free_in_xy(s, "at boot")
+
+        # $20 clears sys.soft_limits for every axis inside the setter.
+        s.write_setting("$20=0")
+        blocked_both_ways(s, "after a $20 write")
+
+        # $13x clears sys.homed for the axis too, but only when the value
+        # changes, so move it and put it back. Both writes drop Z.
+        z_travel = s.setting("$132")
+        s.write_setting("$132=%.3f" % (float(z_travel) + 1.0))
+        blocked_both_ways(s, "after a $132 write")
+        s.write_setting("$132=%s" % z_travel)
+        blocked_both_ways(s, "after $132 is restored")
+        check(s.setting("$132") == z_travel, "$132 restored to %s" % z_travel,
+              "$132 did not go back to %s" % z_travel)
+
+        free_in_xy(s, "after the settings writes")
+    finally:
+        s.close()
+    print("PASS z_envelope_test")
+
+
+if __name__ == "__main__":
+    main()