From 1efbfecb7f30df659e6d7a2f5f429f2f219a9670 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 6 Sep 2026 23:27:10 +0000
Subject: [PATCH 01/39] tools: observer_gate_diff.sh normalises the exe-dir and
 the out-of-tree import-shadow warning before diffing (#1115)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Repro (byte-identical trees, binaries at two paths; captures via
EIGS_GATE_DIFF_DIR=$S/caps):
  EIGS_GATE_DIFF_BIN=/home/user/EigenScript/src/eigenscript capture base ; capture base2
  EIGS_GATE_DIFF_BIN=$WT/src/eigenscript capture wt
  EIGS_OBS_FORCE=1 EIGS_GATE_DIFF_BIN=$WT/src/eigenscript capture wtf

Before (tool at a6c50fb):
  compare base wt  -> "FAIL: SAME binary AND the same EIGS_OBS_FORCE" rc=2
                      (same sha at two paths was refused outright)
  compare base wtf -> mismatches: 9, RESULT: FAIL rc=1 — 7 of them are
                      location: 5 x "stdlib roots '<exe-dir>/../<path>'" in
                      cannot-read errors (lib/test_runner, tests/test_import,
                      test_import_errors, test_import_toplevel_scope,
                      test_module_scope) and 2 x the project-vs-stdlib
                      import-shadow warning that fires only out of tree
                      (lib/engineering, lib/linalg importing complex).
After:
  compare base wt  -> location-only differences: 7 (named), residual
                      mismatches: 0, RESULT: LOCATION-CLEAN rc=0
  compare base wtf -> location-only: 7, residual mismatches: 2
                      (test_chunk_verify_stack, test_desc_unrecorded_read —
                      genuine force-arm divergences, untouched), rc=1

What changed in compare:
- each arm's capture is normalised with that arm's own exe-dir (dirname of
  the manifest's realpath'd bin): the exe-dir string -> <EXE_DIR>, and the
  import-shadow warning is dropped ONLY in the exact shape "using
  '<corpus>/lib/N.eigs', shadowing '<arm-tree>/lib/N.eigs'" (same N).
  Nothing else is touched; an arm whose exe-dir is '/', '.', '' or relative
  compares raw, announced by NOTE.
- arm identity is (sha, force, path): same build at the SAME path is still
  refused; same build at two paths is admitted with the verdict word
  LOCATION-CLEAN (never PASS) because it measures location-independence,
  not the gate. The determinism reference must match base on all three.
- `location-only differences ... : K` lists every absorbed program by name
  with its first raw diff line; `residual mismatches: M` is what RESULT
  gates on.
- `selftest` subcommand (9 cases) drives the real `compare` entry point over
  synthetic captures: both location shapes absorbed; a different error
  message, a differently-named shadow, a project-file shadow, a corpus-path
  difference and the root-exe-dir guard each still FAIL; the two provenance
  refusals still fire; different builds still PASS.
- slug() is pure bash (same output): the selftest went 12.6s -> 4.6s.

Regression test: suite section [99q] runs the selftest and pins the tally
"9 ok, 0 failed (of 9)". Planted fault (normaliser made identity): case 1
fails, [99q] goes red, and `compare base wt` reports residual mismatches: 7.

Residuals (documented in the tool header): $HOME in the same error line, the
corpus tree's own path, and the argv[0] fallback on platforms without
/proc/self/exe are deliberately NOT normalised.

Closes #1115

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 tests/run_all_tests.sh      |  29 +++
 tools/observer_gate_diff.sh | 394 ++++++++++++++++++++++++++++++++++--
 2 files changed, 402 insertions(+), 21 deletions(-)

diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index f1f154a3..8e6d6ff3 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -6293,6 +6293,35 @@ else
 fi
 echo ""
 
+# [99q] Observer-gate corpus diff: location normalisation self-test (#1115).
+# tools/observer_gate_diff.sh compares full-corpus captures byte-for-byte, and
+# an out-of-tree baseline binary echoes its own exe-dir into two shapes of
+# text (the stdlib-roots list in every "cannot read" error, and the project-
+# vs-stdlib import-shadow warning that fires only out of tree). Seven programs
+# mismatched on exactly those shapes across three critic rounds on #1038 and a
+# clean run read as a regression. The tool now canonicalises ONLY those two
+# shapes; this self-test drives the real `compare` entry point over synthetic
+# captures (no corpus run) and pins that (1) both shapes are absorbed and named,
+# (2) a different error message, a differently-named shadow, a project-file
+# shadow, a corpus-path difference and the root-exe-dir guard each still FAIL,
+# (3) the same-build-same-path and path-mismatched-reference refusals still
+# fire, (4) genuinely different builds still get PASS. The case count is
+# pinned (mechanical-gates §37): a self-test shrunk to one case also exits 0.
+echo "[99q] Observer-gate corpus diff location normalisation (#1115)"
+TOTAL=$((TOTAL + 1))
+OGD_EXPECTED=9
+OGD_OUT=$(bash "$TESTS_DIR/../tools/observer_gate_diff.sh" selftest 2>&1); OGD_RC=$?
+OGD_TALLY=$(printf '%s\n' "$OGD_OUT" | sed -n 's/^SELFTEST: \([0-9]*\) ok, \([0-9]*\) failed (of \([0-9]*\))$/\1 \2 \3/p')
+if [ "$OGD_RC" -eq 0 ] && [ "$OGD_TALLY" = "$OGD_EXPECTED 0 $OGD_EXPECTED" ]; then
+    PASS=$((PASS + 1))
+    echo "  PASS: exe-dir + import-shadow normalisation absorbs only the location shapes ($OGD_EXPECTED/$OGD_EXPECTED self-test cases)"
+else
+    FAIL=$((FAIL + 1))
+    echo "  FAIL: observer_gate_diff.sh self-test broke or shrank (rc=$OGD_RC, tally='${OGD_TALLY:-none}', expected '$OGD_EXPECTED 0 $OGD_EXPECTED')"
+    printf '%s\n' "$OGD_OUT" | grep -E '^  FAIL|^SELFTEST|^FAIL' | head -8 | sed 's/^/      /'
+fi
+echo ""
+
 # [99m] Lint archive symbol-collision gate (#917, hole closed by #922).
 # The #917 split turned lint's json_escape helper into an external symbol and
 # broke the static-library route for any embedder with its own json_escape.
diff --git a/tools/observer_gate_diff.sh b/tools/observer_gate_diff.sh
index 5c053b95..8f755976 100755
--- a/tools/observer_gate_diff.sh
+++ b/tools/observer_gate_diff.sh
@@ -40,9 +40,68 @@
 # That arm runs the code that shipped before the gate existed, which is the
 # question a user actually has.
 #
+# LOCATION NORMALISATION (#1115) — what `compare` canonicalises, and only that.
+#
+# An out-of-tree baseline (the flow above) runs a binary whose executable
+# directory is NOT this checkout's src/, and the runtime echoes that directory
+# into two pieces of text:
+#   1. `eigs_file_resolve_error` (src/builtins_host.c) prints the stdlib roots
+#      it tried as '<exe-dir>/../<path>' and '<exe-dir>/../lib/eigenscript' —
+#      so every "cannot read" error line carries the arm's own exe-dir.
+#   2. The project-vs-stdlib import-shadow warning (src/vm.c, `import`) fires
+#      only when the project hit and the stdlib hit are DIFFERENT files. In
+#      tree, `lib/engineering.eigs` importing `complex` resolves both to this
+#      checkout's lib/complex.eigs and stays silent; out of tree the stdlib arm
+#      is <arm-tree>/lib/complex.eigs, a different inode with the same bytes,
+#      and the warning fires — in that arm only.
+# Bought (#1038, both blind critics, three rounds): 7 programs mismatched on
+# exactly these two shapes and a clean run read as a 7-program regression.
+#
+# Before diffing, each arm's capture is passed through ONE normaliser driven by
+# that arm's .MANIFEST (`bin=` is the binary's realpath; its dirname is the
+# exe-dir the runtime echoes, because /proc/self/exe resolves the same way):
+#   - every occurrence of the arm's exe-dir string becomes `<EXE_DIR>`;
+#   - a warning line of the EXACT shape
+#       Warning: import 'N' ... using '<corpus-tree>/lib/N.eigs', shadowing
+#       '<arm-tree>/lib/N.eigs' (project-first; ...)
+#     — this checkout's own copy of stdlib module N shadowing the arm's copy of
+#     the SAME module — is dropped. Any other collision (a different module in
+#     the two paths, a project file outside lib/, a shadowed path not under the
+#     arm's tree) is left in place and mismatches.
+# Nothing else is touched. Programs whose ONLY difference is one of those two
+# shapes are reported by name as `location-only`, and `residual mismatches`
+# (the count the RESULT gates on) is what is left after normalisation. The
+# normaliser is switched OFF for an arm whose manifest exe-dir is not an
+# absolute path with at least one component ('/', '.', '' would rewrite every
+# line) — announced on the provenance line, and the arm then compares raw.
+#
+# Residuals — what compare still CANNOT canonicalise across (each is a real
+# axis, not a location artifact, so it deliberately stays a mismatch):
+#   - $HOME: the same error line prints '$HOME/.local/lib/eigenscript', and a
+#     different HOME can genuinely change resolution (an installed stdlib
+#     there wins some lookups). Capture both arms under one HOME.
+#   - the corpus tree's own path: 'tried containing directory <checkout>/…'
+#     names THIS checkout, so captures must come from one checkout (`capture`
+#     always cds here, so this holds unless a capture dir is copied between
+#     checkouts).
+#   - an argv[0] fallback: without /proc/self/exe the runtime echoes the
+#     UNRESOLVED argv[0] directory; the manifest records the realpath. A
+#     symlinked binary on such a platform escapes normalisation — loudly, as a
+#     mismatch, never silently.
+#   - two arms of the SAME build (same sha, same force) at different paths are
+#     accepted, but the verdict is `RESULT: LOCATION-CLEAN`, never PASS: that
+#     run proves the captures are location-independent, not that a gate did
+#     anything. Same build, same force AND same path is still refused.
+# `selftest` (below) plants each of these shapes into synthetic captures and
+# drives the real `compare` entry point: the location-only shapes must be
+# absorbed, and a genuinely different error message, a differently-named
+# shadow, a project-file shadow, a corpus-path difference, and the
+# root-exe-dir guard must each still FAIL.
+#
 # Usage:
 #   tools/observer_gate_diff.sh capture <label>      # run corpus with $EIGS_GATE_DIFF_BIN
 #   tools/observer_gate_diff.sh compare <base> <gated>
+#   tools/observer_gate_diff.sh selftest             # synthetic captures, no corpus run (~5s)
 #
 # Typical run:
 #   make                                    # baseline build
@@ -63,6 +122,9 @@ set -u
 
 REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$REPO" || exit 2
+# The runtime realpath()s the paths it prints in the import-shadow warning, so
+# the corpus tree must be matched in resolved form too.
+REPO_REAL="$(pwd -P)"
 
 CAPROOT="${EIGS_GATE_DIFF_DIR:-$REPO/.observer_gate_captures}"
 TIMEOUT="${EIGS_GATE_DIFF_TIMEOUT:-25}"
@@ -106,7 +168,10 @@ is_denied() {
 
 corpus() { git ls-files '*.eigs' | sort; }
 
-slug() { echo "$1" | tr '/.' '__'; }
+# Pure bash: this runs once per corpus entry per compare (520 x 9 in the
+# selftest); with a `tr` subprocess each time the selftest took 12.6s, pure
+# bash 4.6s (#1115). Same output: `/` and `.` both become `_`.
+slug() { local s="${1//\//_}"; echo "${s//./_}"; }
 
 # Every capture records WHICH BINARY produced it. Without this the determinism
 # reference is a silent laundering channel: `compare <base> <gated>` uses
@@ -144,6 +209,66 @@ capture_manifest() {
 }
 manifest_field() { sed -n "s/^$2=//p" "$1/.MANIFEST" 2>/dev/null; }
 
+# The exe-dir the runtime echoed for this arm: dirname of the manifest's
+# realpath'd binary. /proc/self/exe resolves symlinks the same way realpath
+# does, and `src/eigenscript` is a HARD link, so the two agree byte-for-byte.
+arm_exe_dir() {
+    local bin; bin="$(manifest_field "$1" bin)"
+    case "$bin" in
+        */*) echo "${bin%/*}" ;;
+        *)   echo "" ;;
+    esac
+}
+
+# Is this exe-dir safe to rewrite? An absolute path with at least one
+# component. '/', '.', '' or a relative dir would match inside every line.
+exe_dir_usable() {
+    case "$1" in
+        ""|/|.|./*|../*) return 1 ;;
+        /*) return 0 ;;
+        *)  return 1 ;;
+    esac
+}
+
+# Normalise ONE capture file of ONE arm to stdout (see the header). $1 = the
+# arm's exe-dir ("" disables both rules), $2 = the file. Portable awk only
+# (mawk / BSD awk: no gensub, no 3-arg match) — literal index/substr
+# replacement, no regex built from a path.
+normalise_capture() {
+    local exe="$1" file="$2"
+    if ! exe_dir_usable "$exe"; then cat "$file"; return; fi
+    local tree="${exe%/*}"
+    awk -v exe="$exe" -v tree="$tree" -v repo="$REPO_REAL" \
+        -v w_pre="Warning: import " \
+        -v w_mid=" matches both a project file and a stdlib module — using " \
+        -v w_sep=", shadowing " \
+        -v w_tail=" (project-first; rename the file to use the stdlib module)" '
+    function replace_all(s, from, to,    out, i) {
+        out = ""
+        while ((i = index(s, from)) > 0) {
+            out = out substr(s, 1, i - 1) to
+            s = substr(s, i + length(from))
+        }
+        return out s
+    }
+    {
+        line = $0
+        # Rule 2: the location-induced import-shadow warning, exact shape only.
+        # Split on the single quotes: 7 fields for the 3 quoted operands.
+        if (index(line, w_pre) == 1) {
+            n = split(line, f, "\047")
+            if (n == 7 && f[1] == w_pre && f[3] == w_mid && f[5] == w_sep && f[7] == w_tail) {
+                name = f[2]; used = f[4]; shadowed = f[6]
+                if (name != "" && used == repo "/lib/" name ".eigs" &&
+                    shadowed == tree "/lib/" name ".eigs" && used != shadowed)
+                    next
+            }
+        }
+        # Rule 1: the exe-dir string itself, wherever the runtime echoed it.
+        print replace_all(line, exe, "<EXE_DIR>")
+    }' "$file"
+}
+
 do_capture() {
     local label="$1"
     [ -x "$BIN" ] || { echo "FAIL: $BIN is not executable — run make first"; exit 2; }
@@ -184,31 +309,55 @@ do_compare() {
     local frc_a frc_b frc_ref
     frc_a=$(manifest_field "$da" force); frc_b=$(manifest_field "$db" force)
     frc_ref=$(manifest_field "$dref" force)
+    local bin_a bin_b bin_ref exe_a exe_b
+    bin_a=$(manifest_field "$da" bin); bin_b=$(manifest_field "$db" bin)
+    bin_ref=$(manifest_field "$dref" bin)
+    exe_a=$(arm_exe_dir "$da"); exe_b=$(arm_exe_dir "$db")
     echo "provenance: base=${sha_a:0:12}(force=${frc_a:-?}) ref=${sha_ref:0:12}(force=${frc_ref:-?}) gated=${sha_b:0:12}(force=${frc_b:-?})"
+    echo "exe-dir: base=${exe_a:-?} gated=${exe_b:-?}"
+    # #1115: an arm whose exe-dir cannot be rewritten safely compares RAW.
+    # Said out loud (mechanical-gates §11) rather than silently degraded.
+    local norm_a="$exe_a" norm_b="$exe_b"
+    if ! exe_dir_usable "$exe_a"; then norm_a=""; echo "NOTE: base exe-dir '${exe_a}' is not normalisable — base arm compares raw"; fi
+    if ! exe_dir_usable "$exe_b"; then norm_b=""; echo "NOTE: gated exe-dir '${exe_b}' is not normalisable — gated arm compares raw"; fi
     # The second half of the claim, now actually implemented: the two arms must
-    # DIFFER in something. Same binary AND same gate setting means the run is
-    # diffing a build against itself, and PASS carries no information.
-    if [ "$sha_a" = "$sha_b" ] && [ "${frc_a:-0}" = "${frc_b:-0}" ]; then
+    # DIFFER in something. Same binary AND same gate setting AND same path means
+    # the run is diffing a build against itself, and PASS carries no
+    # information. Same binary at a DIFFERENT path is admitted (#1115) — that
+    # run is the location-independence check and gets its own verdict word
+    # below, never PASS.
+    if [ "$sha_a" = "$sha_b" ] && [ "${frc_a:-0}" = "${frc_b:-0}" ] && [ "$bin_a" = "$bin_b" ]; then
         echo "FAIL: '$a' and '$b' used the SAME binary AND the same EIGS_OBS_FORCE setting."
         echo "      Nothing distinguishes the arms; this would pass trivially."
         exit 2
     fi
-    # An arm's identity is (sha, force) — BOTH axes, for the reference too. This
-    # guard ranged over sha alone: capturing '<base>2' with the force flag off
-    # while '<base>' had it on made the two arms of the SAME binary disagree on
-    # three programs, which the filter then excluded as nondeterministic.
-    # Executed on a build with `case OP_REPORT_NAME:` deleted from
-    # opcode_is_observer_reader(): honest run reports `mismatches: 3` / rc=1,
-    # the reference-swapped run reports `nondet:` x3, `compared: 413`,
+    local same_build=0
+    if [ "$sha_a" = "$sha_b" ] && [ "${frc_a:-0}" = "${frc_b:-0}" ]; then
+        same_build=1
+        echo "NOTE: '$a' and '$b' are the SAME build (same sha, same force) at two paths:"
+        echo "      this run measures location-independence of the captures, not the gate."
+    fi
+    # An arm's identity is (sha, force, path) — every axis, for the reference
+    # too. This guard ranged over sha alone: capturing '<base>2' with the force
+    # flag off while '<base>' had it on made the two arms of the SAME binary
+    # disagree on three programs, which the filter then excluded as
+    # nondeterministic. Executed on a build with `case OP_REPORT_NAME:` deleted
+    # from opcode_is_observer_reader(): honest run reports `mismatches: 3` /
+    # rc=1, the reference-swapped run reports `nondet:` x3, `compared: 413`,
     # `RESULT: PASS`, rc=0 — 413 is far above the 380 floor, so nothing fired.
     # mechanical-gates §61: the guard was repaired on the narrower axis (sha, on
     # 2026-08-22) and left open on the other; §45: the bypass is a superset of
     # the population, so the count barely moves while what it counts is gone.
-    if [ "$sha_a" != "$sha_ref" ] || [ "${frc_a:-0}" != "${frc_ref:-0}" ]; then
+    # The path axis (#1115): the self-diff runs RAW, so a reference captured
+    # from the same build at another path would exclude every program that
+    # echoes the exe-dir as "nondeterministic" — the same laundering, one axis
+    # over.
+    if [ "$sha_a" != "$sha_ref" ] || [ "${frc_a:-0}" != "${frc_ref:-0}" ] || [ "$bin_a" != "$bin_ref" ]; then
         echo "FAIL: '$a' and '${a}2' were captured with DIFFERENT arms."
-        echo "      base=${sha_a:0:12}(force=${frc_a:-?})  ref=${sha_ref:0:12}(force=${frc_ref:-?})"
-        echo "      The determinism reference must match the baseline on BOTH the"
-        echo "      binary and the gate setting, or every real divergence is excluded"
+        echo "      base=${sha_a:0:12}(force=${frc_a:-?}) at ${bin_a:-?}"
+        echo "      ref =${sha_ref:0:12}(force=${frc_ref:-?}) at ${bin_ref:-?}"
+        echo "      The determinism reference must match the baseline on the binary,"
+        echo "      the gate setting AND the path, or every real divergence is excluded"
         echo "      as nondeterminism and this run reports PASS."
         exit 2
     fi
@@ -218,8 +367,8 @@ do_compare() {
     # definitions + 5 fuzz corpus files), i.e. 16% of the headline. Reported
     # rather than hidden: a number that is 16% vacuous should say so (§1/§43).
     local total=0 nondet=0 compared=0 mismatch=0 informative=0 silent=0
-    local onesided=0
-    local -a NONDET=() MISMATCH=() ONESIDED=()
+    local onesided=0 loconly=0
+    local -a NONDET=() MISMATCH=() ONESIDED=() LOCONLY=()
     while IFS= read -r f; do
         is_denied "$f" && continue
         local s; s="$(slug "$f")"
@@ -258,7 +407,15 @@ do_compare() {
             silent=$((silent+1))
         fi
         if ! cmp -s "$da/$s" "$db/$s"; then
-            mismatch=$((mismatch+1)); MISMATCH+=("$f")
+            # Raw bytes differ. Location-only if the normalised texts agree
+            # (#1115); residual otherwise. Both arms go through the SAME
+            # normaliser, each with its own exe-dir.
+            if cmp -s <(normalise_capture "$norm_a" "$da/$s") \
+                      <(normalise_capture "$norm_b" "$db/$s"); then
+                loconly=$((loconly+1)); LOCONLY+=("$f")
+            else
+                mismatch=$((mismatch+1)); MISMATCH+=("$f")
+            fi
         fi
     done < <(corpus)
 
@@ -272,10 +429,19 @@ do_compare() {
         exit 2
     fi
     echo "compared: $compared (informative: $informative, silent: $silent)"
-    echo "mismatches: $mismatch"
+    # Every program the normaliser absorbed is named, with the first raw
+    # difference, so a reader can see WHAT was canonicalised — a silently
+    # absorbed diff is the laundering this tool exists to refuse.
+    echo "location-only differences (normalised away: exe-dir, import-shadow): $loconly"
+    for f in "${LOCONLY[@]+"${LOCONLY[@]}"}"; do
+        echo "    location-only: $f"
+        diff "$da/$(slug "$f")" "$db/$(slug "$f")" | grep '^[<>]' | head -2 | cut -c1-160 | sed 's/^/        /'
+    done
+    echo "residual mismatches: $mismatch"
     for f in "${MISMATCH[@]+"${MISMATCH[@]}"}"; do
         echo "--- MISMATCH: $f"
-        diff "$da/$(slug "$f")" "$db/$(slug "$f")" | head -15 | sed 's/^/        /'
+        diff <(normalise_capture "$norm_a" "$da/$(slug "$f")") \
+             <(normalise_capture "$norm_b" "$db/$(slug "$f")") | head -15 | sed 's/^/        /'
     done
 
     # ABSOLUTE population floor, not just a ratio. The ratio below divides
@@ -318,6 +484,14 @@ do_compare() {
         echo "RESULT: FAIL — the gate changed observable behaviour on $mismatch program(s)"
         exit 1
     fi
+    if [ "$same_build" -eq 1 ]; then
+        # Deliberately NOT the word PASS: nothing about the gate was measured.
+        echo "RESULT: LOCATION-CLEAN — $compared programs byte-identical modulo exe-dir"
+        echo "NOTE: both arms are the SAME build at two paths. This proves the captures are"
+        echo "      location-independent (the #1115 normaliser did its job); it says NOTHING"
+        echo "      about the gate. Rebuild the gated arm and compare again for a gate verdict."
+        exit 0
+    fi
     echo "RESULT: PASS — $compared programs byte-identical"
     echo "NOTE: a clean diff is necessary, not sufficient. It proves nothing unless the"
     echo "      gated build actually gated something — check the gate's own elision"
@@ -325,8 +499,186 @@ do_compare() {
     echo "      build (observer disabled outright) before trusting this PASS."
 }
 
+# ---------------------------------------------------------------------------
+# selftest — proves the #1115 normaliser absorbs ONLY the two location shapes,
+# by driving the REAL `compare` entry point (a subprocess of this script, so
+# there is one code path to regress — verify-and-fix: a guard that re-spells
+# the command under test is not a guard). Synthetic capture dirs, three
+# real corpus names, floors lowered to the synthetic population by the same
+# env knobs a user has. No corpus run: ~5s (9 compares x 520 corpus names).
+#
+# Both halves of every control are present (mechanical-gates §15): the shapes
+# that MUST be absorbed (1) and the shapes that MUST still mismatch (2-6), plus
+# the provenance guards that must still refuse (7-8) and the normal PASS
+# verdict for genuinely different builds (9).
+# ---------------------------------------------------------------------------
+st_pass=0; st_fail=0
+st_ok()   { st_pass=$((st_pass+1)); echo "  ok:   $1"; }
+st_bad()  { st_fail=$((st_fail+1)); echo "  FAIL: $1"; printf '%s\n' "$2" | sed 's/^/        /' | head -12; }
+
+# st_arm <dir> <bin> <sha> <force>
+st_arm() {
+    rm -rf "$1"; mkdir -p "$1"
+    printf 'bin=%s\nforce=%s\nsha=%s\nrev=selftest\n' "$2" "$4" "$3" > "$1/.MANIFEST"
+}
+# st_write <dir> <corpus-name> <content...>  (rc line appended, like capture)
+st_write() { local d="$1" f="$2"; shift 2; { printf '%s\n' "$@"; printf 'rc=0\n'; } > "$d/$(slug "$f")"; }
+
+st_compare() {  # prints output; returns compare's rc
+    EIGS_GATE_DIFF_DIR="$ST_ROOT" EIGS_GATE_DIFF_FLOOR=1 EIGS_GATE_DIFF_INFO_FLOOR=1 \
+        bash "${BASH_SOURCE[0]}" compare "$1" "$2"
+}
+
+# The error line the runtime prints, with the exe-dir of the given arm.
+st_err() {  # $1 = exe-dir, $2 = missing file name
+    printf "Error line 5: import: cannot read '%s.eigs and lib/%s.eigs' (not found or unreadable); tried containing directory '%s/tests', eigs_modules walk, no eigs.json above %s/tests; stdlib roots '%s/../<path>', '%s/../lib/eigenscript', '/home/someone/.local/lib/eigenscript' (also stripping lib/; absolute paths are used as-is)" \
+        "$2" "$2" "$REPO_REAL" "$REPO_REAL" "$1" "$1"
+}
+st_shadow() {  # $1 = name, $2 = using path, $3 = shadowed path
+    printf "Warning: import '%s' matches both a project file and a stdlib module — using '%s', shadowing '%s' (project-first; rename the file to use the stdlib module)" "$1" "$2" "$3"
+}
+
+do_selftest() {
+    ST_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/ogd_selftest.XXXXXX")"
+    trap 'rm -rf "${ST_ROOT:-}"' EXIT
+    local -a names=()
+    local f
+    while IFS= read -r f; do
+        is_denied "$f" && continue
+        names+=("$f"); [ "${#names[@]}" -ge 3 ] && break
+    done < <(corpus)
+    if [ "${#names[@]}" -ne 3 ]; then echo "FAIL: selftest needs 3 corpus names, found ${#names[@]}"; exit 2; fi
+    local p1="${names[0]}" p2="${names[1]}" p3="${names[2]}"
+    local A="$ST_ROOT/fakeA/src" B="$ST_ROOT/fakeB/src"   # two exe-dirs, never created
+    local SHA1=1111111111111111111111111111111111111111111111111111111111111111
+    local SHA2=2222222222222222222222222222222222222222222222222222222222222222
+    local out rc
+
+    # Common fixture: base/base2 at A, gated at B, same sha. p1 echoes the
+    # exe-dir; p2 carries the out-of-tree shadow warning in the base arm only
+    # (exactly the two #1038 shapes); p3 is plain identical output.
+    fixture() {  # $1 = gated sha
+        st_arm "$ST_ROOT/base"  "$A/eigenscript" "$SHA1" 0
+        st_arm "$ST_ROOT/base2" "$A/eigenscript" "$SHA1" 0
+        st_arm "$ST_ROOT/gated" "$B/eigenscript" "$1"    0
+        for d in base base2; do
+            st_write "$ST_ROOT/$d" "$p1" "hello" "$(st_err "$A" tmp_mod)"
+            st_write "$ST_ROOT/$d" "$p2" "$(st_shadow complex "$REPO_REAL/lib/complex.eigs" "$ST_ROOT/fakeA/lib/complex.eigs")" "42"
+            st_write "$ST_ROOT/$d" "$p3" "plain"
+        done
+        st_write "$ST_ROOT/gated" "$p1" "hello" "$(st_err "$B" tmp_mod)"
+        st_write "$ST_ROOT/gated" "$p2" "42"
+        st_write "$ST_ROOT/gated" "$p3" "plain"
+    }
+
+    echo "selftest: observer_gate_diff.sh #1115 location normalisation"
+
+    # 1. The two location-only shapes, same build at two paths: absorbed, and
+    #    the verdict is LOCATION-CLEAN (never PASS), rc 0, both programs named.
+    fixture "$SHA1"
+    out=$(st_compare base gated); rc=$?
+    if [ "$rc" -eq 0 ] && printf '%s\n' "$out" | grep -q '^residual mismatches: 0$' \
+       && printf '%s\n' "$out" | grep -q '^location-only differences.*: 2$' \
+       && printf '%s\n' "$out" | grep -q "^    location-only: $p1\$" \
+       && printf '%s\n' "$out" | grep -q "^    location-only: $p2\$" \
+       && printf '%s\n' "$out" | grep -q '^RESULT: LOCATION-CLEAN' \
+       && ! printf '%s\n' "$out" | grep -q '^RESULT: PASS'; then
+        st_ok "exe-dir echo + out-of-tree import-shadow warning are absorbed (rc=0, LOCATION-CLEAN, 2 named)"
+    else st_bad "location-only shapes not absorbed as specified (rc=$rc)" "$out"; fi
+
+    # 2. A genuinely different error MESSAGE (same exe-dir shape, different
+    #    missing file) must survive normalisation: residual 1, rc 1, named.
+    fixture "$SHA1"
+    st_write "$ST_ROOT/gated" "$p1" "hello" "$(st_err "$B" other_mod)"
+    out=$(st_compare base gated); rc=$?
+    if [ "$rc" -eq 1 ] && printf '%s\n' "$out" | grep -q '^residual mismatches: 1$' \
+       && printf '%s\n' "$out" | grep -q "^--- MISMATCH: $p1\$" \
+       && printf '%s\n' "$out" | grep -q '^RESULT: FAIL'; then
+        st_ok "a different error message behind the same exe-dir still mismatches (rc=1)"
+    else st_bad "real error-text divergence was absorbed (rc=$rc)" "$out"; fi
+
+    # 3. A shadow warning naming a DIFFERENT module in the shadowed path than
+    #    in the used path is not the location shape: must survive.
+    fixture "$SHA1"
+    st_write "$ST_ROOT/base" "$p2" "$(st_shadow complex "$REPO_REAL/lib/complex.eigs" "$ST_ROOT/fakeA/lib/linalg.eigs")" "42"
+    cp "$ST_ROOT/base/$(slug "$p2")" "$ST_ROOT/base2/$(slug "$p2")"
+    out=$(st_compare base gated); rc=$?
+    if [ "$rc" -eq 1 ] && printf '%s\n' "$out" | grep -q '^residual mismatches: 1$' \
+       && printf '%s\n' "$out" | grep -q "^--- MISMATCH: $p2\$"; then
+        st_ok "a shadow warning naming a different module is NOT absorbed (rc=1)"
+    else st_bad "mismatched-module shadow warning was absorbed (rc=$rc)" "$out"; fi
+
+    # 4. A genuine PROJECT-file shadow (used path outside <corpus>/lib/) is a
+    #    real diagnostic, not location: must survive.
+    fixture "$SHA1"
+    st_write "$ST_ROOT/base" "$p2" "$(st_shadow complex "$REPO_REAL/tests/complex.eigs" "$ST_ROOT/fakeA/lib/complex.eigs")" "42"
+    cp "$ST_ROOT/base/$(slug "$p2")" "$ST_ROOT/base2/$(slug "$p2")"
+    out=$(st_compare base gated); rc=$?
+    if [ "$rc" -eq 1 ] && printf '%s\n' "$out" | grep -q '^residual mismatches: 1$' \
+       && printf '%s\n' "$out" | grep -q "^--- MISMATCH: $p2\$"; then
+        st_ok "a project-file shadow warning (outside lib/) is NOT absorbed (rc=1)"
+    else st_bad "project-file shadow warning was absorbed (rc=$rc)" "$out"; fi
+
+    # 5. A path that is NOT the exe-dir (the corpus tree in "tried containing
+    #    directory") differing between arms must survive: the normaliser is
+    #    specific to the exe-dir string.
+    fixture "$SHA1"
+    st_write "$ST_ROOT/gated" "$p1" "hello" "$(st_err "$B" tmp_mod | sed "s|containing directory '$REPO_REAL/tests'|containing directory '/elsewhere/tests'|")"
+    out=$(st_compare base gated); rc=$?
+    if [ "$rc" -eq 1 ] && printf '%s\n' "$out" | grep -q '^residual mismatches: 1$' \
+       && printf '%s\n' "$out" | grep -q "^--- MISMATCH: $p1\$"; then
+        st_ok "a non-exe-dir path difference is NOT absorbed (rc=1)"
+    else st_bad "corpus-path difference was absorbed (rc=$rc)" "$out"; fi
+
+    # 6. Root exe-dir guard: an arm whose binary sits in '/' must compare RAW
+    #    (rewriting '/' would erase every path), announced by NOTE.
+    fixture "$SHA1"
+    st_arm "$ST_ROOT/gated" "/eigenscript" "$SHA1" 0
+    st_write "$ST_ROOT/gated" "$p1" "hello" "$(st_err "" tmp_mod)"
+    st_write "$ST_ROOT/gated" "$p2" "42"
+    st_write "$ST_ROOT/gated" "$p3" "plain"
+    out=$(st_compare base gated); rc=$?
+    if [ "$rc" -eq 1 ] && printf '%s\n' "$out" | grep -q '^NOTE: gated exe-dir .* not normalisable' \
+       && printf '%s\n' "$out" | grep -q '^residual mismatches: 1$'; then
+        st_ok "an unusable exe-dir disables normalisation loudly and the arm compares raw (rc=1)"
+    else st_bad "root exe-dir guard did not hold (rc=$rc)" "$out"; fi
+
+    # 7. Same build, same force, SAME path is still refused (rc 2).
+    fixture "$SHA1"
+    st_arm "$ST_ROOT/gated" "$A/eigenscript" "$SHA1" 0
+    st_write "$ST_ROOT/gated" "$p1" "x"; st_write "$ST_ROOT/gated" "$p2" "x"; st_write "$ST_ROOT/gated" "$p3" "x"
+    out=$(st_compare base gated); rc=$?
+    if [ "$rc" -eq 2 ] && printf '%s\n' "$out" | grep -q 'SAME binary AND the same EIGS_OBS_FORCE'; then
+        st_ok "same build at the same path is still refused (rc=2)"
+    else st_bad "same-build-same-path was not refused (rc=$rc)" "$out"; fi
+
+    # 8. A determinism reference from the same build at ANOTHER path is refused
+    #    (the self-diff runs raw, so it would launder exe-dir echoes as nondet).
+    fixture "$SHA2"
+    st_arm "$ST_ROOT/base2" "$B/eigenscript" "$SHA1" 0
+    for p in "$p1" "$p2" "$p3"; do cp "$ST_ROOT/base/$(slug "$p")" "$ST_ROOT/base2/$(slug "$p")"; done
+    out=$(st_compare base gated); rc=$?
+    if [ "$rc" -eq 2 ] && printf '%s\n' "$out" | grep -q 'captured with DIFFERENT arms'; then
+        st_ok "a reference from another path is refused (rc=2)"
+    else st_bad "path-mismatched reference was accepted (rc=$rc)" "$out"; fi
+
+    # 9. Genuinely different builds, location-only differences: the normal
+    #    gate verdict PASS, rc 0, with the 2 absorbed programs still named.
+    fixture "$SHA2"
+    out=$(st_compare base gated); rc=$?
+    if [ "$rc" -eq 0 ] && printf '%s\n' "$out" | grep -q '^RESULT: PASS' \
+       && printf '%s\n' "$out" | grep -q '^location-only differences.*: 2$' \
+       && printf '%s\n' "$out" | grep -q '^residual mismatches: 0$'; then
+        st_ok "different builds, location-only differences: PASS with the 2 absorbed programs named"
+    else st_bad "different-build clean run did not PASS as specified (rc=$rc)" "$out"; fi
+
+    echo "SELFTEST: $st_pass ok, $st_fail failed (of 9)"
+    [ "$st_fail" -eq 0 ] && [ "$st_pass" -eq 9 ]
+}
+
 case "${1:-}" in
     capture) shift; do_capture "${1:?usage: capture <label>}" ;;
     compare) shift; do_compare "${1:?usage: compare <base> <gated>}" "${2:?usage: compare <base> <gated>}" ;;
-    *) echo "usage: $0 capture <label> | compare <base> <gated>"; exit 2 ;;
+    selftest) do_selftest ;;
+    *) echo "usage: $0 capture <label> | compare <base> <gated> | selftest"; exit 2 ;;
 esac

From b6aff7e25a84e443246b52d67ed20b3ecbf9de39 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 00:00:54 +0000
Subject: [PATCH 02/39] embed: store obs_history_gap at the end of a closed
 isolated eval unit (#1114)

Under eigs_set_eval_observer_isolated(1), after an explicitly armed unit,
an un-armed read-free unit that reassigns a binding runs with the gate
closed. The missing-history flag was stored only at the NEXT eval
boundary, so a host reading observer_predicate_at DIRECTLY between units
was told "history complete" (gap=0) for exactly one boundary while the
answer came from the stale window.

Repro (C host linked against the v0.43.0 release objects, run from src/):

    arm; eval(series); eval("x is 1000\nx is 2000\nx")
    before:  un-armed reassigning unit: obs_needed=0 gap=0
             DIRECT improving(x)=1 obs_needed=0 gap=0
             third boundary: gap=1            <- one boundary late
    after:   un-armed reassigning unit: obs_needed=0 gap=1
             DIRECT improving(x)=1 obs_needed=0 gap=1

Fix: eval_source records the closed execution immediately after
vm_execute (same `!obs_needed && obs_exec_started` condition, same sticky
release store) via a small helper shared with the pre-existing boundary
site, which is kept for code that executes closed outside eval_source. No
verdict, scan, guard or store order changes; the armed recipe's
`isolated host: DIRECT improving=1 obs_needed=1 gap=0` line is unchanged
and the eval-unit read after the direct read still raises naming
EIGS_OBS_FORCE=1 (#1028). The predicate answer itself is still the
stale-window answer by contract (direct reads bypass the eval guard); the
flag is the host's signal.

Regression: new `isolated gap` arm in tests/test_embed_observer.c (full
run and --isolated-host): armed unit -> gap=0; un-armed reassigning unit
-> closed; direct improving read -> assert gap=1; eval-unit read still
raises. The driver pins the printed line and 41 passed. Planted fault
(end-of-unit store removed): FAIL "isolated gap: flag is set before the
next eval boundary", 40 passed, 1 failed.

Docs: EMBEDDING.md states the immediate-truth guarantee;
EMBED_OBSERVER_VALIDATION.md round 4 records the reproducer, fix and
planted fault.

Residual: the direct predicate ANSWER is not corrected (documented as
stale; the host must arm each interrogated unit).

Closes #1114

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 docs/EMBEDDING.md                 | 14 ++++++-
 docs/EMBED_OBSERVER_VALIDATION.md | 62 ++++++++++++++++++++++++++++++-
 src/eigs_embed.c                  | 20 +++++++++-
 tests/test_embed_observer.c       | 30 ++++++++++++++-
 tests/test_embed_observer.sh      |  5 ++-
 5 files changed, 125 insertions(+), 6 deletions(-)

diff --git a/docs/EMBEDDING.md b/docs/EMBEDDING.md
index bcdf3350..cfe4dcdb 100644
--- a/docs/EMBEDDING.md
+++ b/docs/EMBEDDING.md
@@ -185,6 +185,17 @@ An explicit arm is consumed at one eval compilation boundary; call it again
 before each unit whose assignments the host will interrogate directly. Arming
 by a source scan or by internal runtime code does not create that host request.
 
+**The gap flag is truthful immediately (#1114).** When an isolated unit
+executes with the gate closed, `obs_history_gap` is set before that
+`eigs_eval_string`/`eigs_eval_file` call returns -- not at the next eval
+boundary. A host that consults the flag as a secondary trust check around a
+direct `observer_predicate_at` call between units is therefore never told
+"history complete" for a unit that ran unrecorded. The predicate *answer*
+itself is still computed from whatever window was recorded (direct reads
+bypass the eval guard, as above); the flag, not the answer, is the host's
+signal to distrust it. The armed recipe is unchanged: an explicitly armed unit
+records, and the flag stays 0 after it.
+
 ```c
 eigs_set_eval_observer_isolated(1);
 eigs_obs_enable();
@@ -225,7 +236,8 @@ correct cross-unit queries even with the opt-in enabled.
 The regression instrument is `bash tests/test_embed_observer.sh`: native slot
 updates and assembled bytecode without compilation, default cross-unit history,
 isolated read-free units, a rejected cross-unit read, retained functions and the
-force-on recovery path, plus C callback observation and late registration. It uses the same build variant as `src/eigenscript`,
+force-on recovery path, plus C callback observation and late registration, and
+the immediate gap flag at a direct read after a closed unit (#1114). It uses the same build variant as `src/eigenscript`,
 including ASan, and is enrolled in the full suite.
 The [validation record](EMBED_OBSERVER_VALIDATION.md) contains the baseline
 reproducer, planted-fault output and measurement setup.
diff --git a/docs/EMBED_OBSERVER_VALIDATION.md b/docs/EMBED_OBSERVER_VALIDATION.md
index 45b0c72b..4ced6640 100644
--- a/docs/EMBED_OBSERVER_VALIDATION.md
+++ b/docs/EMBED_OBSERVER_VALIDATION.md
@@ -4,7 +4,9 @@ The first sections record round 1. The
 [round-2 record](#round-2-raw-host-coverage) distinguishes state creation from
 the separate embed-initialization pin; the
 [round-3 record](#round-3-explicit-host-arming-across-an-isolated-eval-boundary)
-corrects the explicit-host-arm recipe across an isolated eval boundary.
+corrects the explicit-host-arm recipe across an isolated eval boundary; the
+[round-4 record](#round-4-immediate-gap-flag-for-direct-reads-1114) makes the
+gap flag truthful at the end of a closed unit instead of one boundary later.
 
 Baseline: `origin/main` at `cd99388163c3ff6478851de1f5be906f7626341a`.
 The baseline runtime was built in this worktree before the runtime edits.
@@ -408,3 +410,61 @@ all three captures. `tests/test_throw_unwind.eigs` is therefore outside the
 497-program comparison. No differential-tool normalization, exclusion rule
 or coverage floor was changed. No new measurement contradicted the round-3
 brief; the reported F4 silent-wrong recipe was reproduced and repaired.
+
+## Round 4: immediate gap flag for direct reads (#1114)
+
+Baseline: v0.43.0 (`a6c50fb`). Found by a blind critic confirming round 3:
+under the opt-in, after an armed unit, an un-armed read-free unit that
+reassigns a binding runs closed, and a host reading `observer_predicate_at`
+DIRECTLY afterwards saw `obs_history_gap == 0`. The flag was only stored at
+the NEXT eval boundary (`eval_source`'s `!obs_needed && obs_exec_started`
+check), so for exactly one boundary the flag said "history complete" while the
+answer came from the stale window. The eval-unit read still raised (the
+#1028 promise held) and the documented recipe told hosts to arm each
+interrogated unit, so a conforming host was fine -- but the flag lied.
+
+Reproducer (a C program linked against the baseline release objects, run
+from `src/`; `series` is the fixture's descending trajectory):
+
+```text
+armed unit: err=0 obs_needed=1 gap=0
+un-armed reassigning unit: err=0 obs_needed=0 gap=0
+DIRECT improving(x)=1 obs_needed=0 gap=0       <- x went 1000 -> 2000 unrecorded
+third boundary: err=0 obs_needed=0 gap=1       <- the flag catches up here
+```
+
+Fix: `eval_source` records the closed execution at the END of the unit,
+immediately after `vm_execute` (same condition, same sticky release store),
+through a small helper shared with the pre-existing boundary site. The
+boundary site is kept for code that executes closed outside `eval_source`.
+No verdict logic, compile scan, guard or store order changed. After the fix:
+
+```text
+armed unit: err=0 obs_needed=1 gap=0
+un-armed reassigning unit: err=0 obs_needed=0 gap=1
+DIRECT improving(x)=1 obs_needed=0 gap=1
+third boundary: err=0 obs_needed=0 gap=1
+```
+
+The predicate answer is deliberately still the stale-window answer: direct
+reads bypass the eval guard by contract, and the flag is the host's signal.
+
+New fixture arm `isolated gap` (in the full run and `--isolated-host`):
+isolation on, explicit arm, `series`, assert `obs_needed && !gap`; un-armed
+`x is 1000 / x is 2000 / x`, assert `!obs_needed`; direct `improving` on `x`;
+assert `gap`; then an eval-unit `improving of x` must still raise naming
+`EIGS_OBS_FORCE=1`. The driver pins
+`isolated gap: DIRECT improving=[01] obs_needed=0 gap=1` (the answer is not
+pinned) and the count **41 passed, 0 failed**. The new fixture source linked
+against the baseline objects and run with `--isolated-host`:
+
+```text
+isolated gap: DIRECT improving=1 obs_needed=0 gap=0
+FAIL: isolated gap: flag is set before the next eval boundary
+embed observer: 9 passed, 1 failed
+```
+
+Planted fault (the end-of-unit store removed from the fixed tree, rebuilt):
+the same single `FAIL` line, `40 passed, 1 failed`, driver exit 1. Restored:
+41 passed, driver exit 0. The round-3 armed-recipe line
+`isolated host: DIRECT improving=1 obs_needed=1 gap=0` is unchanged.
diff --git a/src/eigs_embed.c b/src/eigs_embed.c
index 6a05b4d4..5aa6a834 100644
--- a/src/eigs_embed.c
+++ b/src/eigs_embed.c
@@ -75,6 +75,17 @@ void eigs_set_eval_observer_isolated(int enabled) {
         eigs_current->state->eval_observer_isolated = enabled != 0;
 }
 
+/* Missing-history evidence: a unit that executed while recording was off has
+ * assignments no later reader can reconstruct. The flag is sticky and the
+ * store is idempotent, so it is safe to record at both the end of the unit
+ * (#1114: truthful for a DIRECT host predicate read between units) and the
+ * next boundary (the pre-#1114 site, kept for code that executes closed
+ * outside eval_source, e.g. a host driving vm_execute itself). */
+static void obs_record_closed_execution(void) {
+    if (!g_obs_needed && g_obs_exec_started)
+        obs_flag_store(obs_history_gap, 1);
+}
+
 static EigsValue *eval_source(const char *src, const char *file_dir) {
     if (!src || !eigs_current || !g_global_env) return NULL;
     Env *global = g_global_env;
@@ -119,8 +130,7 @@ static EigsValue *eval_source(const char *src, const char *file_dir) {
         &eigs_current->state->obs_host_arm_pending, 0, __ATOMIC_ACQ_REL);
     if (eigs_current->state->eval_observer_isolated &&
         !g_obs_eval_host_callbacks) {
-        if (!g_obs_needed && g_obs_exec_started)
-            obs_flag_store(obs_history_gap, 1);
+        obs_record_closed_execution();
         if (!g_obs_eval_retains_code) {
             obs_flag_store(obs_exec_started, 0);
             obs_flag_store(obs_needed, 1);
@@ -156,6 +166,12 @@ static EigsValue *eval_source(const char *src, const char *file_dir) {
             "Restart the state with EIGS_OBS_FORCE=1 before the first eval.");
     }
     Value *result = g_has_error || g_parse_errors ? NULL : vm_execute(chunk, global);
+    /* #1114: the unit has finished. If it executed with the gate closed, its
+     * assignments already have no history -- record that NOW, not at the next
+     * boundary, so a host reading observer_predicate_at directly between
+     * units sees a truthful flag. Stored even when the unit raised: the
+     * assignments before the raise are just as unrecorded. */
+    obs_record_closed_execution();
     chunk_free(chunk);
     free_ast(ast);
     free_tokenlist(&tl);
diff --git a/tests/test_embed_observer.c b/tests/test_embed_observer.c
index c788e046..6ec216d4 100644
--- a/tests/test_embed_observer.c
+++ b/tests/test_embed_observer.c
@@ -194,6 +194,33 @@ static void isolated_host(void) {
     check(!g_obs_needed, "isolated host: explicit pin is consumed by one unit");
     eigs_close(st);
 }
+/* #1114: the gap flag must be truthful the moment a closed unit finishes,
+ * not one eval boundary later. Armed unit, then an UN-armed read-free unit
+ * that reassigns x (runs closed), then a DIRECT predicate read from C. The
+ * answer itself is computed from the stale window (documented: direct reads
+ * bypass the eval guard); the flag is what tells the host not to trust it. */
+static void isolated_gap_truth(void) {
+    EigsState *st = eigs_open();
+    if (!st) { check(0, "isolated gap: open state"); return; }
+    eigs_set_eval_observer_isolated(1);
+    eigs_obs_enable();
+    eval_ok(series, "isolated gap: armed unit executes");
+    check(g_obs_needed && !g_obs_history_gap,
+          "isolated gap: armed unit leaves no gap");
+    eval_ok("x is 1000\nx is 2000\nx\n",
+            "isolated gap: un-armed reassigning unit executes");
+    check(!g_obs_needed, "isolated gap: un-armed unit ran closed");
+    int slot = -1;
+    for (int i = 0; i < g_global_env->count; i++)
+        if (!strcmp(g_global_env->names[i], "x")) { slot = i; break; }
+    int answer = slot < 0 ? -1 : observer_predicate_at(g_global_env, slot, 2, 1);
+    printf("isolated gap: DIRECT improving=%d obs_needed=%d gap=%d\n",
+           answer, g_obs_needed, g_obs_history_gap);
+    check(g_obs_history_gap,
+          "isolated gap: flag is set before the next eval boundary");
+    gap("improving of x", "isolated gap: eval-unit read after the direct read still raises");
+    eigs_close(st);
+}
 static void eval_contract(void) {
     /* A native host can load/compile a module without routing through the
      * eval API. That module's verdict says nothing about the C caller. */
@@ -285,11 +312,12 @@ int main(int argc, char **argv) {
     if (!direct_only && !isolated_only) raw_host();
     if (!raw_only && !isolated_only) direct();
 #ifndef EIGS_OBS_BASELINE_ONLY
-    if (isolated_only) isolated_host();
+    if (isolated_only) { isolated_host(); isolated_gap_truth(); }
     else if (!raw_only && !direct_only) {
         raw_compile_then_arm();
         eval_contract();
         isolated_host();
+        isolated_gap_truth();
     }
 #endif
     printf("embed observer: %d passed, %d failed\n", passed, failed);
diff --git a/tests/test_embed_observer.sh b/tests/test_embed_observer.sh
index 16093bb0..bfd50d84 100644
--- a/tests/test_embed_observer.sh
+++ b/tests/test_embed_observer.sh
@@ -35,8 +35,11 @@ lsan_classify "$(cat "$out")" || classification=$?
 if [[ "$rc" -ne 0 || "$classification" -ne 2 ]]; then
     exit 1
 fi
-grep -q '^embed observer: 35 passed, 0 failed$' "$out"
+grep -q '^embed observer: 41 passed, 0 failed$' "$out"
 grep -q '^raw host: obs_needed=1 improving=1$' "$out"
 grep -q '^isolated host: DIRECT improving=1 obs_needed=1 gap=0$' "$out"
+# #1114: after a closed unit the gap flag is already 1 at a DIRECT read. The
+# improving answer is deliberately not pinned (documented as stale).
+grep -q '^isolated gap: DIRECT improving=[01] obs_needed=0 gap=1$' "$out"
 grep -q '^embed obs-gate: unobserved$' "$out"
 grep -q '^obs-gate: unobserved ' "$out"

From c3dd4bc25634d2b07661d184a9ab34c4dc39cbaa Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 00:17:18 +0000
Subject: [PATCH 03/39] eigen: honour the report/report_value reservation in
 the meta-interpreter (#1111)

lib/eigen.eigs (the EigenScript-in-EigenScript meta-interpreter) still let
`report` / `report_value` be bound and accepted non-identifier operands,
reproducing the shadowing #1102 removed from the runtime. It now mirrors the
C parser stage-for-stage: the tokenizer lexes both words as a reserved
"report" token; `_p_expect` rejects that token in every binding position
(assignment, define name, parameter, lambda/for/comprehension/catch variable,
import, bare value use); the primary parser accepts only `report of <ident>`
(operand parsed at unary precedence like the C `of` RHS, so parentheses are
transparent and `report of x + "!"` is `(report of x) + "!"`); dot keys
still admit the word (`d.report` stays a data key). The message carries the
runtime's E005 text. Eval routes the new ["report", kind, name] node through
fresh-parameter bridges (`report of v` / `report_value of v`), keeping the
documented value-only classification (equilibrium / opaque); the `report`
value entry is gone from the default env, and `report_value of x` now works
in eigen (it was an undefined variable before).

Repro (baseline):
  src/eigenscript -e 'load_file of "lib/eigen.eigs"
  print of (eigen_run of "report is 4\nprint of report")
  print of (eigen_run of "define report(v) as:\n    return \"mine\"\nx is 1\nx is 2\nprint of (report of x)")'
  -> 4 / null / mine / null            (native: E005 on both, rc=1)
After:
  -> parse error line 1: 'report' is a reserved observer form; use it with
     'of variable', never as a binding [E005]   (raised by eigen_run, rc=1)

tests/test_meta_parity.eigs ([107]) now asserts, per probe, that native
`eval` raises kind "parse" AND `eigen_run` raises an E005-shaped message:
15 binding/operand forms for both words, the unbound-operand runtime raise
on both sides, and positive controls (bound identifier, parenthesised
identifier, `of` precedence, host-function operand, dict fields). With the
old lib/eigen.eigs planted back, 30 checks print FAIL and the file then
aborts on `undefined variable 'report_value'` (rc=1).
tests/test_report_reserved.sh's old `eigen_run of "report of 5"` ==
"equilibrium" pin is replaced by the bridge fallback on a bound name
(`x is 5 / report of x`).

Residual (unchanged, documented): the meta bridge classifies the VALUE
without the host's binding trajectory, so a moved binding reports
`equilibrium` where native reports `moving`, and a meta-defined function
(a list value) reports `equilibrium` where native reports `opaque`.

Closes #1111

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 docs/STDLIB.md                | 21 ++++++--
 lib/eigen.eigs                | 94 +++++++++++++++++++++++++++++++----
 tests/run_all_tests.sh        |  8 +--
 tests/test_meta_parity.eigs   | 69 +++++++++++++++++++++++++
 tests/test_report_reserved.sh |  2 +-
 5 files changed, 176 insertions(+), 18 deletions(-)

diff --git a/docs/STDLIB.md b/docs/STDLIB.md
index 8a82b829..8b393328 100644
--- a/docs/STDLIB.md
+++ b/docs/STDLIB.md
@@ -964,11 +964,22 @@ print of msg   # "World is running v0.5"
 
 ### lib/eigen.eigs — Meta-Circular Interpreter
 
-The meta-interpreter's `report` bridge classifies values without the host's
-binding trajectories: it returns `equilibrium` for ordinary values and `opaque`
-for functions. Since #1102 a fresh-parameter wrapper uses the reserved host
-syntax to preserve that existing fallback; the meta-interpreter remains a
-separate, partial implementation of the language.
+The meta-interpreter honours the `report` / `report_value` reservation
+(#1102, mirrored here by #1111) at the same stage as the runtime — its
+tokenizer lexes both words as a reserved token and its parser rejects every
+binding position (assignment, `define` name, parameter, loop/comprehension/
+catch/lambda variable, bare value use) and every non-identifier operand
+(`report of 5`, `report_value of (x + 1)`) with a parse error carrying the
+runtime's E005 text: `parse error line N: 'report' is a reserved observer
+form; use it with 'of variable', never as a binding [E005]` (operands:
+`... requires a variable name operand [E005]`). `report of x` /
+`report_value of x` over a bound identifier (parentheses allowed) and dict
+fields such as `d.report` work as in the runtime. The classification itself
+is the meta-interpreter's value-only bridge, without the host's binding
+trajectories: `equilibrium` for ordinary values and `opaque` for host
+functions. `tests/test_meta_parity.eigs` pins that native and meta agree on
+each of these probes. The meta-interpreter remains a separate, partial
+implementation of the language.
 
 | Function | Signature | Description |
 |----------|-----------|-------------|
diff --git a/lib/eigen.eigs b/lib/eigen.eigs
index bd4ea970..79801705 100644
--- a/lib/eigen.eigs
+++ b/lib/eigen.eigs
@@ -14,6 +14,15 @@
 # error instead of silently lexing to wrong values (`<<`/`>>` lex as two
 # comparisons and raise at parse time). (Slices, destructuring, and
 # parameter defaults also raise, at parse time — #339.)
+# RESERVED OBSERVER FORMS (#1102/#1111): `report` and `report_value` are
+# reserved words here exactly as in the C parser — never a binding
+# (assignment, define name, parameter, loop/comprehension/catch/lambda
+# variable, bare value use), and `report of x` / `report_value of x` require
+# an identifier operand (parentheses around the identifier are fine; dict
+# fields such as `d.report` stay legal data keys). A violation raises a parse
+# error whose text mirrors the runtime's E005 diagnostic, e.g.
+# "parse error line 1: 'report' is a reserved observer form; use it with
+# 'of variable', never as a binding [E005]".
 # DIAGNOSTICS are best-effort and intentionally differ (issue #306): raised
 # errors carry no "line N" prefix (eval-time AST nodes don't track source
 # lines), and divide-or-modulo-by-zero raises in both (the C VM raises a
@@ -37,6 +46,7 @@ load_file of "lib/math.eigs"
 
 # Token types (strings for readability):
 # "num", "str", "ident", "op", "kw", "newline", "indent", "dedent", "eof"
+# "report" (the reserved observer forms `report` / `report_value`, #1102)
 # "lparen", "rparen", "lbracket", "rbracket", "lbrace", "rbrace"
 # "comma", "colon", "dot", "arrow", "pipe", "null", "true", "false"
 
@@ -67,6 +77,10 @@ _interrogatives is ["what", "who", "when", "where", "why", "how"]
 # Predicate keywords
 _predicates is ["converged", "stable", "improving", "oscillating", "diverging", "equilibrium"]
 
+# Reserved observer forms (#1102/#1111): their own token kind, so the parser
+# can reject every binding position exactly where the C parser does.
+_reserved_forms is ["report", "report_value"]
+
 define _is_keyword(word) as:
     for i in range of (len of _keywords):
         if word == _keywords[i]:
@@ -85,6 +99,12 @@ define _is_predicate(word) as:
             return 1
     return 0
 
+define _is_reserved_form(word) as:
+    for i in range of (len of _reserved_forms):
+        if word == _reserved_forms[i]:
+            return 1
+    return 0
+
 define _predicate_index(word) as:
     for i in range of (len of _predicates):
         if word == _predicates[i]:
@@ -342,6 +362,8 @@ define eigen_tokenize(source) as:
                     append of [tokens, ["interrogative", buf, line]]
                 elif (_is_predicate of buf) == 1:
                     append of [tokens, ["predicate", buf, line]]
+                elif (_is_reserved_form of buf) == 1:
+                    append of [tokens, ["report", buf, line]]
                 elif (_is_keyword of buf) == 1:
                     append of [tokens, ["kw", buf, line]]
                 else:
@@ -460,6 +482,7 @@ define eigen_tokenize(source) as:
 #   ["assign", "x", expr]
 #   ["binop", "+", left, right]
 #   ["call", fn_expr, arg_expr]
+#   ["report", "report" | "report_value", "x"]   (#1102: `report of x`)
 #   ["if", cond, if_body, else_body]
 #   ["loop", cond, body]
 #   ["for", var, iter, body]
@@ -512,8 +535,28 @@ define _p_peek_at(p, offset) as:
         return ["eof", null, 0]
     return p[0][idx]
 
+# #1102/#1111 parity: one reservation rule for every parser entry point. A
+# "report" token is never an identifier; only `report of <ident>` and a dot
+# key consume it. The message mirrors the C parser's E005 diagnostic (line
+# only — eigen tokens carry no column).
+define _p_report_error(tok, operand) as:
+    if operand == 1:
+        throw of f"parse error line {tok[2]}: '{tok[1]}' is a reserved observer form; requires a variable name operand [E005]"
+    throw of f"parse error line {tok[2]}: '{tok[1]}' is a reserved observer form; use it with 'of variable', never as a binding [E005]"
+
+# A dot key may be any word, including a reserved observer form (#1102:
+# `d.report` is a data key, never a binding).
+define _p_expect_key(p) as:
+    tok is _p_cur of p
+    if tok[0] == "report":
+        _p_advance of p
+        return tok
+    return _p_expect of [p, "ident"]
+
 define _p_expect(p, ttype) as:
     tok is _p_cur of p
+    if tok[0] == "report":
+        _p_report_error of [tok, 0]
     if tok[0] != ttype:
         throw of f"parse error: expected {ttype}, got {tok[0]} ('{tok[1]}') at line {tok[2]}"
     _p_advance of p
@@ -774,7 +817,7 @@ define _p_parse_postfix(p) as:
     loop while ((_p_peek_type of p) == "dot") or ((_p_peek_type of p) == "lbracket"):
         if (_p_peek_type of p) == "dot":
             _p_advance of p
-            key_tok is _p_expect of [p, "ident"]
+            key_tok is _p_expect_key of p
             node is ["dot", node, key_tok[1]]
         else:
             _p_advance of p
@@ -908,7 +951,7 @@ define _p_parse_call(p) as:
             left is ["index", left, idx]
         elif (_p_peek_type of p) == "dot":
             _p_advance of p
-            key_tok is _p_expect of [p, "ident"]
+            key_tok is _p_expect_key of p
             left is ["dot", left, key_tok[1]]
         else:
             parsing is 0
@@ -965,6 +1008,24 @@ define _p_parse_primary(p) as:
         _p_advance of p
         return ["ident", tok[1]]
 
+    # #1102/#1111: reserved observer forms. `report of <ident>` is the only
+    # value-producing shape (C parser: parse_primary + parse_relation);
+    # anything else is E005. The operand is parsed at unary precedence,
+    # mirroring the C parser's `of` RHS, so `report of x + "!"` is
+    # `(report of x) + "!"` and `report of (x)` is the identifier `x`.
+    if tt == "report":
+        tok is _p_cur of p
+        _p_advance of p
+        if (_p_peek_type of p) != "kw":
+            _p_report_error of [tok, 0]
+        if (_p_peek_val of p) != "of":
+            _p_report_error of [tok, 0]
+        _p_advance of p
+        operand is _p_parse_unary of p
+        if operand[0] != "ident":
+            _p_report_error of [tok, 1]
+        return ["report", tok[1], operand[1]]
+
     if tt == "lparen":
         # Check for lambda: (params) => expr
         saved_pos is p[1]
@@ -978,7 +1039,7 @@ define _p_parse_primary(p) as:
                 scan_ok is 0
             else:
                 stok is p[0][scan_pos]
-                if (stok[0] == "ident") or (stok[0] == "comma"):
+                if (stok[0] == "ident") or (stok[0] == "comma") or (stok[0] == "report"):
                     scan_pos is scan_pos + 1
                 elif stok[0] == "rparen":
                     # Check if next is arrow
@@ -1218,6 +1279,18 @@ define eigen_eval(node, env) as:
             throw of f"undefined variable '{node[1]}'"
         return _env_get of [env, node[1]]
 
+    if ntype == "report":
+        # #1102/#1111: `report of x` / `report_value of x` over a bound name.
+        # The operand must be bound (the C VM raises undefined_name at run
+        # time); the classification is this interpreter's documented
+        # value-only bridge (no host trajectory: equilibrium / opaque).
+        if (_env_has of [env, node[2]]) == 0:
+            throw of f"undefined variable '{node[2]}'"
+        val is _env_get of [env, node[2]]
+        if node[1] == "report_value":
+            return _report_value_bridge of val
+        return _report_bridge of val
+
     if ntype == "assign":
         val is eigen_eval of [node[2], env]
         _env_set of [env, node[1], val]
@@ -1694,11 +1767,19 @@ define _eval_block(stmts, env) as:
 # Built-in functions for the meta-circular environment
 # ============================================================
 
+# #1102/#1111: the reserved forms are parser syntax, never values in the meta
+# environment. `report of x` / `report_value of x` in meta source evaluate
+# through these fresh-parameter wrappers — this interpreter's documented
+# value-only bridge (no host trajectory -> equilibrium; host functions ->
+# opaque) — without exposing the host's named binding history to the meta env.
+_report_bridge is (v) => report of v
+_report_value_bridge is (v) => report_value of v
+
 define _make_default_env as:
     env is _env_new of null
     # Bridge the C builtins into the meta-interpreter's environment.
     # Since we're running inside the C runtime, these names resolve to
-    # VAL_BUILTIN values (report uses the wrapper below). The "call" handler calls them
+    # VAL_BUILTIN values. The "call" handler calls them
     # with `fn of arg` which the C runtime handles natively.
     _env_set_local of [env, "print", print]
     _env_set_local of [env, "write", write]
@@ -1708,11 +1789,6 @@ define _make_default_env as:
     _env_set_local of [env, "num", num]
     _env_set_local of [env, "append", append]
     _env_set_local of [env, "type", type]
-    # #1102: report is reserved syntax, so it cannot be stored as a value.
-    # This fresh-parameter wrapper preserves this interpreter's existing
-    # value-only bridge: no trajectory -> equilibrium, functions -> opaque.
-    # It does not expose the host's named binding history to the meta env.
-    _env_set_local of [env, "report", (v) => report of v]
     _env_set_local of [env, "assert", assert]
     _env_set_local of [env, "throw", throw]
     _env_set_local of [env, "keys", keys]
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 8e6d6ff3..d33bcb4d 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -1495,9 +1495,11 @@ fi
 # [107] Meta-interpreter parity (#306). lib/eigen.eigs (the meta-circular
 # interpreter) must agree with the C evaluator on and/or value-returning
 # short-circuit, raising on unbound identifiers, and div/mod-by-zero values —
-# the divergences it used to ship while claiming "full parity".
-echo "[107] Meta-Interpreter Parity (#306)"
-check_eigs_suite "eigen_run matches C VM (and/or operands, unbound raises, div/0)" test_meta_parity.eigs "All tests passed" 1
+# the divergences it used to ship while claiming "full parity". Since #1111 it
+# also pins the #1102 reservation: report/report_value cannot be bound and
+# need an identifier operand — native E005 and meta both raise.
+echo "[107] Meta-Interpreter Parity (#306, #1111)"
+check_eigs_suite "eigen_run matches C VM (and/or operands, unbound raises, div/0, report/report_value reservation #1111)" test_meta_parity.eigs "All tests passed" 1
 
 # [108] sandbox_run allocation budget (#292). The size-controlled allocators
 # (zeros/fill/buffer/range) charge a per-run byte budget so untrusted generated
diff --git a/tests/test_meta_parity.eigs b/tests/test_meta_parity.eigs
index 186a3e53..bcb9a2c2 100644
--- a/tests/test_meta_parity.eigs
+++ b/tests/test_meta_parity.eigs
@@ -123,6 +123,75 @@ check of ["paren'd 1-elem literal binds whole list (#355)", eigen_run of spread_
 spread_src_fill is "define f3(a, b, c) as:\n    if c == null:\n        return a + b\n    return 0\nf3 of [1, 2]"
 check of ["short spread null-fills trailing params", eigen_run of spread_src_fill, 3]
 
+# --- #1102/#1111: `report` / `report_value` are reserved observer forms ---
+# Native: the shared parser rejects every binding position and every
+# non-identifier operand with E005 before the unit runs (`eval` raises kind
+# "parse"). Meta: lib/eigen.eigs's tokenizer/parser must reject the same
+# programs, with a message that carries the runtime's E005 shape. Each probe
+# asserts BOTH sides raise (the div-by-zero pattern above, on both oracles).
+define both_reject(label, src) as:
+    local native_kind is "did not raise"
+    try:
+        eval of src
+    catch ne:
+        native_kind is ne.kind
+    check of [f"native E005 (parse) rejects: {label}", native_kind, "parse"]
+    local meta_msg is "did not raise"
+    try:
+        eigen_run of src
+    catch me:
+        meta_msg is me
+    check of [f"meta rejects: {label}", contains of [meta_msg, "is a reserved observer form"], 1]
+    check of [f"meta names E005: {label}", contains of [meta_msg, "[E005]"], 1]
+
+# binding positions (the issue's two probes first)
+both_reject of ["report is 4 / print of report", "report is 4\nprint of report"]
+both_reject of ["define report(v) shadows the form", "define report(v) as:\n    return \"mine\"\nrx is 1\nrx is 2\nprint of (report of rx)"]
+both_reject of ["report_value is 4 / print of report_value", "report_value is 4\nprint of report_value"]
+both_reject of ["define report_value(v)", "define report_value(v) as:\n    return 1"]
+both_reject of ["bare report as a value", "rb is 1\nprint of report"]
+both_reject of ["report as a parameter", "define rf(a, report) as:\n    return a"]
+both_reject of ["report_value as a lambda parameter", "rg is (a, report_value) => a"]
+both_reject of ["report as a for variable", "for report in [1]:\n    print of 1"]
+both_reject of ["report as a comprehension variable", "rys is [1 for report in [1]]"]
+both_reject of ["report_value as a catch name", "try:\n    rt is 1\ncatch report_value:\n    rt is 2"]
+# non-identifier operands (replaces the old `report of 5` == "equilibrium" pin)
+both_reject of ["report of 5", "report of 5"]
+both_reject of ["report_value of (x + 1)", "rq is 1\nreport_value of (rq + 1)"]
+both_reject of ["report of -x", "ru is 1\nreport of -ru"]
+both_reject of ["report of d.field", "rd is {\"a\": 1}\nreport of rd.a"]
+both_reject of ["report of ([1])", "report of ([1])"]
+
+# an UNBOUND identifier operand is a run-time error on both sides
+unb_native is "did not raise"
+try:
+    eval of "report of nope_report_operand"
+catch une:
+    unb_native is une.kind
+check of ["native: report of unbound raises undefined_name", unb_native, "undefined_name"]
+unb_meta is "did not raise"
+try:
+    eigen_run of "report of nope_report_operand"
+catch ume:
+    unb_meta is ume
+check of ["meta: report of unbound raises", contains of [unb_meta, "undefined variable"], 1]
+
+# positive controls: a bound identifier operand still works on both sides.
+# Values are the documented divergence (the meta bridge classifies the VALUE
+# with no host trajectory -> "equilibrium"; host functions -> "opaque"), so
+# the native side is pinned as "does not raise, returns a string".
+pv_native is eval of "pv1 is 1\npv1 is 2\nreport of pv1"
+check of ["native: report of bound ident returns a label", type of pv_native, "str"]
+check of ["meta: report of bound ident (bridge fallback)", eigen_run of "pv2 is 1\npv2 is 2\nreport of pv2", "equilibrium"]
+check of ["meta: report_value of bound ident (bridge fallback)", eigen_run of "pv3 is 1\npv3 is 2\nreport_value of pv3", "equilibrium"]
+check of ["meta: parenthesised identifier operand", eigen_run of "pv4 is 1\nreport of (pv4)", "equilibrium"]
+check of ["meta: report_value of ((x))", eigen_run of "pv5 is 1\nreport_value of ((pv5))", "equilibrium"]
+check of ["meta: `of` binds the identifier only (report of x + \"!\")", eigen_run of "pv6 is 1\nreport of pv6 + \"!\"", "equilibrium!"]
+check of ["native: `of` binds the identifier only", ends_with of [eval of "pv7 is 1\nreport of pv7 + \"!\"", "!"], 1]
+check of ["meta: host function operand is opaque", eigen_run of "report of print", "opaque"]
+check of ["meta: dict fields named report/report_value stay data keys", eigen_run of "rdk is {\"report\": 7, \"report_value\": 8}\nrdk.report is 9\nrdk.report + rdk.report_value", 17]
+check of ["native: dict fields named report/report_value stay data keys", eval of "rdn is {\"report\": 7, \"report_value\": 8}\nrdn.report is 9\nrdn.report + rdn.report_value", 17]
+
 if checks == passed:
     print of "All tests passed"
 else:
diff --git a/tests/test_report_reserved.sh b/tests/test_report_reserved.sh
index 3e9be9e8..a2f91f3c 100644
--- a/tests/test_report_reserved.sh
+++ b/tests/test_report_reserved.sh
@@ -155,7 +155,7 @@ print of d.report
 print of d.report_value
 print of f"{report of x}:{report_value of x}"
 load_file of "lib/eigen.eigs"
-print of (eigen_run of "report of 5")
+print of (eigen_run of "x is 5\\nreport of x")
 print of (eigen_run of "report of print")
 '''
     expected = 'moving\nmoving\nmoving\nmoving\nmoving!\nmoving\nmoving\nopaque\nopaque\n7\n8\n9\n10\nmoving:moving\nequilibrium\nopaque\n'

From 24acd597894cdd2b57373cdecfb241bc1d883cae Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 6 Sep 2026 23:49:27 +0000
Subject: [PATCH 04/39] compiler: a fresh for binder is loop-scoped inside a
 function too (#1105)

A `for` binder with NO pre-existing binding was loop-scoped at module
scope but persisted inside a function: the env-skip fast path gave it a
fresh frame slot and nothing stopped a post-loop read from resolving to
that slot, so it silently answered the last element.

    define probe() as:
        for z in [7, 8]:
            0
        return z
    print of (probe of [])     # before: 8   after: Error ... undefined variable 'z'
    for m in [7, 8]:
        0
    print of m                 # Error: undefined variable 'm' (unchanged)

Before, on all three roads (main / load_file / import): `8`, exit 0.
After: `Error line 4: undefined variable 'z'` on all three roads, exit 1,
identical with EIGS_JIT_OFF=1 and EIGS_JIT_OSR_THRESHOLD=1.

Root: compiler.c AST_FOR, the can_skip_env path. `add_local(loop_var)`
allocated the binder's slot and left it resolvable for the rest of the
function. The fix retires that slot at the loop exit (`Local.retired`,
skipped by resolve_local and name_in_enclosing): every GET_LOCAL/SET_LOCAL
already emitted for the body stays valid, a post-loop read compiles to
OP_GET_NAME and raises `undefined variable` unless an outer binding exists
(the module answer), a post-loop write or a later `for` over the same name
allocates a new slot. The #1064 restore of a binder over an existing
parameter/local/plain-assigned slot is untouched (and guarded: a binder
whose #1064 save slot could not be allocated at MAX_LOCALS keeps its
existing slot, which is the parameter itself). No JIT change: the loop
body's bytecode is identical; only the post-loop read changes shape.
tools/jit_diff.sh: OK (231 programs x {jit, osr} vs the interpreter).

Uniform rule now (docs/LANGUAGE_CONTRACT.md, SPEC.md, COMPARISON.md,
llms.txt): a `for` binder is loop-scoped everywhere; a pre-existing
binding is restored; a fresh one is gone. The "function-slot exception"
prose is deleted from all four docs and tests/roads/README.md.

lib/eigen.eigs (meta-circular interpreter) mirrored: `for` saves the
current env's own binding and restores or removes it on every exit;
tests/test_meta_parity.eigs asserts meta and VM both raise for the fresh
function and module binders and both restore a parameter.

Lint aligned (src/lint_host.c E003, docs/DIAGNOSTICS.md): the resolver
encoded the old exception ("a function-level for var survives"). It now
loop-scopes every `for` binder, with a separate bind_scope so a body's
plain `is` binds in the enclosing function/module scope (#1056). That also
removes a pre-existing E003 false positive: a module-level
`for k ...: from_for is 4` followed by `print of from_for` was flagged
although the runtime binds it (the `blocks` road fixture). The [stdlib]
lint gate over lib/*.eigs stays clean, so a stdlib post-loop read of a
fresh binder is now caught statically as well as at runtime.

Inventory (a temporary compile-time diagnostic over every lib/, tests/,
examples/, tools/ .eigs): the only code reading a fresh function binder
after its loop was the two sites that asserted the exception --
tests/test_for_binder_scoped_in_function.eigs (f_fresh) and
tests/roads/binders.eigs (fresh_result). No stdlib function relied on it.

Regression tests:
- tests/test_for_binder_fresh_loop_scoped.eigs (new; run on the JIT and
  interpreter tiers in run_all_tests.sh): fresh binder raises after the
  loop and after break; body reads intact; post-loop write is a fresh
  binding; compound assign is loud; sequential and nested same-name
  loops; captured and interrogated (loop-env tier) binders also loud;
  parameter/local/plain-assigned restore (#1064) and body-fresh function
  scoping (#1056) unchanged; hot for-range value; module control.
  On the baseline binary 4 of its 16 checks fail (the slot-path cases).
- tests/roads/binders.eigs: fresh_result snapshots the caught message on
  all three roads; new shadow_result (fresh binder over a module name
  reads the module value after) and rebind_result controls. The baseline
  binary fails the fixture on all 6 runs (`+["fresh_result", 1, 8]`).
- tests/test_lint.sh: E003 fires on a function post-loop binder read;
  silent on post-loop reads of body-assigned names at both levels.

Residuals: `chunk->local_names[]` still carries the retired slot's name
(debugger/DAP variable listings show it as before); .claude/skills/
write-eigenscript/SKILL.md line 36 still describes for-body assignments
as loop-local (a #1056-era staleness, not this rule).

Closes #1105

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 docs/COMPARISON.md                            |  23 ++-
 docs/DIAGNOSTICS.md                           |   6 +-
 docs/LANGUAGE_CONTRACT.md                     |  17 +-
 docs/SPEC.md                                  |  30 +++-
 docs/llms.txt                                 |  11 +-
 lib/eigen.eigs                                |  33 +++-
 src/compiler.c                                |  27 ++-
 src/lint_host.c                               |  52 ++++--
 tests/roads/README.md                         |  14 +-
 tests/roads/binders.eigs                      |  18 +-
 tests/roads/binders.out                       |   4 +-
 tests/run_all_tests.sh                        |  12 +-
 tests/test_for_binder_fresh_loop_scoped.eigs  | 158 ++++++++++++++++++
 tests/test_for_binder_scoped_in_function.eigs |  12 +-
 tests/test_lint.sh                            |  40 ++++-
 tests/test_meta_parity.eigs                   |  34 ++++
 16 files changed, 431 insertions(+), 60 deletions(-)
 create mode 100644 tests/test_for_binder_fresh_loop_scoped.eigs

diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md
index af7fa942..47f13339 100644
--- a/docs/COMPARISON.md
+++ b/docs/COMPARISON.md
@@ -529,10 +529,25 @@ stops at the module boundary, preserving the importer's bindings. Top-level `ret
 load_file yields its value, import finishes its namespace, and main discards
 its value.
 
-The existing function-slot exception remains: a binder with no prior binding
-inside a function retains its final value after the loop on every road. A
-pre-existing parameter or local is restored. This change preserves that
-exception; see the scope notes in LANGUAGE_CONTRACT.md.
+There is no function-scope exception (#1105): a binder with no prior binding
+inside a function is loop-scoped like any other, so reading it after the loop
+raises `undefined variable` on every road (Python, by contrast, leaks the
+loop variable into the enclosing function). A pre-existing parameter, `local`
+or module binding is restored after the loop.
+
+```eigenscript
+define probe() as:
+    for z in [7, 8]:
+        0
+    return z
+try:
+    print of (probe of [])
+catch e:
+    print of e.message
+```
+```output
+undefined variable 'z'
+```
 
 <!-- Embed contract: #1038/#1028; language-level observer semantics unchanged. -->
 The C embedding API starts observer recording open. Source evals retain
diff --git a/docs/DIAGNOSTICS.md b/docs/DIAGNOSTICS.md
index 37aaedc4..ba32f4ef 100644
--- a/docs/DIAGNOSTICS.md
+++ b/docs/DIAGNOSTICS.md
@@ -413,8 +413,10 @@ two) — ROADMAP's sanctioned alternative to a type system. Its model:
   closures read enclosing function scopes; module names are
   order-insensitive (a body may read a module name bound after the
   definition); a nested `define` binds its name in the enclosing
-  function only; a **module-level `for` loop-scopes its variable** (the
-  VM drops it at loop exit — a function-level `for` var survives);
+  function only; a **`for` loop-scopes its variable at every level** (the
+  VM drops a module binder at loop exit and retires a function binder's
+  slot, #1105 — a post-loop read is a runtime error either way), while a
+  body's plain `is` binds in the enclosing function/module scope (#1056);
   listcomp and `catch` vars bind in the containing scope. Within a
   scope, "bound on some path" still suppresses (sibling-branch first
   assignments stay silent) — path-precise analysis is the remaining
diff --git a/docs/LANGUAGE_CONTRACT.md b/docs/LANGUAGE_CONTRACT.md
index 4975ac76..b5224741 100644
--- a/docs/LANGUAGE_CONTRACT.md
+++ b/docs/LANGUAGE_CONTRACT.md
@@ -113,10 +113,10 @@ partial AST — consistent with the **Errors** promise.
   continues; import finishes the module; the main program discards the value
   and exits successfully.
 
-The existing function-slot exception remains: a binder with no prior binding
-inside a function retains its final value after the loop on every road. A
-pre-existing parameter or local is restored. This change preserves that
-exception; see the scope notes in LANGUAGE_CONTRACT.md.
+There is no function-scope exception (#1105): a binder with no prior binding
+inside a function is loop-scoped like any other, and reading it after the loop
+raises `undefined variable` on every road. A pre-existing parameter, `local`
+or module binding is restored. See the scope notes below.
 
 **Status:** Enforced — `tools/road_diff.sh` and `tests/roads/`, `tests/test_import.eigs`,
 `tests/test_import_errors.eigs` (parse-error surfacing for `import` /
@@ -235,10 +235,11 @@ else is truthy (including functions).
   and each iteration binds a fresh variable (so closures created in a loop
   capture distinct values). Inside a function, a binder whose name was
   already bound (a parameter, a `local`, an earlier assignment) has that
-  earlier value again after the loop (#1064). Function-scope note: a binder
-  whose name had NO prior binding in the function stays readable after the
-  loop with its last value — the loop var lives in a frame slot there, and
-  the unbound case is not diagnosed the way module scope diagnoses it.
+  earlier value again after the loop (#1064). A binder whose name had NO
+  prior binding is loop-scoped in a function exactly as at module scope:
+  reading it after the loop is an `undefined variable` error (#1105), and a
+  later plain assignment to the name creates a fresh binding. One rule,
+  every scope, every road (main, `load_file`, `import`).
 - Name resolution walks the scope chain; an unresolved name is a fatal
   runtime error.
 - Functions resolve referenced names at call time (late binding), so
diff --git a/docs/SPEC.md b/docs/SPEC.md
index 29400947..6076e318 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -1180,10 +1180,32 @@ A top-level `return value` ends the current file, skipping all later statements:
 `load_file` yields the value to its caller; import finishes its namespace;
 the main program discards the value and exits successfully.
 
-The existing function-slot exception remains: a binder with no prior binding
-inside a function retains its final value after the loop on every road. A
-pre-existing parameter or local is restored. This change preserves that
-exception; see the scope notes in LANGUAGE_CONTRACT.md.
+There is no function-scope exception (#1105): a binder with no prior binding
+inside a function is loop-scoped like any other, so reading it after the loop
+raises `undefined variable` on every road. A pre-existing parameter, `local`
+or module binding is restored after the loop; a post-loop plain assignment to
+the name creates a fresh binding.
+
+```eigenscript
+define probe() as:
+    for z in [7, 8]:
+        0
+    return z
+try:
+    print of (probe of [])
+catch e:
+    print of e.message
+x is 5
+define over_module() as:
+    for x in [7, 8]:
+        0
+    return x
+print of (over_module of [])
+```
+```output
+undefined variable 'z'
+5
+```
 
 **Module write boundary.** A loaded (or imported) module's *functions*
 can read the loader's globals and call its functions, but they can
diff --git a/docs/llms.txt b/docs/llms.txt
index ff4b2f97..92c9c68c 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -68,11 +68,12 @@ not any outer `n`.
 - Two `local` traps: each **sibling `if`/`elif`/`else` branch** needs its own
   `local` for a first assignment (a `local` in one branch doesn't run for
   another), and a first assignment inside a `loop while` body needs `local`.
-- `if` blocks do NOT create a scope (assignments leak out). a `for` binder is loop-scoped
-  and never writes an outer binding; plain `is` in its body binds in the
-  enclosing scope, including an imported module. A fresh function-local
-  binder currently retains its slot after the loop (the existing exception). Comprehension variables
-  DO leak.
+- `if` blocks do NOT create a scope (assignments leak out). A `for` binder is loop-scoped
+  everywhere -- module scope AND inside a function -- and never writes an outer
+  binding; reading it after the loop is `undefined variable` (a pre-existing
+  parameter/local/module binding is restored instead). Plain `is` in its body
+  binds in the enclosing scope, including an imported module. Comprehension
+  variables DO leak.
 
 ## Reserved and soft keywords (cannot be plain variable names)
 
diff --git a/lib/eigen.eigs b/lib/eigen.eigs
index 79801705..637c4e06 100644
--- a/lib/eigen.eigs
+++ b/lib/eigen.eigs
@@ -1189,6 +1189,23 @@ define _env_set_local(env, name, val) as:
     append of [bindings, [name, val]]
     return null
 
+# #1105: the current env's OWN bindings only (no chain walk) -- a `for`
+# binder saves and restores exactly the scope it binds into.
+define _env_has_local(env, name) as:
+    bindings is env[0]
+    for i in range of (len of bindings):
+        if bindings[i][0] == name:
+            return 1
+    return 0
+
+define _env_unset_local(env, name) as:
+    bindings is env[0]
+    for i in range of (len of bindings):
+        if bindings[i][0] == name:
+            list_remove_at of [bindings, i]
+            return null
+    return null
+
 # Return / break / continue mechanism — global flags
 _eigen_returning is 0
 _eigen_return_val is null
@@ -1524,16 +1541,30 @@ define eigen_eval(node, env) as:
         var_name is node[1]
         iter is eigen_eval of [node[2], env]
         result is null
+        # #1105: the binder is loop-scoped. The C VM restores a binding the
+        # name already had (parameter, local, module name) and raises
+        # `undefined variable` on a post-loop read of a fresh one, in every
+        # scope and on every road. This evaluator binds the loop var straight
+        # into the current env, so mirror that by saving the current env's
+        # own binding (if any) and restoring or removing it on every exit.
+        had_prior is _env_has_local of [env, var_name]
+        prior_val is null
+        if had_prior == 1:
+            prior_val is _env_get of [env, var_name]
         for i in range of (len of iter):
             _env_set_local of [env, var_name, iter[i]]
             result is _eval_block of [node[3], env]
             if _eigen_returning == 1:
-                return result
+                break
             if _eigen_breaking == 1:
                 _eigen_breaking is 0
                 break
             if _eigen_continuing == 1:
                 _eigen_continuing is 0
+        if had_prior == 1:
+            _env_set_local of [env, var_name, prior_val]
+        else:
+            _env_unset_local of [env, var_name]
         return result
 
     if ntype == "func":
diff --git a/src/compiler.c b/src/compiler.c
index d6cb44fd..b4a7f527 100644
--- a/src/compiler.c
+++ b/src/compiler.c
@@ -29,6 +29,11 @@ typedef struct {
     int      depth;     /* scope depth (0 = function-level) */
     int      slot;
     int      captured;
+    int      retired;   /* #1105: a fresh `for` binder's slot after its loop.
+                         * Still owned by the frame (the slot index stays
+                         * allocated) but invisible to name resolution, so a
+                         * post-loop read compiles to OP_GET_NAME and raises
+                         * `undefined variable` like module scope does. */
 } Local;
 
 typedef struct {
@@ -570,6 +575,7 @@ static int add_num_constant(Compiler *c, double num) {
 
 static int resolve_local(Compiler *c, const char *name, uint32_t hash) {
     for (int i = c->local_count - 1; i >= 0; i--) {
+        if (c->locals[i].retired) continue;   /* #1105 */
         if (c->locals[i].hash == hash && strcmp(c->locals[i].name, name) == 0)
             return c->locals[i].slot;
     }
@@ -601,6 +607,7 @@ static int add_local(Compiler *c, const char *name, uint32_t hash) {
     c->locals[slot].depth = c->scope_depth;
     c->locals[slot].slot = slot;
     c->locals[slot].captured = 0;
+    c->locals[slot].retired = 0;
     c->local_count++;
     return slot;
 }
@@ -1771,7 +1778,7 @@ static int scan_dispatch_rebind_block(ASTNode **stmts, int count) {
 static int name_in_enclosing(Compiler *c, const char *name) {
     for (Compiler *e = c->enclosing; e && e->enclosing; e = e->enclosing) {
         for (int i = 0; i < e->local_count; i++)
-            if (strcmp(e->locals[i].name, name) == 0) return 1;
+            if (!e->locals[i].retired && strcmp(e->locals[i].name, name) == 0) return 1;
         if (name_set_has(&e->captured, name)) return 1;
         if (name_set_has(&e->interrogated, name)) return 1;
     }
@@ -2282,8 +2289,8 @@ static void compile_node_inner(Compiler *c, ASTNode *node) {
                          * 8 for p). Save the pre-loop value in a hidden slot
                          * and restore it at the loop exit (both the exhausted
                          * and the break paths converge there). A name with
-                         * NO prior binding keeps its fresh slot (see the
-                         * contract's function-scope note). */
+                         * NO prior binding gets a fresh slot that is
+                         * retired at the loop exit (#1105, below). */
                         prior_slot = loop_var_slot;
                         save_slot = add_local(c, "__for_save", env_hash_name("__for_save"));
                     } else
@@ -2422,6 +2429,20 @@ static void compile_node_inner(Compiler *c, ASTNode *node) {
             emit_op_u16(c, OP_GET_LOCAL, (uint16_t)save_slot, node->line);
             emit_op_u16(c, OP_SET_LOCAL, (uint16_t)prior_slot, node->line);
             emit(c, OP_POP, node->line);
+        } else if (can_skip_env && prior_slot < 0) {
+            /* #1105: a binder with NO prior binding is loop-scoped here
+             * exactly as at module scope. The slot was the loop's storage;
+             * once the loop is over, no later statement may resolve the
+             * name to it. Retiring it (rather than reusing it) keeps every
+             * GET_LOCAL/SET_LOCAL already emitted for the body valid and
+             * routes a post-loop read through OP_GET_NAME, which raises
+             * `undefined variable` unless an outer binding exists -- the
+             * same answer module scope gives. A post-loop write or a later
+             * `for` over the same name allocates a new slot. (A binder over
+             * an EXISTING slot whose #1064 save slot could not be allocated
+             * at MAX_LOCALS reaches here with prior_slot >= 0: that slot is
+             * the parameter/local itself and must never be retired.) */
+            c->locals[loop_var_slot].retired = 1;
         }
         emit(c, OP_NULL, node->line); /* for-loop result */
 
diff --git a/src/lint_host.c b/src/lint_host.c
index 104ebf83..485f7074 100644
--- a/src/lint_host.c
+++ b/src/lint_host.c
@@ -692,8 +692,11 @@ void check_stdlib_shadow(ASTNode *ast, const char *path,
  *   - module-level names are order-insensitive (a function body may read
  *     a module name bound after the definition);
  *   - a nested `define` binds its name in the ENCLOSING function only;
- *   - a module-level `for` LOOP-SCOPES its variable (reading it after
- *     the loop is a runtime error) — a function-level `for` does not;
+ *   - a `for` LOOP-SCOPES its variable at every level (#1105: reading
+ *     it after the loop is a runtime error inside a function too); a
+ *     body's plain `is` binds in the enclosing function/module scope,
+ *     not the loop (#1056), so a post-loop read of a body-assigned
+ *     name stays silent;
  *   - listcomp vars and catch vars bind in the containing scope.
  * Within a scope the binder set is still an over-approximation across
  * paths ("bound on some path" suppresses — the sibling-branch
@@ -730,9 +733,14 @@ void check_stdlib_shadow(ASTNode *ast, const char *path,
 typedef struct {
     Env *bind;                      /* base: builtins + flat external binders */
     Env *module_scope;              /* the linted file's top-level scope */
-    Env *scope;                     /* current scope (chains to bind via parents) */
+    Env *scope;                     /* current LOOKUP scope (chains to bind via parents) */
+    Env *bind_scope;                /* nearest function/module scope: where a
+                                     * plain `is`, a listcomp/catch var and a
+                                     * nested define's name bind. Differs from
+                                     * `scope` inside a `for`, whose pushed
+                                     * scope holds only the binder (#1105). */
     /* Scope registry: COLLECT creates one Env per scope-introducing node
-     * (function, lambda, module-level for) in walk order; FLAG re-enters
+     * (function, lambda, for) in walk order; FLAG re-enters
      * the same Envs by replaying the counter. Both walks visit the same
      * nodes in the same order, so the indices agree by construction. */
     Env *scopes[E003_MAX_SCOPES];
@@ -754,9 +762,14 @@ static void e003_bind_in(Env *env, const char *name) {
         env_set_local_owned(env, name, make_null());
 }
 
-/* Bind in the CURRENT scope — external (loaded-file) collection routes
- * flat to the base env instead. */
+/* Bind in the nearest function/module scope — external (loaded-file)
+ * collection routes flat to the base env instead. */
 static void e003_bind_name(E003 *e, const char *name) {
+    e003_bind_in(e->external ? e->bind : e->bind_scope, name);
+}
+
+/* #1105: a `for` binder lives in the loop's own lookup scope only. */
+static void e003_bind_loop_var(E003 *e, const char *name) {
     e003_bind_in(e->external ? e->bind : e->scope, name);
 }
 
@@ -922,6 +935,8 @@ static void e003_walk(ASTNode *n, E003 *e, LintContext *ctx, int mode) {
              * params and body binders live in the function's own scope. */
             if (mode == E003_COLLECT) e003_bind_name(e, n->data.func.name);
             Env *prev = e003_scope_push(e, mode);
+            Env *prev_bind = e->bind_scope;
+            e->bind_scope = e->scope;
             if (mode == E003_COLLECT)
                 for (int i = 0; i < n->data.func.param_count; i++)
                     e003_bind_name(e, n->data.func.params[i]);
@@ -931,28 +946,33 @@ static void e003_walk(ASTNode *n, E003 *e, LintContext *ctx, int mode) {
             for (int i = 0; i < n->data.func.body_count; i++)
                 e003_walk(n->data.func.body[i], e, ctx, mode);
             e->scope = prev;
+            e->bind_scope = prev_bind;
             break;
         }
         case AST_LAMBDA: {
             Env *prev = e003_scope_push(e, mode);
+            Env *prev_bind = e->bind_scope;
+            e->bind_scope = e->scope;
             if (mode == E003_COLLECT)
                 for (int i = 0; i < n->data.lambda.param_count; i++)
                     e003_bind_name(e, n->data.lambda.params[i]);
             e003_walk(n->data.lambda.body, e, ctx, mode);
             e->scope = prev;
+            e->bind_scope = prev_bind;
             break;
         }
         case AST_FOR: {
-            /* Module-level `for` LOOP-SCOPES its variable (the VM drops
-             * it at loop exit — reading it after the loop is a runtime
-             * error); a function-level `for` var is an ordinary local.
-             * The iterable is evaluated before the var exists, so it
-             * walks in the outer scope. */
+            /* A `for` LOOP-SCOPES its variable at every level (#1105: the
+             * VM drops a module binder at loop exit and retires a function
+             * binder's slot -- reading it after the loop is a runtime
+             * error either way). Only the binder lives in the pushed
+             * scope: a body's plain `is` binds in the enclosing
+             * function/module scope (#1056), through bind_scope. The
+             * iterable is evaluated before the var exists, so it walks in
+             * the outer scope. */
             e003_walk(n->data.forloop.iter, e, ctx, mode);
-            int module_level = (!e->external && e->scope == e->module_scope);
-            Env *prev = e->scope;
-            if (module_level) prev = e003_scope_push(e, mode);
-            if (mode == E003_COLLECT) e003_bind_name(e, n->data.forloop.var);
+            Env *prev = e003_scope_push(e, mode);
+            if (mode == E003_COLLECT) e003_bind_loop_var(e, n->data.forloop.var);
             for (int i = 0; i < n->data.forloop.body_count; i++)
                 e003_walk(n->data.forloop.body[i], e, ctx, mode);
             e->scope = prev;
@@ -1073,6 +1093,7 @@ void check_undefined_names(ASTNode *ast, const char *path,
     e.bind = env_new(NULL);
     e.module_scope = env_new(e.bind);
     e.scope = e.module_scope;
+    e.bind_scope = e.module_scope;
     register_builtins(e.bind);   /* store/gfx-when-built ride inside (#742) */
     /* Extension builtins bind by NAME regardless of this binary's build
      * flags (ext_names.h, the same lists their registrars expand): the lint
@@ -1138,6 +1159,7 @@ void check_undefined_names(ASTNode *ast, const char *path,
     e003_walk(ast, &e, NULL, E003_COLLECT);
     if (!e.dynamic) {
         e.scope = e.module_scope;   /* replay from the top */
+        e.bind_scope = e.module_scope;
         e.scope_idx = 0;
         e003_walk(ast, &e, ctx, E003_FLAG);
     }
diff --git a/tests/roads/README.md b/tests/roads/README.md
index 81dc8db0..4d2bc2a5 100644
--- a/tests/roads/README.md
+++ b/tests/roads/README.md
@@ -112,12 +112,14 @@ An inode-only scan memo missed the observing sibling and raised at runtime;
 the memo must include the containing directory. This was reproduced during
 #1056, and is why file provenance belongs in the scan as well as execution.
 
-`binders` deliberately retains the existing function-slot exception documented
-in LANGUAGE_CONTRACT.md: a binder with no prior binding in a function remains
-readable after the loop. On c1684bc `define f(): for z in [7, 8]: ...; return z`
-returns 8. This differs from module scope, but is uniform across roads; #1056
-does not change it. Pre-existing parameters, locals and module bindings are
-protected on every road.
+`binders` pins the uniform binder rule (#1105): a `for` binder with no prior
+binding is loop-scoped inside a function exactly as at module scope, so
+`define f(): for z in [7, 8]: ...; return z` raises `undefined variable 'z'`
+on every road (the fixture catches it and snapshots the message; before #1105
+the function returned 8 -- the retired "function-slot exception"). A fresh
+binder that shadows a module name reads the module value after the loop, and
+a post-loop write creates a fresh binding. Pre-existing parameters, locals and
+module bindings are restored on every road.
 
 The sanitizer run also checks compiler ownership: extending loop-binder
 tracking from functions to modules requires freeing the root compiler's
diff --git a/tests/roads/binders.eigs b/tests/roads/binders.eigs
index 0a4cd6ff..18e9c19a 100644
--- a/tests/roads/binders.eigs
+++ b/tests/roads/binders.eigs
@@ -1,4 +1,4 @@
-# road-bind: y x module_result function_result parameter_result local_result nested_result fresh_result k
+# road-bind: y x module_result function_result parameter_result local_result nested_result fresh_result shadow_result rebind_result k
 y is 100
 for y in [1, 2, 3]:
     y is y + 10
@@ -31,7 +31,21 @@ nested_result is nested of []
 define fresh() as:
     for z in [7, 8]:
         0
-    return z
+    try:
+        return z
+    catch e:
+        return e.message
 fresh_result is fresh of []
+define shadow() as:
+    for x in [7, 8]:
+        0
+    return x
+shadow_result is shadow of []
+define rebind() as:
+    for z in [7, 8]:
+        0
+    z is 5
+    return z
+rebind_result is rebind of []
 for k in [1, 2]:
     print of k
diff --git a/tests/roads/binders.out b/tests/roads/binders.out
index ac2fe93c..74666d14 100644
--- a/tests/roads/binders.out
+++ b/tests/roads/binders.out
@@ -7,5 +7,7 @@
 ["parameter_result", 1, 1]
 ["local_result", 1, 42]
 ["nested_result", 1, 30]
-["fresh_result", 1, 8]
+["fresh_result", 1, "undefined variable 'z'"]
+["shadow_result", 1, 5]
+["rebind_result", 1, 5]
 ["k", 0]
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index d33bcb4d..37042f59 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -3691,9 +3691,17 @@ check_eigs_suite "for binder in a loop env: body write lands in the loop env (#1
 # [70j] #1064 — a for binder that reuses an existing frame slot (parameter,
 # `local`, earlier assignment) is restored to its pre-loop value at loop exit
 # (exhausted and break paths), so the contract's "does not leak" holds inside
-# functions too. A binder with no prior binding keeps its function-scoped slot
-# (contract note).
+# functions too. A binder with no prior binding is loop-scoped as well since
+# #1105 (next block).
 check_eigs_suite "for binder over an existing slot is restored after the loop (#1064)" test_for_binder_scoped_in_function.eigs "All tests passed" 9
+# [70j2] #1105 -- a `for` binder with NO prior binding is loop-scoped inside a
+# function exactly as at module scope: the env-skip fast path's fresh frame
+# slot is retired at the loop exit, so a post-loop read raises
+# `undefined variable` (it returned the last element). Run on both tiers: the
+# hot for-range loop is JIT-compiled, and the post-loop read must be loud
+# whether or not the loop body went native.
+check_eigs_suite "fresh for binder is loop-scoped in a function too (#1105)" test_for_binder_fresh_loop_scoped.eigs "All tests passed" 16
+EIGS_JIT_OFF=1 check_eigs_suite "fresh for binder is loop-scoped in a function too, interpreter tier (#1105)" test_for_binder_fresh_loop_scoped.eigs "All tests passed" 16
 # [70k] #1062 — a module-scope `for` whose body reads the observer stays on the
 # CLEAR tier (the overwrite tier skipped the per-iteration reset of the binder's
 # observer slot, so `observe of i` accumulated across iterations for a
diff --git a/tests/test_for_binder_fresh_loop_scoped.eigs b/tests/test_for_binder_fresh_loop_scoped.eigs
new file mode 100644
index 00000000..4d702d79
--- /dev/null
+++ b/tests/test_for_binder_fresh_loop_scoped.eigs
@@ -0,0 +1,158 @@
+# test_for_binder_fresh_loop_scoped.eigs — #1105.
+#
+# LANGUAGE_CONTRACT: a `for` binder is loop-scoped everywhere. Module scope
+# always kept that promise (the binder lives in a loop env); inside a function
+# a binder with NO prior binding took the env-skip fast path, got a fresh
+# frame slot, and stayed readable after the loop with its last value
+# (`define f(): for z in [7, 8]: ...; return z` returned 8). The compiler now
+# retires that slot at the loop exit, so the post-loop read compiles to a
+# name lookup and raises `undefined variable` exactly as module scope does.
+# Every other tier (loop env for captured/interrogated/shadowing binders) and
+# the #1064 restore of a pre-existing binding are asserted unchanged here.
+# `--lint` reports E003 on the deliberate post-loop reads below: that is the
+# static form of the same rule (lint_host.c's E003 model was aligned in the
+# same change), so this file is intentionally not lint-clean.
+
+load_file of "lib/test.eigs"
+
+define kind_of(thunk) as:
+    try:
+        return ["ok", thunk of []]
+    catch e:
+        return ["err", e.kind]
+
+# (1) the issue: fresh binder, slot path -> loud after the loop
+define fresh() as:
+    for z in [7, 8]:
+        0
+    return z
+r1 is kind_of of fresh
+assert_true of [(r1[0] == "err") and (r1[1] == "undefined_name"), "fresh binder: post-loop read raises undefined_name (#1105)"]
+
+# (2) the body still sees its binder; only the post-loop read is gone
+define body_reads() as:
+    local seen is []
+    for z in [7, 8]:
+        append of [seen, z * 2]
+    return seen
+assert_true of [(str of (body_reads of [])) == "[14, 16]", "body reads the binder normally"]
+
+# (3) break path is loop-scoped too
+define brk() as:
+    for z in [1, 2, 3]:
+        if z == 2:
+            break
+    return z
+r3 is kind_of of brk
+assert_true of [(r3[0] == "err") and (r3[1] == "undefined_name"), "break path: binder still loop-scoped"]
+
+# (4) a post-loop plain write is a fresh binding, not an error
+define rebind() as:
+    for z in [7, 8]:
+        0
+    z is 5
+    return z
+assert_true of [(rebind of []) == 5, "post-loop write creates a fresh binding"]
+
+# (5) a compound write reads first, so it is loud
+define compound() as:
+    for z in [7, 8]:
+        0
+    z += 1
+    return z
+r5 is kind_of of compound
+assert_true of [(r5[0] == "err") and (r5[1] == "undefined_name"), "post-loop compound assign reads the dead binder: loud"]
+
+# (6) sequential loops over the same fresh name each get their own binder
+define twice() as:
+    local out is []
+    for z in [1, 2]:
+        append of [out, z]
+    for z in [30, 40]:
+        append of [out, z]
+    return out
+assert_true of [(str of (twice of [])) == "[1, 2, 30, 40]", "sequential same-name loops: each a fresh binder"]
+
+# (7) nested: the inner fresh binder is gone in the outer body
+define nested() as:
+    local out is []
+    for a in [1, 2]:
+        for b in [10]:
+            append of [out, a * b]
+        try:
+            append of [out, b]
+        catch e2:
+            append of [out, "no b"]
+    return out
+assert_true of [(str of (nested of [])) == "[10, \"no b\", 20, \"no b\"]", "inner fresh binder is not visible in the outer body"]
+
+# (8) a fresh binder that shadows a module name: the module value is back
+shadowed is 99
+define shadow() as:
+    for shadowed in [7, 8]:
+        0
+    return shadowed
+assert_true of [(shadow of []) == 99, "binder over a module name (loop-env tier): module value after the loop"]
+
+# (9) captured binder (loop-env tier because a closure reads it): loud too
+define captured() as:
+    local fns is []
+    for z in [1, 2]:
+        append of [fns, (q) => q + z]
+    return z
+r9 is kind_of of captured
+assert_true of [(r9[0] == "err") and (r9[1] == "undefined_name"), "captured binder (loop-env tier): post-loop read raises"]
+
+# (10) interrogated binder (loop-env tier): loud too
+define interrogated() as:
+    for z in [1, 2]:
+        w is who is z
+    return z
+r10 is kind_of of interrogated
+assert_true of [(r10[0] == "err") and (r10[1] == "undefined_name"), "interrogated binder (loop-env tier): post-loop read raises"]
+
+# (11) positive controls, #1064 unchanged: parameter / local / plain-assigned
+define f_param(p) as:
+    for p in [7, 8]:
+        p is p + 10
+    return p
+assert_true of [(f_param of 1) == 1, "parameter binder: restored (#1064 unchanged)"]
+define f_local() as:
+    local q is 42
+    for q in [7, 8]:
+        q is q + 10
+    return q
+assert_true of [(f_local of []) == 42, "local binder: restored (#1064 unchanged)"]
+define f_plain() as:
+    q is 20
+    for q in [7, 8]:
+        q is q + 10
+    return q
+assert_true of [(f_plain of []) == 20, "plain-assigned binder: restored (#1064 unchanged)"]
+
+# (12) body-fresh assignments (not the binder) still bind in the function scope
+define body_fresh() as:
+    for j in range of 3:
+        fin is j
+    return fin
+assert_true of [(body_fresh of []) == 2, "a body-fresh name is function-scoped (#1056 unchanged); only the binder is loop-scoped"]
+
+# (13) hot for-range over a fresh binder: the fast path still runs (value right)
+define hot(n) as:
+    local s is 0
+    for i in range of n:
+        s is s + i
+    return s
+assert_true of [(hot of 100000) == 4999950000, "hot for-range over a fresh binder: sum right"]
+
+# (14) module scope control: unchanged
+for m in [7, 8]:
+    0
+try:
+    print of m
+    mod_kind is "leaked"
+catch e3:
+    mod_kind is e3.kind
+assert_true of [mod_kind == "undefined_name", "module scope: still loop-scoped"]
+
+test_summary of null
diff --git a/tests/test_for_binder_scoped_in_function.eigs b/tests/test_for_binder_scoped_in_function.eigs
index 7965bdd5..2f8659ab 100644
--- a/tests/test_for_binder_scoped_in_function.eigs
+++ b/tests/test_for_binder_scoped_in_function.eigs
@@ -6,8 +6,9 @@
 # assignment -- reused the slot and the loop's last value became the name's
 # value afterwards (`define f(p): for p in [7, 8]: p is p + 10` returned 18).
 # The compiler now saves the pre-loop value and restores it at loop exit, on
-# both the exhausted and the break path. A name with NO prior binding keeps
-# its function-scoped slot (documented function-scope note).
+# both the exhausted and the break path. A name with NO prior binding is
+# loop-scoped too (#1105): its slot is retired at the loop exit, so a
+# post-loop read raises `undefined variable` exactly as module scope does.
 
 load_file of "lib/test.eigs"
 
@@ -63,8 +64,11 @@ assert_true of [(str of (f_nested of 0)) == "[10, 1, 10, 2, 0]", "nested same-na
 define f_fresh(q) as:
     for k in [1, 2]:
         k is k * 3
-    return k
-assert_true of [(f_fresh of 0) == 6, "fresh name (no prior binding): function-scoped slot, documented"]
+    try:
+        return k
+    catch e:
+        return e.kind
+assert_true of [(f_fresh of 0) == "undefined_name", "fresh name (no prior binding): loop-scoped, post-loop read raises (#1105)"]
 
 define f_range(n) as:
     local i is 99
diff --git a/tests/test_lint.sh b/tests/test_lint.sh
index 97c622e3..85e5ce58 100644
--- a/tests/test_lint.sh
+++ b/tests/test_lint.sh
@@ -1256,6 +1256,39 @@ OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
 check_contains "E003 fires on post-loop read of module for-var" "$OUTPUT" "undefined name 'item'"
 rm -f "$TMPFILE"
 
+# Fires (#1105): a FUNCTION-level `for` loop-scopes its variable too — the
+# VM retires the binder's frame slot at loop exit, so a post-loop read is
+# `undefined variable` inside a function exactly as at module scope.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+cat > "$TMPFILE" << 'EIGS'
+define probe() as:
+    for z in [7, 8]:
+        0
+    return z
+print of (probe of null)
+EIGS
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_contains "E003 fires on post-loop read of function for-var (#1105)" "$OUTPUT" "undefined name 'z'"
+rm -f "$TMPFILE"
+
+# Silent (#1056 rule, #1105 lint model): a body's plain `is` binds in the
+# enclosing function/module scope, not the loop — only the BINDER is
+# loop-scoped. Both levels; the module case was a false positive before.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+cat > "$TMPFILE" << 'EIGS'
+for k in range of 1:
+    from_for is 4
+print of from_for
+define fn() as:
+    for j in range of 2:
+        fin is j
+    return fin
+print of (fn of null)
+EIGS
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_not_contains "E003 silent on post-loop read of a body-assigned name (module + function)" "$OUTPUT" "E003"
+rm -f "$TMPFILE"
+
 # Near-miss suggestion: edit-distance-1 against the visible binding set.
 TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
 cat > "$TMPFILE" << 'EIGS'
@@ -1268,7 +1301,8 @@ rm -f "$TMPFILE"
 
 # Silent: the scope rules the runtime actually has — closures read
 # enclosing function locals; a function body reads a module name bound
-# after the definition; a FUNCTION-level for-var survives its loop;
+# after the definition; a parameter rebound by a `for` is restored after
+# the loop (#1064) and a body-assigned name is function-scoped (#1056);
 # a listcomp var leaks to the containing scope; a closure defined in a
 # module loop body reads the loop var.
 TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
@@ -1280,10 +1314,10 @@ define outer() as:
     return inner of null
 define late_reader() as:
     return bound_later
-define fn_for() as:
+define fn_for(j) as:
     for j in [1, 2]:
         x is j
-    return j
+    return j + x
 bound_later is 5
 squares is [v * v for v in [1, 2]]
 last_v is v
diff --git a/tests/test_meta_parity.eigs b/tests/test_meta_parity.eigs
index bcb9a2c2..b1b794a2 100644
--- a/tests/test_meta_parity.eigs
+++ b/tests/test_meta_parity.eigs
@@ -192,6 +192,40 @@ check of ["meta: host function operand is opaque", eigen_run of "report of print
 check of ["meta: dict fields named report/report_value stay data keys", eigen_run of "rdk is {\"report\": 7, \"report_value\": 8}\nrdk.report is 9\nrdk.report + rdk.report_value", 17]
 check of ["native: dict fields named report/report_value stay data keys", eval of "rdn is {\"report\": 7, \"report_value\": 8}\nrdn.report is 9\nrdn.report + rdn.report_value", 17]
 
+# --- #1105: a fresh `for` binder is loop-scoped in a function too (both raise) ---
+define meta_probe(src) as:
+    try:
+        return ["ok", eigen_run of src]
+    catch pe:
+        return ["err"]
+check of ["fresh function binder: meta raises after the loop",
+    meta_probe of "define probe() as:\n    for z in [7, 8]:\n        0\n    return z\nprobe of []",
+    ["err"]]
+check of ["fresh module binder: meta raises after the loop",
+    meta_probe of "for m in [7, 8]:\n    0\nm",
+    ["err"]]
+check of ["parameter binder: restored after the loop",
+    meta_probe of "define f(p) as:\n    for p in [7, 8]:\n        p is p + 10\n    return p\nf of 1",
+    ["ok", 1]]
+check of ["fresh binder over a module name: module value after the loop",
+    meta_probe of "x is 5\ndefine g() as:\n    for x in [7, 8]:\n        0\n    return x\ng of []",
+    ["ok", 5]]
+check of ["post-loop write is a fresh binding",
+    meta_probe of "define h() as:\n    for z in [7, 8]:\n        0\n    z is 5\n    return z\nh of []",
+    ["ok", 5]]
+# The C VM answers the same five programs (the oracle side of the parity).
+define vm_probe(src) as:
+    try:
+        return ["ok", eval of src]
+    catch ve:
+        return ["err"]
+check of ["VM: fresh function binder raises",
+    vm_probe of "define probe1105() as:\n    for z in [7, 8]:\n        0\n    return z\nprobe1105 of []",
+    ["err"]]
+check of ["VM: parameter binder restored",
+    vm_probe of "define f1105(p) as:\n    for p in [7, 8]:\n        p is p + 10\n    return p\nf1105 of 1",
+    ["ok", 1]]
+
 if checks == passed:
     print of "All tests passed"
 else:

From 2eabdd5298932c1a9d22e0169d1bdd4bd8c7ed75 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 00:20:53 +0000
Subject: [PATCH 05/39] observer: `unobserved:` keeps the value window complete
 (#1049)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An elided assignment was ABSENT from the observer's 10-deep value window,
so every value-channel verdict (`report`, the six predicates on a numeric
binding, `report_value`, a trajectory's rel/raw lists) differed from the
unelided program until the missing sample would have aged out. The
issue's two measurements, reconstructed as tests/test_unobserved_neutral.eigs:

  (1) an elided `b is 0.0` initialiser moved the window-fill boundary:
      observed-init   hits=31 at=[9, 10, 11, ...]
      unobserved-init hits=30 at=[10, 11, ...]     differing reads = [0, 5, 6, 9]
  (2) one elided assignment at read 50 of 80 (equal hit COUNTS):
      differing reads = [53, 60]  (the merged step, then its aging-out)

After: hits identical ([9, 10, 11, ...] both), differing reads = [] in both.

Root: OP_OBSERVE_ASSIGN_LOCAL / OP_OBSERVE_NAME_POST (and their JIT
helpers) skipped the WHOLE update under g_unobserved_depth. The block
exists to skip the expensive half — the entropy walk (entropy_of_num's
log2s, compute_entropy's O(children) pass) — not the O(1) sample. The
four sites now call observer_slot_sample[_num] when the depth is nonzero:
a scalar's rel/raw step enters the value ring and the slot counts as
`used`; a non-numeric value only flips the #861 route bit (no walk). Not
recorded for an elided assignment: entropy, dH and its window, obs_age,
the tape's observer snapshot, and the bare-predicate alias (kept on the
last OBSERVED binding so scratch work inside the block cannot hijack a
`loop while not converged`). Still elision-sensitive, documented in
PREDICATES.md "Inputs": `why`/`how`, `observe`'s dH pair, a snapshot's
dh/dH/last_entropy, `classify of [t, "entropy"]`, `report`/predicates on a
NON-numeric binding, the stall backstop, a bare predicate. Gated by the
#915 observer gate (eigs_obs_gate_open, now a static inline in
eigenscript.h so vm.c can ask it before resolving a name it will only
sample) — a program that never reads the observer still pays nothing.

One library relied on the old drop-the-sample behaviour: lib/experiment.eigs
(#735) seeded `tracker is 0` inside `unobserved:` so the seed-to-first-
reading jump would stay out of the window. Under #1049 that seed IS a
sample, and test_lab/test_experiment went red (ten identical readings no
longer read stable within 3). The block was never the right tool for
"declare without sampling"; the seed is now `tracker is null` — null and
boolean assignments are skipped by the observe ops on both paths — and
PREDICATES.md/SPEC.md document that idiom as the replacement.

Regression: tests/test_unobserved_neutral.eigs (section [51a], 26
checks) pins both probes as whole verdict STREAMS on the fn-local slot
path, the name path and a 20000-iteration JIT-hot loop; that the entropy
channel is still elided (empty dh window, dH untouched); the route bit;
the alias. Two existing checks pinned the old drop-the-sample behaviour
and were rewritten to the property: test_unobserved.eigs UO-871L (now
asserts the samples land AND the dH window is empty) and
test_observer_interactions.eigs OI-895 literals ("equilibrium" -> "moving",
observed 0 -> 1; the promoted == env-bound invariant is unchanged).

Cost (n=5 medians, this shared 4-CPU box, gate open): 400k two-assignment
loop inside `unobserved:` 21 ms -> 26 ms (4M iterations: 158 -> 227 ms,
~1.45x, ~8 ns/sample; variants that return early attribute ~2.5 ns to the
call + gate check, ~2.5 ns to the slot lookup, ~3-4 ns to the ring write,
and a deferred pending-value ring was prototyped at 216 ms — no better,
so the eager record stays); the README accumulator shape 253 -> 246 ms
(unchanged); a 20000-iteration container-assignment loop inside the block
5 -> 5 ms (the O(children) walk, 734 ms observed, is still elided). The
block still buys 2x on the pathological scalar loop and >100x on
container assignment; with the gate closed it costs zero.

Residual: ouroboros aot/aot_rt.h still returns early under
g_unobserved_depth (aot_observe / aot_observe_num), so the AOT diverges
from the VM on this until it calls observer_slot_sample[_num] — a
follow-up there at the next pin bump. lib/eigen.eigs models `unobserved`
as transparent with no window at all, so there is nothing to mirror.

Closes #1049

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 README.md                             |  12 +-
 docs/ARCHITECTURE.md                  |   3 +-
 docs/BUILTINS.md                      |   3 +-
 docs/COMPARISON.md                    |   9 +-
 docs/OBSERVER.md                      |  21 ++-
 docs/PREDICATES.md                    |  43 ++++++
 docs/SPEC.md                          |  45 +++++-
 docs/llms.txt                         |   4 +-
 lib/experiment.eigs                   |  29 ++--
 src/eigenscript.c                     |  62 +++++++-
 src/eigenscript.h                     |  15 ++
 src/vm.c                              |  37 ++++-
 tests/run_all_tests.sh                |  10 ++
 tests/test_observer_interactions.eigs |  13 +-
 tests/test_unobserved.eigs            |  13 +-
 tests/test_unobserved_neutral.eigs    | 212 ++++++++++++++++++++++++++
 16 files changed, 480 insertions(+), 51 deletions(-)
 create mode 100644 tests/test_unobserved_neutral.eigs

diff --git a/README.md b/README.md
index d5fe910e..6293f26f 100644
--- a/README.md
+++ b/README.md
@@ -225,10 +225,14 @@ unobserved:
         i is i + 1
 ```
 
-Inside the block, assignments to plain variables skip the observer and
-mutate the existing `Value` in place. Outside, normal behavior resumes.
-Measured 2.7x on a 2M-iteration accumulator loop (834ms → 307ms, n=5
-medians); iLambdaAi saw ~22% end-to-end on an 18-hour training run.
+Inside the block, assignments to plain variables skip the observer's
+entropy walk and mutate the existing `Value` in place. Outside, normal
+behavior resumes. Measured 2.7x on a 2M-iteration accumulator loop
+(834ms → 307ms, n=5 medians); iLambdaAi saw ~22% end-to-end on an
+18-hour training run. A scalar assignment inside the block still drops its
+O(1) sample into the value window (#1049), so the verdicts `report` and the
+predicates give a numeric binding are the same with the block as without
+it — only the entropy channel (`why`/`how`, the dH window) is elided.
 
 The block only helps **plain variables** — `x is ...`. A dict field or
 list element (`d.k is ...`, `xs[i] is ...`) is never observed in the
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index cb01e9c5..87d2d033 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -186,7 +186,8 @@ and drives `loop while not converged` termination.
 Observation uses lazy evaluation: `OP_OBSERVE_ASSIGN` marks values dirty
 (O(1)), and entropy is computed on demand when observer state is read.
 The last observed value is tracked via a thread-local pointer
-(`g_last_observer`). `unobserved` blocks skip observer marking entirely.
+(`g_last_observer`). `unobserved` blocks skip the entropy update; a scalar
+assignment inside one still records its value-window sample (#1049).
 
 Loop stall detection (`OP_LOOP_STALL_CHECK`) exits while-loops after 100
 consecutive iterations with `|dH| < threshold`, setting `__loop_exit__`
diff --git a/docs/BUILTINS.md b/docs/BUILTINS.md
index ea246e51..4c274539 100644
--- a/docs/BUILTINS.md
+++ b/docs/BUILTINS.md
@@ -242,7 +242,8 @@ sandbox allowlist can name them) but every call raises `value`:
 
 Six keywords for querying a value's observer state. Asking is cheap — the
 state is already there — but note that maintaining it is not free: every
-assignment outside `unobserved:` is sampled whether or not you ever ask. See
+assignment outside `unobserved:` is sampled whether or not you ever ask, and
+inside one a scalar still pays the O(1) value-window sample (#1049). See
 [OBSERVER.md](OBSERVER.md#cost).
 
 | Name | Syntax | Returns |
diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md
index 47f13339..71a7f477 100644
--- a/docs/COMPARISON.md
+++ b/docs/COMPARISON.md
@@ -346,9 +346,12 @@ contributes only its size term, #685). The boundary is explicit too: a
 binding holding a function classifies `opaque` — a function has no content
 to sample, and the observer names its blind spots (#708) rather than
 reporting a band it cannot defend. (The `unobserved` boundary is about
-observation only — assignments inside such a block are still counted by
-`when is x` and still addressable by ordinal, because a performance
-annotation must not change an answer, #908.) You can ask a variable about
+the entropy walk only — assignments inside such a block are still counted
+by `when is x` and still addressable by ordinal, #908, and a scalar's
+sample still enters the value window the numeric predicates read, #1049,
+because a performance annotation must not change an answer; what stays
+elided is entropy/dH, so `why`/`how` and the non-numeric route can still
+differ.) You can ask a variable about
 itself, terminate loops on *convergence* instead of a hand-written
 epsilon test, and read a variable's past:
 
diff --git a/docs/OBSERVER.md b/docs/OBSERVER.md
index 63a3e61b..2d704d50 100644
--- a/docs/OBSERVER.md
+++ b/docs/OBSERVER.md
@@ -409,9 +409,13 @@ One observation stands (not a defect — a property to know):
   time — has its window pushed on **every** assignment, with entropy and dH
   computed then and there. So `report of x` after a batch of writes reflects the
   whole window, not just the last value, and `loop while not converged` sees
-  each step because each `x is …` sampled it. `unobserved:` is the only thing
-  that skips the push — and the only thing that does. A binding you never
-  interrogate anywhere is still sampled on every assignment; see **Cost**.
+  each step because each `x is …` sampled it. `unobserved:` skips the
+  *entropy* push only (#1049): a scalar assignment inside the block still
+  lands in the value window the numeric predicates read, so their verdicts
+  do not change; `dH` and its window do not move — see
+  [PREDICATES.md](PREDICATES.md#inputs) for the readers that can differ. A
+  binding you never interrogate anywhere is still sampled on every
+  assignment; see **Cost**.
 
 ## Cost
 
@@ -436,8 +440,15 @@ everything it can reach; that distinction is what #685 was. The dH ring buffer
 is allocated lazily on a binding's **second** observation — again regardless of
 interrogation.
 
-`unobserved:` is the only opt-out, and it is a real one: it skips the emission,
-so a hot region inside it pays nothing.
+`unobserved:` is the only opt-out, and it is a real one: everything in the
+table above is skipped inside it. What it does *not* skip (#1049) is the O(1)
+value-window sample of a scalar assignment — one subtraction, one division,
+two ring stores — so that the block cannot change a numeric verdict.
+Measured on a 4M-iteration two-assignment loop with the gate open: observed
+~445 ms, inside `unobserved:` ~227 ms (was ~158 ms when the block also
+dropped the sample); a container-assignment loop inside the block is
+unchanged (the walk is what it elides). With the gate closed (below) the
+sample is skipped too and the block costs nothing.
 
 ### The automatic opt-out — the observer gate (#915/#972)
 
diff --git a/docs/PREDICATES.md b/docs/PREDICATES.md
index b528ec45..4cd6f9de 100644
--- a/docs/PREDICATES.md
+++ b/docs/PREDICATES.md
@@ -102,6 +102,49 @@ unconditionally (see [OBSERVER.md](OBSERVER.md#cost)). `unobserved:` is what
 avoids it. Arena values skip the buffer entirely —
 they cannot be tracked across resets.
 
+**What `unobserved:` elides, precisely (#1049).** An assignment inside the
+block still records its **value-channel** sample: a scalar's relative and
+raw step enter `v_window`/`vr_window` and `last_value` moves (O(1) — one
+subtraction, one division, two ring writes), and a non-numeric value flips
+the route bit exactly as an observed one would. So the window the numeric
+route reads is complete, and every verdict on that route — the six
+predicates on a numeric binding, `report`, `report_value`, a `trajectory`
+snapshot's `rel`/`raw` — is **identical with and without the block**
+(an elided `b is 0.0` initialiser no longer moves the window-fill
+boundary by one read; one elided step mid-stream no longer perturbs the
+next ten verdicts). What the block does not compute is the entropy walk
+and everything built on it, so these remain **elision-sensitive**:
+
+| Reader | Why it can differ under `unobserved:` |
+|---|---|
+| `why is x`, `how is x` | read `dH`, which the block never updates |
+| `observe of x` | its `dH`/`prev_dH` elements; the band is routed like `report` |
+| `trajectory of x` | the `dh` list, `dH`, `last_entropy` (`rel`/`raw`/`last_value` are complete) |
+| `classify of [t, "entropy"]` | the explicit entropy channel |
+| `report` / the six predicates on a **non-numeric** binding | the entropy route — its `dh_window` is missing the elided steps |
+| the loop stall backstop | reads the last observed slot's `dH` |
+| a **bare** predicate | reads the last **observed** binding — the alias is deliberately not moved by an elided assignment, so scratch work inside the block cannot hijack a `loop while not converged` |
+
+`where is x` is unaffected: it is recomputed from the current value at
+ask time (#711). A predicate asked *inside* the block still raises (#871).
+
+One consequence: `unobserved:` is no longer a way to **declare** a numeric
+binding without putting a sample in its window (the pre-#1049 idiom in
+`lib/experiment.eigs`, which seeded `tracker is 0` inside a block so the
+seed-to-first-reading jump would not sit at the head of the trajectory).
+Seed with `null` instead — null and boolean assignments are never sampled,
+on either path — and the first real reading is the first observation:
+
+```eigenscript
+define first_stable(values) as:
+    tracker is null            # declares the binding; not a sample
+    for v in values:
+        tracker is v
+        if stable of tracker:
+            return v
+    return null
+```
+
 `window` below means the `dh_window` contents oldest→newest;
 `count = window_size(v)` is how many real samples it holds (≤ N).
 
diff --git a/docs/SPEC.md b/docs/SPEC.md
index 6076e318..8605d2d1 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -1467,9 +1467,9 @@ diverging
 diverging
 ```
 
-`unobserved:` blocks (and `loop` bodies inside them) skip observer
-updates entirely — use them for hot numeric loops. The depth is
-dynamic, so it covers functions called from inside the block; an
+`unobserved:` blocks (and `loop` bodies inside them) skip the
+**entropy** half of observation — use them for hot numeric loops. The
+depth is dynamic, so it covers functions called from inside the block; an
 observer predicate asked anywhere under one **raises**, because there is
 no trajectory for it to classify (a performance annotation must not
 change an answer):
@@ -1487,14 +1487,49 @@ print of total
 4999950000
 ```
 
-What the block suppresses is **observation**, not assignment. The writes
-still happen, still land in the history, and are still counted and
+What the block suppresses is the **entropy walk**, not assignment. The
+writes still happen, still land in the history, and are still counted and
 addressed like any other: `when is x` includes them, and each one takes
 an ordinal that `<kw> is x when <n>` can address (#908). The same rule
 that makes a predicate raise rather than answer from a dead trajectory
 is why the counter does not quietly shrink — a performance annotation
 must not change an answer.
 
+For the same reason a scalar assignment inside the block still records
+its **sample into the value window** (#1049): the relative and raw step
+enter the 10-deep ring the numeric predicates, `report` and
+`report_value` read, at O(1) per assignment. So the window is complete,
+and the verdicts a numeric binding gives after (or inside) the block are
+identical to the ones it gives without it — an elided initialiser no
+longer shifts the window-fill boundary, and a mid-stream elided step no
+longer merges two steps into one. What is *not* computed for an elided
+assignment is the entropy and everything built on it: `where`'s stored
+entropy (the query-time read is unaffected), `dH` and its window
+(`why`/`how`, `observe`'s dH pair, a `trajectory` snapshot's `dh`/`dH`),
+the tape's observer snapshot, and the bare-predicate alias (a bare
+`converged` keeps reading the last **observed** binding, so scratch work
+inside the block cannot hijack it). Those entropy-channel readers — and
+`report`/the predicates on a **non-numeric** binding, which route
+through the entropy channel — therefore remain sensitive to elision;
+[PREDICATES.md](PREDICATES.md#inputs) lists them. (It follows that the
+block is not a way to declare a numeric binding without a sample; seed
+with `null`, which is never sampled.)
+
+```eigenscript
+x is 9.0
+unobserved:
+    x is x * 0.5
+    x is x * 0.5
+print of (report of x)
+print of (len of (trajectory of x).rel)
+print of (why is x)
+```
+```output
+moving
+2
+0
+```
+
 ```eigenscript
 c is 0
 c is 1
diff --git a/docs/llms.txt b/docs/llms.txt
index 92c9c68c..70351c02 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -117,7 +117,9 @@ print of ("sqrt(2) = " + (str of (newton_sqrt of 2)))   # sqrt(2) = 1.4142135623
   converges. Don't guess the predicate — see docs/PREDICATES.md.
 - Temporal reads: `prev of x` (value before the last assignment),
   `what is x at 12` / `state_at of 12` (past-line state). Bare `x at 12` is a
-  parse error. Wrap hot loops in `unobserved:` to skip observer bookkeeping.
+  parse error. Wrap hot loops in `unobserved:` to skip the observer's entropy
+  walk (a scalar's value-window sample still lands, so numeric verdicts do not
+  change; `why`/`how` and non-numeric bindings' verdicts can).
 
 ## Values and strings
 
diff --git a/lib/experiment.eigs b/lib/experiment.eigs
index e662af86..9a68d650 100644
--- a/lib/experiment.eigs
+++ b/lib/experiment.eigs
@@ -16,16 +16,19 @@
 # identifies behavioral regimes, and convergence detection
 # determines when measurements have stabilized.
 #
-# Each analyzer declares its `tracker` inside `unobserved:` (#735). Seeding it
-# with an OBSERVED sentinel put a synthetic `0 -> values[0]` entropy jump at
-# the head of the trajectory, which is a real step to every windowed predicate:
-# ten identical readings then carried one large dH and no band fired. The
-# sentinel is a declaration, not a measurement, so it must not be observed.
+# Each analyzer declares its `tracker` before its loop by seeding it with
+# `null`. Seeding it with a NUMERIC sentinel put a synthetic `0 -> values[0]`
+# jump at the head of the trajectory (#735), which is a real step to every
+# windowed predicate: ten identical readings then carried one large step and
+# no band fired. The sentinel is a declaration, not a measurement, so it must
+# not enter the window — and since #1049 `unobserved:` no longer keeps a
+# scalar OUT of the value window (an elided sample still lands, so the block
+# cannot change a verdict), the only seed that is never sampled is a
+# non-numeric one: `null` (and booleans) are skipped by the observe ops.
 
 # ---- track_measurements: annotate each measurement with observer state ----
 define track_measurements(values) as:
-    unobserved:
-        tracker is 0        # seed unobserved — see the note above
+    tracker is null         # a declaration, never sampled — see the note above
     results is []
 
     for i in range of (len of values):
@@ -43,8 +46,7 @@ define track_measurements(values) as:
 
 # ---- is_measurement_stable: check if recent measurements are stable ----
 define is_measurement_stable(values, min_stable_count) as:
-    unobserved:
-        tracker is 0        # seed unobserved — see the note above
+    tracker is null         # a declaration, never sampled — see the note above
     stable_count is 0
 
     for i in range of (len of values):
@@ -59,8 +61,7 @@ define is_measurement_stable(values, min_stable_count) as:
 
 # ---- detect_entropy_spikes: find anomalies via entropy derivative ----
 define detect_entropy_spikes(values, threshold) as:
-    unobserved:
-        tracker is 0        # seed unobserved — see the note above
+    tracker is null         # a declaration, never sampled — see the note above
     spikes is []
 
     for i in range of (len of values):
@@ -74,8 +75,7 @@ define detect_entropy_spikes(values, threshold) as:
 
 # ---- convergence_rate: estimate how fast a sequence converges ----
 define convergence_rate(values) as:
-    unobserved:
-        tracker is 0        # seed unobserved — see the note above
+    tracker is null         # a declaration, never sampled — see the note above
     dH_values is []
 
     for i in range of (len of values):
@@ -100,8 +100,7 @@ define convergence_rate(values) as:
 
 # ---- detect_regimes: identify behavioral phase transitions ----
 define detect_regimes(values) as:
-    unobserved:
-        tracker is 0        # seed unobserved — see the note above
+    tracker is null         # a declaration, never sampled — see the note above
     regimes is []
     current_status is ""
     regime_start is 0
diff --git a/src/eigenscript.c b/src/eigenscript.c
index 50309d3b..cdb4c31a 100644
--- a/src/eigenscript.c
+++ b/src/eigenscript.c
@@ -601,23 +601,21 @@ static void observer_slot_update_e(Env *e, int idx, double new_entropy) {
     s->used = 1;
 }
 
-/* #915: the one place the observer gate is decided.
+/* #915: the one place the observer gate is decided — eigs_obs_gate_open,
+ * a static inline in eigenscript.h (#1049 moved it there so the observe ops
+ * in vm.c can ask it too).
  *
  * g_obs_needed is the compile-time half: chunk_reads_observer said some unit in
  * this state can interrogate. g_trace_obs_hist is the runtime half: a tape is
  * recording observer snapshots, so the bookkeeping is needed even though the
  * PROGRAM never asks for it.
  *
- * The trace flag is READ here rather than mirrored into g_obs_needed at each of
+ * The trace flag is READ there rather than mirrored into g_obs_needed at each of
  * the five sites that arm it (builtins.c, chunk.c, compiler.c x2, repl.c).
  * Mirroring would be five hand-maintained copies of one fact, and a sixth arming
  * site added later would silently record a tape full of dead observer snapshots
  * — the same drift shape #921/#925 are open on. One read, no copies. */
-extern int g_trace_obs_hist_storage;   /* trace.h — not included here */
 #define g_trace_obs_hist __atomic_load_n(&g_trace_obs_hist_storage, __ATOMIC_RELAXED)
-static inline int eigs_obs_gate_open(void) {
-    return g_obs_needed || g_trace_obs_hist;
-}
 
 void observer_slot_update(Env *e, int idx, Value *newval) {
     /* #915: nothing compiled into this state can interrogate the observer, so
@@ -660,6 +658,58 @@ void observer_slot_update_num(Env *e, int idx, double num) {
     if (vs) observer_slot_record_value(vs, num);
 }
 
+/* #1049: the ELIDED assignment — what an `unobserved:` block still records.
+ *
+ * The block exists to skip the expensive half of an observation: the entropy
+ * walk (entropy_of_num's two log2s for a scalar, compute_entropy's
+ * O(children) pass for a container) and the dH bookkeeping built on it. It
+ * used to skip the whole update, so an elided assignment was ABSENT from the
+ * value window, and every value-channel verdict (`report`, the six predicates
+ * on a numeric binding, `report_value`, a trajectory snapshot's rel/raw
+ * lists) differed from the unelided program until the missing sample would
+ * have aged out of the 10-deep window: an elided `b is 0.0` initialiser
+ * moved the window-fill boundary by one read, a mid-stream elision merged two
+ * steps into one. A performance annotation was changing answers.
+ *
+ * So the O(1) half still runs here: a scalar's sample enters the value ring
+ * (observer_slot_record_value — one subtraction, one division, two ring
+ * writes, no log2), and the slot counts as having a trajectory (`used`,
+ * with obs_age untouched so the next OBSERVED assignment still seeds the
+ * entropy channel as a first observation). A non-numeric value only flips
+ * the route bit (v_last) the way an observed one would, so a binding rebound
+ * from number to container inside the block routes to the entropy channel
+ * exactly as it does outside — nothing is walked. What is NOT recorded:
+ * entropy, dH, the dH window, obs_age, the tape's observer snapshot, and the
+ * bare-predicate alias (g_last_obs_slot_*) — that alias is deliberately left
+ * on the last OBSERVED binding, because shielding a bare `loop while not
+ * converged` from scratch work is one of the block's documented uses. The
+ * entropy-channel readers (`why`/`how`, `observe`'s dH pair, a snapshot's
+ * `dh` list, `classify of [t, "entropy"]`, and `report`/predicates on a
+ * NON-numeric binding) therefore remain elision-sensitive; PREDICATES.md
+ * says so. Gated by the same #915 observer gate as the full update: a
+ * program nothing in which reads the observer still pays nothing. */
+void observer_slot_sample_num(Env *e, int idx, double num) {
+    if (!eigs_obs_gate_open()) return;
+    if (!e || idx < 0) return;
+    if (idx >= e->obs_cap && !observer_obs_grow(e, idx)) return;
+    ObserverSlot *s = env_obs_slot(e, idx);
+    if (!s) return;
+    observer_slot_record_value(s, num);
+    s->used = 1;
+}
+
+void observer_slot_sample(Env *e, int idx, Value *newval) {
+    if (!eigs_obs_gate_open()) return;
+    if (newval && newval->type == VAL_NUM) {
+        observer_slot_sample_num(e, idx, newval->data.num);
+        return;
+    }
+    if (!e || idx < 0) return;
+    if (idx >= e->obs_cap && !observer_obs_grow(e, idx)) return;
+    ObserverSlot *s = env_obs_slot(e, idx);
+    if (s) s->v_last = 0;   /* #861 route bit only — no walk, no `used` */
+}
+
 void observer_slot_reset(Env *e) {
     if (!e || !e->obs) return;
     vm_obs_slot_dropped(e);   /* invalidate the VM's last-observed-slot tracker */
diff --git a/src/eigenscript.h b/src/eigenscript.h
index 3d46f39c..4fe253a8 100644
--- a/src/eigenscript.h
+++ b/src/eigenscript.h
@@ -367,6 +367,11 @@ size_t observer_window_size(const Value *v);
 void observer_slot_update(struct Env *e, int idx, Value *newval);
 /* #262 Phase-3 D: slot update from a raw immediate number (no Value needed). */
 void observer_slot_update_num(struct Env *e, int idx, double num);
+/* #1049: the elided (`unobserved:`) assignment — value-window sample only,
+ * no entropy walk. What the observe ops call when g_unobserved_depth != 0;
+ * exported so the AOT runtime can call the same thing instead of skipping. */
+void observer_slot_sample(struct Env *e, int idx, Value *newval);
+void observer_slot_sample_num(struct Env *e, int idx, double num);
 void observer_slot_reset(struct Env *e);
 /* Observed-loop halting on an explicit env (no VM-frame dependency): one
  * iteration of OP_LOOP_STALL_CHECK / OP_LOOP_CAP_CHECK. Returns 1 when the loop
@@ -1443,6 +1448,16 @@ static inline struct ObserverSlot *env_obs_slot(Env *e, int idx) {
     return &e->obs[idx];
 }
 
+/* #915/#1049: the observer gate as every TU sees it — g_obs_needed is the
+ * compile-time half, the trace-history flag the runtime half. The full
+ * rationale is on observer_slot_update (eigenscript.c). Lives here so the
+ * observe ops in vm.c can ask it before resolving a name they will only
+ * sample (#1049). */
+extern int g_trace_obs_hist_storage;   /* trace.h — the relaxed-load idiom */
+static inline int eigs_obs_gate_open(void) {
+    return g_obs_needed || __atomic_load_n(&g_trace_obs_hist_storage, __ATOMIC_RELAXED);
+}
+
 Env* env_new(Env *parent);
 void env_global_shared_lock(void);    /* #1035: module-env lock for external readers */
 void env_global_shared_unlock(void);
diff --git a/src/vm.c b/src/vm.c
index eb313418..9be38309 100644
--- a/src/vm.c
+++ b/src/vm.c
@@ -1579,13 +1579,18 @@ void jit_helper_observe_assign(EigsChunk *chunk, int name_idx) {
 }
 
 void jit_helper_observe_assign_local(int slot) {
-    if (g_unobserved_depth != 0) return;
     /* #262 Phase-3/E — slot model: observe the persistent (fn_env, slot)
      * trajectory directly from TOS. No promotion, no Value-side state, no window
      * migration (the slot persists across assigns). */
     CallFrame *frame = &g_vm.frames[g_vm.frame_count - 1];
     EigsSlot s = g_vm.stack[g_vm.sp - 1];
     Env *e = frame->fn_env;
+    if (g_unobserved_depth != 0) {
+        /* #1049: elided — value-window sample only (mirrors the CASE body). */
+        if (slot_is_num(s))      observer_slot_sample_num(e, slot, s.d);
+        else if (slot_is_ptr(s)) observer_slot_sample(e, slot, slot_as_ptr(s));
+        return;
+    }
     if (slot_is_num(s)) {
         observer_slot_update_num(e, slot, s.d);
         g_last_obs_slot_env = e; g_last_obs_slot_idx = slot;
@@ -1622,7 +1627,10 @@ void jit_helper_report_slot(int slot) {
 /* OP_OBSERVE_NAME_POST [name_idx] — observe a name binding's slot from TOS
  * after its SET. Peeks TOS; no stack change. Mirrors CASE(OBSERVE_NAME_POST). */
 void jit_helper_observe_name_post(EigsChunk *chunk, int name_idx) {
-    if (g_unobserved_depth != 0) return;
+    /* #1049: inside `unobserved:` the name is still resolved (when the #915
+     * gate is open) so the elided assignment's sample reaches the value
+     * window; only the entropy update, alias and tape snapshot are skipped. */
+    if (g_unobserved_depth != 0 && !eigs_obs_gate_open()) return;
     CallFrame *frame = &g_vm.frames[g_vm.frame_count - 1];
     EigsSlot s = g_vm.stack[g_vm.sp - 1];
     /* #262 Phase-3 D: TOS may be an immediate num (the default path no longer
@@ -1634,6 +1642,11 @@ void jit_helper_observe_name_post(EigsChunk *chunk, int name_idx) {
     if (h == 0) { h = env_hash_name(name); if (chunk->const_hashes) chunk->const_hashes[name_idx] = h; }
     int oidx = -1, odepth = 0;
     Env *oe = env_resolve_chain(frame->env, name, h, &oidx, &odepth);
+    if (oe && oidx >= 0 && g_unobserved_depth != 0) {
+        if (slot_is_num(s)) observer_slot_sample_num(oe, oidx, s.d);
+        else                observer_slot_sample(oe, oidx, slot_as_ptr(s));
+        return;
+    }
     if (oe && oidx >= 0) {
         if (slot_is_num(s)) observer_slot_update_num(oe, oidx, s.d);
         else observer_slot_update(oe, oidx, slot_as_ptr(s));
@@ -5014,6 +5027,15 @@ static Value *vm_run_ex(EigsChunk *chunk, Env *env, Task *resume,
                 observer_slot_update(e, (int)slot, slot_as_ptr(s));
                 g_last_obs_slot_env = e; g_last_obs_slot_idx = (int)slot;
             }
+        } else {
+            /* #1049: elided assignment — the sample still enters the value
+             * window (O(1)); the entropy walk, the bare-predicate alias and
+             * the tape snapshot are what the block skips. See
+             * observer_slot_sample_num (eigenscript.c). */
+            EigsSlot s = g_vm.stack[g_vm.sp - 1];
+            Env *e = frame->fn_env;
+            if (slot_is_num(s))      observer_slot_sample_num(e, (int)slot, s.d);
+            else if (slot_is_ptr(s)) observer_slot_sample(e, (int)slot, slot_as_ptr(s));
         }
         DISPATCH();
     }
@@ -5229,7 +5251,11 @@ static Value *vm_run_ex(EigsChunk *chunk, Env *env, Task *resume,
          * still on TOS (SET peeked, didn't pop). Fixes the first-assignment
          * lag for name bindings. Emitted only under the compile-time flag. */
         uint16_t name_idx = read_u16(ip); ip += 2;
-        if (g_unobserved_depth == 0) {
+        /* #1049: inside `unobserved:` the binding is still resolved (when the
+         * #915 gate is open) so the elided assignment's sample reaches the
+         * value window; the entropy update, the alias and the tape snapshot
+         * are what the block skips. Mirrors jit_helper_observe_name_post. */
+        if (g_unobserved_depth == 0 || eigs_obs_gate_open()) {
             EigsSlot s = g_vm.stack[g_vm.sp - 1];
             /* #262 Phase-3 D: TOS is now an immediate num for an observed name
              * (default path no longer promotes), or a heap value. Observe the
@@ -5240,7 +5266,10 @@ static Value *vm_run_ex(EigsChunk *chunk, Env *env, Task *resume,
                 if (h == 0) { h = env_hash_name(name); if (chunk->const_hashes) chunk->const_hashes[name_idx] = h; }
                 int oidx = -1, odepth = 0;
                 Env *oe = env_resolve_chain(frame->env, name, h, &oidx, &odepth);
-                if (oe && oidx >= 0) {
+                if (oe && oidx >= 0 && g_unobserved_depth != 0) {
+                    if (slot_is_num(s)) observer_slot_sample_num(oe, oidx, s.d);
+                    else                observer_slot_sample(oe, oidx, slot_as_ptr(s));
+                } else if (oe && oidx >= 0) {
                     if (slot_is_num(s)) observer_slot_update_num(oe, oidx, s.d);
                     else observer_slot_update(oe, oidx, slot_as_ptr(s));
                     g_last_obs_slot_env = oe;
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 37042f59..02d8bce8 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -2845,6 +2845,16 @@ else
 fi
 echo ""
 
+# [51a] #1049: `unobserved:` is verdict-neutral for the value channel. An
+# elided scalar assignment still lands in the value window (O(1)); only the
+# entropy walk is skipped. Both issue measurements (elided initialiser at the
+# window-fill boundary; one mid-stream elision) compare whole verdict streams,
+# on the fn-local slot path, the name path and the JIT-hot path.
+echo "[51a] Unobserved Verdict Neutrality (#1049)"
+check_eigs_suite "unobserved: elided samples still enter the value window; entropy channel still elided (#1049)" \
+    test_unobserved_neutral.eigs "All tests passed" 26
+echo ""
+
 # [52] Stream I/O
 echo "[52] Stream Tensor I/O"
 SI_OUTPUT=$(./eigenscript ../tests/test_stream_io.eigs 2>&1); SI_OUTPUT_RC=$?
diff --git a/tests/test_observer_interactions.eigs b/tests/test_observer_interactions.eigs
index 53d8a0a0..54a563fa 100644
--- a/tests/test_observer_interactions.eigs
+++ b/tests/test_observer_interactions.eigs
@@ -164,7 +164,10 @@ if rep_g == "stable":
 # variable" two lines above a plain read of `m` that works. The answers
 # below must be the ones the same code gives when the name is NOT
 # promoted: an optimization may not change an answer, and it may
-# certainly not turn one into an error.
+# certainly not turn one into an error. (The literal answers moved with
+# #1049: the block no longer drops the samples from the value window, so
+# a 9.0 -> 4.5 step reads "moving" and the binding counts as observed;
+# the invariant under test — promoted == env-bound — is unchanged.)
 
 unobserved:  # lint: allow W020 -- promotion of a block-local name is the point
     m895 is 9.0
@@ -176,10 +179,10 @@ unobserved:  # lint: allow W020 -- promotion of a block-local name is the point
     plain895 is m895
 
 assert of [plain895 == 4.5, "OI-895 the plain read still works"]
-assert of [rep895 == "equilibrium", "OI-895 report of a promoted name resolves"]
-assert of [repv895 == "equilibrium", "OI-895 report_value of a promoted name resolves"]
-assert of [traj895.observed == 0, "OI-895 trajectory of a promoted name resolves"]
-assert of [obs895[0] == "equilibrium", "OI-895 observe of a promoted name resolves"]
+assert of [rep895 == "moving", "OI-895 report of a promoted name resolves"]
+assert of [repv895 == "moving", "OI-895 report_value of a promoted name resolves"]
+assert of [traj895.observed == 1, "OI-895 trajectory of a promoted name resolves"]
+assert of [obs895[0] == "moving", "OI-895 observe of a promoted name resolves"]
 
 # Same block, but the name escapes it, so nothing is promoted and the
 # *_NAME opcodes run. The answers must be identical.
diff --git a/tests/test_unobserved.eigs b/tests/test_unobserved.eigs
index 070a0567..0cf02557 100644
--- a/tests/test_unobserved.eigs
+++ b/tests/test_unobserved.eigs
@@ -188,13 +188,24 @@ assert of [(nested_return of 0) == 7, "UO-871L nested return still returns"]
 assert of [(moving_probe of 0) == "moving", "UO-871L nested return restores every level"]
 
 # 6. and the block still WORKS after all that — it is not stuck off either.
+# What "works" means changed with #1049: the block elides the ENTROPY half of
+# an observation (the walk, dH, the dH window), while a scalar sample still
+# enters the value window so verdicts stay identical with and without the
+# block. This used to assert `report of m == "equilibrium"` — i.e. that the
+# two elided samples were ABSENT — which pinned the very behaviour #1049
+# removed. The property is: value samples land, the entropy channel does not
+# move.
 seen_inside is ""
 m is 9.0
 unobserved:  # lint: allow W020 -- checking the block is still functional
     m is m * 0.5
     m is m * 0.5
     seen_inside is report of m
-assert of [seen_inside == "equilibrium", "UO-871L the block still suppresses observation"]
+    traj_inside is trajectory of m
+assert of [seen_inside == "moving", "UO-871L/1049 the elided samples are in the value window"]
+assert of [(len of traj_inside.rel) == 2, "UO-871L/1049 both elided steps were recorded"]
+assert of [(len of traj_inside.dh) == 0, "UO-871L/1049 the block still elides the entropy channel (no dH window)"]
+assert of [(why is m) == 0, "UO-871L/1049 dH was never computed for the elided steps"]
 assert of [(moving_probe of 0) == "moving", "UO-871L and normal observation resumes after it"]
 
 # ---- #908: `when is x` counts assignments made inside the block ----
diff --git a/tests/test_unobserved_neutral.eigs b/tests/test_unobserved_neutral.eigs
new file mode 100644
index 00000000..de9f1c7c
--- /dev/null
+++ b/tests/test_unobserved_neutral.eigs
@@ -0,0 +1,212 @@
+# #1049: `unobserved:` is verdict-neutral for the value channel.
+#
+# The block exists to elide the EXPENSIVE half of an observation — the entropy
+# walk. It used to elide the whole update, so an elided assignment was absent
+# from the 10-deep value window and every value-channel verdict (`report`, the
+# six predicates on a numeric binding, `report_value`, a snapshot's rel/raw
+# lists) differed from the unelided program until the missing sample would
+# have aged out. A performance annotation was changing answers.
+#
+# Now a scalar assignment inside the block still records its sample into the
+# value window (O(1)); entropy / dH / the dH window are what is not computed.
+# These checks compare whole verdict STREAMS (per read), not counts — the
+# issue's second measurement had equal totals and four differing reads.
+load_file of "lib/test.eigs"
+
+# ---- Probe 1 (issue measurement 1): an elided initialiser used to shift the
+# window-fill boundary. `converged` needs a full 10-step value window, so the
+# first hit lands on the read where the window fills — one read later when the
+# initialiser's sample is missing. fn-local slot path (OBSERVE_ASSIGN_LOCAL).
+define run1(elide_init) as:
+    if elide_init == 1:
+        unobserved:  # lint: allow W020 -- the elided initialiser is the point
+            b is 0.0
+    else:
+        b is 0.0
+    hits is []
+    verdicts is []
+    amp is 0.0004
+    k is 0
+    loop while k < 40:
+        b is amp * (k % 2)             # settled: a decaying sub-deadband wobble
+        amp is amp * 0.9
+        append of [verdicts, report of b]
+        if converged of b:
+            append of [hits, k]
+        k is k + 1
+    return [hits, verdicts]
+
+o1 is run1 of 0
+u1 is run1 of 1
+assert_eq of [str of (o1[0][0:3]), "[9, 10, 11]", "P1 control: the observed-init window fills at read 9"]
+assert_eq of [str of u1[0], str of o1[0], "P1 hit INDICES identical with the initialiser elided"]
+assert_eq of [str of u1[1], str of o1[1], "P1 verdict stream identical with the initialiser elided"]
+assert_eq of [len of u1[0], len of o1[0], "P1 hit count identical"]
+
+# ---- Probe 2 (issue measurement 2): one mid-stream elided assignment (read
+# 50 of 80) used to merge two steps into one and perturb the verdicts until it
+# aged out of the window (reads 50..59), with the COUNT unchanged.
+define run2(elide_at) as:
+    b is 0.0
+    hits is []
+    verdicts is []
+    k is 0
+    loop while k < 80:
+        nb is b + (1.0 - b) * 0.3
+        if k % 7 == 0:
+            nb is nb - 0.02
+        if k == elide_at:
+            unobserved:  # lint: allow W020 -- the one elided sample is the point
+                b is nb
+        else:
+            b is nb
+        append of [verdicts, report of b]
+        if stable of b:
+            append of [hits, k]
+        k is k + 1
+    return [hits, verdicts]
+
+o2 is run2 of (0 - 1)
+u2 is run2 of 50
+distinct2 is []
+for v2 in o2[1]:
+    if not (contains of [distinct2, v2]):
+        append of [distinct2, v2]
+assert_true of [(len of distinct2) >= 2, "P2 control: the stream is not one constant verdict"]
+assert_eq of [str of u2[1], str of o2[1], "P2 verdict stream identical with read 50 elided"]
+assert_eq of [str of u2[0], str of o2[0], "P2 hit indices identical with read 50 elided"]
+
+# ---- Name path (OBSERVE_NAME_POST): the same two probes at module scope,
+# where the binding is an env name rather than a frame slot.
+unobserved:  # lint: allow W020 -- elided initialiser, name path
+    nu is 0.0
+no is 0.0
+namp is 0.0004
+nk is 0
+n_hits_o is []
+n_hits_u is []
+n_verd_o is []
+n_verd_u is []
+loop while nk < 40:
+    nu is namp * (nk % 2)
+    no is namp * (nk % 2)
+    namp is namp * 0.9
+    append of [n_verd_o, report of no]
+    append of [n_verd_u, report of nu]
+    if converged of no:
+        append of [n_hits_o, nk]
+    if converged of nu:
+        append of [n_hits_u, nk]
+    nk is nk + 1
+assert_eq of [str of (n_hits_o[0:3]), "[9, 10, 11]", "N1 control: the name-path window fills at read 9"]
+assert_eq of [str of n_hits_u, str of n_hits_o, "N1 name path: hit indices identical with the initialiser elided"]
+assert_eq of [str of n_verd_u, str of n_verd_o, "N1 name path: verdict stream identical"]
+
+mo is 0.0
+mu is 0.0
+mk is 0
+m_verd_o is []
+m_verd_u is []
+loop while mk < 80:
+    mno is mo + (1.0 - mo) * 0.3
+    mnu is mu + (1.0 - mu) * 0.3
+    if mk % 7 == 0:
+        mno is mno - 0.02
+        mnu is mnu - 0.02
+    mo is mno
+    if mk == 50:
+        unobserved:  # lint: allow W020 -- the one elided sample, name path
+            mu is mnu
+    else:
+        mu is mnu
+    append of [m_verd_o, report of mo]
+    append of [m_verd_u, report of mu]
+    mk is mk + 1
+assert_eq of [str of m_verd_u, str of m_verd_o, "N2 name path: verdict stream identical with read 50 elided"]
+
+# ---- JIT-hot path: a 20000-iteration loop with the assignment inside the
+# block on every iteration, so the JIT thunk's helper (jit_helper_observe_
+# assign_local) is what records. The value windows must be byte-identical to
+# the observed run; the entropy channel must still be empty.
+define hot(elide) as:
+    x is 0.0
+    k is 0
+    loop while k < 20000:
+        nx is 1.0 + ((k % 3) - 1) * 0.001
+        if elide == 1:
+            unobserved:
+                x is nx
+        else:
+            x is nx
+        k is k + 1
+    return trajectory of x
+
+th_o is hot of 0
+th_u is hot of 1
+assert_eq of [len of th_o.rel, 10, "J control: the observed window is full"]
+assert_eq of [str of th_u.rel, str of th_o.rel, "J hot loop: rel window identical"]
+assert_eq of [str of th_u.raw, str of th_o.raw, "J hot loop: raw window identical"]
+assert_eq of [th_u.last_value, th_o.last_value, "J hot loop: last value identical"]
+assert_eq of [classify of th_u, classify of th_o, "J hot loop: snapshot classifies identically"]
+assert_eq of [th_u.observed, 1, "J the sampled binding counts as observed"]
+assert_eq of [len of th_o.dh, 10, "J control: the observed dH window is full"]
+assert_eq of [len of th_u.dh, 0, "J the ENTROPY channel is still elided: no dH window"]
+assert_eq of [th_u.dH, 0, "J the ENTROPY channel is still elided: dH never computed"]
+
+# ---- Route bit: a non-numeric elided assignment ends the numeric route
+# exactly as an observed one does (O(1), no walk), so `report` does not answer
+# from a stale numeric trajectory after the block.
+define route(elide) as:
+    y is 1.0
+    y is 1.5
+    y is 2.0
+    if elide == 1:
+        unobserved:  # lint: allow W020 -- the route flip is the point
+            y is [1, 2]
+    else:
+        y is [1, 2]
+    return [report of y, report_value of y]
+
+ro is route of 0
+ru is route of 1
+assert_true of [ro[0] != "moving", "R control: the observed container routes to the entropy channel"]
+assert_true of [ru[0] != "moving", "R an elided container also leaves the numeric route"]
+assert_eq of [ru[1], ro[1], "R the explicit value channel is identical either way"]
+
+# ---- What the block still skips is documented, and pinned here so the
+# elision stays real: dH/why is not computed for an elided assignment.
+define why_probe(elide) as:
+    w is 4.0
+    w is 2.0
+    if elide == 1:
+        unobserved:  # lint: allow W020 -- dH elision is the point
+            w is 1.0
+    else:
+        w is 1.0
+    return why is w
+
+define why_before() as:
+    w is 4.0
+    w is 2.0
+    return why is w
+
+assert_true of [(why_probe of 0) != (why_before of 0), "W control: an observed assignment moves dH"]
+assert_eq of [why_probe of 1, why_before of 0, "W an elided assignment leaves dH at the previous OBSERVED step's"]
+
+# ---- The bare-predicate alias (the last OBSERVED binding) is not moved by an
+# elided assignment: shielding a bare `loop while not converged` from scratch
+# work inside the block is one of its documented uses.
+define alias_probe() as:
+    a is 1.0
+    i is 0
+    loop while i < 12:
+        i is i + 1
+        a is 1.0                       # last OBSERVED assignment: the alias points at `a`
+    unobserved:  # lint: allow W020 -- the alias is the point
+        scratch is 5.0
+        scratch is 50.0
+    return converged  # lint: allow W016 -- the bare alias is exactly what is under test
+
+assert_eq of [alias_probe of 0, 1, "A bare predicate still reads the last OBSERVED binding after the block"]
+
+test_summary of null

From f167c20d9422856538d5376a4353eb91ec382d30 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 17:14:46 +0000
Subject: [PATCH 06/39] observer: configurable window depth + scale-free
 relative step (#1044, #1045)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both were found by phugoid grading observer verdicts against a physical
oracle. Baseline (v0.43.0) reproduction, in the phugoid repo:

  eigenscript tests/observer_check.eigs
    O.ph1s.t120/t200/t280   stable / diverging / improving  (truth: oscillating)
  eigenscript tests/observer_lat_check.eigs
    O2.units.rad/deg/mrad   converged / moving / moving     (one trajectory)

#1045 — rel = dv / max(|v|, |v_prev|, scale). The old dv/(1+|v|) was the
entropy normalisation borrowed as a step: below |v| ~ 1 the denominator is
~1 and rel is just dv, an absolute deadband, so the unit a value was stored
in decided the verdict. The step's own local scale is the textbook relative
step, symmetrised (|rel| <= 2, defined across a zero crossing); `scale`
(set_observer_scale / get_observer_scale, default 1e-3) is the magnitude
below which a value counts as "at zero" and the deadband turns absolute
(|dv| < dh_zero*scale = 1e-6). Read as the textbook criterion, `converged`
is |dx| <= rtol*|x| with rtol = dh_zero and atol = dh_zero*scale.

The default 1e-3 against the bar's three properties: (a) the rad/deg/mrad
triplet at 0.0124 rad sits 12x above the scale, so all three read `moving`
(fixture U1-U5); (b) rounding noise around an exact zero is 1e-16/1e-3 =
1e-13 relative and certifies (Z1-Z2); (c) a geometric decay keeps
rel = 1 - r until inside the scale — 1e6*0.3^k reads `improving` at
x = 14.3 and first certifies at x = 5.6e-12, 8*0.5^k at 1.9e-9 (D1-D5).
A larger scale (1e-2) leaves only 1.24x margin on (a); a smaller one only
lengthens decays' certification. NOT the window's running max |v| that the
design first proposed: for a monotone decay that maximum is the OLDEST
sample, so rel = (1-r)*r^(N-1) and any r < ~0.5 certifies at the first full
window regardless of how far the value still is from its limit (1e6*0.3^k
at x ~= 1.8) — and a wider #1044 window makes it worse (r^49 at N = 50).
The local scale keeps the two knobs independent.

#1044 — set_observer_window of n (state default, live, like the
thresholds) and set_observer_window of ["x", n] (one binding, resolved by
name from the call site; a string-literal operand marks a fn-local
interrogated so plain locals are reachable; ["x", 0] clears), 4..64, 10 at
start; get_observer_window of null | "x". Rings carry a capacity (v_cap /
dh_cap) and grow on the next push when the depth in force exceeds it
(samples preserved, oldest first); a smaller depth reads the newest N.
The default depth allocates exactly what it did before. A trajectory
snapshot carries `window`, so classify of (trajectory of x) agrees with
report of x. The tape/step/DAP slot rebuilds read the same state default.

After (this build): the 1 Hz phugoid (T = 46.9 s) with w1 widened to 50
reads oscillating at all three probes, and a full-window census over 186
samples is {"oscillating": 186} — `diverging` never appears (it is 71 of
269 at N = 10, measured in the same run on a sibling binding). Unit
triplet with default knobs: moving / moving / moving.

Regression test: tests/test_observer_window_scale.eigs, section [51b]
(34 checks): the unit triplet, noise-around-zero, decay-to-zero at two
ratios, the scale knob restoring the old shape, the synthetic phugoid at
N = 10 (control: diverging present) and N = 50 (never), the three probes,
the sibling-binding control, snapshot depth, clear/default/narrow forms,
fn-local reach, and the loud errors. Planted faults, rebuilt and run:
F1 (old dv/(1+|v|) step) -> 6 FAIL (U1-U5, D5; rad=converged deg=moving);
F2 (obs_win pinned to 10, knob ignored) -> 12 FAIL (P1-P16; probes
stable/diverging/stable).

Flipped fixtures, each decided (no blind re-baselining):
- test_predicate_matrix "#735 residual drift": 0.9*0.5^20 = 8.6e-7 with
  steps still 50% of |m| -> `improving` is right (property (c)); pinned at
  20 as improving, and converged at 30 once ten steps sit under 1e-6.
- test_observer_saturation run_converge, test_report_alignment RA3,
  test_step.sh fixture: 30 halvings of 100/1024 end at 1e-7..1e-6 with only
  the last step under the absolute floor -> `improving`; 40 halvings settle
  (converged). The absolute settle floor moved from dh_zero to dh_zero*scale.
- test_unobserved_neutral: a 4e-4 wobble around zero is 40% of the scale —
  real motion; the "sub-deadband" amplitude is 4e-7 now. Elision-neutrality,
  the property under test, holds identically.
- Doc examples [89]/[90]: none flipped.
- phugoid oracle rows (external, not pinned here), default knobs:
  O.sp.t29 converged->moving (measured on this build: w goes -0.014923 ->
  -0.015066 -> -0.015212 m/s, a 1.46e-4 step = 0.96% of |w| per sample and
  still growing in magnitude — the old `converged` was the absolute
  deadband reading 1.46e-4 < 1e-3, i.e. it depended on w being stored in
  m/s; in mm/s the same physics read `moving`), O2.units.rad
  converged->moving (the fix), O2.roll.fast stable->moving (draining 2.5%
  per step), O2.phi.t35 converged->oscillating (a decaying 0.6 mrad DR
  residual is a damped oscillation). All four are pinned by phugoid as
  divergence-class rows that flip loudly on exactly this change.

Validation: release suite 4308/4308, 0 failed; ASan+UBSan suite with
ASAN_OPTIONS=detect_leaks=1 4309/4309, 0 failed, no "NOTE: N test
program(s)" line — leak tally 0, unchanged (the lazy rings are freed on the
same slot teardown as before, and a grow/shrink/re-grow stress across every
depth 4..64 is ASan-clean). tools/replay_diff.sh OK (232 programs, 0
ledgered) and tools/jit_diff.sh OK (232 x {jit, osr}, 0 ledgered);
test_spawn_channel_exit.eigs segfaults on its replay arm on the BASE commit
too — pre-existing, not from this change.

Tape/step parity: a recorded tape stepped with --step prints the same
verdicts as the live run (spiral=moving, osc=oscillating, conv=converged);
tests/test_step.sh (22 checks) passes with the new formula.

Cost (n=5, user CPU, under load ~8 on 4 cores, provisional): 400k observed
scalar loop 0.036 -> 0.038 s median; 4M loop 0.338 -> 0.346 s median
(+2.4%). The hot path reads the state default with one branch and two loads
— the depth is validated at the seam, so nothing is re-clamped per
assignment.

The sandbox allowlist deliberately does NOT gain these four builtins: the
setters mutate process-global state (the rule set_observer_thresholds is
already out for), and the getters stay out under the fail-closed default.

Residuals: the tape does not record set_observer_window/set_observer_scale
calls (nor set_observer_thresholds — the pre-existing class), so `--step`
verdicts on a program that changes the knobs at runtime use the defaults;
a computed (non-literal) name in the per-binding form only reaches
name-resolvable bindings; the rung-2 fast-mode sibling (O2.roll.fast) wants
a narrower window or a coarser cadence, documented, not a knob default.
lib/eigen.eigs models only the pointwise entropy predicates — no mirror.

Closes #1044
Closes #1045

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 docs/BUILTINS.md                      |  10 +-
 docs/COMPARISON.md                    |   6 +-
 docs/OBSERVER.md                      |  13 +-
 docs/PREDICATES.md                    | 114 ++++++++++-
 docs/SPEC.md                          |  25 ++-
 docs/llms.txt                         |  10 +-
 src/builtins.c                        | 119 +++++++++++
 src/compiler.c                        |  22 +++
 src/eigenscript.c                     | 273 +++++++++++++++++++-------
 src/eigenscript.h                     |  37 +++-
 src/lsp_builtin_index.h               |   4 +
 src/state.c                           |   2 +
 tests/run_all_tests.sh                |  11 ++
 tests/test_observer_saturation.eigs   |   6 +-
 tests/test_observer_window_scale.eigs | 245 +++++++++++++++++++++++
 tests/test_predicate_matrix.eigs      |  14 +-
 tests/test_report_alignment.eigs      |   5 +-
 tests/test_step.sh                    |  13 +-
 tests/test_unobserved_neutral.eigs    |   7 +-
 19 files changed, 822 insertions(+), 114 deletions(-)
 create mode 100644 tests/test_observer_window_scale.eigs

diff --git a/docs/BUILTINS.md b/docs/BUILTINS.md
index 4c274539..4abcdebe 100644
--- a/docs/BUILTINS.md
+++ b/docs/BUILTINS.md
@@ -28,7 +28,9 @@ streaming subprocess I/O (`proc_spawn`, `proc_write`, `proc_read_line`,
 `sha256_file`, `md5_file`, `hmac_sha256`), EigenStore (`store_open`,
 `store_close`, `store_put`, `store_get`, `store_delete`, `store_query`,
 `store_count`, `store_update`, `store_collections`, `store_drop`),
-observer tuning (`set_observer_thresholds`, `get_observer_thresholds`),
+observer tuning (`set_observer_thresholds`, `get_observer_thresholds`,
+`set_observer_scale`, `get_observer_scale`, `set_observer_window`,
+`get_observer_window`),
 audio (`audio_open`, `audio_close`, `audio_pause`, `audio_play`,
 `audio_play_loop`, `audio_volume`, `audio_stop`, `audio_queue_size`, `audio_clear`, `audio_sine`,
 `audio_saw`, `audio_sweep`,
@@ -271,6 +273,12 @@ Query a binding's assignment history. Always on for top-level bindings;
 | Name | Signature | Description |
 |------|-----------|-------------|
 | `observe` | `observe of value` | Return [status, entropy, dH, prev_dH] snapshot |
+| `set_observer_thresholds` | `set_observer_thresholds of [dh_zero, dh_small, h_low]` | Set the classification thresholds (defaults 0.001 / 0.01 / 0.1); `dh_zero < dh_small`, all positive, else raises. Process-global for the state; blocked in the sandbox |
+| `get_observer_thresholds` | `get_observer_thresholds of null` | `[dh_zero, dh_small, h_low]` |
+| `set_observer_scale` | `set_observer_scale of s` | #1045: the value channel's characteristic scale — the magnitude below which a value counts as zero. The relative step is `Δv / max(\|v\|, \|v_prev\|, s)`: unit-free above `s`, an absolute deadband `dh_zero·s` below it. Default `0.001`; choose it in the unit the binding is stored in. Non-positive raises |
+| `get_observer_scale` | `get_observer_scale of null` | The characteristic scale |
+| `set_observer_window` | `set_observer_window of n` / `set_observer_window of ["x", n]` | #1044: the window depth (samples) every verdict classifies over, `4..64`. The bare form sets the state default (10 at start), live; the list form overrides one binding, resolved by name from the call site (a string literal also marks a function local interrogated so plain locals are reachable), `n = 0` clears it. A mode slower than `n` samples of the observation cadence cannot fold inside the window — size it to the slowest mode. Unbound name / out-of-range depth raise |
+| `get_observer_window` | `get_observer_window of null` / `get_observer_window of "x"` | The default depth, or the depth in force on binding `x` |
 | `classify` | `classify of t` or `classify of [t, "entropy"]` | Classify a trajectory snapshot (from `trajectory of x`, #421): value-channel label by default, entropy-channel with `"entropy"`. Raises `type_mismatch` on a non-snapshot — a bare value never silently classifies |
 
 **`report` and `report_value` are reserved** (#1102). They cannot be bound or
diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md
index 71a7f477..5d867f3a 100644
--- a/docs/COMPARISON.md
+++ b/docs/COMPARISON.md
@@ -327,8 +327,10 @@ sqrt(2) = 1.414213562373095
 ```
 
 `converged` reads the loop's last-assigned value and fires once a full
-window of its relative steps sits under the settle deadband — the standard
-mixed-tolerance stopping criterion, built in (#861). This run exits
+window of its relative steps (`Δv` over the step's own scale, #1045 — so
+the unit the value is stored in does not matter) sits under the settle
+deadband — the standard mixed-tolerance stopping criterion, built in
+(#861). This run exits
 through the predicate itself in 13 iterations; the deadband is the
 tolerance (`set_observer_thresholds`), and an input that genuinely
 diverges ends via the observer's stall backstop with
diff --git a/docs/OBSERVER.md b/docs/OBSERVER.md
index 2d704d50..93303918 100644
--- a/docs/OBSERVER.md
+++ b/docs/OBSERVER.md
@@ -95,6 +95,10 @@ lines are the three thresholds:
 ```eigenscript
 set_observer_thresholds of [dh_zero, dh_small, h_low]
 # defaults: 0.001, 0.01, 0.1
+set_observer_scale of scale      # the value channel's "what counts as zero" (#1045)
+# default: 0.001
+set_observer_window of n         # how many samples a verdict spans (#1044)
+# default: 10; per binding: set_observer_window of ["x", n]
 ```
 
 So `set_observer_thresholds` is not a minor tuning footnote. **It is the
@@ -169,8 +173,15 @@ in the flat-entropy plateau around 5 — see #294.)
 
 `report_value of x` classifies the **value's own trajectory** instead, using
 the identical windowed logic and thresholds on the value's relative step
-`Δv/(1+|x|)` (relative, so the bands mean the same across value scales). On the
+`Δv / max(|x|, |x_prev|, scale)` (#1045 — relative to the step's own local
+scale, so the bands mean the same across value scales *and units*; `scale`,
+`set_observer_scale`, default `0.001`, is the magnitude below which a value
+counts as zero and the deadband turns absolute). On the
 same oracle it answers `moving`/`oscillating` — correctly never `converged`.
+The window the bands read is `N` samples deep — 10 by default,
+`set_observer_window` per state or per binding (#1044): a mode slower than
+`N` samples of the observation cadence cannot fold inside it, so size the
+window to the slowest mode you expect (PREDICATES.md "The window").
 Its vocabulary is `oscillating` (sign of `Δv` keeps flipping), `diverging`
 (non-vanishing same-sign steps — see below), `converged` (a full window of
 ~zero relative steps), `stable` (small relative steps, no flips), `moving`
diff --git a/docs/PREDICATES.md b/docs/PREDICATES.md
index 4cd6f9de..24d3d8fb 100644
--- a/docs/PREDICATES.md
+++ b/docs/PREDICATES.md
@@ -29,7 +29,8 @@ under noise — see "Pointwise behavior replaced" in each section.)
 
 The predicate words and `report` are **routed**: a binding whose most
 recent observed assignment is **numeric** answers from the **value
-channel** — the classifier below, over relative steps `Δv/(1+|v|)`; every
+channel** — the classifier below, over relative steps
+`rel = Δv / max(|v|, |v_prev|, scale)` (#1045); every
 other binding (strings, containers) answers from the **entropy channel**,
 the windowed formulas in "The six predicates". `report_value of x` is the
 value-channel classifier by name (identical to the routed words on a
@@ -48,8 +49,10 @@ gave the same computation targeting 5000, 5 and 0.005 three different
 verdicts. The value channel scores 25/27; the two misses are the
 irreducible tolerance floor, not defects (see the honesty bound below).
 
-**The numeric definitions** (window `N = 10` relative steps
-`rel = Δv/(1+|v|)`, raw steps `Δv` kept alongside — #422):
+**The numeric definitions** (window `N` relative steps — `N = 10` by
+default, per state or per binding via `set_observer_window`, see [The
+window](#the-window-1044) — `rel = Δv / max(|v|, |v_prev|, scale)`, raw
+steps `Δv` kept alongside — #422):
 
 | band | fires when |
 |---|---|
@@ -66,6 +69,33 @@ bands exclude the raw structure tests; the motion bands are mutually
 exclusive. `report` resolves the canonical priority `oscillating →
 diverging → improving → converged → equilibrium → stable → moving`.
 
+**The relative step is scale-free (#1045).** `rel` divides the raw step
+by the step's own local scale, `max(|v|, |v_prev|)`, floored at the
+state's **characteristic scale** (`set_observer_scale of s`, default
+`0.001`). Above the scale a verdict is **unit-free**: one physical
+trajectory stored in radians, degrees or milliradians reads the same
+(phugoid's spiral mode — bank angle `0.0124 rad = 0.71 deg = 12.4 mrad`,
+halving every 14.9 s, replayed at 1 Hz — reads `moving` in all three;
+`tests/test_observer_window_scale.eigs`). Below the scale the deadband
+turns absolute: `|Δv| < dh_zero · scale` (`1e-6` by default), so
+rounding noise around an exact zero (`Δv ~ 1e-16`) is not motion, and a
+geometric decay toward zero keeps `rel = 1 − r` — `improving`, never
+`converged` — until it is inside the scale. Read as the textbook
+criterion, `converged` is `|Δx| ≤ rtol·|x|` with `rtol = dh_zero` and an
+absolute floor `atol = dh_zero · scale`. The previous step,
+`Δv/(1+|v|)`, was the entropy formula's normalisation borrowed as a step:
+below `|v| ~ 1` it was just `Δv`, an absolute deadband, and the unit the
+consumer stored the value in decided the verdict. The scale is the one
+number a unit choice still touches — choose it in the unit the binding
+is stored in (a bank angle kept in radians with milliradian relevance
+wants `set_observer_scale of 1e-6`; `set_observer_scale of 1` restores the
+old absolute shape for values under 1). Why the local scale and not the
+window's running maximum: for a monotone decay that maximum is the
+*oldest* sample, so `rel = (1−r)·r^(N−1)` and any ratio under ~0.5 would
+certify `converged` at the first full window no matter how far from its
+limit the value still was (`1e6·0.3^k` at `x ≈ 1.8`) — and a wider window
+would make it worse.
+
 **The honesty bound.** `converged` is a **stopping criterion, not a
 proof**: it means *settled at the deadband* — every recent step below the
 tolerance — which is the strongest claim a finite window supports.
@@ -90,7 +120,7 @@ assigned top-level value (`g_last_observer`):
 | `entropy` | current information content `where is x` — **recomputed from the value present at ask time** (#711), so in-place mutation is visible | `compute_entropy_impl` via `observer_entropy_now` |
 | `dH` | change since previous observation `why is x` — a trajectory of **assignments**; mutation does not move it, and a query never writes back | `update_observer` (`new − last`) |
 | `prev_dH` | the previous step's `dH` | `update_observer` |
-| `dh_window` | ring buffer of the last `OBSERVER_WINDOW_N` (=10) `dH` values | `observer_window_push` in `update_observer` |
+| `dh_window` | ring buffer of the last `N` `dH` values (`N` = the window depth in force, 10 by default — [The window](#the-window-1044)) | `observer_window_push` in `update_observer` |
 | `obs_age` | number of observations since the value first existed | `update_observer` |
 
 The ring buffer is allocated lazily on the *second* observation (the
@@ -160,13 +190,79 @@ h_low    = 0.1     entropy below this is "low information content"
 
 Override with `set_observer_thresholds of [dh_zero, dh_small, h_low]`.
 
-Two derived window constants (functions of `N = OBSERVER_WINDOW_N = 10`):
+A fourth number, the value channel's characteristic scale (#1045):
+
+```
+scale    = 0.001   |v| below this counts as "at zero": rel = Δv / max(|v|, |v_prev|, scale)
+```
+
+Override with `set_observer_scale of s` (`get_observer_scale of null`
+reads it). See "The relative step is scale-free" above for what it means.
+
+Two derived window constants (functions of the window depth `N`, 10 by
+default):
 
 ```
 VOTE  = 0.6                min fraction of genuine same-direction steps for improving/diverging
-FLIPS = ceil(N / 3)  = 4   min sign-flips in the window for oscillating
+FLIPS = ceil(N / 3)  = 4   min sign-flips in the window for oscillating (17 at N = 50)
 ```
 
+## The window (#1044)
+
+Every predicate classifies over the last `N` **samples** — observed
+assignments, not seconds. The depth is configurable:
+
+```eigenscript
+set_observer_window of 30           # the state default (4..64; 10 at start)
+set_observer_window of ["u", 50]    # one binding, by name — only that slot
+set_observer_window of ["u", 0]     # clear the override, back to the default
+get_observer_window of null         # -> 30
+get_observer_window of "u"          # -> 50
+```
+
+Both forms take effect **live**, like the thresholds: a binding already
+carrying a trajectory classifies over the new depth at its next verdict
+(its ring grows on the next sample, keeping what it holds; a smaller
+depth reads fewer samples). The per-binding form resolves the name from
+the call site the way `report of x` does; a string-literal operand also
+marks a function local interrogated, so the knob reaches plain locals. An
+override lives on the **binding**, exactly like the trajectory it governs:
+a global keeps it for the run, a function local gets it per call (set it
+where the local is initialised). A `trajectory of x` snapshot carries its
+depth (`t.window`), so `classify` of it agrees with the live verdict. An
+unbound name, a depth outside `4..64` or a non-integer raise.
+
+**Time versus samples.** A mode slower than about `N` samples of the
+consumer's cadence cannot fold inside the window, and the failure is not
+insensitivity — the verdict is confidently wrong. The 747 phugoid
+(`T = 46.9 s`, physics truth `oscillating` throughout) replayed through
+a binding at 1 Hz with the default `N = 10` reads `diverging` on its
+rising quarter-cycles and `stable`/`improving` elsewhere; the same signal
+decimated to 5 s (9.4 samples per cycle) reads `oscillating` at every
+probe. The folding rule (≥ 2 reversals, net travel ≤ 0.3× path) is the
+right test; it just never saw a fold. Widened to cover a period —
+`set_observer_window of ["u", 50]` — the same 1 Hz replay reads
+`oscillating` at every full-window sample and `diverging` never appears
+(`tests/test_observer_window_scale.eigs`; phugoid's
+`tests/observer_check.eigs` rows `O.ph1s.*`). The rule of thumb: **the
+window must span at least one period of the slowest mode you expect to
+see, in samples of the cadence you observe at** — `N ≥ T / Δt` — and the
+window must be *full* before a slow mode's verdict is trustworthy (the
+motion bands are early-warning and fire from 4 samples: during the
+first `N` samples a rising quarter-cycle still reads `diverging`). The
+opposite mismatch exists too: a mode *faster* than a few samples
+(phugoid's roll mode, `t_half = 0.56 s` at 0.02 s cadence) needs the
+window narrower or the cadence coarser, or its contraction test never
+spans enough of the mode. Choose the depth in samples from the physics;
+a frame-locked consumer with several timescales gives each binding its
+own.
+
+The window-widening cost: a ring of `N` doubles per channel per binding
+(the value channel keeps two), allocated at the depth in force on the
+first sample — the default depth allocates exactly what it did before
+#1044 — and the folding/variance tests are `O(N)` per verdict asked, not
+per assignment.
+
 ## Partial-window rule (applies to all six)
 
 If the window does not yet hold enough samples, **every predicate returns
@@ -715,8 +811,10 @@ loop while not (converged of x):
 
 ## Cost
 
-The `dh_window` costs one `xcalloc(N * sizeof(double))` (80 bytes at N=10)
-per *interrogated* value, lazily on the second observation. Per assignment
+The `dh_window` costs one `xcalloc(N * sizeof(double))` (80 bytes at the
+default N=10; the depth in force at the first push, see [The
+window](#the-window-1044)) per *interrogated* value, lazily on the second
+observation. Per assignment
 the cost is one buffer write + head advance, gated on the compile-time
 observer-tracking flag — values that no predicate or interrogative ever
 reads pay nothing. Free is handled in `free_value` before the `VAL_NUM`
diff --git a/docs/SPEC.md b/docs/SPEC.md
index 8605d2d1..8a0151b4 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -1290,10 +1290,13 @@ print of converged
 
 For a **numeric** binding the predicates classify the value's own
 trajectory (#861): the observed signal is the relative step
-`Δv/(1+|v|)` — the standard mixed-tolerance stopping criterion, with
-the settle deadband as the tolerance — so the starting value and the
-limit's magnitude do not matter. A loop converging to `5`, `5000` or
-`0.005` certifies identically. Non-numeric bindings (strings,
+`Δv / max(|v|, |v_prev|, scale)` (#1045) — the standard mixed-tolerance
+stopping criterion `|Δx| ≤ rtol·|x|` with the settle deadband as `rtol`
+and `dh_zero · scale` as the absolute floor (`scale` is
+`set_observer_scale`, default `0.001`) — so the starting value, the
+limit's magnitude and the **unit** the value is stored in do not matter.
+A loop converging to `5`, `5000` or `0.005` certifies identically, and a
+bank angle reads the same in radians and degrees. Non-numeric bindings (strings,
 containers) classify their entropy trajectory as before; the entropy
 MEASUREMENT (`where is x`) is unchanged for everything.
 
@@ -1425,8 +1428,12 @@ diverging
 
 **The value channel** (`report_value of x`) is, since #861, the same
 classifier the predicate words and `report` use on numeric bindings —
-the two surfaces cannot disagree about one trajectory. Over a 10-sample
-window of relative steps `Δv/(1+|v|)`: `converged` is a full window all
+the two surfaces cannot disagree about one trajectory. Over a window of
+relative steps `Δv / max(|v|, |v_prev|, scale)` — `N` samples deep, 10
+by default, `set_observer_window of n` per state or
+`set_observer_window of ["x", n]` per binding (#1044; a mode slower than
+`N` samples of the observation cadence cannot fold inside the window) —
+`converged` is a full window all
 under the settle deadband; `stable` all under the small-motion band;
 `equilibrium` zero-mean, variance under deadband²; `improving` monotone
 steps contracting geometrically (a summable tail — genuinely closing on
@@ -1440,8 +1447,10 @@ path length — a sinusoid sampled slower than its half-period).
 not imply a limit (the harmonic series' steps vanish; its sum does not
 converge), so it means *settled at the deadband* — the strongest claim a
 finite window supports. The deadband is the tolerance knob
-(`set_observer_thresholds`); the structure rules are deliberately
-threshold-free.
+(`set_observer_thresholds`), the characteristic scale
+(`set_observer_scale`) is where the tolerance turns absolute, and the
+window depth (`set_observer_window`) is how many samples a verdict
+spans; the structure rules are deliberately threshold-free.
 
 **Trajectories cross call boundaries as snapshots** (#421). Observer state
 is binding-identity — a value passed to a function arrives with no history —
diff --git a/docs/llms.txt b/docs/llms.txt
index 70351c02..124fdde1 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -112,9 +112,13 @@ print of ("sqrt(2) = " + (str of (newton_sqrt of 2)))   # sqrt(2) = 1.4142135623
 - `report of x` returns the routed state string (value channel for numeric
   bindings, entropy channel otherwise); `report_value of x` uses the value
   channel explicitly. Both read the named binding's trajectory.
-- `converged` needs LOW absolute entropy on top of a settled window: a value
-  pinned at `5.0` reports `stable`, never `converged`; pinned at `0.0`/`1.0` it
-  converges. Don't guess the predicate — see docs/PREDICATES.md.
+- Numeric verdicts are over the value's RELATIVE step, `Δv / max(|v|, |v_prev|,
+  scale)`, N samples deep: unit-free above `scale` (`set_observer_scale`,
+  default 1e-3), an absolute floor `dh_zero*scale` below it; a decay toward
+  zero reads `improving` until inside the scale. A mode slower than N samples
+  of your cadence cannot fold in the window — `set_observer_window of ["x", n]`
+  (4..64; default 10, `set_observer_window of n`) so N >= period/step.
+  Don't guess the predicate — see docs/PREDICATES.md.
 - Temporal reads: `prev of x` (value before the last assignment),
   `what is x at 12` / `state_at of 12` (past-line state). Bare `x at 12` is a
   parse error. Wrap hot loops in `unobserved:` to skip the observer's entropy
diff --git a/src/builtins.c b/src/builtins.c
index 42e0a3d3..56b12606 100644
--- a/src/builtins.c
+++ b/src/builtins.c
@@ -639,6 +639,121 @@ Value* builtin_get_observer_thresholds(Value *arg) {
     return result;
 }
 
+/* #1044: the observer window depth.
+ *
+ * The bare form (a number) sets the per-state DEFAULT depth in samples
+ * that every value-channel and entropy-channel verdict classifies over:
+ * 4..64, 10 at start. Read live, like the thresholds: a binding already
+ * carrying a trajectory classifies over the new depth at its next verdict
+ * (its ring grows on the next sample; a smaller depth reads fewer
+ * samples). The list form (["x", n]) is a per-BINDING override on the
+ * binding `x` visible from the call site (the same scope walk `report of
+ * x` does), affecting only that slot; n == 0 clears it back to the
+ * default. An unbound name raises — there is no slot to widen. Both
+ * return null.
+ *
+ * Why a depth knob: the window is in SAMPLES, and a mode slower than ~N
+ * samples of the consumer's cadence cannot fold inside it — the phugoid
+ * (T = 46.9 s) observed at 1 Hz read `diverging` on its rising quarter
+ * cycles with the fixed 10. Widening the binding's window to cover a
+ * period lets the folding rule see the fold. The ceiling is the ring
+ * counters' width; the floor is the motion bands' two-samples-per-half. */
+static int obs_window_arg(Value *v, const char *who) {
+    if (!v || v->type != VAL_NUM) {
+        rt_error(EK_TYPE, 0, "%s: window depth must be a number", who);
+        return -1;
+    }
+    double d = v->data.num;
+    if (d != (int)d || d < OBSERVER_WINDOW_MIN || d > OBSERVER_WINDOW_MAX) {
+        rt_error(EK_VALUE, 0, "%s: window depth must be an integer in [%d, %d], got %g",
+                 who, OBSERVER_WINDOW_MIN, OBSERVER_WINDOW_MAX, d);
+        return -1;
+    }
+    return (int)d;
+}
+
+/* set_observer_window of n | ["x", n] — set the default (n) or one binding's (["x", n]) observer window depth, 4..64 samples. */
+Value* builtin_set_observer_window(Value *arg) {
+    if (arg && arg->type == VAL_LIST) {
+        if (arg->data.list.count != 2 || !arg->data.list.items[0] ||
+            arg->data.list.items[0]->type != VAL_STR) {
+            rt_error(EK_TYPE, 0, "set_observer_window requires n or [\"name\", n]");
+            return make_null();
+        }
+        const char *name = arg->data.list.items[0]->data.str;
+        Value *nv = arg->data.list.items[1];
+        int n;
+        if (nv && nv->type == VAL_NUM && nv->data.num == 0.0) {
+            n = 0;   /* clear the override */
+        } else {
+            n = obs_window_arg(nv, "set_observer_window");
+            if (n < 0) return make_null();
+        }
+        Env *start = g_builtin_call_env ? g_builtin_call_env : g_global_env;
+        int slot = -1, depth = 0;
+        Env *target = env_resolve_chain(start, name, env_hash_name(name), &slot, &depth);
+        if (!target || slot < 0) {
+            rt_error(EK_UNDEFINED_NAME, 0, "set_observer_window: no binding named '%s'", name);
+            return make_null();
+        }
+        if (!observer_slot_set_window(target, slot, n)) {
+            rt_error(EK_LIMIT, 0, "set_observer_window: observer slot table full");
+            return make_null();
+        }
+        return make_null();
+    }
+    int n = obs_window_arg(arg, "set_observer_window");
+    if (n < 0) return make_null();
+    g_obs_window = n;
+    return make_null();
+}
+
+/* get_observer_window of null | "x" — the default window depth, or the depth in force on binding "x". */
+Value* builtin_get_observer_window(Value *arg) {
+    if (arg && arg->type == VAL_STR) {
+        const char *name = arg->data.str;
+        Env *start = g_builtin_call_env ? g_builtin_call_env : g_global_env;
+        int slot = -1, depth = 0;
+        Env *target = env_resolve_chain(start, name, env_hash_name(name), &slot, &depth);
+        if (!target || slot < 0) {
+            rt_error(EK_UNDEFINED_NAME, 0, "get_observer_window: no binding named '%s'", name);
+            return make_null();
+        }
+        const ObserverSlot *s = (slot < target->obs_cap) ? env_obs_slot(target, slot) : NULL;
+        return make_num((double)observer_slot_window(s));
+    }
+    return make_num((double)observer_slot_window(NULL));
+}
+
+/* #1045: the characteristic scale of the value channel — the magnitude
+ * below which a value counts as "at zero". The relative step is
+ * Δv / max(|v|, |v_prev|, scale): above the scale a verdict is unit-free
+ * (the same physics stored in radians, degrees or milliradians reads the
+ * same); below it the deadband turns absolute (|Δv| < dh_zero·scale), so
+ * float noise around an exact zero is not motion. Default 0.001. Choose it
+ * in the unit the binding is stored in — it is the one number a unit
+ * choice still touches. */
+/* set_observer_scale of s — set the value channel's characteristic scale (the |v| below which a value counts as zero), s > 0. */
+Value* builtin_set_observer_scale(Value *arg) {
+    if (!arg || arg->type != VAL_NUM) {
+        rt_error(EK_TYPE, 0, "set_observer_scale requires a number");
+        return make_null();
+    }
+    double sc = arg->data.num;
+    if (!(sc > 0.0) || sc > 1e300) {
+        rt_error(EK_VALUE, 0, "observer scale must be positive and finite, got %g", sc);
+        return make_null();
+    }
+    g_obs_scale = sc;
+    return make_null();
+}
+
+/* get_observer_scale of null — the value channel's characteristic scale. */
+Value* builtin_get_observer_scale(Value *arg) {
+    (void)arg;
+    return make_num(g_obs_scale);
+}
+
 /* exit of N — request a clean process exit with code N (default 0). Sets the
  * unwind flag (g_has_error) so vm_run returns to main, plus g_exit_requested so
  * the unwind is UNCATCHABLE (a `try` must not swallow `exit`) and main exits
@@ -6659,6 +6774,10 @@ void register_builtins(Env *env) {
     env_set_local_owned(env, "report", make_builtin(builtin_report));
     env_set_local_owned(env, "set_observer_thresholds", make_builtin(builtin_set_observer_thresholds));
     env_set_local_owned(env, "get_observer_thresholds", make_builtin(builtin_get_observer_thresholds));
+    env_set_local_owned(env, "set_observer_window", make_builtin(builtin_set_observer_window));
+    env_set_local_owned(env, "get_observer_window", make_builtin(builtin_get_observer_window));
+    env_set_local_owned(env, "set_observer_scale", make_builtin(builtin_set_observer_scale));
+    env_set_local_owned(env, "get_observer_scale", make_builtin(builtin_get_observer_scale));
     env_set_local_owned(env, "assert", make_builtin(builtin_assert));
     env_set_local_owned(env, "exit", make_builtin(builtin_exit));
     env_set_local_owned(env, "throw", make_builtin(builtin_throw));
diff --git a/src/compiler.c b/src/compiler.c
index b4a7f527..de6d4036 100644
--- a/src/compiler.c
+++ b/src/compiler.c
@@ -1311,6 +1311,27 @@ static void stamp_local_traced(EigsChunk *ch, NameSet *interrogated) {
         ch->local_traced[i] = ch->local_names[i] && name_set_has(interrogated, ch->local_names[i]) ? 1 : 0;
 }
 
+/* #1044: `set_observer_window of ["x", n]` / `get_observer_window of "x"`
+ * name a binding by STRING at runtime, so the builtin resolves it through
+ * the env chain exactly as `eval` would — and a plain fn-local is a bare
+ * slot with no env name unless something interrogates it. A string-literal
+ * operand is therefore treated as an interrogation of that name (the same
+ * slow path `when is x` buys), so the per-binding knob reaches locals. A
+ * computed name (a variable holding "x") cannot be scanned and only
+ * reaches name-resolvable bindings; the builtin raises on a miss. */
+static void scan_window_name_arg(ASTNode *node, NameSet *out) {
+    ASTNode *fn = node->data.relation.left, *arg = node->data.relation.right;
+    if (!fn || fn->type != AST_IDENT || !arg) return;
+    if (strcmp(fn->data.ident.name, "set_observer_window") != 0 &&
+        strcmp(fn->data.ident.name, "get_observer_window") != 0) return;
+    ASTNode *lit = NULL;
+    if (arg->type == AST_STR) lit = arg;
+    else if (arg->type == AST_LIST && arg->data.list.count >= 1 &&
+             arg->data.list.elems[0] && arg->data.list.elems[0]->type == AST_STR)
+        lit = arg->data.list.elems[0];
+    if (lit && lit->data.str) name_set_add(out, lit->data.str);
+}
+
 static void scan_for_interrogated(ASTNode *node, NameSet *out) {
     if (!node) return;
     switch (node->type) {
@@ -1331,6 +1352,7 @@ static void scan_for_interrogated(ASTNode *node, NameSet *out) {
         scan_for_interrogated(node->data.unary.operand, out);
         break;
     case AST_RELATION:
+        scan_window_name_arg(node, out);
         scan_for_interrogated(node->data.relation.left, out);
         scan_for_interrogated(node->data.relation.right, out);
         break;
diff --git a/src/eigenscript.c b/src/eigenscript.c
index cdb4c31a..e9e2b591 100644
--- a/src/eigenscript.c
+++ b/src/eigenscript.c
@@ -443,24 +443,68 @@ double compute_entropy(Value *v) {
  * aliasing temps tracks correctly. This is what fixed #262 — the value-path
  * observer model (state on the Value) was removed in Step E. */
 
-static void observer_slot_window_push(ObserverSlot *s, double dh) {
-    if (!s->dh_window) {
-        s->dh_window = xcalloc(OBSERVER_WINDOW_N, sizeof(double));
-        s->dh_window_head = 0;
-        s->dh_window_count = 0;
-    }
-    s->dh_window[s->dh_window_head] = dh;
-    s->dh_window_head = (uint8_t)((s->dh_window_head + 1) % OBSERVER_WINDOW_N);
-    if (s->dh_window_count < OBSERVER_WINDOW_N) s->dh_window_count++;
+/* #1044: the window depth a slot classifies over. A per-binding override
+ * (set_observer_window of ["x", n]) wins; otherwise the state default
+ * (set_observer_window of n), read LIVE — like the thresholds, changing the
+ * default changes every subsequent verdict, not only bindings first seen
+ * after the call. The tape/step/DAP surfaces build slots without an env and
+ * get the default through the same read. */
+static inline int obs_win(const ObserverSlot *s) {
+    if (s && s->win_override) return s->win_override;
+    /* g_obs_window is validated at the seam (builtin_set_observer_window
+     * clamps to [MIN, MAX]) and seeded at OBSERVER_WINDOW_N, so the hot
+     * path re-checks nothing: this read is one branch and two loads per
+     * observed assignment. */
+    return eigs_current ? eigs_current->state->obs_window : OBSERVER_WINDOW_N;
+}
+int observer_slot_window(const ObserverSlot *s) { return obs_win(s); }
+
+/* The sample counts the classifiers read: the ring may hold MORE than the
+ * depth in force (the default was lowered, or an override shrank it), and
+ * then only the newest `depth` samples are the window. */
+static inline size_t obs_dh_count(const ObserverSlot *s) {
+    size_t n = (size_t)obs_win(s);
+    return s->dh_window_count < n ? s->dh_window_count : n;
+}
+static inline size_t obs_v_count(const ObserverSlot *s) {
+    size_t n = (size_t)obs_win(s);
+    return s->v_window_count < n ? s->v_window_count : n;
 }
 
 static double observer_slot_window_get(const ObserverSlot *s, size_t offset_back) {
     if (!s->dh_window || offset_back >= s->dh_window_count) return 0.0;
     int idx = (int)s->dh_window_head - 1 - (int)offset_back;
-    while (idx < 0) idx += OBSERVER_WINDOW_N;
+    while (idx < 0) idx += s->dh_cap;
     return s->dh_window[idx];
 }
 
+/* Make the dH ring at least `n` deep, keeping the samples it holds (newest
+ * min(count, n) of them, re-laid oldest-first). Allocation is the one cost
+ * #1044 adds to the common path, and only when the depth in force exceeds
+ * the capacity — at the default depth this is the same single xcalloc the
+ * ring always paid. */
+static void observer_slot_dh_ensure(ObserverSlot *s, int n) {
+    if (s->dh_window && s->dh_cap >= n) return;
+    double *nw = xcalloc((size_t)n, sizeof(double));
+    int cnt = s->dh_window ? s->dh_window_count : 0;
+    if (cnt > n) cnt = n;
+    for (int i = 0; i < cnt; i++)
+        nw[i] = observer_slot_window_get(s, (size_t)(cnt - 1 - i));
+    free(s->dh_window);
+    s->dh_window = nw;
+    s->dh_cap = (uint8_t)n;
+    s->dh_window_count = (uint8_t)cnt;
+    s->dh_window_head = (uint8_t)(cnt % n);
+}
+
+static void observer_slot_window_push(ObserverSlot *s, double dh) {
+    int n = obs_win(s);
+    if (!s->dh_window || s->dh_cap < n) observer_slot_dh_ensure(s, n);
+    s->dh_window[s->dh_window_head] = dh;
+    if (++s->dh_window_head >= s->dh_cap) s->dh_window_head = 0;
+    if (s->dh_window_count < s->dh_cap) s->dh_window_count++;
+}
+
 /* #294 value-signal channel: same ring buffer as the entropy window, but the
  * pushed quantity is the value's own relative step Δv/(1+|v|). #422 adds a
  * parallel RAW-step ring (Δv un-normalized, same head/count): the relative
@@ -468,33 +512,50 @@ static double observer_slot_window_get(const ObserverSlot *s, size_t offset_back
  * two classes — additive/polynomial runaway (Δv/|v| → 0 while Δv doesn't)
  * and oscillation below the deadband — and both are recoverable from the
  * raw step's sign/decay structure alone. */
-static void observer_slot_v_push(ObserverSlot *s, double rel_delta, double raw_delta) {
-    if (!s->v_window) {
-        s->v_window = xcalloc(OBSERVER_WINDOW_N, sizeof(double));
-        s->vr_window = xcalloc(OBSERVER_WINDOW_N, sizeof(double));
-        s->v_window_head = 0;
-        s->v_window_count = 0;
-    }
-    s->v_window[s->v_window_head] = rel_delta;
-    if (s->vr_window) s->vr_window[s->v_window_head] = raw_delta;
-    s->v_window_head = (uint8_t)((s->v_window_head + 1) % OBSERVER_WINDOW_N);
-    if (s->v_window_count < OBSERVER_WINDOW_N) s->v_window_count++;
-}
-
 static double observer_slot_v_get(const ObserverSlot *s, size_t offset_back) {
     if (!s->v_window || offset_back >= s->v_window_count) return 0.0;
     int idx = (int)s->v_window_head - 1 - (int)offset_back;
-    while (idx < 0) idx += OBSERVER_WINDOW_N;
+    while (idx < 0) idx += s->v_cap;
     return s->v_window[idx];
 }
 
 static double observer_slot_vr_get(const ObserverSlot *s, size_t offset_back) {
     if (!s->vr_window || offset_back >= s->v_window_count) return 0.0;
     int idx = (int)s->v_window_head - 1 - (int)offset_back;
-    while (idx < 0) idx += OBSERVER_WINDOW_N;
+    while (idx < 0) idx += s->v_cap;
     return s->vr_window[idx];
 }
 
+/* #1044: value-channel twin of observer_slot_dh_ensure (both rings share
+ * head/count, so they grow together). */
+static void observer_slot_v_ensure(ObserverSlot *s, int n) {
+    if (s->v_window && s->v_cap >= n) return;
+    double *nv = xcalloc((size_t)n, sizeof(double));
+    double *nr = xcalloc((size_t)n, sizeof(double));
+    int cnt = s->v_window ? s->v_window_count : 0;
+    if (cnt > n) cnt = n;
+    for (int i = 0; i < cnt; i++) {
+        nv[i] = observer_slot_v_get(s, (size_t)(cnt - 1 - i));
+        nr[i] = observer_slot_vr_get(s, (size_t)(cnt - 1 - i));
+    }
+    free(s->v_window);
+    free(s->vr_window);
+    s->v_window = nv;
+    s->vr_window = nr;
+    s->v_cap = (uint8_t)n;
+    s->v_window_count = (uint8_t)cnt;
+    s->v_window_head = (uint8_t)(cnt % n);
+}
+
+static void observer_slot_v_push(ObserverSlot *s, double rel_delta, double raw_delta) {
+    int n = obs_win(s);
+    if (!s->v_window || s->v_cap < n) observer_slot_v_ensure(s, n);
+    s->v_window[s->v_window_head] = rel_delta;
+    s->vr_window[s->v_window_head] = raw_delta;
+    if (++s->v_window_head >= s->v_cap) s->v_window_head = 0;
+    if (s->v_window_count < s->v_cap) s->v_window_count++;
+}
+
 /* #422 raw-step structure tests. Both require a FULL window and steps above
  * the fp-noise floor (a settled double wobbles by ULPs whose signs are
  * meaningless — 4·ε·(1+|v|) scales the floor to the value's magnitude), and
@@ -521,7 +582,7 @@ static double observer_slot_vr_get(const ObserverSlot *s, size_t offset_back) {
  * false where the old semantics said true. The full-window requirement
  * stays where it belongs: on the REST bands, which certify. */
 static int observer_slot_raw_nonvanishing(const ObserverSlot *s) {
-    size_t cnt = s->v_window_count;
+    size_t cnt = obs_v_count(s);
     if (cnt < 4) return 0;
     double floor_eps = 4.0 * DBL_EPSILON * (1.0 + fabs(s->last_value));
     size_t half = cnt / 2;
@@ -536,7 +597,7 @@ static int observer_slot_raw_nonvanishing(const ObserverSlot *s) {
 
 static int observer_slot_raw_diverging(const ObserverSlot *s) {
     if (!observer_slot_raw_nonvanishing(s)) return 0;
-    size_t cnt = s->v_window_count;
+    size_t cnt = obs_v_count(s);
     double first = observer_slot_vr_get(s, 0);
     for (size_t i = 1; i < cnt; i++)
         if (observer_slot_vr_get(s, i) * first <= 0.0) return 0;
@@ -545,8 +606,8 @@ static int observer_slot_raw_diverging(const ObserverSlot *s) {
 
 static int observer_slot_raw_oscillating(const ObserverSlot *s) {
     if (!observer_slot_raw_nonvanishing(s)) return 0;
-    size_t cnt = s->v_window_count;
-    const int FLIPS = (OBSERVER_WINDOW_N + 2) / 3;
+    size_t cnt = obs_v_count(s);
+    const int FLIPS = (observer_slot_window(s) + 2) / 3;
     double floor_eps = 4.0 * DBL_EPSILON * (1.0 + fabs(s->last_value));
     int flips = 0;
     for (size_t i = 0; i + 1 < cnt; i++) {
@@ -558,13 +619,40 @@ static int observer_slot_raw_oscillating(const ObserverSlot *s) {
 }
 
 /* Fold one observed numeric value into the slot's value channel. The stored
- * step is RELATIVE (Δv/(1+|v|)) so the thresholds carry the same meaning across
- * value scales: a ±0.6 swing around 5 reads "moving" (~12% steps), the same
- * swing around 1e6 is effectively settled. First value seeds last_value only. */
+ * step is RELATIVE so the thresholds carry the same meaning across value
+ * scales: a ±0.6 swing around 5 reads "moving" (~12% steps), the same swing
+ * around 1e6 is effectively settled. First value seeds last_value only.
+ *
+ * #1045: rel = Δv / max(|v|, |v_prev|, scale). The old Δv/(1+|v|) was the
+ * entropy formula's normalisation borrowed as a step: below |v| ~ 1 the
+ * denominator is ~1 and rel is just Δv — an ABSOLUTE deadband — so one
+ * physical trajectory read `converged` stored in radians and `moving` in
+ * degrees (phugoid's spiral mode, 0.0124 rad = 0.71 deg). The step's own
+ * local scale, max(|v|, |v_prev|), is the textbook relative step |Δx|/|x|
+ * symmetrised so it is bounded (|rel| <= 2) and defined across a zero
+ * crossing; `scale` (set_observer_scale, default 1e-3) is the magnitude
+ * below which a value counts as "at zero" and the tolerance turns absolute
+ * — so float noise around an exact zero (Δv ~ 1e-16) reads 1e-13, not O(1).
+ * Above the scale the verdict is unit-free: `converged` means every recent
+ * step under dh_zero of the value's own size, i.e. |Δx| <= rtol·|x| with
+ * an absolute floor of rtol·scale (1e-6 by default), and a geometric decay
+ * toward zero keeps rel = (1 - r) — `improving`, never `converged` — until
+ * it is inside the scale.
+ *
+ * Not the window's running max |v| (the design first proposed): for a
+ * monotone decay that max is the OLDEST sample, so rel = (1 - r)·r^(N-1)
+ * and any ratio r < ~0.5 reads `converged` at the first full window no
+ * matter how far from its limit the value still is (1e6·0.3^k certifies at
+ * x ~= 1.8) — and widening the window (#1044) makes it worse, r^49 at
+ * N = 50. The local scale keeps the two knobs independent. */
 void observer_slot_record_value(ObserverSlot *s, double v) {
     if (s->v_used) {
         double raw = v - s->last_value;
-        double rel = raw / (1.0 + fabs(v));
+        double a = fabs(v), b = fabs(s->last_value);
+        if (b > a) a = b;
+        double fl = eigs_current ? eigs_current->state->obs_scale : 0.001;
+        if (fl > a) a = fl;
+        double rel = raw / a;
         observer_slot_v_push(s, rel, raw);
     }
     s->last_value = v;
@@ -710,6 +798,19 @@ void observer_slot_sample(Env *e, int idx, Value *newval) {
     if (s) s->v_last = 0;   /* #861 route bit only — no walk, no `used` */
 }
 
+/* #1044: per-binding window override. Only the OVERRIDE is written — the
+ * rings grow on the next push if the new depth exceeds their capacity, and
+ * a smaller depth simply reads fewer samples — so the call is O(1) and
+ * touches no sample. n == 0 restores the state default. */
+int observer_slot_set_window(Env *e, int idx, int n) {
+    if (!e || idx < 0) return 0;
+    if (idx >= e->obs_cap && !observer_obs_grow(e, idx)) return 0;
+    ObserverSlot *s = env_obs_slot(e, idx);
+    if (!s) return 0;
+    s->win_override = (uint8_t)n;
+    return 1;
+}
+
 void observer_slot_reset(Env *e) {
     if (!e || !e->obs) return;
     vm_obs_slot_dropped(e);   /* invalidate the VM's last-observed-slot tracker */
@@ -787,7 +888,7 @@ static int observer_slot_saturated(const ObserverSlot *s) {
 
 /* Window flags: every |rel step| under dh_zero / dh_small. */
 static void obs_num_flags(const ObserverSlot *s, int *all_zero, int *all_small) {
-    size_t cnt = s->v_window_count;
+    size_t cnt = obs_v_count(s);
     *all_zero = 1; *all_small = 1;
     for (size_t i = 0; i < cnt; i++) {
         double w = fabs(observer_slot_v_get(s, i));
@@ -799,9 +900,9 @@ static void obs_num_flags(const ObserverSlot *s, int *all_zero, int *all_small)
 /* Relative-step sign-flip oscillation — the head test report_value has
  * always run (flips above the deadband, >= FLIPS of them). */
 static int obs_num_rel_oscillating(const ObserverSlot *s) {
-    size_t cnt = s->v_window_count;
+    size_t cnt = obs_v_count(s);
     if (cnt < 3) return 0;
-    const int FLIPS = (OBSERVER_WINDOW_N + 2) / 3;
+    const int FLIPS = (observer_slot_window(s) + 2) / 3;
     int flips = 0;
     for (size_t i = 0; i + 1 < cnt; i++) {
         double a = observer_slot_v_get(s, i);
@@ -822,8 +923,8 @@ static int obs_num_rel_oscillating(const ObserverSlot *s) {
  * a pure sampled sinusoid nets ~0 over any full window; a drift-with-
  * wiggle nets ~its path and stays out. */
 static int obs_num_bounded_oscillating(const ObserverSlot *s) {
-    size_t cnt = s->v_window_count;
-    if (cnt < OBSERVER_WINDOW_N) return 0;
+    size_t cnt = obs_v_count(s);
+    if (cnt < (size_t)observer_slot_window(s)) return 0;
     /* No non-vanishing gate here, deliberately: an underdamped oscillator's
      * x DECAYS while oscillating, and its oscillation is the fact worth
      * reporting mid-flight. The handoff to the settle bands is the all-under-
@@ -877,7 +978,7 @@ static int obs_num_diverging(const ObserverSlot *s) {
  * the band instead of being promised a limit it does not have. */
 static int obs_num_improving(const ObserverSlot *s) {
     if (observer_slot_saturated(s)) return 0;
-    size_t cnt = s->v_window_count;
+    size_t cnt = obs_v_count(s);
     if (cnt < 4) return 0;                       /* early-warning band: same
                                                   * 4-sample floor as the raw
                                                   * tests, not the rest bands'
@@ -932,7 +1033,7 @@ static int obs_num_improving(const ObserverSlot *s) {
  * its raw steps do not). */
 static int obs_num_converged(const ObserverSlot *s) {
     if (observer_slot_saturated(s)) return 0;
-    if (s->v_window_count < OBSERVER_WINDOW_N) return 0;
+    if (obs_v_count(s) < (size_t)observer_slot_window(s)) return 0;
     int all_zero, all_small;
     obs_num_flags(s, &all_zero, &all_small);
     if (!all_zero) return 0;
@@ -945,18 +1046,19 @@ static int obs_num_converged(const ObserverSlot *s) {
  * (all-under-deadband forces both), preserving the quiescent lattice. */
 static int obs_num_equilibrium(const ObserverSlot *s) {
     if (observer_slot_saturated(s)) return 0;
-    if (s->v_window_count < OBSERVER_WINDOW_N) return 0;
+    size_t N = (size_t)observer_slot_window(s);
+    if (obs_v_count(s) < N) return 0;
     if (observer_slot_raw_diverging(s) || observer_slot_raw_oscillating(s)) return 0;
     double sum = 0.0;
-    for (size_t i = 0; i < OBSERVER_WINDOW_N; i++) sum += observer_slot_v_get(s, i);
-    double mean = sum / (double)OBSERVER_WINDOW_N;
+    for (size_t i = 0; i < N; i++) sum += observer_slot_v_get(s, i);
+    double mean = sum / (double)N;
     if (fabs(mean) >= g_obs_dh_zero) return 0;
     double var = 0.0;
-    for (size_t i = 0; i < OBSERVER_WINDOW_N; i++) {
+    for (size_t i = 0; i < N; i++) {
         double d = observer_slot_v_get(s, i) - mean;
         var += d * d;
     }
-    var /= (double)OBSERVER_WINDOW_N;
+    var /= (double)N;
     return (var < g_obs_dh_zero * g_obs_dh_zero) ? 1 : 0;
 }
 
@@ -965,12 +1067,13 @@ static int obs_num_equilibrium(const ObserverSlot *s) {
  * steps live here: real motion, no certified limit). converged => stable. */
 static int obs_num_stable(const ObserverSlot *s) {
     if (observer_slot_saturated(s)) return 0;
-    if (s->v_window_count < OBSERVER_WINDOW_N) return 0;
+    size_t N = (size_t)observer_slot_window(s);
+    if (obs_v_count(s) < N) return 0;
     if (observer_slot_raw_diverging(s) || observer_slot_raw_oscillating(s)) return 0;
     int all_zero, all_small;
     obs_num_flags(s, &all_zero, &all_small);
     if (!all_small) return 0;
-    for (size_t i = 0; i + 1 < OBSERVER_WINDOW_N; i++) {
+    for (size_t i = 0; i + 1 < N; i++) {
         double a = observer_slot_v_get(s, i);
         double b = observer_slot_v_get(s, i + 1);
         if (a * b < 0.0 && fabs(a) > g_obs_dh_zero && fabs(b) > g_obs_dh_zero) return 0;
@@ -983,13 +1086,13 @@ static int obs_num_stable(const ObserverSlot *s) {
  * partial-window fallback preserved verbatim. */
 static const char *obs_num_report(const ObserverSlot *s) {
     if (!s || !s->v_used) return "equilibrium";   /* no numeric trajectory */
-    size_t cnt = s->v_window_count;
+    size_t cnt = obs_v_count(s);
     if (cnt == 0) return "equilibrium";           /* one value seen, no step yet */
     if (obs_num_oscillating(s)) return "oscillating";
     if (obs_num_diverging(s))   return "diverging";
     if (obs_num_improving(s))   return "improving";   /* partial-capable, like
                                                        * the two bands above */
-    if (cnt >= OBSERVER_WINDOW_N) {
+    if (cnt >= (size_t)observer_slot_window(s)) {
         if (obs_num_converged(s))   return "converged";
         if (obs_num_equilibrium(s)) return "equilibrium";
         if (obs_num_stable(s))      return "stable";
@@ -1014,25 +1117,29 @@ static int obs_route_num(const ObserverSlot *s) {
  * handles saturation itself, so the entropy route can no longer see one. */
 int observer_slot_converged(const ObserverSlot *s) {
     if (obs_route_num(s)) return obs_num_converged(s);
-    if (!s || s->dh_window_count < OBSERVER_WINDOW_N) return 0;
-    for (size_t i = 0; i < OBSERVER_WINDOW_N; i++)
+    if (!s) return 0;
+    size_t N = (size_t)observer_slot_window(s);
+    if (obs_dh_count(s) < N) return 0;
+    for (size_t i = 0; i < N; i++)
         if (fabs(observer_slot_window_get(s, i)) >= g_obs_dh_zero) return 0;
     return (s->entropy < g_obs_h_low) ? 1 : 0;
 }
 
 int observer_slot_equilibrium(const ObserverSlot *s) {
     if (obs_route_num(s)) return obs_num_equilibrium(s);
-    if (!s || s->dh_window_count < OBSERVER_WINDOW_N) return 0;
+    if (!s) return 0;
+    size_t N = (size_t)observer_slot_window(s);
+    if (obs_dh_count(s) < N) return 0;
     double sum = 0.0;
-    for (size_t i = 0; i < OBSERVER_WINDOW_N; i++) sum += observer_slot_window_get(s, i);
-    double mean = sum / (double)OBSERVER_WINDOW_N;
+    for (size_t i = 0; i < N; i++) sum += observer_slot_window_get(s, i);
+    double mean = sum / (double)N;
     if (fabs(mean) >= g_obs_dh_zero) return 0;
     double var = 0.0;
-    for (size_t i = 0; i < OBSERVER_WINDOW_N; i++) {
+    for (size_t i = 0; i < N; i++) {
         double d = observer_slot_window_get(s, i) - mean;
         var += d * d;
     }
-    var /= (double)OBSERVER_WINDOW_N;
+    var /= (double)N;
     return (var < g_obs_dh_zero * g_obs_dh_zero) ? 1 : 0;
 }
 
@@ -1040,7 +1147,7 @@ int observer_slot_equilibrium(const ObserverSlot *s) {
  * the observer_*(Value*) versions above, reading the slot's window/entropy. */
 int observer_slot_improving(const ObserverSlot *s) {
     if (obs_route_num(s)) return obs_num_improving(s);
-    size_t cnt = s ? s->dh_window_count : 0;
+    size_t cnt = s ? obs_dh_count(s) : 0;
     if (cnt < 3) return 0;
     double sum = 0.0; int down = 0;
     for (size_t i = 0; i < cnt; i++) {
@@ -1053,7 +1160,7 @@ int observer_slot_improving(const ObserverSlot *s) {
 
 int observer_slot_diverging(const ObserverSlot *s) {
     if (obs_route_num(s)) return obs_num_diverging(s);
-    size_t cnt = s ? s->dh_window_count : 0;
+    size_t cnt = s ? obs_dh_count(s) : 0;
     if (cnt < 3) return 0;
     double sum = 0.0; int up = 0;
     for (size_t i = 0; i < cnt; i++) {
@@ -1066,9 +1173,9 @@ int observer_slot_diverging(const ObserverSlot *s) {
 
 int observer_slot_oscillating(const ObserverSlot *s) {
     if (obs_route_num(s)) return obs_num_oscillating(s);
-    size_t cnt = s ? s->dh_window_count : 0;
+    size_t cnt = s ? obs_dh_count(s) : 0;
     if (cnt < 3) return 0;
-    const int FLIPS = (OBSERVER_WINDOW_N + 2) / 3;
+    const int FLIPS = (observer_slot_window(s) + 2) / 3;
     int flips = 0;
     for (size_t i = 0; i + 1 < cnt; i++) {
         double a = observer_slot_window_get(s, i);
@@ -1080,8 +1187,8 @@ int observer_slot_oscillating(const ObserverSlot *s) {
 
 int observer_slot_stable(const ObserverSlot *s) {
     if (obs_route_num(s)) return obs_num_stable(s);
-    size_t cnt = s ? s->dh_window_count : 0;
-    if (cnt < OBSERVER_WINDOW_N) return 0;
+    size_t cnt = s ? obs_dh_count(s) : 0;
+    if (cnt < (size_t)observer_slot_window(s)) return 0;
     if (s->entropy < g_obs_h_low) return 0;
     for (size_t i = 0; i < cnt; i++)
         if (fabs(observer_slot_window_get(s, i)) >= g_obs_dh_small) return 0;
@@ -1129,7 +1236,7 @@ const char *observer_slot_report_entropy(const ObserverSlot *s) {
      * band, "moving" — the same label the value channel uses for exactly this
      * state. Reporting a still-moving value as settled is what broke the
      * documented settled-plus-hold recipe. */
-    if (s->dh_window_count >= OBSERVER_WINDOW_N) return "moving";
+    if (obs_dh_count(s) >= (size_t)observer_slot_window(s)) return "moving";
     /* Partial-window best-effort label (mirrors builtin_report's tail). */
     if (fabs(s->dH) < g_obs_dh_zero) return "equilibrium";
     if (fabs(s->dH) < g_obs_dh_small && s->entropy >= g_obs_h_low) return "stable";
@@ -1226,8 +1333,8 @@ Value *observer_slot_trajectory(const ObserverSlot *s) {
     Value *out = make_dict(10);
     if (!out) return NULL;
     dict_set_owned(out, "kind", make_str("trajectory"));
-    int vcnt = (s && s->v_window)  ? s->v_window_count  : 0;
-    int dcnt = (s && s->dh_window) ? s->dh_window_count : 0;
+    int vcnt = (s && s->v_window)  ? (int)obs_v_count(s)  : 0;
+    int dcnt = (s && s->dh_window) ? (int)obs_dh_count(s) : 0;
     Value *rel = make_list_heap(vcnt > 0 ? vcnt : 1);
     Value *raw = make_list_heap(vcnt > 0 ? vcnt : 1);
     Value *dh  = make_list_heap(dcnt > 0 ? dcnt : 1);
@@ -1248,6 +1355,10 @@ Value *observer_slot_trajectory(const ObserverSlot *s) {
     dict_set_owned(out, "last_value",   make_num((s && s->v_used) ? s->last_value : 0.0));
     dict_set_owned(out, "observed",     make_num(s ? (s->used != 0) : 0));
     dict_set_owned(out, "numeric",      make_num(s ? (s->v_used != 0) : 0));
+    /* #1044: the depth this slot classifies over travels with the snapshot,
+     * so `classify of (trajectory of x)` agrees with `report of x` for a
+     * binding carrying a per-binding override. */
+    dict_set_owned(out, "window",       make_num((double)observer_slot_window(s)));
     return out;
 }
 
@@ -1267,13 +1378,27 @@ int observer_slot_from_trajectory(ObserverSlot *out, Value *dict) {
     if (!rel || rel->type != VAL_LIST || !raw || raw->type != VAL_LIST ||
         !dh || dh->type != VAL_LIST)
         return 0;
-    /* Only the most recent OBSERVER_WINDOW_N entries matter — a hand-built
-     * longer list classifies identically to its tail, same ring semantics. */
+    /* #1044: a snapshot carries the depth it was taken at (a hand-built dict
+     * may omit it — the state default then applies). Out of range means a
+     * malformed snapshot, refused like any other wrong shape. */
+    {
+        Value *w = dict_get(dict, "window");
+        if (w) {
+            if (w->type != VAL_NUM || w->data.num < OBSERVER_WINDOW_MIN ||
+                w->data.num > OBSERVER_WINDOW_MAX || w->data.num != (int)w->data.num)
+                return 0;
+            out->win_override = (uint8_t)(int)w->data.num;
+        }
+    }
+    const int N = observer_slot_window(out);
+    /* Only the most recent N entries matter — a hand-built longer list
+     * classifies identically to its tail, same ring semantics. */
     int vcnt = rel->data.list.count;
     if (raw->data.list.count < vcnt) vcnt = raw->data.list.count;
-    int vstart = vcnt > OBSERVER_WINDOW_N ? vcnt - OBSERVER_WINDOW_N : 0;
-    out->v_window  = xcalloc(OBSERVER_WINDOW_N, sizeof(double));
-    out->vr_window = xcalloc(OBSERVER_WINDOW_N, sizeof(double));
+    int vstart = vcnt > N ? vcnt - N : 0;
+    out->v_window  = xcalloc((size_t)N, sizeof(double));
+    out->vr_window = xcalloc((size_t)N, sizeof(double));
+    out->v_cap = out->dh_cap = (uint8_t)N;
     for (int i = vstart; i < vcnt; i++) {
         Value *a = rel->data.list.items[i], *b = raw->data.list.items[i];
         if (!a || a->type != VAL_NUM || !b || b->type != VAL_NUM) {
@@ -1285,10 +1410,10 @@ int observer_slot_from_trajectory(ObserverSlot *out, Value *dict) {
         out->vr_window[out->v_window_count] = b->data.num;
         out->v_window_count++;
     }
-    out->v_window_head = (uint8_t)(out->v_window_count % OBSERVER_WINDOW_N);
+    out->v_window_head = (uint8_t)(out->v_window_count % N);
     int dcnt = dh->data.list.count;
-    int dstart = dcnt > OBSERVER_WINDOW_N ? dcnt - OBSERVER_WINDOW_N : 0;
-    out->dh_window = xcalloc(OBSERVER_WINDOW_N, sizeof(double));
+    int dstart = dcnt > N ? dcnt - N : 0;
+    out->dh_window = xcalloc((size_t)N, sizeof(double));
     for (int i = dstart; i < dcnt; i++) {
         Value *a = dh->data.list.items[i];
         if (!a || a->type != VAL_NUM) {
@@ -1298,7 +1423,7 @@ int observer_slot_from_trajectory(ObserverSlot *out, Value *dict) {
         }
         out->dh_window[out->dh_window_count++] = a->data.num;
     }
-    out->dh_window_head = (uint8_t)(out->dh_window_count % OBSERVER_WINDOW_N);
+    out->dh_window_head = (uint8_t)(out->dh_window_count % N);
     Value *v;
     if ((v = dict_get(dict, "entropy"))      && v->type == VAL_NUM) out->entropy = v->data.num;
     if ((v = dict_get(dict, "dH"))           && v->type == VAL_NUM) out->dH = v->data.num;
diff --git a/src/eigenscript.h b/src/eigenscript.h
index 4fe253a8..0f58fdf3 100644
--- a/src/eigenscript.h
+++ b/src/eigenscript.h
@@ -259,22 +259,34 @@ typedef struct {
 typedef struct ObserverSlot {
     double  entropy, last_entropy, dH, prev_dH;
     int     obs_age;
-    double *dh_window;          /* lazily allocated, OBSERVER_WINDOW_N doubles */
+    double *dh_window;          /* lazily allocated ring of dH values; dh_cap deep */
     uint8_t dh_window_head, dh_window_count;
     uint8_t used;               /* 1 once this slot has been observed */
     /* #294 value-signal channel: the entropy window above tracks
      * entropy(value) — a lossy proxy that goes flat in mid-magnitude regions
      * (so a real value-oscillation reads "stable"). This parallel window tracks
-     * the value's OWN relative step Δv/(1+|v|), so `report_value of x`
-     * classifies the value trajectory directly. Same windowed logic/thresholds
-     * as the entropy channel; only the observed signal differs. */
+     * the value's OWN relative step (#1045: Δv / max(|v|, |v_prev|, scale)),
+     * so `report_value of x` classifies the value trajectory directly. Same
+     * windowed logic/thresholds as the entropy channel; only the observed
+     * signal differs. */
     double  last_value;         /* last observed numeric value (Δv source) */
-    double *v_window;           /* lazily allocated, OBSERVER_WINDOW_N relative-deltas */
+    double *v_window;           /* lazily allocated ring of relative steps; v_cap deep */
     double *vr_window;          /* #422 raw deltas (Δv un-normalized), same head/count:
                                  * the non-vanishing-step signal that catches additive
                                  * runaway and sub-deadband oscillation, both of which
                                  * relative normalization erases */
     uint8_t v_window_head, v_window_count;
+    /* #1044: ring CAPACITIES (what is allocated) and the per-binding window
+     * OVERRIDE (what the classifiers read). The depth a slot classifies over
+     * is observer_slot_window(s): win_override when nonzero, else the
+     * state's default (set_observer_window of n, OBSERVER_WINDOW_N at
+     * start). A ring is allocated at that depth on first push and re-grown
+     * (samples preserved, oldest first) when the depth in force exceeds the
+     * capacity; a depth SMALLER than the capacity simply reads the newest
+     * `depth` samples. So the common case — default depth, never touched —
+     * allocates exactly what it did before #1044. */
+    uint8_t v_cap, dh_cap;
+    uint8_t win_override;       /* 0 = follow the state default */
     uint8_t v_used;             /* 1 once a numeric value has been recorded */
     uint8_t v_last;             /* #861: 1 iff the MOST RECENT observed
                                  * assignment was numeric. The predicates and
@@ -359,6 +371,17 @@ struct Value {
  * a full window (count == OBSERVER_WINDOW_N) for "converged"-class
  * checks and a partial window (count >= 3) for trend-class checks. */
 #define OBSERVER_WINDOW_N 10
+/* #1044: the per-state default is set_observer_window of n; the per-binding
+ * form set_observer_window of ["x", n] overrides one slot. Both are clamped
+ * to [OBSERVER_WINDOW_MIN, OBSERVER_WINDOW_MAX]: the motion bands need two
+ * samples per half-window (4), and the ring counters are 8-bit. */
+#define OBSERVER_WINDOW_MIN 4
+#define OBSERVER_WINDOW_MAX 64
+/* Effective window depth of a slot (see the ObserverSlot comment). */
+int observer_slot_window(const struct ObserverSlot *s);
+/* Set / clear a binding's per-slot override (n == 0 clears). Grows the env's
+ * slot table if needed; returns 0 on OOM. */
+int observer_slot_set_window(struct Env *e, int idx, int n);
 
 /* Returns the current fill of v's dH window (0..OBSERVER_WINDOW_N). */
 size_t observer_window_size(const Value *v);
@@ -599,6 +622,8 @@ struct EigsState {
     double          obs_dh_zero;    /* |dH| < this → "zero change"  (default 0.001) */
     double          obs_dh_small;   /* |dH| < this → "small change" (default 0.01)  */
     double          obs_h_low;      /* entropy < this → "low info"  (default 0.1)   */
+    int             obs_window;     /* #1044 default value/dH window depth (default OBSERVER_WINDOW_N) */
+    double          obs_scale;      /* #1045 characteristic scale: rel = Δv / max(|v|, |v_prev|, obs_scale) (default 0.001) */
     /* #971: strict mode. Off by default — a wrong-typed or out-of-domain
      * argument gets a finite stand-in (NaN→0, domain clamps substitute,
      * overflow saturates, `cos of "hello"` → 0). On (EIGS_STRICT=1, read
@@ -1078,6 +1103,8 @@ extern __thread EigsThread *eigs_current;
 #define g_obs_dh_zero       (eigs_current->state->obs_dh_zero)
 #define g_obs_dh_small      (eigs_current->state->obs_dh_small)
 #define g_obs_h_low         (eigs_current->state->obs_h_low)
+#define g_obs_window        (eigs_current->state->obs_window)
+#define g_obs_scale         (eigs_current->state->obs_scale)
 #define g_global_env          (eigs_current->state->global_env)
 #define g_script_dir          (eigs_current->state->script_dir)
 #define g_exe_dir             (eigs_current->state->exe_dir)
diff --git a/src/lsp_builtin_index.h b/src/lsp_builtin_index.h
index d2ea1aa3..2739eca6 100644
--- a/src/lsp_builtin_index.h
+++ b/src/lsp_builtin_index.h
@@ -114,7 +114,9 @@ static const char *builtin_docs[][2] = {
     {"free_val", "free_val of value → frees a heap-allocated Value tree. Returns null."},
     {"gather", "gather of [tensor, indices, dim] → select elements at indices along last dim"},
     {"get_at", "get_at of [list, index] or get_at of [list, row, col]"},
+    {"get_observer_scale", "get_observer_scale of null — the value channel's characteristic scale."},
     {"get_observer_thresholds", "get_observer_thresholds — builtin; see docs/BUILTINS.md"},
+    {"get_observer_window", "get_observer_window of null | \"x\" — the default window depth, or the depth in force on binding \"x\"."},
     {"getcwd", "getcwd of null → current working directory as string"},
     {"gfx_circle", "gfx_circle of [cx, cy, radius, r, g, b] — filled circle via midpoint"},
     {"gfx_clear", "gfx_clear of [r, g, b]"},
@@ -255,7 +257,9 @@ static const char *builtin_docs[][2] = {
     {"seed_random", "seed_random of n → seeds the RNG, returns 1"},
     {"send", "send — builtin; see docs/BUILTINS.md"},
     {"set_at", "set_at of [list, index, value] — sets list[index] = value, returns list"},
+    {"set_observer_scale", "set_observer_scale of s — set the value channel's characteristic scale (the |v| below which a value counts as zero), s > 0."},
     {"set_observer_thresholds", "set_observer_thresholds — builtin; see docs/BUILTINS.md"},
+    {"set_observer_window", "set_observer_window of n | [\"x\", n] — set the default (n) or one binding's ([\"x\", n]) observer window depth, 4..64 samples."},
     {"sgd_update", "sgd_update of [param, grad, lr] — in-place param = param - lr * grad"},
     {"sgd_update_cols", "sgd_update_cols of [matrix, grad, col_indices, lr]"},
     {"sgd_update_rows", "sgd_update_rows of [matrix, grad, row_indices, lr]"},
diff --git a/src/state.c b/src/state.c
index 2438478f..8b6539e7 100644
--- a/src/state.c
+++ b/src/state.c
@@ -38,6 +38,8 @@ EigsState *eigs_state_new(void) {
     st->obs_dh_zero  = 0.001;
     st->obs_dh_small = 0.01;
     st->obs_h_low    = 0.1;
+    st->obs_window   = OBSERVER_WINDOW_N;   /* #1044 */
+    st->obs_scale    = 0.001;               /* #1045 */
     /* #971: strict math mode, read once from env at creation (like the JIT
      * thresholds below). Any non-empty, non-"0" value enables it. */
     st->strict = eigs_env_flag("EIGS_STRICT");
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 02d8bce8..7a985a9f 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -2855,6 +2855,17 @@ check_eigs_suite "unobserved: elided samples still enter the value window; entro
     test_unobserved_neutral.eigs "All tests passed" 26
 echo ""
 
+# [51b] #1044/#1045: the value channel's window depth (set_observer_window,
+# per state and per binding) and characteristic scale (set_observer_scale).
+# Closed-form stand-ins for phugoid's oracle: the rad/deg/mrad triplet gives
+# one verdict, rounding noise around zero certifies, a geometric decay is
+# `improving` until inside the scale, and the 1 Hz phugoid reads oscillating
+# (never diverging) once its binding's window covers a period.
+echo "[51b] Observer Window Depth + Characteristic Scale (#1044, #1045)"
+check_eigs_suite "scale-free relative step; per-state/per-binding window depth" \
+    test_observer_window_scale.eigs "All tests passed" 34
+echo ""
+
 # [52] Stream I/O
 echo "[52] Stream Tensor I/O"
 SI_OUTPUT=$(./eigenscript ../tests/test_stream_io.eigs 2>&1); SI_OUTPUT_RC=$?
diff --git a/tests/test_observer_saturation.eigs b/tests/test_observer_saturation.eigs
index 75386361..ad8fe119 100644
--- a/tests/test_observer_saturation.eigs
+++ b/tests/test_observer_saturation.eigs
@@ -42,9 +42,9 @@ define run_negative() as:
 define run_converge() as:
     local x is 100.0
     local k is 0
-    loop while k < 30:
-        x is x * 0.5
-        k is k + 1
+    loop while k < 40:                 # #1045: settles once ten steps sit under
+        x is x * 0.5                   # dh_zero*scale = 1e-6 (k >= 37); at 30
+        k is k + 1                     # it was still `improving` at x = 9e-8
     return [report of x, converged of x]
 
 # One decade below the ceiling, held constant: unsaturated, so the SATURATION
diff --git a/tests/test_observer_window_scale.eigs b/tests/test_observer_window_scale.eigs
new file mode 100644
index 00000000..b8339cbc
--- /dev/null
+++ b/tests/test_observer_window_scale.eigs
@@ -0,0 +1,245 @@
+# #1044 / #1045 — the value channel's window depth and characteristic scale.
+#
+# Both were found by phugoid grading observer verdicts against a physical
+# oracle (its tests/observer_check.eigs, tests/observer_lat_check.eigs):
+#
+#   #1045  rel = Δv/(1+|v|) was an ABSOLUTE deadband below |v| ~ 1, so one
+#          physical trajectory read `converged` stored in radians and `moving`
+#          in degrees. Now rel = Δv / max(|v|, |v_prev|, scale): unit-free above
+#          the characteristic scale (set_observer_scale, default 1e-3), an
+#          absolute floor dh_zero*scale below it.
+#   #1044  the window was a fixed 10 SAMPLES, so a mode slower than ~10 samples
+#          of the consumer's cadence could not fold inside it and read
+#          `diverging` on its rising quarter-cycles. set_observer_window of n
+#          (state default) and set_observer_window of ["x", n] (one binding)
+#          make the depth configurable, 4..64.
+#
+# The trajectories are closed-form stand-ins for the phugoid oracle's
+# (period, damping and magnitudes taken from the B747 approach data), so the
+# fixture is self-contained; the oracle programs themselves were rerun against
+# this build and flip exactly as the issues predicted (commit body).
+load_file of "lib/test.eigs"
+
+# ---------------------------------------------------------------- helpers
+# Verdict census over a replay: feed `chan` into a fresh binding, classify
+# after `warm` samples (a full window), return {verdict: count}.
+define census(chan, warm, win) as:
+    local z is 0.0
+    if win > 0:
+        set_observer_window of ["z", win]
+    local counts is {}
+    local i is 0
+    loop while i < (len of chan):
+        z is chan[i] + 0.0
+        if i >= warm:
+            local r is report of z
+            if has_key of [counts, r]:
+                counts[r] is counts[r] + 1
+            else:
+                counts[r] is 1
+        i is i + 1
+    return counts
+
+define count_of(counts, key) as:
+    if has_key of [counts, key]:
+        return counts[key]
+    return 0
+
+# ================================================================ #1045
+# --- (a) the unit triplet: the 747 spiral mode, bank angle 0.05 rad decaying
+# with t-half 14.9 s, replayed at 1 Hz in radians, degrees and milliradians.
+# Same physics, ONE verdict — and not `converged`: at t = 30 s the state is
+# still halving every 15 s (a ~4.6% step per sample).
+spiral is []
+t is 0
+loop while t <= 40:
+    append of [spiral, 0.05 * (pow of [2.0, 0.0 - t / 14.9])]
+    t is t + 1
+urad is 0.0
+udeg is 0.0
+umr is 0.0
+i is 0
+v_rad is ""
+v_deg is ""
+v_mr is ""
+loop while i < (len of spiral):
+    local s is spiral[i]
+    urad is s + 0.0
+    udeg is s * 57.29577951308232 + 0.0
+    umr is s * 1000.0 + 0.0
+    if i == 30:
+        v_rad is report of urad
+        v_deg is report of udeg
+        v_mr is report of umr
+    i is i + 1
+print of f"units: rad={v_rad} deg={v_deg} mrad={v_mr}"
+assert_eq of [v_deg, v_rad, "U1 radians and degrees give one verdict"]
+assert_eq of [v_mr, v_rad, "U2 radians and milliradians give one verdict"]
+assert_true of [v_rad != "converged", "U3 a state halving every 15 s is not converged (was `converged` in radians only)"]
+# the relative steps themselves agree across units (the scale is not reached)
+tr_rad is trajectory of urad
+tr_deg is trajectory of udeg
+assert_near of [tr_rad.rel[9], tr_deg.rel[9], 1e-12, "U4 the stored relative step is unit-free"]
+assert_near of [tr_rad.rel[9], 0.0 - 0.04545, 1e-3, "U5 rel is Δv over the step's own scale (~ -4.5% per sample at t-half 14.9 s)"]
+
+# --- (b) float noise around an exact zero is not motion: a value that is
+# analytically 0 but computed with rounding jitter must certify.
+nz is 0.0
+k is 0
+loop while k < 24:
+    nz is ((sin of (k * 1.0)) + (sin of (k * 1.0 + 3.141592653589793))) * 1e-1
+    k is k + 1
+assert_true of [(abs of nz) < 1e-15, "Z0 the probe really is rounding noise"]
+print of f"noise-around-zero: {report of nz}"
+assert_eq of [report of nz, "converged", "Z1 rounding noise around an exact zero reads converged"]
+assert_true of [converged of nz, "Z2 the converged predicate agrees"]
+
+# --- (c) a geometric decay toward zero reads improving, never converged, until
+# it is inside the scale — at ANY ratio, from any magnitude. The window-max
+# normalisation first proposed for #1045 fails exactly here (rel = (1-r)·r^9
+# certifies r = 0.3 at the first full window, 1e6·0.3^11 ≈ 1.8).
+define first_certified(x0, r, steps) as:
+    local x is x0
+    local k is 0
+    local hit_k is 0 - 1
+    local hit_x is 0.0
+    local mid is ""
+    loop while k < steps:
+        x is x * r
+        k is k + 1
+        if k == 15:
+            mid is report of x
+        if hit_k < 0:
+            if converged of x:
+                hit_k is k
+                hit_x is x
+    return [hit_k, hit_x, mid, x]
+
+d1 is first_certified of [1000000.0, 0.3, 60]
+print of f"decay 1e6*0.3^k: report@15={d1[2]} first converged at k={d1[0]} x={d1[1]}"
+assert_eq of [d1[2], "improving", "D1 1e6*0.3^15 = 14.3: still decaying -> improving (window-max would say converged)"]
+assert_true of [d1[0] > 0, "D2 the decay does certify eventually"]
+assert_true of [(abs of d1[1]) < (get_observer_scale of null), "D3 ... only once inside the characteristic scale"]
+d2 is first_certified of [8.0, 0.5, 60]
+print of f"decay 8*0.5^k: report@15={d2[2]} first converged at k={d2[0]} x={d2[1]}"
+assert_eq of [d2[2], "improving", "D4 8*0.5^15 = 2.4e-4: inside the scale but steps still 50% of |x| -> improving"]
+assert_true of [(abs of d2[1]) < 1e-6, "D5 certifies when a full window of steps sits under dh_zero*scale = 1e-6"]
+
+# --- the scale knob: raising it to 1 restores an absolute deadband of dh_zero
+# (the pre-#1045 shape) — the radians reading certifies while degrees move.
+set_observer_scale of 1.0
+assert_eq of [get_observer_scale of null, 1, "S0 get_observer_scale reads the knob"]
+srad is 0.0
+sdeg is 0.0
+i is 0
+loop while i < (len of spiral):
+    local s2 is spiral[i]
+    srad is s2 + 0.0
+    sdeg is s2 * 57.29577951308232 + 0.0
+    i is i + 1
+print of f"scale=1: rad={report of srad} deg={report of sdeg}"
+assert_eq of [report of srad, "converged", "S1 scale 1: sub-unit radians fall under the absolute deadband"]
+assert_true of [(report of sdeg) != "converged", "S2 scale 1: the same physics in degrees does not (the #1045 defect, now opt-in)"]
+set_observer_scale of 0.001
+
+# ================================================================ #1044
+# --- the 747 phugoid at 1 Hz: T = 46.9 s, lightly damped, riding on the trim
+# airspeed (~272 m/s, amplitude ~10 m/s — a 3.7% swing whose per-sample steps
+# stay above the deadband for the whole replay). Physics truth throughout:
+# oscillating.
+phug is []
+t is 0
+loop while t < 240:
+    local env_ is 10.0 * (exp of (0.0 - 0.003 * t))
+    append of [phug, 272.4 + env_ * (cos of (6.283185307179586 * t / 46.9))]
+    t is t + 1
+
+# control: at the default 10-sample window the fold is invisible — the census
+# over every full-window sample contains the alarm verdict `diverging`.
+c10 is census of [phug, 10, 0]
+print of f"phugoid @ N=10: {c10}"
+assert_true of [(count_of of [c10, "diverging"]) > 0, "P0 control: N=10 reads diverging on rising quarter-cycles (the #1044 defect)"]
+
+# fix: widen the binding's window to cover a period (50 >= 46.9 samples).
+c50 is census of [phug, 50, 50]
+print of f"phugoid @ N=50: {c50}"
+assert_eq of [count_of of [c50, "diverging"], 0, "P1 N=50: diverging never appears at a full window"]
+assert_eq of [count_of of [c50, "oscillating"], 240 - 50, "P2 N=50: every full-window sample reads oscillating"]
+
+# the three probe points, the oracle's shape (w1 widened, its sibling not)
+w1 is 0.0
+w10 is 0.0
+set_observer_window of ["w1", 50]
+assert_eq of [get_observer_window of "w1", 50, "P3 get_observer_window reads the override"]
+assert_eq of [get_observer_window of "w10", 10, "P4 the sibling binding keeps the default"]
+p1 is []
+p10 is []
+i is 0
+loop while i < (len of phug):
+    w1 is phug[i] + 0.0
+    w10 is phug[i] + 0.0
+    if i == 75 or i == 155 or i == 235:
+        append of [p1, report of w1]
+        append of [p10, report of w10]
+    i is i + 1
+print of f"probes N=50: {p1}   N=10: {p10}"
+assert_eq of [str of p1, "[\"oscillating\", \"oscillating\", \"oscillating\"]", "P5 the three probe points read oscillating"]
+assert_true of [(str of p10) != (str of p1), "P6 the override affected only its binding (the sibling still misreads)"]
+assert_true of [oscillating of w1, "P7 the named predicate agrees"]
+
+# the snapshot carries the depth: classify of (trajectory of w1) == report of w1
+tw is trajectory of w1
+assert_eq of [tw.window, 50, "P8 a trajectory snapshot records its window depth"]
+assert_eq of [len of tw.rel, 50, "P9 ... and holds that many steps"]
+assert_eq of [classify of tw, report of w1, "P10 classify of a snapshot agrees with the live verdict"]
+
+# clearing the override returns the binding to the default
+set_observer_window of ["w1", 0]
+assert_eq of [get_observer_window of "w1", 10, "P11 [name, 0] clears the override"]
+
+# the state default: applies to bindings that never set an override, live
+set_observer_window of 50
+assert_eq of [get_observer_window of null, 50, "P12 get_observer_window of null reads the default"]
+cdef is census of [phug, 50, 0]
+assert_eq of [count_of of [cdef, "diverging"], 0, "P13 the default depth governs an unoverridden binding"]
+set_observer_window of 10
+
+# a narrower window certifies sooner (four quiet steps)
+q is 5.0
+set_observer_window of ["q", 4]
+for j in range of 4:
+    q is 5.0
+assert_true of [converged of q, "P14 a 4-deep window certifies after four quiet steps"]
+q2 is 5.0
+for j in range of 4:
+    q2 is 5.0
+assert_false of [converged of q2, "P15 ... while the default 10-deep window does not yet"]
+
+# a fn-local reached by name (the string operand marks the local interrogated)
+define widen_local() as:
+    local zz is 0.0
+    set_observer_window of ["zz", 20]
+    return get_observer_window of "zz"
+assert_eq of [widen_local of null, 20, "P16 the per-binding form reaches a function local"]
+
+# the range is enforced loudly
+bad is 0
+try:
+    set_observer_window of 3
+catch e:
+    bad is bad + 1
+try:
+    set_observer_window of 65
+catch e:
+    bad is bad + 1
+try:
+    set_observer_window of ["no_such_binding", 12]
+catch e:
+    bad is bad + 1
+try:
+    set_observer_scale of 0
+catch e:
+    bad is bad + 1
+assert_eq of [bad, 4, "E1 out-of-range depth, unbound name and non-positive scale all raise"]
+
+test_summary of null
diff --git a/tests/test_predicate_matrix.eigs b/tests/test_predicate_matrix.eigs
index 79627909..1997dba9 100644
--- a/tests/test_predicate_matrix.eigs
+++ b/tests/test_predicate_matrix.eigs
@@ -215,8 +215,20 @@ mi is 0
 loop while mi < 20:
     m is m * 0.5
     mi is mi + 1
+pm20 is [converged of m, stable of m, improving of m, diverging of m, oscillating of m, equilibrium of m, report of m]
+# #1045: after 20 halvings m is 8.6e-7 — inside the characteristic scale
+# (1e-3), but its steps are still 50% of its own size per step and only the
+# last one is under the absolute floor dh_zero*scale = 1e-6: a decay still in
+# progress reads `improving` (the (c) property of the scale-free step — a
+# geometric decay is never certified merely for being small). The old
+# Δv/(1+|v|) certified it here because 8.8e-4 < dh_zero in ABSOLUTE terms —
+# the same decay stored in millis would have read improving.
+expect of ["mid-decay toward zero (#1045)", pm20, 0, 0, 1, 0, 0, 0, "improving"]
+loop while mi < 30:
+    m is m * 0.5
+    mi is mi + 1
 pm is [converged of m, stable of m, improving of m, diverging of m, oscillating of m, equilibrium of m, report of m]
-# #861: the value route CERTIFIES this settle — a decay toward zero is exactly what converged should claim. The #735 no-band gray state remains constructible only on the entropy channel (non-numeric bindings)
+# #861: the value route CERTIFIES this settle — a decay toward zero is exactly what converged should claim once a full window of steps sits under the floor (ten more halvings: steps 4e-7 .. 8e-10). The #735 no-band gray state remains constructible only on the entropy channel (non-numeric bindings)
 expect of ["full-window residual drift (#735)", pm, 1, 1, 0, 0, 0, 1, "converged"]
 
 # --- The full-window agreement guarantee (PREDICATES.md "The report builtin"),
diff --git a/tests/test_report_alignment.eigs b/tests/test_report_alignment.eigs
index d5f74576..c54a928a 100644
--- a/tests/test_report_alignment.eigs
+++ b/tests/test_report_alignment.eigs
@@ -33,10 +33,13 @@ print of (report of b)
 print of ""
 
 # RA3: converged — a settled decay (full window under the deadband).
+# #1045: the deadband is absolute only inside the characteristic scale, at
+# dh_zero*scale = 1e-6; 30 halvings of 100 (9e-8, steps 7e-7..9e-8 over the
+# last four) were still `improving`, 40 sit a full window under the floor.
 print of "--- RA3: Converged (settled decay) ---"
 c is 100.0
 i is 0
-loop while i < 30:
+loop while i < 40:
     c is c * 0.5
     i is i + 1
 print of (str of (converged of c))
diff --git a/tests/test_step.sh b/tests/test_step.sh
index 32f6f664..1b0a380c 100644
--- a/tests/test_step.sh
+++ b/tests/test_step.sh
@@ -28,16 +28,19 @@ if [ ! -x "$EIGS" ]; then
 fi
 
 # ---- fixture: an oscillator, a halving (converging) binding, a string,
-# and one nondet call. 30 halvings of 1024 push the relative step below
-# dh_zero (0.001) with a full 10-wide window to spare -> [converged];
-# the +1/-1 alternation sign-flips every step -> [oscillating].
+# and one nondet call. 40 halvings of 1024 push the step below the absolute
+# settle floor dh_zero*scale (1e-3 * 1e-3 = 1e-6, #1045 — a value inside the
+# characteristic scale settles on |dv|, above it on dv/|v|) with a full
+# 10-wide window to spare -> [converged]; 30 halvings only reached 9.5e-7
+# on the LAST step, one under the floor, so the window still read
+# [improving]. The +1/-1 alternation sign-flips every step -> [oscillating].
 FIX="$TMPDIR/fix.eigs"
 cat > "$FIX" <<'EOF'
 osc is 1
 conv is 1024
 msg is "hello"
 seed is random of null
-for i in range of 30:
+for i in range of 40:
     osc is 0 - osc
     conv is conv / 2
 print of conv
@@ -116,7 +119,7 @@ echo "$OUT" | grep -q "line 8" && echo "$OUT" | grep -q "line 1" \
 
 # ---- 8. trajectory view: per-assign running labels
 OUT=$(drive "s 200" "t conv" q)
-echo "$OUT" | grep -q "^conv: 31 assigns" \
+echo "$OUT" | grep -q "^conv: 41 assigns" \
     && echo "$OUT" | grep -q "earlier assign(s) elided" \
     && echo "$OUT" | grep -Eq "\[improving\]" \
     && echo "$OUT" | grep -Eq "\[converged\]" \
diff --git a/tests/test_unobserved_neutral.eigs b/tests/test_unobserved_neutral.eigs
index de9f1c7c..b0f3f0cf 100644
--- a/tests/test_unobserved_neutral.eigs
+++ b/tests/test_unobserved_neutral.eigs
@@ -25,7 +25,10 @@ define run1(elide_init) as:
         b is 0.0
     hits is []
     verdicts is []
-    amp is 0.0004
+    amp is 0.0000004                   # #1045: "sub-deadband" is now under the
+                                       # ABSOLUTE floor dh_zero*scale = 1e-6 (a
+                                       # 4e-4 wobble around zero is 40% of the
+                                       # scale — real motion, not settled)
     k is 0
     loop while k < 40:
         b is amp * (k % 2)             # settled: a decaying sub-deadband wobble
@@ -81,7 +84,7 @@ assert_eq of [str of u2[0], str of o2[0], "P2 hit indices identical with read 50
 unobserved:  # lint: allow W020 -- elided initialiser, name path
     nu is 0.0
 no is 0.0
-namp is 0.0004
+namp is 0.0000004                      # #1045: under the absolute floor (see P1)
 nk is 0
 n_hits_o is []
 n_hits_u is []

From 983053cb615ae57b90a83e0e79e426efb538a065 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 17:04:25 +0000
Subject: [PATCH 07/39] observer: hoist the gate ahead of the observe helpers,
 interpreter and JIT (#972)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#972's last measured residual. With the #915 gate CLOSED — nothing compiled
into the state can interrogate the observer — `OBSERVE_ASSIGN_LOCAL` and
`OBSERVE_NAME_POST` still dispatched into their helpers on every assignment:
a call, the TOS decode, the slot or (module level) hashed name resolution,
only to return at `observer_slot_update_num`'s own gate test one frame later.
`unobserved:` short-circuited earlier, which is where the measured gap came
from.

The gate test is now the FIRST thing both opcodes do — in the interpreter
`CASE` bodies, in the two JIT helpers, and inlined into the thunk ahead of the
call by a new `emit_obs_gate_test()` (the same two loads `eigs_obs_gate_open()`
makes: `VM.owner -> EigsThread.state -> obs_needed`, then the trace-history
flag through its baked storage address, so a mid-run arming, a SIGUSR1 dump or
a descriptor still opens it live — nothing is baked but the flag's address).
%rax is scratch between ops and the stack is untouched, so `last_imm` is the
same on both arms of the merge and the post-op advance writeback is emitted
after it. The JIT also stops emitting a call for `OP_OBSERVE_ASSIGN`, whose
helper has been a no-op since #262 Phase-3/E (a name binding is observed by
the `OBSERVE_NAME_POST` after its SET); the op still advances 3 bytes and
still falls through the `last_imm` switch default.

Repro (20M-iteration read-free loop, user+sys CPU, n=5 medians, shared box —
provisional, see docs/OBSERVER.md for the table):

  before  eigenscript verify972/big_a.eigs   4.12 s   (module level, `x` a NAME)
  after   eigenscript verify972/big_a.eigs   3.88 s
  before  eigenscript verify972/fn_a.eigs    2.94 s   (function level, JIT'd)
  after   eigenscript verify972/fn_a.eigs    2.85 s

and against the like-for-like `unobserved:` control (`big_c2`: the same block,
but `print of x` outside it, so #871 Part B refuses the module-slot promotion
and the binding stays a NAME) the read-free arm went +5.6% -> -1.8%. The ~15%
that remains against the *promoted* `unobserved:` arm is that slot promotion,
not the observer: `big_c` 3.37 s vs `big_c2` 3.95 s on the same binary. Reader
arm (`report of x`) and `EIGS_OBS_FORCE=1` arms are unchanged within 0.3%.

The instrument. `obs-gate: unobserved <unit>` cannot tell "skipped" from
"called and returned at the gate", and neither can the observer slot's `used`
flag — the helper never touched the slot in either case. So
`EIGS_OBS_GATE_STATS=1` now also prints, at exit, `obs-gate: observe-calls N`:
how many times an observer update/sample entry point was ENTERED, counted
before each one's own gate test. Off, it is one predictable branch on a cold
global; on, a relaxed atomic add (workers observe too). Host-only report; the
freestanding profile never sets the flag.

Regression: suite section [99u] checks 45-50 (pin 44 -> 50). A read-free
module-level loop and a read-free fn-local loop must report `calls=0` after
1000 assignments, on the interpreter AND on a WITNESSED JIT thunk
(`EIGS_JIT_STATS` `compiled=` is part of the verdict — a loop that never got a
thunk would score 0 while running interpreted), plus two controls: a reader
and `EIGS_OBS_FORCE=1` must report `populated`. Planted faults, all executed:
(A) interpreter hoists reverted -> checks 45-48 red (`calls=populated`, and
`calls=2` on the JIT arms from the pre-OSR iterations); (B) `emit_obs_gate_test`
removed -> 47/48 red (`calls=999`); (C) the tally made vacuous -> the two
controls red. Section green at 51/51 on release and under ASan.

Verifier's four #972 items, re-executed on this build: (1) the elision — this
commit; (2) assembled chunks arm via `eigs_obs_enable_runtime()` in
`vm_run_bytecode`/`sandbox_run` — [99u] "a descriptor ARMS the observer for its
OWN writes" green; (3) the JIT reader needs no own scan, the read opcode is in
the chunk the compiler scanned — `tools/obs_reader_sync_check.sh` PASS (15
marker readers, 17 switch entries, 38 assertions); (4) the SIGUSR1 dump says
"observer gate CLOSED … absence of data, NOT equilibrium" — [99e] green.

Correctness: `tools/observer_gate_diff.sh` base-vs-hoist over the full corpus,
both binaries run out of the same worktree `src/` so stdlib and diagnostic
paths are identical — 498 programs compared, 0 mismatches, 24 nondeterministic
excluded by the two-run self-diff. `tools/jit_diff.sh` OK (231 programs x
{jit, osr}, 0 ledgered). `tools/obs_marker_check.sh` PASS. `make jit-smoke`,
`make freestanding-check` green. Full release suite 4280/4280.

Closes #972

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 docs/OBSERVER.md       | 48 +++++++++++++++++++++++++-
 src/eigenscript.c      | 15 +++++++++
 src/eigenscript.h      | 17 ++++++++++
 src/jit.c              | 76 ++++++++++++++++++++++++++++++++----------
 src/jit.h              |  6 ++++
 src/jit_smoke.c        |  1 +
 src/main.c             |  7 ++++
 src/vm.c               | 43 +++++++++++++++++++-----
 tests/run_all_tests.sh | 70 +++++++++++++++++++++++++++++++++++++-
 9 files changed, 255 insertions(+), 28 deletions(-)

diff --git a/docs/OBSERVER.md b/docs/OBSERVER.md
index 93303918..9b65b982 100644
--- a/docs/OBSERVER.md
+++ b/docs/OBSERVER.md
@@ -511,6 +511,52 @@ reads **no** observer state at all — `when` / `where` / `why` / `how` on a val
 operand return constants, because observer state is binding-keyed and a bare
 value has no binding.
 
+**What "pays nothing" means at the instruction level (#972).** The gate is
+decided at compile time but *tested* at run time, because it can open mid-run
+(a runtime arming, a SIGUSR1 dump, a descriptor). Where that test sits
+matters: until #972's last residual was closed, `OBSERVE_ASSIGN_LOCAL` and
+`OBSERVE_NAME_POST` still dispatched into their helpers — a call, the TOS
+decode, the slot or name resolution (a hash lookup for a module-level name) —
+and only *then* returned at `observer_slot_update_num`'s gate test, which
+measured as +18% (module level) / +14% (function level, JIT) over
+`unobserved:` on a 20M-iteration read-free loop. The test is now the first
+thing both opcodes do, in the interpreter `CASE` bodies and inlined into the
+JIT thunk ahead of the helper call (`emit_obs_gate_test`, src/jit.c — the
+same two loads `eigs_obs_gate_open()` makes, through the VM's owner
+back-pointer so nothing is baked but the trace flag's address), and the JIT
+no longer emits a call for the no-op `OP_OBSERVE_ASSIGN` at all. With the gate
+closed a read-free program's assignment therefore costs the two flag loads and
+a branch; with it open nothing changes. The `observe-calls` tally above is the
+regression instrument: suite section [99u] pins it at `0` for a read-free loop
+on both the interpreter and a witnessed JIT thunk, and at `populated` with a
+reader or `EIGS_OBS_FORCE=1`.
+
+**And what is left is not the observer — measured, with the control.** After
+the hoist, a read-free module-level loop is still slower than the same loop
+wrapped in `unobserved:`, and it is tempting to read that as observer cost
+still leaking. It is not. `unobserved:` does a *second* thing at module scope:
+#871 Part B promotes the names a block writes to module SLOTS when escape
+analysis says nothing outside the block reads them, which replaces a hashed
+`SET_NAME` with a slot store. The control that separates the two is the same
+`unobserved:` program with its `print` moved OUTSIDE the block, so the
+promotion is refused and the binding stays a module name (20M iterations, user
++sys CPU, n=5 medians, one shared box):
+
+| module-level probe | v0.43.0 | pre-hoist | post-hoist |
+|---|---|---|---|
+| read-free, `x` a module NAME | 4.13 s | 4.12 s | **3.88 s** |
+| `unobserved:`, `x` promoted to a module SLOT | 3.41 s | 3.42 s | 3.37 s |
+| `unobserved:`, promotion refused, `x` a NAME | 3.91 s | 3.90 s | 3.95 s |
+
+Against the like-for-like row the read-free arm went from +5.6% to −1.8%: the
+observer residual is gone. The ~15% that remains against the promoted row is
+the slot promotion, and it is available to any binding a slot can hold — it is
+a scope-and-storage result, not an observer one. Inside a function, where
+locals are already slots, the read-free arm is at or just under the
+`unobserved:` one (2.85 s vs 2.93 s post-hoist; 2.94 s vs 2.96 s before it). Quoting
+the raw `unobserved:`-vs-plain gap as "what the observer costs" over-attributes
+it by roughly three-quarters.
+
 ## Using the gate
 
 The gate is automatic and needs no source change. A program that never reads
@@ -519,7 +565,7 @@ observer state pays nothing for it; a program that does is unaffected.
 | control | effect |
 |---|---|
 | `EIGS_OBS_FORCE=1` | force observer recording ON, whatever the scan decided. The escape hatch, and the baseline arm for any measurement — one byte-identical binary serves both arms. |
-| `EIGS_OBS_GATE_STATS=1` | print one `obs-gate: observed\|unobserved <unit>` line per compiled unit on stderr. |
+| `EIGS_OBS_GATE_STATS=1` | print one `obs-gate: observed\|unobserved <unit>` line per compiled unit on stderr, and at exit one `obs-gate: observe-calls N` line: how many times an observer update/sample entry point was *entered* (counted before its own gate test). A read-free program must report `0` — the observe ops skip the helper call outright when the gate is closed (#972, below), and the per-unit verdict alone cannot tell "skipped" from "called and returned at the gate". |
 
 Both follow the tree's flag convention: any non-empty value that does not
 start with `0` turns the control on, so `=0` and `=` leave it off.
diff --git a/src/eigenscript.c b/src/eigenscript.c
index e9e2b591..9cb59b75 100644
--- a/src/eigenscript.c
+++ b/src/eigenscript.c
@@ -705,7 +705,19 @@ static void observer_slot_update_e(Env *e, int idx, double new_entropy) {
  * — the same drift shape #921/#925 are open on. One read, no copies. */
 #define g_trace_obs_hist __atomic_load_n(&g_trace_obs_hist_storage, __ATOMIC_RELAXED)
 
+/* #972: the observe-call tally (eigenscript.h) — a debug instrument, so its
+ * report is host-only; the freestanding profile never sets the flag. */
+int  g_obs_count_observe_calls = 0;
+long g_obs_observe_calls = 0;
+void eigs_obs_gate_stats_report(void) {
+#if !EIGENSCRIPT_FREESTANDING
+    fprintf(stderr, "obs-gate: observe-calls %ld\n",
+            __atomic_load_n(&g_obs_observe_calls, __ATOMIC_RELAXED));
+#endif
+}
+
 void observer_slot_update(Env *e, int idx, Value *newval) {
+    eigs_obs_count_call();   /* #972: before the gate test, by design */
     /* #915: nothing compiled into this state can interrogate the observer, so
      * skip the entropy walk entirely. compute_entropy recurses through every
      * reachable list item and dict value, which is where the 88% goes.
@@ -740,6 +752,7 @@ void observer_slot_update(Env *e, int idx, Value *newval) {
  * number, so the default path can observe without promoting the num to a
  * tracked Value. Same trajectory math as observer_slot_update. */
 void observer_slot_update_num(Env *e, int idx, double num) {
+    eigs_obs_count_call();   /* #972 */
     if (!eigs_obs_gate_open()) return;           /* #915 — see observer_slot_update */
     observer_slot_update_e(e, idx, entropy_of_num(num));
     ObserverSlot *vs = env_obs_slot(e, idx);    /* #294 value-signal channel */
@@ -777,6 +790,7 @@ void observer_slot_update_num(Env *e, int idx, double num) {
  * says so. Gated by the same #915 observer gate as the full update: a
  * program nothing in which reads the observer still pays nothing. */
 void observer_slot_sample_num(Env *e, int idx, double num) {
+    eigs_obs_count_call();   /* #972 */
     if (!eigs_obs_gate_open()) return;
     if (!e || idx < 0) return;
     if (idx >= e->obs_cap && !observer_obs_grow(e, idx)) return;
@@ -787,6 +801,7 @@ void observer_slot_sample_num(Env *e, int idx, double num) {
 }
 
 void observer_slot_sample(Env *e, int idx, Value *newval) {
+    eigs_obs_count_call();   /* #972 */
     if (!eigs_obs_gate_open()) return;
     if (newval && newval->type == VAL_NUM) {
         observer_slot_sample_num(e, idx, newval->data.num);
diff --git a/src/eigenscript.h b/src/eigenscript.h
index 0f58fdf3..34579ba7 100644
--- a/src/eigenscript.h
+++ b/src/eigenscript.h
@@ -1485,6 +1485,23 @@ static inline int eigs_obs_gate_open(void) {
     return g_obs_needed || __atomic_load_n(&g_trace_obs_hist_storage, __ATOMIC_RELAXED);
 }
 
+/* #972: debug counter behind EIGS_OBS_GATE_STATS=1 — how many times an
+ * observer update/sample entry point (observer_slot_update[_num],
+ * observer_slot_sample[_num], the JIT observe helpers) was ENTERED, counted
+ * before each one's own gate test. With the gate closed the observe ops are
+ * meant to skip the helper call entirely (the hoist this counter pins), so
+ * the tally must read 0 for a read-free program; `obs-gate: unobserved`
+ * alone cannot see the difference between "skipped" and "called and
+ * returned at the gate". One predictable branch on a cold global when the
+ * flag is off; a relaxed atomic add when it is on (workers observe too). */
+extern int  g_obs_count_observe_calls;
+extern long g_obs_observe_calls;
+static inline void eigs_obs_count_call(void) {
+    if (__builtin_expect(g_obs_count_observe_calls, 0))
+        __atomic_fetch_add(&g_obs_observe_calls, 1, __ATOMIC_RELAXED);
+}
+void eigs_obs_gate_stats_report(void);   /* prints `obs-gate: observe-calls N` */
+
 Env* env_new(Env *parent);
 void env_global_shared_lock(void);    /* #1035: module-env lock for external readers */
 void env_global_shared_unlock(void);
diff --git a/src/jit.c b/src/jit.c
index 30898a20..9479cfb4 100644
--- a/src/jit.c
+++ b/src/jit.c
@@ -1711,6 +1711,43 @@ static uint8_t *emit_incl_rdi_r9_4(uint8_t *w) {
 static uint8_t *emit_cmpl_0_mem_rax(uint8_t *w) {
     *w++ = 0x83; *w++ = 0x38; *w++ = 0x00; return w;
 }
+static uint8_t *emit_mov_disp32_rax_to_rax(uint8_t *w, int32_t disp);
+static uint8_t *emit_cmpl_imm32_disp32_rax(uint8_t *w, int32_t disp, uint32_t imm);
+static uint8_t *emit_jne_rel32(uint8_t *w, uint8_t **patch);
+static uint8_t *emit_je_rel32(uint8_t *w, uint8_t **patch);
+static void patch_rel32(uint8_t *patch, uint8_t *target);
+/* #972: the observer gate, inline, ahead of an observe helper call.
+ *
+ *     mov    off_vm_owner(%rbx), %rax        ; EigsThread*
+ *     mov    off_thread_state(%rax), %rax    ; EigsState*
+ *     cmpl   $0, off_state_obs_needed(%rax)  ; compile-time half
+ *     jne    .call
+ *     movabs $&g_trace_obs_hist_storage, %rax
+ *     cmpl   $0, (%rax)                      ; runtime half (a tape recording)
+ *     je     .skip                           ; <- caller patches after the call
+ * .call:
+ *
+ * Exactly eigs_obs_gate_open() (eigenscript.h), read live: the gate can open
+ * mid-run (a runtime arming, SIGUSR1, a descriptor), so nothing is baked but
+ * the trace flag's ADDRESS — the storage symbol, as the SET_NAME arms do.
+ * The plain loads are relaxed atomics at ISA level on x86 (the recorded JIT
+ * rule). Before this, a read-free program's OSR'd loop paid a full helper
+ * call per assignment (call, TOS decode, slot/name resolution) only to
+ * return at the helper's own gate test — the one residual #1034/#1024 left
+ * on #972. %rax is scratch between ops; the stack is untouched, so last_imm
+ * is the same on both arms of the merge. */
+static uint8_t *emit_obs_gate_test(uint8_t *w, uint8_t **skip_patch) {
+    uint8_t *call_p;
+    w = emit_mov_disp32_rbx_to_rax(w, g_layout.off_vm_owner);
+    w = emit_mov_disp32_rax_to_rax(w, g_layout.off_thread_state);
+    w = emit_cmpl_imm32_disp32_rax(w, g_layout.off_state_obs_needed, 0);
+    w = emit_jne_rel32(w, &call_p);
+    w = emit_movabs_rax(w, (uint64_t)(uintptr_t)&g_trace_obs_hist_storage);
+    w = emit_cmpl_0_mem_rax(w);
+    w = emit_je_rel32(w, skip_patch);
+    patch_rel32(call_p, w);
+    return w;
+}
 /* mov (%rax), %rax  (3 bytes) — deref a baked pointer-to-pointer (#410:
  * load the registered abort-flag pointer before testing the flag). */
 static uint8_t *emit_mov_mem_rax_to_rax(uint8_t *w) {
@@ -3006,30 +3043,27 @@ static void jit_compile_to_thunk(struct EigsChunk *chunk,
             if (done_p) patch_rel32(done_p, w);
             i += 5;
         } else if (op == OP_OBSERVE_ASSIGN) {
-            /* Stage 4o: out-of-line call to
-             *   jit_helper_observe_assign(chunk, name_idx).
-             * chunk arrives via %r14 (has_bail_op forces load). Helper
-             * reads g_vm.stack[sp-1] — sync %ecx → g_vm.sp before call.
-             * Helper does not change sp; reload %ecx after for safety
-             * (matches existing helper pattern, ~1 load). */
-            uint16_t name_idx = (uint16_t)(chunk->code[i + 1] |
-                                           ((uint16_t)chunk->code[i + 2] << 8));
-            w = emit_mov_ecx_to_disp32_rbx(w, g_layout.off_sp);
-            w = emit_mov_r14_rdi(w);
-            w = emit_mov_imm32_esi(w, (uint32_t)name_idx);
-            w = emit_push_rcx(w);
-            w = emit_movabs_rax(w, (uint64_t)(uintptr_t)&jit_helper_observe_assign);
-            w = emit_call_rax(w);
-            w = emit_pop_rcx(w);
-            w = emit_mov_disp32_rbx_to_ecx(w, g_layout.off_sp);
+            /* Stage 4o used to emit an out-of-line call to
+             *   jit_helper_observe_assign(chunk, name_idx)
+             * here. Since #262 Phase-3/E that helper (and the interpreter's
+             * CASE(OBSERVE_ASSIGN)) is a no-op — a name binding is observed by
+             * the OBSERVE_NAME_POST the compiler emits after its SET — so the
+             * call was a full helper-call round trip per name assignment that
+             * did nothing (#972). Emit nothing; the op still advances by its
+             * 3 bytes, and last_imm falls through the switch's default (0)
+             * exactly as it did around the call. The helper stays defined
+             * (jit_smoke stubs it) for anything that still takes its address. */
             i += 3;
         } else if (op == OP_OBSERVE_ASSIGN_LOCAL) {
             /* Stage 4o: out-of-line call to
              *   jit_helper_observe_assign_local(slot).
              * No chunk needed; slot in %edi. Same sp sync/reload as
-             * OBSERVE_ASSIGN. */
+             * OBSERVE_NAME_POST. #972: guarded by the inline gate test — a
+             * read-free program skips the call entirely. */
             uint16_t slot = (uint16_t)(chunk->code[i + 1] |
                                        ((uint16_t)chunk->code[i + 2] << 8));
+            uint8_t *skip_p;
+            w = emit_obs_gate_test(w, &skip_p);
             w = emit_mov_ecx_to_disp32_rbx(w, g_layout.off_sp);
             w = emit_mov_imm32_edi(w, (uint32_t)slot);
             w = emit_push_rcx(w);
@@ -3037,6 +3071,7 @@ static void jit_compile_to_thunk(struct EigsChunk *chunk,
             w = emit_call_rax(w);
             w = emit_pop_rcx(w);
             w = emit_mov_disp32_rbx_to_ecx(w, g_layout.off_sp);
+            patch_rel32(skip_p, w);
             i += 3;
         } else if (op == OP_REPORT_SLOT) {
             /* #262 C.2: jit_helper_report_slot(slot) — pushes the band string.
@@ -3055,9 +3090,13 @@ static void jit_compile_to_thunk(struct EigsChunk *chunk,
         } else if (op == OP_OBSERVE_NAME_POST) {
             /* #262 C.2: jit_helper_observe_name_post(chunk, name_idx). chunk via
              * %r14 (has_bail_op); name_idx in %esi. Peeks TOS, no stack change;
-             * same sp sync/reload as OBSERVE_ASSIGN. */
+             * sp synced before and reloaded after (the helper pattern). #972:
+             * guarded by the inline gate test — a read-free program skips the
+             * call (and the name resolution inside it) entirely. */
             uint16_t name_idx = (uint16_t)(chunk->code[i + 1] |
                                            ((uint16_t)chunk->code[i + 2] << 8));
+            uint8_t *skip_p;
+            w = emit_obs_gate_test(w, &skip_p);
             w = emit_mov_ecx_to_disp32_rbx(w, g_layout.off_sp);
             w = emit_mov_r14_rdi(w);
             w = emit_mov_imm32_esi(w, (uint32_t)name_idx);
@@ -3066,6 +3105,7 @@ static void jit_compile_to_thunk(struct EigsChunk *chunk,
             w = emit_call_rax(w);
             w = emit_pop_rcx(w);
             w = emit_mov_disp32_rbx_to_ecx(w, g_layout.off_sp);
+            patch_rel32(skip_p, w);
             i += 3;
         } else if (op == OP_UNOBSERVED_BEGIN) {
             /* unobserved_depth now lives on EigsThread; reach it via
diff --git a/src/jit.h b/src/jit.h
index c9fb1fce..29ae17f3 100644
--- a/src/jit.h
+++ b/src/jit.h
@@ -129,6 +129,12 @@ typedef struct {
                                        * to the owning EigsThread; lets the
                                        * JIT reach EigsThread fields without
                                        * a second TLS lookup mid-thunk. */
+    /* #972: the observer gate, inlined ahead of the observe helpers —
+     * eigs_obs_gate_open() is `eigs_current->state->obs_needed ||
+     * g_trace_obs_hist_storage`; the thunk reaches the state through
+     * VM.owner -> EigsThread.state. */
+    int  off_thread_state;            /* offsetof(EigsThread, state) */
+    int  off_state_obs_needed;        /* offsetof(EigsState, obs_needed) */
     int  off_sp;
     int  off_stack;
     int  off_frame_count;
diff --git a/src/jit_smoke.c b/src/jit_smoke.c
index cf178e52..0e62c2dc 100644
--- a/src/jit_smoke.c
+++ b/src/jit_smoke.c
@@ -39,6 +39,7 @@ void gc_note_possible_root(Value *v) { (void)v; }
 /* Stage 5b references &g_trace_hist as an immediate in the SET-name
  * inline trace gate. Lives in trace.c in the real binary. */
 int g_trace_hist_storage = 0;
+int g_trace_obs_hist_storage = 0;   /* #972: emit_obs_gate_test bakes its address */
 /* OP_LINE bakes &g_trace_current_line to stamp the history line. trace.c. */
 int g_trace_current_line = 0;
 /* #410: the back-edge abort poll bakes &g_vm_abort_flag (vm.c). Never NULL
diff --git a/src/main.c b/src/main.c
index 7309837c..bd3ab9a7 100644
--- a/src/main.c
+++ b/src/main.c
@@ -145,6 +145,13 @@ int main(int argc, char **argv) {
 
     trace_init();
     atexit(trace_shutdown);
+    /* #972: EIGS_OBS_GATE_STATS=1 also tallies observe-helper entries (the
+     * per-unit verdict lines come from compile_ast); reported at exit so a
+     * read-free program can be checked for `observe-calls 0`. */
+    if (eigs_env_flag("EIGS_OBS_GATE_STATS")) {
+        g_obs_count_observe_calls = 1;
+        atexit(eigs_obs_gate_stats_report);
+    }
 
     /* --fmt is a pure source transformer; no VM, no arena, no state. */
     if (argc >= 2 && strcmp(argv[1], "--fmt") == 0) {
diff --git a/src/vm.c b/src/vm.c
index 9be38309..48a67cf6 100644
--- a/src/vm.c
+++ b/src/vm.c
@@ -1579,6 +1579,13 @@ void jit_helper_observe_assign(EigsChunk *chunk, int name_idx) {
 }
 
 void jit_helper_observe_assign_local(int slot) {
+    eigs_obs_count_call();   /* #972: entered — the emitter's inline gate test
+                              * is what keeps this at 0 for a read-free program */
+    /* #972: the gate first, before the slot is even resolved — mirrors the
+     * CASE body. The emitter inlines the same test ahead of the call, so this
+     * runs only with the gate open (or when the helper is reached some other
+     * way); kept so the helper is correct on its own. */
+    if (!eigs_obs_gate_open()) return;
     /* #262 Phase-3/E — slot model: observe the persistent (fn_env, slot)
      * trajectory directly from TOS. No promotion, no Value-side state, no window
      * migration (the slot persists across assigns). */
@@ -1627,10 +1634,14 @@ void jit_helper_report_slot(int slot) {
 /* OP_OBSERVE_NAME_POST [name_idx] — observe a name binding's slot from TOS
  * after its SET. Peeks TOS; no stack change. Mirrors CASE(OBSERVE_NAME_POST). */
 void jit_helper_observe_name_post(EigsChunk *chunk, int name_idx) {
-    /* #1049: inside `unobserved:` the name is still resolved (when the #915
-     * gate is open) so the elided assignment's sample reaches the value
+    eigs_obs_count_call();   /* #972 — see jit_helper_observe_assign_local */
+    /* #972: gate closed -> nothing to record, so skip the name resolution and
+     * the slot lookup entirely (they were the measured residual: a read-free
+     * program resolved every assigned name only to return at the helper's
+     * gate test). #1049: inside `unobserved:` the name is still resolved when
+     * the gate IS open, so the elided assignment's sample reaches the value
      * window; only the entropy update, alias and tape snapshot are skipped. */
-    if (g_unobserved_depth != 0 && !eigs_obs_gate_open()) return;
+    if (!eigs_obs_gate_open()) return;
     CallFrame *frame = &g_vm.frames[g_vm.frame_count - 1];
     EigsSlot s = g_vm.stack[g_vm.sp - 1];
     /* #262 Phase-3 D: TOS may be an immediate num (the default path no longer
@@ -2705,6 +2716,8 @@ void eigs_jit_get_layout(EigsJitLayout *out) {
     out->off_thread_vm                = (int)offsetof(EigsThread, vm);
     out->off_thread_unobserved_depth  = (int)offsetof(EigsThread, unobserved_depth);
     out->off_vm_owner                 = (int)offsetof(VM, owner);
+    out->off_thread_state             = (int)offsetof(EigsThread, state);   /* #972 */
+    out->off_state_obs_needed         = (int)offsetof(EigsState, obs_needed);
     out->off_sp              = (int)offsetof(VM, sp);
     out->off_stack           = (int)offsetof(VM, stack);
     out->off_frame_count     = (int)offsetof(VM, frame_count);
@@ -5013,6 +5026,16 @@ static Value *vm_run_ex(EigsChunk *chunk, Env *env, Task *resume,
          * write, so report/predicate misclassify a slot-bound variable
          * (#129). */
         uint16_t slot = read_u16(ip); ip += 2;
+        /* #972: the gate test comes FIRST — before the TOS/slot resolution and
+         * the helper call. With the gate closed (#915: nothing in this state
+         * can interrogate the observer) every helper below returns at its own
+         * gate test anyway, so the only things this skips are the call and
+         * the bare-predicate alias, and the alias is unreadable while the
+         * gate is closed (OP_PREDICATE is a reader, which opens it at compile
+         * time; a descriptor's read after a mid-run arming raises through the
+         * #1027 gap guard before consulting it). Mirrors the JIT emitter's
+         * inline test (jit.c, emit_obs_gate_test). */
+        if (!eigs_obs_gate_open()) DISPATCH();
         if (g_unobserved_depth == 0) {
             /* #262 Phase-3/E — slot model: observe the binding's persistent
              * (fn_env, slot) ObserverSlot directly from TOS. No promotion (the
@@ -5251,11 +5274,15 @@ static Value *vm_run_ex(EigsChunk *chunk, Env *env, Task *resume,
          * still on TOS (SET peeked, didn't pop). Fixes the first-assignment
          * lag for name bindings. Emitted only under the compile-time flag. */
         uint16_t name_idx = read_u16(ip); ip += 2;
-        /* #1049: inside `unobserved:` the binding is still resolved (when the
-         * #915 gate is open) so the elided assignment's sample reaches the
-         * value window; the entropy update, the alias and the tape snapshot
-         * are what the block skips. Mirrors jit_helper_observe_name_post. */
-        if (g_unobserved_depth == 0 || eigs_obs_gate_open()) {
+        /* #972: gate closed -> skip the name resolution, the slot lookup and
+         * the helper call outright (the measured residual: a read-free
+         * program hashed and resolved every assigned name only to return at
+         * the helper's gate test). #1049: inside `unobserved:` the binding is
+         * still resolved when the gate IS open, so the elided assignment's
+         * sample reaches the value window; the entropy update, the alias and
+         * the tape snapshot are what the block skips. Mirrors
+         * jit_helper_observe_name_post. */
+        if (eigs_obs_gate_open()) {
             EigsSlot s = g_vm.stack[g_vm.sp - 1];
             /* #262 Phase-3 D: TOS is now an immediate num for an observed name
              * (default path no longer promotes), or a heap value. Observe the
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 7a985a9f..76855ae2 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -3820,7 +3820,7 @@ OBS_GATE_TMP=$(mktemp -d)
 # CONSUMER counts them: a gate that silently measures LESS still prints OK.
 # Bump this deliberately when adding a check, never to make a run pass.
 OBS_GATE_TOTAL_BEFORE=$TOTAL
-OBS_GATE_EXPECTED_CHECKS=44
+OBS_GATE_EXPECTED_CHECKS=50
 # 1. Sync gate: the rule "which opcodes read observer state" lives in TWO homes
 #    — the /*obs:READS*/ markers in src/vm.h (authoritative, #1024) and the
 #    `case OP_...:` arms of chunk_reads_observer() (the consumer). A marker-
@@ -4553,6 +4553,74 @@ else
     OBS_G43_NOTE=" (SKIP: rlimit not enforced on this platform)"
 fi
 check "a fatal OOM inside the muted window still reaches stderr$OBS_G43_NOTE" "$OBS_G43" "oom-message-reaches-stderr"
+# 45-50. #972's one measured residual: with the gate CLOSED the observe ops
+#     (OBSERVE_ASSIGN_LOCAL / OBSERVE_NAME_POST) still dispatched into their
+#     helpers — call, TOS decode, slot/name resolution — only to return at the
+#     helper's own gate test (+18% module-level / +14% fn-level+JIT over
+#     `unobserved:` at 20M iterations). The gate test is now hoisted ahead of
+#     the helper call in the interpreter CASE bodies AND inlined by the JIT
+#     emitter. `obs-gate: unobserved` cannot see the difference between
+#     "skipped" and "called and returned at the gate", and the slot's `used`
+#     flag cannot either (the helper never touched the slot in either case),
+#     so the instrument is the observe-call TALLY EIGS_OBS_GATE_STATS=1 now
+#     prints at exit: every entry into observer_slot_update[_num] /
+#     observer_slot_sample[_num] / the two JIT observe helpers, counted BEFORE
+#     each one's gate test. Closed -> exactly 0 after 1000 assignments; open
+#     (a reader, or EIGS_OBS_FORCE=1) -> populated. Each verdict also carries
+#     the program's ANSWER and, on the JIT arms, the thunk witness — a loop
+#     that never got a thunk would score 0 calls while running interpreted
+#     (the inline-vs-measure trap), so `jit=compiled` is part of the verdict
+#     on x86_64 (elsewhere the JIT arms still run and are labelled jit=n/a).
+#     Planted fault (either hoist deleted): the interpreter arm reports
+#     calls=1000, the JIT arm calls=1000 — verified red for both before
+#     landing.
+printf 'x is 0.0\nfor i in range of 1000:\n    x is x + 1.5\nprint of x\n' > "$OBS_GATE_TMP/hoist_mod.eigs"
+printf 'define run as:\n    x is 0.0\n    for i in range of 1000:\n        x is x + 1.5\n    return x\nprint of (run of [])\n' > "$OBS_GATE_TMP/hoist_fn.eigs"
+printf 'define run as:\n    x is 0.0\n    for i in range of 1000:\n        x is x + 1.5\n    print of (report of x)\n    return x\nprint of (run of [])\n' > "$OBS_GATE_TMP/hoist_reader.eigs"
+# obs_hoist_verdict <jit|interp> <program> [env...] -> "<answer>/calls=<0|populated|N>/jit=<compiled|none|n/a|off>"
+obs_hoist_verdict() {
+    local OHV_MODE="$1" OHV_PROG="$2"; shift 2
+    local OHV_OUT OHV_RC OHV_ANS OHV_CALLS OHV_JIT
+    if [ "$OHV_MODE" = jit ]; then
+        OHV_OUT=$(env "$@" EIGS_OBS_GATE_STATS=1 EIGS_JIT_STATS=1 EIGS_JIT_OSR_THRESHOLD=1 $EIGS_BIN "$OHV_PROG" 2>&1); OHV_RC=$?
+    else
+        OHV_OUT=$(env "$@" EIGS_OBS_GATE_STATS=1 EIGS_JIT_OFF=1 $EIGS_BIN "$OHV_PROG" 2>&1); OHV_RC=$?
+    fi
+    if [ "$OHV_RC" -ne 0 ]; then echo "died-rc$OHV_RC"; return; fi
+    OHV_ANS=$(printf '%s\n' "$OHV_OUT" | grep -v '^obs-gate:\|^\[jit\]' | tail -1)
+    OHV_CALLS=$(printf '%s\n' "$OHV_OUT" | sed -n 's/^obs-gate: observe-calls \([0-9]*\)$/\1/p')
+    : "${OHV_CALLS:=missing}"
+    if [ "$OHV_CALLS" != missing ] && [ "$OHV_CALLS" -ge 1000 ] 2>/dev/null; then OHV_CALLS=populated; fi
+    if [ "$OHV_MODE" = jit ]; then
+        if [ "$(uname -m)" != x86_64 ]; then OHV_JIT="n/a"
+        elif printf '%s\n' "$OHV_OUT" | grep -qE '^\[jit\] scanned=[0-9]+ compiled=[1-9]'; then OHV_JIT=compiled
+        else OHV_JIT=none; fi
+    else OHV_JIT=off; fi
+    echo "$OHV_ANS/calls=$OHV_CALLS/jit=$OHV_JIT"
+}
+OBS_HOIST_JIT_EXPECT=compiled; [ "$(uname -m)" = x86_64 ] || OBS_HOIST_JIT_EXPECT="n/a"
+# 45. Interpreter, module-level names (OBSERVE_NAME_POST): closed -> no calls.
+OBS_G44=$(obs_hoist_verdict interp "$OBS_GATE_TMP/hoist_mod.eigs")
+check "gate closed: OBSERVE_NAME_POST never enters the observer (interpreter)" "$OBS_G44" "1500/calls=0/jit=off"
+# 46. Interpreter, fn-local slots (OBSERVE_ASSIGN_LOCAL): closed -> no calls.
+OBS_G45=$(obs_hoist_verdict interp "$OBS_GATE_TMP/hoist_fn.eigs")
+check "gate closed: OBSERVE_ASSIGN_LOCAL never enters the observer (interpreter)" "$OBS_G45" "1500/calls=0/jit=off"
+# 47. JIT, module-level names: the emitter's inline gate test skips the helper.
+OBS_G46=$(obs_hoist_verdict jit "$OBS_GATE_TMP/hoist_mod.eigs")
+check "gate closed: the JIT skips jit_helper_observe_name_post (thunk witnessed)" "$OBS_G46" "1500/calls=0/jit=$OBS_HOIST_JIT_EXPECT"
+# 48. JIT, fn-local slots.
+OBS_G47=$(obs_hoist_verdict jit "$OBS_GATE_TMP/hoist_fn.eigs")
+check "gate closed: the JIT skips jit_helper_observe_assign_local (thunk witnessed)" "$OBS_G47" "1500/calls=0/jit=$OBS_HOIST_JIT_EXPECT"
+# 49. Control — a reader opens the gate at compile time and the same JIT'd loop
+#     must then RECORD (populated tally, `diverging` verdict on the ramp). A
+#     do-nothing counter or a gate test that skips the call unconditionally
+#     scores 0 here and goes red.
+OBS_G48=$(obs_hoist_verdict jit "$OBS_GATE_TMP/hoist_reader.eigs")
+check "control: with a reader the JIT'd loop still records every assignment" "$OBS_G48" "1500/calls=populated/jit=$OBS_HOIST_JIT_EXPECT"
+# 50. Control — EIGS_OBS_FORCE=1 opens the gate from process start on the
+#     read-free program; the interpreter's hoisted test must see it open.
+OBS_G49=$(obs_hoist_verdict interp "$OBS_GATE_TMP/hoist_mod.eigs" EIGS_OBS_FORCE=1)
+check "control: EIGS_OBS_FORCE=1 still records the read-free program (interpreter)" "$OBS_G49" "1500/calls=populated/jit=off"
 # The count pin itself (§37). Also the vacuity floor: a section that ran zero
 # checks is not a section that passed.
 TOTAL=$((TOTAL + 1))

From 9e28b508380091af653e323ab69027f000fff919 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 19:16:49 +0000
Subject: [PATCH 08/39] tests: bound the SIGUSR1 fixture by a sentinel, not by
 an iteration count
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Integration finding: the merged observer tree (#1049 + #1044/#1045 + #972) ran
4345/4350 with 5 failures in [99e], while every branch was green on its own and
the section still passed 5/5 standalone at low load. It is not a flake.

#972 hoists the observer gate ahead of the observe helpers, which makes this
fixture's read-free loop much faster. Measured on the same box, whole-fixture
wall time, n=5:

    baseline v0.43.0        ~244 ms
    #1049 alone             ~264 ms
    merged (with #972)      ~131 ms      1.9x faster

The harness prints READY, polls for it at 0.1 s granularity, then signals — and
needs the child alive across TWO signal round-trips (the #915 gated first dump
declares absence and arms observation; the second carries data). At 131 ms of
total child life that race is lost, and under suite load it is lost every time:
"child exited before the signal (no live process to dump)".

The fixture's own header says synchronisation is on observable state only. Its
loop bound was the exception: an iteration count is a time assumption wearing a
counter's clothes. Both fixtures now run until the HARNESS creates a release
file, which it does once it has collected the dumps it asserts on, with a large
finite cap (2e9) so a dead harness cannot hang the suite. The when=1 row
assertion follows the parameter's new value.

No runtime change: the speedup is #972's deliverable, and the fixture was
measuring it as a failure.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 tests/test_sigusr1_dump.sh | 51 ++++++++++++++++++++++++++++++++------
 1 file changed, 43 insertions(+), 8 deletions(-)

diff --git a/tests/test_sigusr1_dump.sh b/tests/test_sigusr1_dump.sh
index 1a395507..663f7441 100644
--- a/tests/test_sigusr1_dump.sh
+++ b/tests/test_sigusr1_dump.sh
@@ -7,9 +7,21 @@
 # spin loop only hopes the child was scheduled in time): the child prints a
 # READY marker to stdout (builtin_print fflushes) once inside its long loop;
 # we poll for that line, then `kill -USR1`. The dump's own "# end dump"
-# trailer on stderr acknowledges the safepoint fired. Then we wait for the
-# child to finish ON ITS OWN (bounded — a hung child is a FAIL, never a hung
-# suite) and require the DONE marker + exit 0.
+# trailer on stderr acknowledges the safepoint fired. Then we release the
+# child through a SENTINEL FILE and require the DONE marker + exit 0.
+#
+# The sentinel is load-bearing, and the reason is worth keeping. The child's
+# loop used to be bounded by a fixed iteration count (2,000,000) chosen so the
+# child would still be alive when the signal landed — an iteration count is a
+# TIME assumption wearing a counter's clothes, and it contradicted the
+# observable-state rule this header states. #972 (hoisting the observer gate
+# ahead of the observe helpers) made this exact loop 1.9x faster — measured
+# 244ms -> 131ms for the whole fixture — and the child began exiting before
+# the harness could signal it: 5 checks failed in the integrated tree while
+# every branch was green on its own, and it still passed 5/5 standalone at
+# low load. The loop is now bounded by a file the HARNESS creates once it has
+# what it needs, with a large finite cap so a dead harness cannot hang the
+# suite. A future speedup cannot re-introduce the race.
 #
 # Subtest 1 (single thread): the entire wait runs INSIDE one train() call,
 # so the dump deterministically catches a live frame: module-scope
@@ -31,6 +43,10 @@ EIGS="$TESTS_DIR/../src/eigenscript"
 
 FIX1=/tmp/eigs_sigusr1_a_$$.eigs
 FIX2=/tmp/eigs_sigusr1_b_$$.eigs
+# Release files: the child polls for these and winds down once the harness has
+# collected its dumps (see the header).
+SENT1=/tmp/eigs_sigusr1_a_$$.go
+SENT2=/tmp/eigs_sigusr1_b_$$.go
 OUT1=/tmp/eigs_sigusr1_a_$$.out
 ERR1=/tmp/eigs_sigusr1_a_$$.err
 OUT2=/tmp/eigs_sigusr1_b_$$.out
@@ -42,7 +58,7 @@ cleanup() {
         kill "$p" 2>/dev/null || true
         wait "$p" 2>/dev/null || true
     done
-    rm -f "$FIX1" "$FIX2" "$OUT1" "$ERR1" "$OUT2" "$ERR2"
+    rm -f "$FIX1" "$FIX2" "$OUT1" "$ERR1" "$OUT2" "$ERR2" "$SENT1" "$SENT2"
 }
 trap cleanup EXIT
 
@@ -72,10 +88,14 @@ define train(n) as:
         epsilon is epsilon * 0.99999
         if step_count == 5000:
             print of "READY"
+        if step_count % 200000 == 0:
+            if file_exists of "@SENT1@":
+                return loss
     return loss
-r is train of 2000000
+r is train of 2000000000
 print of "DONE"
 EOF
+sed -i "s|@SENT1@|$SENT1|" "$FIX1"
 
 # ---- Subtest 1: single-thread dump shape -------------------------------
 
@@ -137,7 +157,7 @@ fi
 # The when=1 counterproof: the live frame's parameter n was bound once this
 # call — it must NOT read as settled.
 if grep -qE '^# scope=frame$' "$ERR1" \
-   && grep -qE '^n \| 2000000 \| when=1 \| entropy=- \| dH=- \| unobserved$' "$ERR1"; then
+   && grep -qE '^n \| 2000000000 \| when=1 \| entropy=- \| dH=- \| unobserved$' "$ERR1"; then
     pass "sigusr1: live-frame row with fresh when=1 binding (distinguishable from settled)"
 else
     fail "sigusr1: live-frame when=1 row for parameter n missing"
@@ -149,6 +169,11 @@ else
     fail "sigusr1: fn-local loss row missing/misshaped"
 fi
 
+# RELEASE the child: every dump this subtest needs has been collected, so let
+# the loop wind down (see the header — the child is bounded by this file, not
+# by an iteration count that a runtime speedup can outrun).
+: > "$SENT1"
+
 # The program must continue correctly after the dump: DONE marker, then a
 # clean exit on its own. DONE is the observable barrier; the wait below only
 # reaps (teardown after DONE cannot hang).
@@ -182,8 +207,11 @@ define churn(n) as:
     loop while i < n:
         i is i + 1
         probe is step_count
+        if i % 200000 == 0:
+            if file_exists of "@SENT2@":
+                return probe
     return probe
-t is spawn of [churn, 2500000]
+t is spawn of [churn, 2500000000]
 define train(n) as:
     loss is 5.0
     loop while step_count < n:
@@ -191,11 +219,15 @@ define train(n) as:
         loss is loss * 0.999 + 0.001
         if step_count == 5000:
             print of "READY"
+        if step_count % 200000 == 0:
+            if file_exists of "@SENT2@":
+                return loss
     return loss
-r is train of 2000000
+r is train of 2000000000
 thread_join of t
 print of "DONE"
 EOF
+sed -i "s|@SENT2@|$SENT2|" "$FIX2"
 
 "$EIGS" "$FIX2" > "$OUT2" 2> "$ERR2" &
 PID=$!
@@ -225,6 +257,9 @@ else
     fail "sigusr1-mt: module step_count row missing/misshaped"
 fi
 
+# RELEASE the worker and the main loop (same rule as subtest 1).
+: > "$SENT2"
+
 if poll_file "$OUT2" "^DONE$" 1200; then
     pass "sigusr1-mt: program completed (DONE) after the dump"
 else

From ca7248ae72097404f14c09238d044162a99ed38e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 17:26:58 +0000
Subject: [PATCH 09/39] replay: boundary refusal on a VM-less worker is a clean
 exit; replay_diff fails on any signal (#1112)

Two defects, one issue.

A. Runtime. Replaying tests/test_spawn_channel_exit.eigs printed the #148
boundary diagnostic and then died by SIGSEGV:

    EIGS_JIT_OFF=1 EIGS_TRACE=/tmp/x.tape  src/eigenscript tests/test_spawn_channel_exit.eigs   # rc 0
    EIGS_JIT_OFF=1 EIGS_REPLAY=/tmp/x.tape src/eigenscript tests/test_spawn_channel_exit.eigs
    before: "Error line 8: recv: not replayable under EIGS_REPLAY (...)" then rc 139
    after:  same diagnostic, rc 1, no signal (both tiers; ASan+UBSan clean, detect_leaks=1)

Root cause: the worker is `spawn of [recv, ch]` -- a builtin run directly
by thread_entry, so that thread never enters vm_execute and
eigs_current->vm is NULL. rt_error has no dispatch loop to defer the
uncaught print to, prints immediately, and calls vm_print_stack_trace,
which read g_vm (= *eigs_current->vm) -> NULL deref at vm.c:2807. The
same shape killed ANY uncaught raise on a direct-builtin worker with no
replay at all (`spawn of [recv, 5]` -> "invalid channel" -> SIGSEGV), and
all 11 replay_blocks() call sites reproduce it. Fix: vm_print_stack_trace
returns when there is no VM (no frames, no trace); all three print sites
already guarded the deferral on that same condition.

That alone makes the refusal exit 0, not 1: main never observed the
worker's death. A spawn()ed worker that dies of an uncaught error now
fails the run (rc 1) whether or not it is joined -- the #493 rule for
cooperative tasks applied to OS threads. thread_entry counts the death
on the state (spawn_err_count, atomic); main reads it after
handle_table_drain has joined every worker. A worker's `exit of N` is a
request, not a death (still decides the status via the #739 latch); an
error caught inside the worker recovers (rc 0). Semantics change ->
docs/SPEC.md + docs/COMPARISON.md + docs/CONCURRENCY.md; docs/TRACE.md
states the boundary contract: a refusal is a clean exit, never a signal.

B. Oracle. tools/replay_diff.sh printed "CRASH ... rep arm rc=139" and
then classified the replay arm as "at the documented boundary" because
its stderr contained the diagnostic; the run said OK (rc 0). A signal
exit (rc >= 128) in EITHER arm is now the first verdict: named, counted,
never a boundary or a row, hard FAIL; --record refuses to write a ledger
over one. `--selftest` plants, through a wrapper binary, a
boundary-plus-crash witness (must FAIL, attributed by the CRASH line), an
identical crash in both arms (invisible to the diff, must FAIL), a
--record-over-crash (must refuse), a clean boundary control from the real
runtime (must stay OK and be counted), a non-signal nonzero rc that must
still diff into a row, and the vacuity floor.

The signal test is numeric (rc >= 128) at both the counting site and the
per-program skip. The first version skipped on a glob over the rc text
(`rc=1[2-9][0-9]`), which also matches 120-127 -- rc 124 (timeout, a
condition this tool has actually hit) and 127 (no such command) would have
been silently skipped instead of diffed. Selftest case 5 pins that.

Regression tests:
  [103a] tests/test_replay_boundary_exit.sh (21 checks): the issue's
    program record+replay on both tiers (rc 1, diagnostic, no signal),
    every #148 boundary builtin as a direct worker, the no-replay direct
    raise, VAL_FN worker death joined/unjoined, and the positive
    controls (caught error rc 0, exit of 4 -> 4, exit of 0 -> 0, clean
    worker rc 0, main-thread refusal). Baseline: 16/21 FAIL (rc 139 / rc 0).
  [99q] tools/replay_diff.sh --selftest (6 cases, count pinned).
Planted faults (each restored, green again): drop the vm.c guard ->
14 checks FAIL "rc=139"; drop the spawn_err_count increment -> 16 FAIL
"rc=0 (want 1)"; neuter crash_check -> the selftest reports the three
planted crash cases "exited 0, want 1" and --record writes a ledger over
a crash; put the rc glob back in place of the flag -> the rc-124 case
reports OK where it must report a row.

Full corpus (CI job replay-differential): replay_diff: OK (230 programs
record+replay; 12 at the documented boundary; 0 nondeterministic;
0 ledgered) -- same 12 boundaries as before, 0 CRASH lines.

Closes #1112

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 docs/COMPARISON.md                 |   5 +
 docs/CONCURRENCY.md                |   9 ++
 docs/SPEC.md                       |  10 ++
 docs/TRACE.md                      |  13 +++
 src/builtins.c                     |   8 ++
 src/eigenscript.h                  |   8 ++
 src/main.c                         |   6 +-
 src/vm.c                           |   7 ++
 tests/run_all_tests.sh             |  43 ++++++++
 tests/test_replay_boundary_exit.sh | 121 ++++++++++++++++++++++
 tools/replay_diff.sh               | 161 ++++++++++++++++++++++++++---
 11 files changed, 377 insertions(+), 14 deletions(-)
 create mode 100755 tests/test_replay_boundary_exit.sh

diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md
index 5d867f3a..4e72bd97 100644
--- a/docs/COMPARISON.md
+++ b/docs/COMPARISON.md
@@ -289,6 +289,11 @@ print of (recv of ch)
 42
 ```
 
+One difference in failure: a Python thread's uncaught exception is printed
+and the process still exits 0. A `spawn`ed EigenScript worker that dies of
+an uncaught error fails the whole run (exit status 1), joined or not — the
+same rule as its cooperative tasks (see SPEC.md "Concurrency").
+
 ## Convergence loops: boilerplate you stop writing
 
 Before the metaphysics, the everyday win. Every numeric fixed-point loop in
diff --git a/docs/CONCURRENCY.md b/docs/CONCURRENCY.md
index 3c55941c..5be84645 100644
--- a/docs/CONCURRENCY.md
+++ b/docs/CONCURRENCY.md
@@ -89,6 +89,15 @@ themselves are not blocked under replay: a worker that returns a pure value
 replays deterministically (the joined result is copied). Keep replayable
 programs off `recv` and off any worker whose result depends on thread ordering.
 
+The refusal is a clean exit, never a signal, on the main thread and on a
+worker alike: `spawn of [recv, ch]` under `EIGS_REPLAY` prints the diagnostic
+and the process exits 1 (#1112 — it died by SIGSEGV before, because a worker
+that runs a builtin directly has no VM and the uncaught-error printer read
+it). The general rule behind that status: a `spawn`ed worker that dies of an
+uncaught error fails the run, joined or not, exactly as a cooperative task
+does (#493); an error caught inside the worker, or a worker's `exit of N`,
+decides its own status.
+
 ## The race gate
 
 The claim that the spawn/channel machinery is data-race-free is not a comment —
diff --git a/docs/SPEC.md b/docs/SPEC.md
index 8a0151b4..153c6ae8 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -1639,6 +1639,16 @@ print of (thread_join of h)
 9
 ```
 
+A worker that **dies of an uncaught error** prints its trace and the
+**process exits non-zero** (status 1) whether or not anything ever
+`thread_join`s it — the same rule as cooperative tasks below (#493), so a
+fire-and-forget thread's failure is never swallowed into a success exit.
+This covers a builtin spawned directly (`spawn of [recv, 5]` raises
+"invalid channel" on the worker) as well as a function body. An error
+`catch`-ed inside the worker recovers normally (exit 0), and a worker's
+`exit of N` still decides the status (#739). The failure is always a
+clean exit, never a signal (#1112).
+
 ## Cooperative tasks
 
 `task_spawn` creates a **cooperative task** on the single interpreter
diff --git a/docs/TRACE.md b/docs/TRACE.md
index 01b223a4..aff85fd3 100644
--- a/docs/TRACE.md
+++ b/docs/TRACE.md
@@ -165,6 +165,19 @@ These builtins raise a catchable runtime error under
 boundary; see docs/TRACE.md)"`. Programs that need to be replay-safe
 must guard these call sites or avoid them entirely.
 
+A boundary refusal is a **clean exit, never a signal**: uncaught, it ends
+the program with exit status 1 like any other runtime error; caught, the
+program continues. That holds on every thread — a refused `recv` on a
+`spawn`ed worker that runs the builtin directly (`spawn of [recv, ch]`)
+used to die by SIGSEGV after printing the diagnostic (#1112: the worker
+has no VM, and the uncaught-error printer dereferenced it); it now prints
+the diagnostic and the process exits 1, because an uncaught death on a
+worker fails the run (docs/SPEC.md "Concurrency"). A signal exit under
+`EIGS_REPLAY` is a runtime bug, and `tools/replay_diff.sh` — the
+same-binary record/replay differential CI runs over the whole corpus —
+fails on any signal exit in either arm regardless of what the arm
+printed; the diagnostic text never excuses a crash.
+
 ## Replay Semantics
 
 With `EIGS_REPLAY` set, each nondet builtin call takes the next `N`
diff --git a/src/builtins.c b/src/builtins.c
index 56b12606..26582308 100644
--- a/src/builtins.c
+++ b/src/builtins.c
@@ -4348,6 +4348,14 @@ static void *thread_entry(void *arg) {
         val_decref(h->result);
         h->result = cloned;
     }
+    /* #1112: an uncaught error on this worker (either path above — a
+     * VAL_FN body that unwound, or a builtin that raised, e.g. the replay
+     * refusal of `recv`) has already been printed; it used to leave the
+     * process exit status at 0, the silent-success #493 closed for tasks.
+     * Count it on the STATE so main fails the run. `exit of N` sets
+     * g_has_error only to unwind and is latched separately — not a death. */
+    if (g_has_error && !g_exit_requested)
+        __atomic_add_fetch(&eigs_current->state->spawn_err_count, 1, __ATOMIC_RELAXED);
     /* An uncaught throw on this thread leaves its structured payload in
      * thread-local storage; release it before the thread exits. */
     eigs_clear_error_value();
diff --git a/src/eigenscript.h b/src/eigenscript.h
index 34579ba7..77fbb168 100644
--- a/src/eigenscript.h
+++ b/src/eigenscript.h
@@ -678,6 +678,14 @@ struct EigsState {
      * flag alone would have silently dropped a worker's exit code to 0. */
     int             exit_latched;
     int             exit_latch_code;
+    /* #1112: number of spawn()ed OS-thread workers that died of an UNCAUGHT
+     * runtime error (the #493 rule for cooperative tasks, applied to
+     * threads: a fire-and-forget worker's death must not green the run).
+     * Incremented atomically by the dying worker in thread_entry, read by
+     * main once handle_table_drain has joined every worker. A worker's
+     * `exit of N` is a request, not a death, and goes through the latch
+     * above instead. */
+    int             spawn_err_count;
     /* Cycle-collector registry — the intrusive list of captured envs and its
      * live count. Per-STATE (not per-thread) so candidates created on any
      * thread survive that thread's death and stay collectable at exit; gc_lock
diff --git a/src/main.c b/src/main.c
index bd3ab9a7..8844911a 100644
--- a/src/main.c
+++ b/src/main.c
@@ -379,6 +379,10 @@ int main(int argc, char **argv) {
      * value world is still alive (channels/threads live in the handle table,
      * not on a GC'd Value, so nothing else reclaims them). */
     handle_table_drain(eigs_st);
+    /* #1112: spawn()ed workers that died of an uncaught error — read AFTER
+     * the drain above has joined every worker (pthread_join is the
+     * happens-before edge for the worker's increment). */
+    int spawn_worker_error = __atomic_load_n(&eigs_st->spawn_err_count, __ATOMIC_RELAXED) > 0;
     /* An uncaught runtime error leaves g_has_error set (vm_run unwinds to
      * here rather than continuing with null). Report it as a non-zero exit
      * so scripts fail loudly for callers, Makefiles, and CI. */
@@ -390,7 +394,7 @@ int main(int argc, char **argv) {
      * is cleared off THIS thread's request, so a worker's exit never erases a
      * genuine main-thread error. */
     int exit_code = g_exit_latched ? g_exit_latch_code
-                    : ((g_has_error || unobserved_task_error) ? 1 : 0);
+                    : ((g_has_error || unobserved_task_error || spawn_worker_error) ? 1 : 0);
     if (g_exit_requested) g_has_error = 0;
     /* An uncaught `throw` leaves its structured payload stashed; release
      * it so exit is leak-clean. */
diff --git a/src/vm.c b/src/vm.c
index 48a67cf6..f5ee7c88 100644
--- a/src/vm.c
+++ b/src/vm.c
@@ -2830,6 +2830,13 @@ static int vm_desc_unrecorded(EigsChunk *chunk, int line, const char *what) {
 }
 
 void vm_print_stack_trace(FILE *out) {
+    /* #1112: a spawned worker that runs a BUILTIN directly (`spawn of
+     * [recv, ch]`) never enters vm_execute, so eigs_current->vm is NULL on
+     * that thread; rt_error/builtin_throw print immediately there (no
+     * dispatch loop to defer to) and used to dereference g_vm here — the
+     * replay refusal of `recv` on such a worker died by SIGSEGV instead of
+     * exiting cleanly. No frames means no trace to print. */
+    if (!eigs_current || !eigs_current->vm) return;
     if (g_vm.frame_count <= 0) return;
     for (int i = g_vm.frame_count - 1; i >= 0; i--) {
         CallFrame *f = &g_vm.frames[i];
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 76855ae2..6f2d4e2c 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -4662,6 +4662,25 @@ check_eigs_suite "concurrent workers, same chunks, exact results" test_spawn_par
 echo "[103] Spawn/Channel Exit (no hang on blocked worker, #303)"
 check_eigs_suite "recv-blocked worker doesn't hang exit" test_spawn_channel_exit.eigs "All tests passed" 1
 
+# [103a] #1112: the same program under EIGS_REPLAY -- the worker's `recv` is
+# refused at the replay boundary (#148), and that refusal, raised on a worker
+# with no VM (a builtin spawned directly), died by SIGSEGV in
+# vm_print_stack_trace. A boundary refusal is a clean rc-1 exit, never a
+# signal; an uncaught death on a spawn()ed worker fails the process (the #493
+# rule for tasks). Child script: every #148 builtin as a direct worker, both
+# tiers on the repro, plus the caught/exit-of-N/clean positive controls.
+echo "[103a] Replay boundary refusal is a clean exit; worker death fails the run (#1112)"
+RBE_OUTPUT=$(bash "$TESTS_DIR/test_replay_boundary_exit.sh" 2>&1); RBE_RC=$?
+RBE_PASS=$(echo "$RBE_OUTPUT" | grep -c "^PASS:" || true)
+RBE_FAIL=$(echo "$RBE_OUTPUT" | grep -c "^FAIL:" || true)
+[ "$RBE_RC" -ne 0 ] && [ "$RBE_FAIL" -eq 0 ] && RBE_FAIL=1
+# 21 checks by construction (1 repro x 2 tiers + 11 boundary builtins + 8
+# controls); fewer PASS lines on a green exit is the child narrowing.
+[ "$RBE_RC" -eq 0 ] && [ "$RBE_PASS" -lt 21 ] && { RBE_FAIL=$((RBE_FAIL + 1)); echo "  FAIL: replay-boundary child ran only $RBE_PASS of 21 checks"; }
+TOTAL=$((TOTAL + RBE_PASS + RBE_FAIL)); PASS=$((PASS + RBE_PASS)); FAIL=$((FAIL + RBE_FAIL))
+if [ "$RBE_FAIL" -gt 0 ]; then echo "  FAIL: replay boundary exit contract"; echo "$RBE_OUTPUT" | grep "^FAIL:" | head -5; else echo "  PASS: all $RBE_PASS replay-boundary exit checks (rc 1, no signal, both tiers)"; fi
+echo ""
+
 # [104] Worker arena-allocated return value survives detach (#302). thread_entry
 # deep-copies the result before arena_destroy frees the worker arena; a UAF here
 # is ASan-caught, and the values are pinned.
@@ -5842,6 +5861,30 @@ else
 fi
 echo ""
 
+# #1112: the same-binary replay differential (CI job `replay-differential`)
+# classified a replay arm that printed the boundary diagnostic and then died
+# by SIGSEGV as "at the boundary" and said OK. A signal exit in either arm is
+# now the first verdict; the selftest plants that witness and an identical
+# crash in both arms through a wrapper binary (each must FAIL, attributed),
+# proves --record refuses over a crash, keeps a real clean boundary refusal
+# classified as boundary (positive control), and pins that a NON-signal
+# nonzero rc (124/127) still diffs into a row. The full corpus run stays a
+# CI job, not a suite section. The case count is pinned, not ">0": a gate
+# reduced to one echo satisfies "at least one case passed".
+echo "[99q] replay_diff crash gate: a signal exit is never a boundary (#1112)"
+TOTAL=$((TOTAL + 1))
+RDS_OUTPUT=$(bash "$TESTS_DIR/../tools/replay_diff.sh" --selftest 2>&1); RDS_RC=$?
+RDS_OK=$(printf '%s\n' "$RDS_OUTPUT" | grep -c "  selftest ok:" || true)
+if [ "$RDS_RC" -eq 0 ] && [ "$RDS_OK" -eq 6 ] && printf '%s\n' "$RDS_OUTPUT" | grep -q "^SELFTEST: all planted faults caught"; then
+    PASS=$((PASS + 1))
+    echo "  PASS: replay_diff selftest (all $RDS_OK planted/control cases)"
+else
+    FAIL=$((FAIL + 1))
+    echo "  FAIL: replay_diff selftest (rc=$RDS_RC, $RDS_OK of 6 ok cases)"
+    printf '%s\n' "$RDS_OUTPUT" | grep -v "selftest ok" | head -8
+fi
+echo ""
+
 echo "[99b] Stdlib/builtin discoverability (#393)"
 TOTAL=$((TOTAL + 1))
 if bash "$TESTS_DIR/../tools/stdlib_index_check.sh" && bash "$TESTS_DIR/../tools/stdlib_index_check.sh" --selftest >/dev/null; then
diff --git a/tests/test_replay_boundary_exit.sh b/tests/test_replay_boundary_exit.sh
new file mode 100755
index 00000000..e55849a7
--- /dev/null
+++ b/tests/test_replay_boundary_exit.sh
@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# #1112: a replay-boundary refusal (`recv` & co. under EIGS_REPLAY, docs/TRACE.md
+# "Non-Replayable Builtins") raised on a spawn()ed worker that runs the builtin
+# DIRECTLY (`spawn of [recv, ch]`) died by SIGSEGV: rt_error printed the
+# uncaught error immediately (no VM to defer to on that thread) and
+# vm_print_stack_trace dereferenced the worker's NULL VM. The same shape killed
+# any uncaught raise on such a worker with no replay at all
+# (`spawn of [recv, 5]`), and an uncaught death on a VAL_FN worker exited 0.
+# Contract pinned here: a boundary refusal is a clean exit -- rc 1, never a
+# signal -- and a worker that dies of an uncaught error fails the process (the
+# #493 rule for tasks, applied to threads). Runs with cwd src/ like every child
+# script; prints PASS:/FAIL: lines; exit 1 on any FAIL.
+#
+# Bounding is pure shell (macOS runners have no `timeout`): background, poll,
+# kill at the deadline. stdin is /dev/null so the proc_* record arms never touch
+# a live terminal fd.
+EIGS="${EIGS:-./eigenscript}"
+T=$(mktemp -d); trap 'rm -rf "$T"' EXIT
+PASS=0; FAIL=0
+ok()   { echo "PASS: $1"; PASS=$((PASS+1)); }
+bad()  { echo "FAIL: $1"; FAIL=$((FAIL+1)); }
+[ -x "$EIGS" ] || { bad "eigenscript binary not found at $EIGS"; echo "REPLAY_BOUNDARY_EXIT: $PASS passed, $FAIL failed"; exit 1; }
+
+# run_bounded OUTFILE [ENV=val ...] -- PROG ; sets RC ("" = killed at the deadline)
+run_bounded() {
+    local out="$1"; shift
+    env -u EIGS_JIT_OSR_THRESHOLD "$@" > "$out" 2>&1 </dev/null &
+    local pid=$!
+    RC=""
+    for _ in $(seq 1 100); do
+        if ! kill -0 "$pid" 2>/dev/null; then wait "$pid"; RC=$?; break; fi
+        sleep 0.1
+    done
+    if [ -z "$RC" ]; then kill "$pid" 2>/dev/null; wait "$pid" 2>/dev/null; echo "  (killed after 10s)" >> "$out"; fi
+}
+# A sanitizer diagnostic in either arm is a hard failure here (the
+# check_task_exit convention -- stricter than rc_ok's leak tolerance).
+clean() { ! grep -qE "Sanitizer|runtime error:" "$1"; }
+DIAG="not replayable under EIGS_REPLAY"
+
+# assert_replay NAME PROG EXTRA_ENV... -- record (JIT off), then replay; the
+# replay arm must exit exactly 1, print the boundary diagnostic, and not die
+# by signal (rc >= 128) in either arm.
+assert_replay() {
+    local name="$1" prog="$2"; shift 2
+    rm -f "$T/tape"
+    run_bounded "$T/rec" EIGS_JIT_OFF=1 EIGS_TRACE="$T/tape" "$@" "$EIGS" "$prog"; local rrc="$RC"
+    if [ -z "$rrc" ] || [ "$rrc" -ne 0 ] || [ ! -s "$T/tape" ] || ! clean "$T/rec"; then
+        bad "$name: record arm rc=${rrc:-hung} tape=$( [ -s "$T/tape" ] && echo written || echo MISSING)"; head -3 "$T/rec" | sed 's/^/    /'; return
+    fi
+    run_bounded "$T/rep" EIGS_JIT_OFF=1 EIGS_REPLAY="$T/tape" "$@" "$EIGS" "$prog"; local prc="$RC"
+    if [ "$prc" = "1" ] && grep -q "$DIAG" "$T/rep" && clean "$T/rep"; then
+        ok "$name: replay refusal is a clean exit (rc=1, diagnostic printed, no signal)"
+    else
+        bad "$name: replay rc=${prc:-hung} (want 1, no signal) diag=$(grep -c "$DIAG" "$T/rep")"; head -4 "$T/rep" | sed 's/^/    /'
+    fi
+}
+
+# 1. The issue's exact reproducer: tests/test_spawn_channel_exit.eigs
+#    (a worker parked in `recv` on a never-closed channel). Both tiers: the
+#    replay arm is also run with the JIT on (#279 class -- tiers drift alone).
+assert_replay "issue #1112 repro (test_spawn_channel_exit)" ../tests/test_spawn_channel_exit.eigs
+run_bounded "$T/rep_jit" EIGS_REPLAY="$T/tape" "$EIGS" ../tests/test_spawn_channel_exit.eigs
+if [ "$RC" = "1" ] && grep -q "$DIAG" "$T/rep_jit" && clean "$T/rep_jit"; then ok "issue #1112 repro, JIT on: rc=1, clean"; else bad "issue #1112 repro, JIT on: rc=${RC:-hung}"; head -3 "$T/rep_jit" | sed 's/^/    /'; fi
+
+# 2. Every boundary builtin (docs/TRACE.md #148 list) as a DIRECT worker --
+#    the issue names one instance of the class; all 11 crashed the same
+#    way before the fix (the 11 replay_blocks() call sites in builtins.c and
+#    builtins_host.c). Channel family + subprocess family.
+printf 'ch is channel of 1\nw is spawn of [recv, ch]\nprint of "MARK_END"\n'            > "$T/b_recv.eigs"
+printf 'ch is channel of 1\nw is spawn of [try_recv, ch]\nprint of "MARK_END"\n'        > "$T/b_try_recv.eigs"
+printf 'ch is channel of 1\nw is spawn of [recv_timeout, ch, 5]\nprint of "MARK_END"\n' > "$T/b_recv_timeout.eigs"
+printf 'w is spawn of [exec_capture, ["true"]]\nprint of "MARK_END"\n'                   > "$T/b_exec_capture.eigs"
+printf 'w is spawn of [proc_spawn, ["true"]]\nprint of "MARK_END"\n'                     > "$T/b_proc_spawn.eigs"
+printf 'w is spawn of [proc_write, 0, "x"]\nprint of "MARK_END"\n'                       > "$T/b_proc_write.eigs"
+printf 'w is spawn of [proc_read_line, 0]\nprint of "MARK_END"\n'                        > "$T/b_proc_read_line.eigs"
+printf 'w is spawn of [proc_read, 0, 1]\nprint of "MARK_END"\n'                          > "$T/b_proc_read.eigs"
+printf 'w is spawn of [proc_read_buf, 0, 1]\nprint of "MARK_END"\n'                      > "$T/b_proc_read_buf.eigs"
+printf 'w is spawn of [proc_close, 0]\nprint of "MARK_END"\n'                            > "$T/b_proc_close.eigs"
+printf 'w is spawn of [proc_wait, 0]\nprint of "MARK_END"\n'                             > "$T/b_proc_wait.eigs"
+for b in recv try_recv recv_timeout exec_capture proc_spawn proc_write proc_read_line proc_read proc_read_buf proc_close proc_wait; do
+    assert_replay "boundary builtin $b on a direct worker" "$T/b_$b.eigs"
+done
+
+# 3. Control, no replay at all: an ordinary raise on a direct worker was the
+#    same NULL-VM crash (`recv of 5` -> "invalid channel" -> SIGSEGV).
+printf 'w is spawn of [recv, 5]\nprint of "MARK_END"\n' > "$T/c_raise.eigs"
+run_bounded "$T/c1" "$EIGS" "$T/c_raise.eigs"
+if [ "$RC" = "1" ] && grep -q "invalid channel" "$T/c1" && grep -q MARK_END "$T/c1" && clean "$T/c1"; then ok "uncaught raise on a direct worker, no replay: rc=1, no signal"; else bad "uncaught raise on a direct worker: rc=${RC:-hung}"; head -3 "$T/c1" | sed 's/^/    /'; fi
+
+# 4. A VAL_FN worker that dies of an uncaught error fails the process (was rc 0
+#    -- the silent-success #493 closed for tasks). Unjoined and joined.
+printf 'define w() as:\n    return recv of 5\nh is spawn of w\nprint of "MARK_END"\n' > "$T/c_fn.eigs"
+run_bounded "$T/c2" "$EIGS" "$T/c_fn.eigs"
+if [ "$RC" = "1" ] && grep -q MARK_END "$T/c2" && clean "$T/c2"; then ok "VAL_FN worker uncaught death (unjoined): rc=1"; else bad "VAL_FN worker uncaught death (unjoined): rc=${RC:-hung}"; fi
+printf 'define w() as:\n    return recv of 5\nh is spawn of w\nr is thread_join of h\nprint of "MARK_END"\n' > "$T/c_fnj.eigs"
+run_bounded "$T/c3" "$EIGS" "$T/c_fnj.eigs"
+if [ "$RC" = "1" ] && grep -q MARK_END "$T/c3" && clean "$T/c3"; then ok "VAL_FN worker uncaught death (joined): rc=1"; else bad "VAL_FN worker uncaught death (joined): rc=${RC:-hung}"; fi
+
+# 5. Positive controls (the other half): a CAUGHT error in the worker, a
+#    worker's `exit of N`, and a clean worker all keep their exit status.
+printf 'define w() as:\n    try:\n        r is recv of 5\n    catch e:\n        print of "caught"\n    return 7\nh is spawn of w\nprint of (thread_join of h)\n' > "$T/c_caught.eigs"
+run_bounded "$T/c4" "$EIGS" "$T/c_caught.eigs"
+if [ "$RC" = "0" ] && grep -q "^caught" "$T/c4" && grep -q "^7" "$T/c4"; then ok "error caught inside the worker: rc=0"; else bad "error caught inside the worker: rc=${RC:-hung}"; fi
+printf 'define w() as:\n    exit of 4\nh is spawn of w\nr is thread_join of h\nprint of "MARK_END"\n' > "$T/c_exit4.eigs"
+run_bounded "$T/c5" "$EIGS" "$T/c_exit4.eigs"
+if [ "$RC" = "4" ]; then ok "worker exit of 4 still decides the status: rc=4"; else bad "worker exit of 4: rc=${RC:-hung} (want 4)"; fi
+printf 'define w() as:\n    exit of 0\nh is spawn of w\nr is thread_join of h\nprint of "MARK_END"\n' > "$T/c_exit0.eigs"
+run_bounded "$T/c6" "$EIGS" "$T/c_exit0.eigs"
+if [ "$RC" = "0" ]; then ok "worker exit of 0 is a request, not a death: rc=0"; else bad "worker exit of 0: rc=${RC:-hung} (want 0)"; fi
+printf 'define w() as:\n    return 3\nh is spawn of w\nprint of (thread_join of h)\n' > "$T/c_clean.eigs"
+run_bounded "$T/c7" "$EIGS" "$T/c_clean.eigs"
+if [ "$RC" = "0" ] && grep -q "^3" "$T/c7"; then ok "clean worker: rc=0"; else bad "clean worker: rc=${RC:-hung}"; fi
+
+# 6. Main-thread boundary refusal (a VM is live there; already clean before
+#    the fix) stays rc 1 -- the guard must not have changed the deferred path.
+printf 'ch is channel of 1\nr is try_recv of ch\nprint of "MARK_END"\n' > "$T/m.eigs"
+assert_replay "main-thread try_recv refusal (control)" "$T/m.eigs"
+
+echo "REPLAY_BOUNDARY_EXIT: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]
diff --git a/tools/replay_diff.sh b/tools/replay_diff.sh
index 6453b9bc..90f5ba58 100755
--- a/tools/replay_diff.sh
+++ b/tools/replay_diff.sh
@@ -16,33 +16,165 @@
 # never traced would replay itself trivially green), and the replay arm must
 # READ it (EIGS_REPLAY of a missing tape is refused by name).
 #
-# Usage: bash tools/replay_diff.sh [--record]
+# #1112: a SIGNAL exit (rc >= 128) in EITHER arm is a hard FAIL, whatever the
+# arm printed. The boundary branch used to classify a replay arm that printed
+# the diagnostic and then died by SIGSEGV as "boundary" and the run said OK
+# over a crash; a crash both arms agree on was likewise invisible to the diff.
+# The crash check runs before any classification and is the first verdict.
+# It is a NUMERIC rc >= 128 test: 120-127 (timeout 124, no-such-command
+# 127) are ordinary nonzero exits and still get diffed into rows.
+#
+# Usage: bash tools/replay_diff.sh [--record | --selftest]
+#   --selftest  plant a boundary-plus-crash witness and an identical-crash
+#               witness through a wrapper binary (each must FAIL, attributed),
+#               and run a clean boundary control (must stay OK). Uses the
+#               overrides below; they exist for that and for nothing else.
+# Overrides (selftest plumbing; resolved per call, mechanical-gates §66):
+#   REPLAY_DIFF_CORPUS=DIR   programs to scan (default: tests/)
+#   REPLAY_DIFF_EIG=PATH     binary under test (default: src/eigenscript)
+#   REPLAY_DIFF_BASE=FILE    ledger (default: tests/replay_diff_expected.txt)
+#   REPLAY_DIFF_FLOOR=N      vacuity floor on the program count (default 100)
 set -u
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"; cd "$ROOT/src" || exit 1
-EIG=./eigenscript; BASE="$ROOT/tests/replay_diff_expected.txt"
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"; SELF="$ROOT/tools/$(basename "$0")"; cd "$ROOT/src" || exit 1
 T=$(mktemp -d); trap 'rm -rf "$T"' EXIT
-got="$T/got"; : > "$got"; n=0; boundary=0; nondet=0
+# The bound is optional: macOS runners ship no coreutils `timeout`, and a
+# suite section runs --selftest there (tests/run_all_tests.sh probes the same
+# way). Unbounded is a hang, not a wrong verdict.
+TMO=""
+if command -v timeout >/dev/null 2>&1; then TMO="timeout 180"
+elif command -v gtimeout >/dev/null 2>&1; then TMO="gtimeout 180"; fi
+
+corpus_dir() { printf '%s' "${REPLAY_DIFF_CORPUS:-$ROOT/tests}"; }
+eig_bin()    { printf '%s' "${REPLAY_DIFF_EIG:-./eigenscript}"; }
 norm() { sed -E 's/0x[0-9a-f]+/0xADDR/g' "$1"; }
 # stdin is pinned to /dev/null: test_terminal's raw_key reads it, and with the
 # harness's inherited stdin the record arm hung (rc 124) while the replay arm
 # exited 3 -- a phantom row from the environment, not the tape.
-run() { local out="$1"; shift; env -u EIGS_JIT_OSR_THRESHOLD EIGS_JIT_OFF=1 "$@" timeout 180 "$EIG" "../tests/$b" > "$out" 2>&1 </dev/null; echo "rc=$?" >> "$out"; }
+run() { local out="$1"; shift; env -u EIGS_JIT_OSR_THRESHOLD EIGS_JIT_OFF=1 "$@" $TMO "$(eig_bin)" "$(corpus_dir)/$b" > "$out" 2>&1 </dev/null; echo "rc=$?" >> "$out"; }
+# crash_check ARM FILE: a signal exit is named AND counted; the count is the
+# first verdict below. rc is the last line the arm wrote (`rc=N`).
+crash=0; prog_crash=0
+crash_check() { local r; r=$(tail -1 "$2" | sed 's/rc=//'); case "$r" in ''|*[!0-9]*) return;; esac; [ "$r" -ge 128 ] && { echo "  CRASH $b $1 arm rc=$r"; crash=$((crash + 1)); prog_crash=1; }; }
+
+# ---------------------------------------------------------------- selftest
+if [ "${1:-}" = "--selftest" ]; then
+    REAL="$ROOT/src/eigenscript"
+    [ -x "$REAL" ] || { echo "replay_diff selftest: no binary at $REAL"; exit 1; }
+    ST_RC=0
+    # The wrapper is the "binary": it forwards to the real one, except for two
+    # planted programs. test_boundary_crash: the REPLAY arm prints the real
+    # diagnostic text and dies by SIGSEGV (the #1112 shape). test_both_crash:
+    # both arms print the same line and die by SIGSEGV (identical output -- the
+    # diff cannot see it). Everything else is the real runtime, so the clean
+    # boundary control is a genuine replay refusal, not a printed string.
+    cat > "$T/eig" <<W
+#!/usr/bin/env bash
+case "\$1" in
+  *test_boundary_crash.eigs) if [ -n "\${EIGS_REPLAY:-}" ]; then echo "Error line 1: recv: not replayable under EIGS_REPLAY (subprocess/concurrency boundary; see docs/TRACE.md)" >&2; kill -SEGV \$\$; fi ;;
+  *test_both_crash.eigs) echo same; kill -SEGV \$\$ ;;
+  *test_near_crash.eigs) if [ -n "\${EIGS_REPLAY:-}" ]; then echo replay; else echo record; fi; exit 124 ;;
+esac
+exec "$REAL" "\$@"
+W
+    chmod +x "$T/eig"
+    mk_corpus() {   # mk_corpus DIR members...  (det is always present: the self-check needs one)
+        local d="$1"; shift; rm -rf "$d"; mkdir -p "$d"
+        printf 'print of 1\n' > "$d/test_a_det.eigs"
+        for m in "$@"; do case "$m" in
+            clean) printf 'ch is channel of 1\nr is try_recv of ch\nprint of "done"\n' > "$d/test_boundary_clean.eigs" ;;
+            bcrash) printf 'print of 1\n' > "$d/test_boundary_crash.eigs" ;;
+            both)  printf 'print of 1\n' > "$d/test_both_crash.eigs" ;;
+            near)  printf 'print of 1\n' > "$d/test_near_crash.eigs" ;;
+        esac; done
+    }
+    # st_case NAME WANT_RC FLOOR ARGS -- WANT_SUBSTR...   (WANT_SUBSTR must ALL appear)
+    st_case() {
+        local name="$1" want_rc="$2" floor="$3"; shift 3
+        local args=""; if [ "$1" != "--" ]; then args="$1"; shift; fi; shift
+        : > "$T/ledger"
+        local out rc
+        out=$(env REPLAY_DIFF_CORPUS="$T/corpus" REPLAY_DIFF_EIG="$T/eig" REPLAY_DIFF_BASE="$T/ledger" ${floor:+REPLAY_DIFF_FLOOR=$floor} bash "$SELF" $args 2>&1); rc=$?
+        if [ "$rc" -ne "$want_rc" ]; then
+            echo "SELFTEST FAIL: '$name' exited $rc, want $want_rc:" >&2; printf '%s\n' "$out" | sed 's/^/    /' >&2; ST_RC=1; return
+        fi
+        # Attribution (mechanical-gates §19): the verdict must be THIS case's,
+        # named by text only the intended path emits -- never a bare filename.
+        for want in "$@"; do
+            if ! printf '%s\n' "$out" | grep -qF -- "$want"; then
+                echo "SELFTEST FAIL: '$name' exited $rc for the wrong reason; wanted '$want', got:" >&2
+                printf '%s\n' "$out" | sed 's/^/    /' >&2; ST_RC=1; return
+            fi
+        done
+        echo "  selftest ok: $name"
+    }
+    # 1. The #1112 witness: diagnostic printed, then a signal -- must FAIL and
+    #    name the crash; the clean control in the same corpus is still
+    #    counted as a boundary (the crash is not what got it counted).
+    mk_corpus "$T/corpus" clean bcrash
+    st_case "planted boundary-plus-crash fails, attributed" 1 3 -- \
+        "CRASH test_boundary_crash.eigs rep arm rc=139" \
+        "replay_diff: FAIL: 1 signal exit(s)" "1 at the documented boundary"
+    # 2. A crash both arms AGREE on (identical output) -- invisible to the
+    #    diff, must still FAIL, both arms named.
+    mk_corpus "$T/corpus" both
+    st_case "identical crash in both arms fails" 1 2 -- \
+        "CRASH test_both_crash.eigs rec arm rc=139" "CRASH test_both_crash.eigs rep arm rc=139" \
+        "replay_diff: FAIL: 2 signal exit(s)"
+    # 3. --record must not bake a crash into a ledger.
+    mk_corpus "$T/corpus" clean bcrash
+    st_case "--record refuses over a crash" 1 3 "--record" \
+        "replay_diff: FAIL: 1 signal exit(s)"
+    [ -s "$T/ledger" ] && { echo "SELFTEST FAIL: --record wrote a ledger over a crash" >&2; ST_RC=1; }
+    # 4. Positive control (both halves, §15): the clean boundary -- a real
+    #    replay refusal from the real runtime, rc 1, no signal -- stays OK
+    #    and is counted as a boundary. The exact program count also proves
+    #    the corpus override took (the real corpus would say 100+).
+    mk_corpus "$T/corpus" clean
+    st_case "clean boundary control stays OK, counted" 0 2 -- \
+        "replay_diff: OK (2 programs record+replay; 1 at the documented boundary; 0 nondeterministic; 0 ledgered)"
+    # 5. rc 120-127 is NOT a signal. A divergence there must still become a
+    #    row: the first version of this gate skipped on a glob over the rc
+    #    text (`rc=1[2-9][0-9]`), which also swallowed 124 (timeout) and 127
+    #    (no such command) -- a loud row turned into no row at all.
+    mk_corpus "$T/corpus" near
+    st_case "non-signal nonzero rc (124) still diffs into a row" 1 2 -- \
+        "replay_diff: LEDGER CHANGED" "> test_near_crash.eigs"
+    # 6. The vacuity floor is not disabled by the plumbing: with no floor
+    #    override the tiny corpus is refused by name.
+    st_case "vacuity floor still fires at the default" 1 "" -- \
+        "the scan is vacuous"
+    [ "$ST_RC" -eq 0 ] && echo "SELFTEST: all planted faults caught"
+    exit "$ST_RC"
+fi
+
+# ---------------------------------------------------------------- the gate
+EIG="$(eig_bin)"; CORPUS="$(corpus_dir)"; BASE="${REPLAY_DIFF_BASE:-$ROOT/tests/replay_diff_expected.txt}"
+FLOOR="${REPLAY_DIFF_FLOOR:-100}"
+got="$T/got"; : > "$got"; n=0; boundary=0; nondet=0
 # self-check on a known-deterministic program
 b=test_math_underflow.eigs
-[ -f "../tests/$b" ] || b=$(ls ../tests/test_*.eigs | head -1 | xargs basename)
+[ -f "$CORPUS/$b" ] || b=$(ls "$CORPUS"/test_*.eigs | head -1 | xargs basename)
 rm -f "$T/tape0"; run "$T/r0" EIGS_TRACE="$T/tape0"
 [ -s "$T/tape0" ] || { echo "replay_diff: FAIL: the record arm wrote no tape for $b -- check EIGS_TRACE"; exit 1; }
 run "$T/p0" EIGS_REPLAY="$T/tape0"
+crash_check rec "$T/r0"; crash_check rep "$T/p0"
+[ "$crash" -eq 0 ] || { echo "replay_diff: FAIL: the self-check program $b died by signal"; exit 1; }
 diff -q <(norm "$T/r0") <(norm "$T/p0") >/dev/null || { echo "replay_diff: FAIL: the self-check program $b does not replay its own tape"; diff <(norm "$T/r0") <(norm "$T/p0") | head -5; exit 1; }
-for f in "$ROOT"/tests/test_*.eigs; do
+for f in "$CORPUS"/test_*.eigs; do
   b=$(basename "$f"); n=$((n + 1))
   rm -f "$T/tape"
   run "$T/rec" EIGS_TRACE="$T/tape"
   run "$T/rep" EIGS_REPLAY="$T/tape"
-  # A crash that the two arms AGREE on is invisible to the diff; name it so a
-  # crashing corpus program is never silently "identical" (one run of this
-  # tool printed a bash "Segmentation fault" line that no row explained).
-  for arm in rec rep; do r=$(tail -1 "$T/$arm" | sed 's/rc=//'); [ "$r" -ge 128 ] 2>/dev/null && echo "  CRASH $b $arm arm rc=$r"; done
+  # #1112: a signal exit is the first verdict -- named, counted, and never a
+  # boundary or a row. A crash that the two arms AGREE on is invisible to the
+  # diff, and a replay arm that printed the boundary diagnostic before dying
+  # is not "at the boundary"; both used to read as OK.
+  prog_crash=0; crash_check rec "$T/rec"; crash_check rep "$T/rep"
+  # Skip on the FLAG, not on a glob over the rc text: `rc=1[2-9][0-9]`
+  # also matches 120-127, which are not signals -- rc 124 (timeout) and
+  # 127 (no such command) would have been silently skipped instead of
+  # diffed, turning a loud row into no row at all.
+  [ "$prog_crash" -eq 0 ] || continue
   diff -q <(norm "$T/rec") <(norm "$T/rep") >/dev/null && continue
   if grep -q "not replayable under EIGS_REPLAY" "$T/rep"; then boundary=$((boundary + 1)); continue; fi
   # Adjudicate (jit_diff's step 1): a program whose record arm is not even
@@ -50,11 +182,14 @@ for f in "$ROOT"/tests/test_*.eigs; do
   rm -f "$T/tape2"; run "$T/rec2" EIGS_TRACE="$T/tape2"; run "$T/rep2" EIGS_REPLAY="$T/tape2"
   if ! diff -q <(norm "$T/rec") <(norm "$T/rec2") >/dev/null; then nondet=$((nondet + 1)); echo "  NONDET $b (record arm differs from itself)"; continue; fi
   if diff -q <(norm "$T/rec2") <(norm "$T/rep2") >/dev/null; then nondet=$((nondet + 1)); echo "  NONDET $b (replay diverged once, then matched)"; continue; fi
-  for arm in rec rep; do r=$(tail -1 "$T/$arm" | sed 's/rc=//'); [ "$r" -ge 128 ] 2>/dev/null && echo "  CRASH $b $arm arm rc=$r"; done
   echo "$b" >> "$got"
 done
 sort -o "$got" "$got"
-[ "$n" -ge 100 ] || { echo "replay_diff: only $n programs found -- the scan is vacuous"; exit 1; }
+[ "$n" -ge "$FLOOR" ] || { echo "replay_diff: only $n programs found -- the scan is vacuous (floor $FLOOR)"; exit 1; }
+if [ "$crash" -gt 0 ]; then
+  echo "replay_diff: FAIL: $crash signal exit(s) -- a crash is never a boundary, whatever the arm printed (#1112); $n programs, $boundary at the documented boundary, $nondet nondeterministic"
+  exit 1
+fi
 if [ "${1:-}" = "--record" ]; then cp "$got" "$BASE"; echo "replay_diff: baseline recorded ($(wc -l < "$BASE") rows, $n programs, $boundary at the documented boundary, $nondet nondeterministic)"; exit 0; fi
 [ -f "$BASE" ] || { echo "replay_diff: no baseline at $BASE (run with --record)"; cat "$got"; exit 1; }
 if diff <(sort "$BASE") "$got" > "$T/d"; then

From a6914d30fb77f53e416519756d638e27b4981859 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 16:52:35 +0000
Subject: [PATCH 10/39] =?UTF-8?q?tasks:=20gated=20task=5Fsched=5Ftrace=20?=
 =?UTF-8?q?=E2=80=94=20a=20pure-reader=20scheduler=20decision=20history=20?=
 =?UTF-8?q?(#846)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A schedule visualizer or a DST wants "who ran when" without instrumenting
every yield site. Nothing in the task layer exposed the scheduler's
decisions, so consumers derived lanes from app-level marks (eddy) or could
not draw run segments at all (third-party task code, liferaft's cluster
sim).

Repro (baseline v0.43.0):
    $ eigenscript repro.eigs            # 2 seeded tasks yield/sleep, then read
    Error line 10: undefined variable 'task_sched_trace'   (rc 1)
    $ EIGS_TASK_TRACE=1 eigenscript repro.eigs             # env var inert, same
After:
    $ eigenscript repro.eigs  -> []                        # off by default
    $ EIGS_TASK_TRACE=1 eigenscript repro.eigs
    [{"seq": 0, "tick": 0, "task": 2, "cause": "spawn"}, {"seq": 1, "tick": 0,
     "task": 1, "cause": "spawn"}, ... {"seq": 6, "tick": 2, "task": 0,
     "cause": "join-release"}]

Surface: `task_sched_trace of 1` arms (so does EIGS_TASK_TRACE=1, read at
thread attach), `of null` reads a list of {seq, tick, task, cause} dicts —
one per task RESUME in schedule order — `of 0` disarms and discards. The
cause vocabulary is enumerated from the scheduler's enqueue sites, every one
of which now names its cause: spawn, yield, sleep-wake, join-release,
kill-release, recv-wake, deadlock (the #509 re-enqueue of main).

Design, against the two DST constraints:
- Pure reader. The cause rides with the ready-queue entry (a parallel byte
  array moved in lockstep by the same compaction, always maintained); the
  trampoline records AFTER sched_ready_pop, so the seeded PRNG draws, the
  clock and the queue order are untouched whether or not the trace is armed.
- Derived, not taped. The schedule is a pure function of program order and
  the seed, so the history is re-derived under EIGS_REPLAY rather than
  recorded; it adds no N records and no N record names it (docs/TRACE.md).
- The arm flag lives on EigsThread, NOT on the TaskScheduler, so arming
  never creates a scheduler: a scheduler that exists unarmed by any spawn is
  a pre-existing hazard (task_sched_seed then task_yield with no spawn
  suspends main against it and vm_execute_common returns the suspend's
  NULL — the program prints nothing, rc 0). Unchanged here; see residuals.
- The history lives on the scheduler and is freed in task_sched_thread_free.
  Unbounded while armed by design — a silent cap would make a long run's
  trace lie about its tail.
- Not added to SANDBOX_ALLOW: the allowlist is fail-closed, so the builtin
  is shadowed inside sandbox_run, which is the right posture for a call
  that mutates per-thread scheduler-observation state.

Regression tests:
- tests/test_task_sched_trace.eigs (suite [104b], 39 checks): every
  expectation written from reading src/vm.c before running — the FIFO
  3-task yield/sleep(30/10/20)/join history by hand, the seed-42 history
  through an independent splitmix64 model of sched_ready_pop (picks b, c, a
  — the same permutation docs/SPEC.md's seeded example prints), plus
  recv-wake, kill-release, deadlock, off-by-default, disarm/re-arm and the
  argument contract, and the sandbox fail-closed posture (a sandboxed chunk
  calling it is denied and the host's trace stays disarmed).
- tests/test_task_sched_trace.sh (20 checks): purity — stdout+stderr+rc
  byte-identical with EIGS_TASK_TRACE=1 across all 12 task programs in the
  tree (3 examples/task_*.eigs, test_tasks, test_task_sleep_order,
  test_task_osr, and the six error-path tests/task_*.eigs, which are the
  only programs reaching kill-release and the deadlock re-enqueue); replay
  — a tape recorded armed replays to the identical printed trace, plain and
  under EIGS_REPLAY_STRICT=1, JIT on and EIGS_JIT_OFF=1; tape — the
  N-record count (1, the probe consumes `random`) is unchanged by arming and
  no N record names the trace or a cause.

Planted faults (each rebuilt, run, restored, green again):
  P1 recording removed          -> fixture "got []", replay checks entries=0
  P2 arming consumes a PRNG draw-> purity red on task_seeded_schedule and
                                   test_tasks (the seeded order changes)
  P3 cause/queue lockstep broken-> seeded fixture reads "spawn" where
                                   "yield" is expected
  P4 tick recorded from the entry address (replay-unstable)
                                -> fixture tick rows red, both replay tiers
                                   diverge
  P5 each entry also written as an N record
                                -> tape count 11 vs 1 and the N-name check
                                   names `sched_trace`

Disabled cost (UNDER LOAD, PROVISIONAL — this box ran ~8 agents' builds):
1.2M-resume yield loop (2 tasks x 600k task_yield), n=5 A/B interleaved,
baseline v0.43.0 binary vs this one with the trace off, load average ~6.2:
baseline 0.464/0.339/0.298/0.348/0.373 (mean 0.364s), this 0.342/0.267/
0.241/0.368/0.349 (mean 0.313s) — the two spreads overlap and this side is
nominally FASTER, which is the shape of noise, not of a win. Armed, for
scale (n=3, 1.2M entries retained): 0.324/0.357/0.377s.

Docs: BUILTINS.md row, SPEC.md "Scheduler trace" subsection (doc-gated
example), CONCURRENCY.md section, TRACE.md derived-not-recorded note;
src/lsp_builtin_index.h regenerated by the Makefile rule.

Residuals: the pre-existing unarmed-scheduler truncation above
(task_sched_seed + task_yield with no spawn prints nothing at rc 0) is not
touched by this change and deserves its own issue; the main task's initial
run precedes the first entry and is implicit (documented).

Closes #846

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 docs/BUILTINS.md                  |   1 +
 docs/CONCURRENCY.md               |  29 ++++
 docs/SPEC.md                      |  41 ++++++
 docs/TRACE.md                     |  11 ++
 src/builtins.c                    |  25 ++++
 src/eigenscript.h                 |  10 ++
 src/lsp_builtin_index.h           |   1 +
 src/state.c                       |   4 +
 src/vm.c                          | 125 +++++++++++++---
 src/vm.h                          |   6 +
 tests/run_all_tests.sh            |  24 ++++
 tests/task_sched_trace_probe.eigs |  20 +++
 tests/test_task_sched_trace.eigs  | 230 ++++++++++++++++++++++++++++++
 tests/test_task_sched_trace.sh    | 103 +++++++++++++
 14 files changed, 613 insertions(+), 17 deletions(-)
 create mode 100644 tests/task_sched_trace_probe.eigs
 create mode 100644 tests/test_task_sched_trace.eigs
 create mode 100755 tests/test_task_sched_trace.sh

diff --git a/docs/BUILTINS.md b/docs/BUILTINS.md
index 4abcdebe..b9aa176c 100644
--- a/docs/BUILTINS.md
+++ b/docs/BUILTINS.md
@@ -822,6 +822,7 @@ Requires full build. Transformer model inference and training.
 | `task_detach` | `task_detach of id` | Mark task `id` **fire-and-forget** (the pthread-detach precedent, #530): it is reaped the moment it finishes — or immediately if already finished — releasing its handle slot for reuse, so task-per-message workloads are bounded by *concurrent* tasks, not lifetime spawns. A detached task's uncaught death still prints its trace and still fails the process at exit (#493). A reaped id reads as unknown afterwards (`task_join` null, `task_alive` 0). A task may detach itself: `task_detach of (task_self of null)`. Returns 1, or 0 for main/unknown. |
 | `task_sleep` | `task_sleep of ticks` | Suspend this task until the **virtual clock** advances by `ticks`. The clock is logical (discrete-event): it only jumps forward — to the earliest sleeper — when nothing else is runnable, so sleeping stays deterministic, not wall-clock. A negative sleep is treated as 0. A no-op when no task has been spawned. Forbidden inside an `arena_mark`…`arena_reset` scope. |
 | `task_now` | `task_now of null` | The current virtual-clock value (a number; 0 before any `task_sleep`). Deterministic — reads a logical counter, records no nondeterminism. |
+| `task_sched_trace` | `task_sched_trace of null` · `task_sched_trace of 1` · `task_sched_trace of 0` | The scheduler's decision history (#846), **off by default**. `of 1` arms it (so does `EIGS_TASK_TRACE=1` in the environment); `of null` returns a list of `{seq, tick, task, cause}` dicts — one per task **resume** since arming, in schedule order: `seq` the entry index, `tick` the virtual clock (`task_now`), `task` the resumed id (`0` = main), `cause` one of `spawn`, `yield`, `sleep-wake`, `join-release`, `kill-release`, `recv-wake`, `deadlock`; `of 0` disarms and discards. A **pure reader**: arming changes no pick, clock or seed (a traced run is byte-identical to the untraced one), and the entries derive from the deterministic schedule — they are not tape `N` records, so `EIGS_REPLAY` reproduces them. Unbounded while armed (one small entry per resume). Arming never creates a scheduler; the main task's initial run is implicit (it precedes every entry). Not sandbox-visible. |
 | `task_sched_seed` | `task_sched_seed of n` | Install a scheduling **seed**: the scheduler switches from FIFO round-robin to picking the next ready task from a seeded, platform-independent PRNG. Same seed ⇒ same interleaving (byte-identical run + replay, zero tape nondeterminism); a different seed explores a different ordering — the lever a deterministic simulation tester uses to search interleavings. No seed ⇒ unchanged FIFO. Typically called once at program start. Returns null. |
 
 **Thread safety:** Values sent through a channel (or returned through
diff --git a/docs/CONCURRENCY.md b/docs/CONCURRENCY.md
index 5be84645..ebc29ab1 100644
--- a/docs/CONCURRENCY.md
+++ b/docs/CONCURRENCY.md
@@ -77,6 +77,35 @@ parallelism: use threads for genuinely parallel work, not to speed up a tight
 serial loop. (A quantified before/after number lands with the replay-pinned
 benchmark harness, #398.)
 
+## The scheduler trace is a reader, not a source (#846)
+
+A schedule visualizer or a DST wants "who ran when" without instrumenting
+every yield site. `task_sched_trace of 1` (or `EIGS_TASK_TRACE=1`) arms a
+per-thread trace of the cooperative scheduler: one `{seq, tick, task, cause}`
+entry per task **resume**, read back with `task_sched_trace of null`. The
+cause vocabulary is enumerated from the scheduler's enqueue sites, so every
+value names a mechanism: `spawn`, `yield`, `sleep-wake`, `join-release`,
+`kill-release`, `recv-wake`, `deadlock` (the #509 re-enqueue of main).
+
+Two properties are load-bearing and gated by `tests/test_task_sched_trace.sh`:
+
+- **Pure reader.** The cause of each ready-queue entry is stamped at enqueue
+  time whether or not the trace is armed (one byte, moved in lockstep with the
+  queue), and arming only decides whether a pop is written down — after the
+  pick, never before it. So the seeded PRNG draws, the clock and the queue
+  order are untouched: a run with the trace armed is byte-identical (stdout,
+  stderr, exit code) to the same seed with it off.
+- **Derived, not taped.** The interleaving is a pure function of program
+  order and the seed, so the trace is re-derived on replay rather than
+  recorded: it adds no `N` records to the tape, and a tape recorded with the
+  trace armed replays to the identical history. A taped copy would be a
+  second source of truth that could disagree with the first.
+
+Arming never creates a scheduler (the flag lives on the thread, the history on
+the scheduler and is freed with it); the main task's initial run precedes the
+first entry and is implicit. The history is unbounded while armed — disarm
+(`task_sched_trace of 0`) to discard it.
+
 ## Replay boundary (#148)
 
 Thread scheduling is nondeterministic, so it cannot be recorded onto the trace
diff --git a/docs/SPEC.md b/docs/SPEC.md
index 153c6ae8..44a7b712 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -1819,6 +1819,47 @@ The same program with no seed prints the round-robin order
 `["a", "b", "c", "a", "b", "c"]`; a different seed prints a different — but
 equally reproducible — permutation.
 
+### Scheduler trace
+
+`task_sched_trace of 1` arms a trace of the scheduler's decisions (off by
+default; `EIGS_TASK_TRACE=1` arms it from the environment). While armed, every
+task **resume** appends one entry — `{seq, tick, task, cause}`: the entry's
+index, the virtual clock, the resumed task's id (`0` is the main task), and
+why it became runnable: `spawn` (its first run), `yield` (a `task_yield`
+re-enqueue), `sleep-wake` (the clock reached its `task_sleep` deadline),
+`join-release` (the task it joined finished), `kill-release` (the task it
+joined was killed), `recv-wake` (a message reached its empty mailbox), or
+`deadlock` (main re-enqueued to receive the catchable deadlock error).
+`task_sched_trace of null` reads the history; `task_sched_trace of 0` disarms
+it and discards it. The trace is a **pure reader**: arming it changes no pick,
+no clock and no seed — a traced run is byte-identical to the untraced one —
+and its entries are derived from the deterministic schedule rather than
+recorded on the trace tape, so a replayed run reproduces the same history.
+
+```eigenscript
+task_sched_trace of 1
+define step(tag) as:
+    task_yield of null
+    task_sleep of 10
+    return tag
+
+a is task_spawn of [step, "a"]
+b is task_spawn of [step, "b"]
+task_join of a
+task_join of b
+for e in task_sched_trace of null:
+    print of f"{e.seq} t={e.tick} task={e.task} {e.cause}"
+```
+```output
+0 t=0 task=1 spawn
+1 t=0 task=2 spawn
+2 t=0 task=1 yield
+3 t=0 task=2 yield
+4 t=10 task=1 sleep-wake
+5 t=10 task=2 sleep-wake
+6 t=10 task=0 join-release
+```
+
 ## Buffers
 
 `buffer of count` allocates a flat array of `count` nums (all 0).
diff --git a/docs/TRACE.md b/docs/TRACE.md
index aff85fd3..844f2fed 100644
--- a/docs/TRACE.md
+++ b/docs/TRACE.md
@@ -49,6 +49,17 @@ into real values on replay:
   visually parseable (truncated records are not replayable; the builtin
   falls back to its live source).
 
+## Derived, Not Recorded: The Scheduler Trace (#846)
+
+The cooperative task scheduler's decision history (`task_sched_trace`, see
+docs/CONCURRENCY.md) is **not** an `N` record. The interleaving is a pure
+function of program order and `task_sched_seed`, so a replayed run
+re-derives the identical history from the same schedule; recording it would
+create a second source of truth that could disagree with the first.
+`tests/test_task_sched_trace.sh` asserts the tape's `N`-record count is
+unchanged by arming the trace and that record → replay yields the same
+history on both tiers.
+
 ## Recorded Builtins
 
 Every builtin whose return value is nondeterministic from the script's
diff --git a/src/builtins.c b/src/builtins.c
index 26582308..16d3bcd6 100644
--- a/src/builtins.c
+++ b/src/builtins.c
@@ -5098,6 +5098,30 @@ Value* builtin_task_sched_seed(Value *arg) {
     return make_null();
 }
 
+/* task_sched_trace of null — the cooperative scheduler's decision history
+ * (#846): a list of {seq, tick, task, cause} dicts, one per task RESUME since
+ * the trace was armed, in schedule order. `task_sched_trace of 1` arms it,
+ * `task_sched_trace of 0` disarms it and discards the history; EIGS_TASK_TRACE=1
+ * arms it from the environment. Off by default. A PURE READER of the schedule:
+ * arming changes no pick, no clock, no seed — a traced run is byte-identical
+ * to the untraced one — and the entries derive from the deterministic
+ * schedule, so they are not tape records and replay reproduces them. Arming
+ * never creates a scheduler (see EigsThread.task_trace_on). */
+Value* builtin_task_sched_trace(Value *arg) {
+    if (!arg || arg->type == VAL_NULL) return task_sched_trace_read();
+    if (arg->type != VAL_NUM) {
+        rt_error(EK_TYPE, 0, "task_sched_trace takes null (read), 1 (arm) or 0 (disarm + clear)");
+        return make_null();
+    }
+    if (arg->data.num != 0) {
+        g_task_trace_on = 1;
+    } else {
+        g_task_trace_on = 0;
+        task_sched_trace_clear();
+    }
+    return make_null();
+}
+
 /* Deterministic teardown of OS-resource handles, run once the program has
  * finished executing (the full value world is still alive, so buffered-message
  * decrefs are safe). Channels and thread handles live in the process handle
@@ -6915,6 +6939,7 @@ void register_builtins(Env *env) {
     env_set_local_owned(env, "task_sleep", make_builtin(builtin_task_sleep));
     env_set_local_owned(env, "task_now", make_builtin(builtin_task_now));
     env_set_local_owned(env, "task_sched_seed", make_builtin(builtin_task_sched_seed));
+    env_set_local_owned(env, "task_sched_trace", make_builtin(builtin_task_sched_trace));
     env_set_local_owned(env, "thread_join", make_builtin(builtin_thread_join));
     env_set_local_owned(env, "channel", make_builtin(builtin_channel));
     env_set_local_owned(env, "send", make_builtin(builtin_send));
diff --git a/src/eigenscript.h b/src/eigenscript.h
index 77fbb168..df7d9eb1 100644
--- a/src/eigenscript.h
+++ b/src/eigenscript.h
@@ -925,6 +925,15 @@ struct EigsThread {
      * Lives here rather than inside TaskScheduler so the CASE(CALL) poll stays
      * one load off the already-hot eigs_current, with no NULL check. */
     int                  task_suspend_request;
+    /* #846: the scheduler trace is ARMED here, on the thread, never on the
+     * TaskScheduler — arming must not create a scheduler. A scheduler that
+     * exists but was never armed by a spawn (task_sched_seed creates one) is
+     * a live hazard: task_yield suspends main against it and
+     * vm_execute_common returns the suspend's NULL, truncating the program
+     * silently (exit 0, no output). Reading this flag costs the trampoline
+     * one load per resume; the history itself lives in the scheduler and is
+     * freed with it. Seeded from EIGS_TASK_TRACE at thread attach. */
+    int                  task_trace_on;
     /* #739: sandbox_run's caps and budget. Per-OS-thread: the save/restore in
      * builtin_sandbox_run is correct for one thread's nesting, but the
      * premise it documented — "sandbox_run is synchronous / single-threaded" —
@@ -1220,6 +1229,7 @@ void eigs_obs_unmute_for_fatal(void);
 #define g_native_call_depth   (eigs_current->native_call_depth)
 #define g_task_sched          (eigs_current->task_sched)
 #define g_task_suspend_request (eigs_current->task_suspend_request)
+#define g_task_trace_on       (eigs_current->task_trace_on)
 #define g_sandbox_loop_max    (eigs_current->sandbox_loop_max)
 #define g_sandbox_cap_hit     (eigs_current->sandbox_cap_hit)
 #define g_sandbox_active      (eigs_current->sandbox_active)
diff --git a/src/lsp_builtin_index.h b/src/lsp_builtin_index.h
index 2739eca6..9e7ed6da 100644
--- a/src/lsp_builtin_index.h
+++ b/src/lsp_builtin_index.h
@@ -313,6 +313,7 @@ static const char *builtin_docs[][2] = {
     {"task_now", "task_now of null → the current virtual-clock value (a number, 0 before any"},
     {"task_recv", "task_recv of null — return the next message from this task's mailbox, or"},
     {"task_sched_seed", "task_sched_seed of n — install a scheduling seed. By default tasks run FIFO"},
+    {"task_sched_trace", "task_sched_trace of null — the cooperative scheduler's decision history"},
     {"task_self", "task_self of null → the running task's id (a number, in the same integer"},
     {"task_send", "task_send of [id, value] — append a deep-copied message to task `id`'s"},
     {"task_sleep", "task_sleep of ticks — suspend the current task until the virtual clock"},
diff --git a/src/state.c b/src/state.c
index 8b6539e7..39fd44c7 100644
--- a/src/state.c
+++ b/src/state.c
@@ -132,6 +132,10 @@ EigsThread *eigs_thread_attach(EigsState *st) {
      * disabling the observer gate's eager pass on every thread. Default ON;
      * only --lint and the LSP clear it. */
     th->obs_gate_scan_enabled = 1;
+    /* #846: EIGS_TASK_TRACE=1 arms the cooperative-scheduler trace for this
+     * thread from the first resume (a program that cannot be edited can
+     * still be traced); `task_sched_trace of 1` arms it from a program. */
+    th->task_trace_on = eigs_env_flag("EIGS_TASK_TRACE");
     th->loop_exit_reason = "normal";
     th->last_obs_slot_idx = -1;   /* #262 Phase-2: no observed slot yet */
 
diff --git a/src/vm.c b/src/vm.c
index f5ee7c88..0d06d198 100644
--- a/src/vm.c
+++ b/src/vm.c
@@ -6419,6 +6419,13 @@ static Value *vm_run(EigsChunk *chunk, Env *env, int call_argc) {
 
 #define TASK_READY_MAX HANDLE_TABLE_SIZE
 
+/* #846: one scheduler-trace entry — a resume. `seq` is the entry's index. */
+typedef struct {
+    double  tick;    /* virtual clock (task_now) at the resume */
+    int     task;    /* resumed task id (0 = main) */
+    uint8_t cause;   /* SCAUSE_* below */
+} SchedTraceEntry;
+
 typedef struct {
     int   ready[TASK_READY_MAX];  /* circular FIFO of runnable task ids (0=main) */
     int   rhead, rcount;
@@ -6431,9 +6438,41 @@ typedef struct {
     double now;                   /* inc 3: virtual clock (logical, starts 0) */
     int   seeded;                 /* inc 4: 1 once task_sched_seed installs a seed */
     uint64_t rng_state;           /* inc 4: splitmix64 state for the seeded pick */
+    /* #846: WHY each ready entry became runnable, kept in lockstep with
+     * `ready` (same index, moved by the same compaction). A property of the
+     * queue entry, not of the task: the cause is fixed at enqueue time and
+     * consumed by the pop that resumes the task. Always maintained — it is
+     * one byte store per enqueue — so arming the trace mid-run changes
+     * nothing about the schedule, only whether a pop is written down. */
+    uint8_t ready_cause[TASK_READY_MAX];
+    int   pop_cause;              /* #846: cause of the most recent sched_ready_pop */
+    /* #846: the recorded history — one entry per trampoline resume while
+     * g_task_trace_on. Freed in task_sched_thread_free. Unbounded by design:
+     * a silent cap would make a long run's trace lie about its tail. */
+    SchedTraceEntry *trace;
+    int   trace_count, trace_cap;
     Task  main_task;              /* task 0 — save-buffer only, never "started" */
 } TaskScheduler;
 
+/* #846: the cause vocabulary, enumerated from the enqueue sites below — every
+ * sched_ready_push names one. A resumed task was enqueued by exactly one of:
+ *   spawn         task_sched_on_spawn — its first run (task_start)
+ *   yield         a task_yield re-enqueue (trampoline / main's first suspend)
+ *   sleep-wake    sched_wake_sleepers advanced the virtual clock to its wake_at
+ *   join-release  the task it was joined on finished (sched_finish)
+ *   kill-release  the task it was joined on was task_kill'ed (task_do_kill)
+ *   recv-wake     task_send delivered to its empty mailbox (task_deliver)
+ *   deadlock      main re-enqueued to receive the catchable deadlock (#509)
+ * Names are the .eigs-visible contract (docs/CONCURRENCY.md). */
+enum {
+    SCAUSE_SPAWN = 0, SCAUSE_YIELD, SCAUSE_SLEEP_WAKE, SCAUSE_JOIN_RELEASE,
+    SCAUSE_KILL_RELEASE, SCAUSE_RECV_WAKE, SCAUSE_DEADLOCK, SCAUSE__COUNT
+};
+static const char *const sched_cause_name[SCAUSE__COUNT] = {
+    "spawn", "yield", "sleep-wake", "join-release", "kill-release",
+    "recv-wake", "deadlock"
+};
+
 static TaskScheduler *sched_get(void) { return (TaskScheduler *)g_task_sched; }
 
 static TaskScheduler *sched_ensure(void) {
@@ -6476,6 +6515,7 @@ void task_sched_thread_free(void) {
     }
     if (m->result) val_decref(m->result);
     if (m->error_value) val_decref(m->error_value);
+    free(s->trace);   /* #846 */
     free(s);
     g_task_sched = NULL;
 }
@@ -6505,9 +6545,11 @@ static Task *task_current_running(void) {
     return s ? sched_lookup(s, s->current) : NULL;
 }
 
-static void sched_ready_push(TaskScheduler *s, int id) {
+static void sched_ready_push(TaskScheduler *s, int id, int cause) {
     if (s->rcount >= TASK_READY_MAX) return;   /* ids are table-bounded; can't overflow */
-    s->ready[(s->rhead + s->rcount) % TASK_READY_MAX] = id;
+    int slot = (s->rhead + s->rcount) % TASK_READY_MAX;
+    s->ready[slot] = id;
+    s->ready_cause[slot] = (uint8_t)cause;   /* #846: rides with the entry */
     s->rcount++;
 }
 
@@ -6520,9 +6562,12 @@ static void sched_ready_push(TaskScheduler *s, int id) {
 static void sched_ready_remove(TaskScheduler *s, int tid) {
     int w = 0;
     for (int k = 0; k < s->rcount; k++) {
-        int id = s->ready[(s->rhead + k) % TASK_READY_MAX];
+        int from = (s->rhead + k) % TASK_READY_MAX;
+        int id = s->ready[from];
         if (id != tid) {
-            s->ready[(s->rhead + w) % TASK_READY_MAX] = id;
+            int to = (s->rhead + w) % TASK_READY_MAX;
+            s->ready[to] = id;
+            s->ready_cause[to] = s->ready_cause[from];   /* #846: lockstep */
             w++;
         }
     }
@@ -6557,6 +6602,7 @@ static int sched_ready_pop(TaskScheduler *s) {
     if (!s->seeded || s->rcount == 1) {
         /* Default FIFO: O(1) head pop — the fast path, unchanged. */
         int id = s->ready[s->rhead];
+        s->pop_cause = s->ready_cause[s->rhead];   /* #846 */
         s->rhead = (s->rhead + 1) % TASK_READY_MAX;
         s->rcount--;
         return id;
@@ -6566,14 +6612,56 @@ static int sched_ready_pop(TaskScheduler *s) {
      * in the ready count, which is tiny and only paid in DST/seeded mode. */
     int idx = (int)(sched_rng_next(s) % (uint64_t)s->rcount);
     int id  = s->ready[(s->rhead + idx) % TASK_READY_MAX];
+    s->pop_cause = s->ready_cause[(s->rhead + idx) % TASK_READY_MAX];   /* #846 */
     for (int k = idx; k < s->rcount - 1; k++) {
-        s->ready[(s->rhead + k) % TASK_READY_MAX] =
-            s->ready[(s->rhead + k + 1) % TASK_READY_MAX];
+        int to = (s->rhead + k) % TASK_READY_MAX, from = (s->rhead + k + 1) % TASK_READY_MAX;
+        s->ready[to] = s->ready[from];
+        s->ready_cause[to] = s->ready_cause[from];   /* #846: lockstep */
     }
     s->rcount--;
     return id;
 }
 
+/* ---- #846: the scheduler trace ------------------------------------------
+ * Pure reader: called from the trampoline AFTER the pick is made and BEFORE
+ * the task runs, with nothing but scheduler state as input. No tape record —
+ * the schedule is a pure function of program order (+ seed), so a replayed
+ * run re-derives the identical history; a tape-recorded trace would be a
+ * second, redundant source of truth that could disagree with the first. */
+static void sched_trace_record(TaskScheduler *s, int id, int cause) {
+    if (s->trace_count == s->trace_cap) {
+        int nc = s->trace_cap ? s->trace_cap * 2 : 64;
+        s->trace = xrealloc(s->trace, sizeof(SchedTraceEntry) * (size_t)nc);
+        s->trace_cap = nc;
+    }
+    SchedTraceEntry *e = &s->trace[s->trace_count++];
+    e->tick  = s->now;
+    e->task  = id;
+    e->cause = (uint8_t)cause;
+}
+
+Value *task_sched_trace_read(void) {
+    TaskScheduler *s = sched_get();
+    if (!s) return make_list(0);
+    Value *out = make_list(s->trace_count);
+    for (int i = 0; i < s->trace_count; i++) {
+        const SchedTraceEntry *e = &s->trace[i];
+        Value *d = make_dict(4);
+        dict_set_owned(d, "seq",   make_num((double)i));
+        dict_set_owned(d, "tick",  make_num(e->tick));
+        dict_set_owned(d, "task",  make_num((double)e->task));
+        dict_set_owned(d, "cause", make_str(e->cause < SCAUSE__COUNT
+                                            ? sched_cause_name[e->cause] : "?"));
+        list_append_owned(out, d);
+    }
+    return out;
+}
+
+void task_sched_trace_clear(void) {
+    TaskScheduler *s = sched_get();
+    if (s) s->trace_count = 0;   /* keep the buffer; re-arming reuses it */
+}
+
 /* Copying-stack save: memcpy the running task's live slice [0,fc)/[0,sp) into
  * its right-sized save-buffer, then retreat the VM to empty. Refs move WITH
  * the bytes (the saved slots/frames own the same counted refs that were on
@@ -6622,7 +6710,7 @@ void task_sched_on_spawn(int id) {
      * pure function of the run. Main is 0 (spawn_counter starts at 1). */
     Task *t = sched_lookup(s, id);
     if (t) t->spawn_seq = ++s->spawn_counter;
-    sched_ready_push(s, id);
+    sched_ready_push(s, id, SCAUSE_SPAWN);
 }
 
 /* task_yield: mark the current task for suspension; the trampoline re-enqueues
@@ -6675,7 +6763,7 @@ int task_deliver(int tid, Value *msg_owned) {
      * second send before the receiver resumes finds count>1 and does not
      * re-enqueue (which would put the task in the ready queue twice). */
     if (t->recv_blocked && t->state == TASK_SUSPENDED && t->mbox_count == 1)
-        sched_ready_push(s, tid);
+        sched_ready_push(s, tid, SCAUSE_RECV_WAKE);
     return 1;
 }
 
@@ -6759,7 +6847,7 @@ static int sched_wake_sleepers(TaskScheduler *s) {
     if (s->main_task.state == TASK_SUSPENDED && s->main_task.sleeping &&
         s->main_task.wake_at <= s->now) {
         s->main_task.sleeping = 0;
-        sched_ready_push(s, 0);
+        sched_ready_push(s, 0, SCAUSE_SLEEP_WAKE);
     }
     for (;;) {
         Task *next = NULL;
@@ -6771,7 +6859,7 @@ static int sched_wake_sleepers(TaskScheduler *s) {
         }
         if (!next) break;
         next->sleeping = 0;
-        sched_ready_push(s, next->id);
+        sched_ready_push(s, next->id, SCAUSE_SLEEP_WAKE);
     }
     return 1;
 }
@@ -6831,10 +6919,10 @@ int task_do_kill(int tid) {
     for (int i = 1; i < HANDLE_TABLE_SIZE; i++) {
         Task *w = (Task *)handle_lookup(i, HANDLE_TASK);
         if (w && w->state == TASK_SUSPENDED && w->join_target == tid)
-            sched_ready_push(s, w->id);
+            sched_ready_push(s, w->id, SCAUSE_KILL_RELEASE);
     }
     if (s->main_task.state == TASK_SUSPENDED && s->main_task.join_target == tid)
-        sched_ready_push(s, 0);
+        sched_ready_push(s, 0, SCAUSE_KILL_RELEASE);
     /* #530: kill of a detached task is an explicit discard — reap now. (Kill
      * is a deliberate teardown, never an uncaught error: no #493 counting.) */
     if (t->detached) task_reap(t);
@@ -6964,10 +7052,10 @@ static void sched_finish(TaskScheduler *s, Task *t, Value *r) {
     for (int i = 1; i < HANDLE_TABLE_SIZE; i++) {
         Task *w = (Task *)handle_lookup(i, HANDLE_TASK);
         if (w && w->state == TASK_SUSPENDED && w->join_target == t->id)
-            sched_ready_push(s, w->id);
+            sched_ready_push(s, w->id, SCAUSE_JOIN_RELEASE);
     }
     if (s->main_task.state == TASK_SUSPENDED && s->main_task.join_target == t->id)
-        sched_ready_push(s, 0);
+        sched_ready_push(s, 0, SCAUSE_JOIN_RELEASE);
     /* #530: a detached task's outcome is nobody's to consume — reap the slot
      * now so task-per-message workloads aren't bounded by lifetime spawns.
      * An uncaught death still fails the process: the #493 flag moves to the
@@ -7065,7 +7153,7 @@ static Value *scheduler_trampoline(TaskScheduler *s) {
                 m->join_target = 0;
                 m->recv_blocked = 0;
                 m->sleeping = 0;
-                sched_ready_push(s, 0);
+                sched_ready_push(s, 0, SCAUSE_DEADLOCK);
                 continue;
             }
             /* No handler in main → terminal: print loudly, exit non-zero. (No
@@ -7076,6 +7164,9 @@ static Value *scheduler_trampoline(TaskScheduler *s) {
         Task *t = sched_lookup(s, id);
         if (!t || t->state == TASK_DONE || t->state == TASK_DEAD) continue;
         s->current = id;
+        /* #846: one entry per resume, written AFTER the pick (the pick is
+         * untouched) and only while armed — off, this is one load + branch. */
+        if (g_task_trace_on) sched_trace_record(s, id, s->pop_cause);
 
         Value *r;
         if (t->state == TASK_SUSPENDED) {
@@ -7092,7 +7183,7 @@ static Value *scheduler_trampoline(TaskScheduler *s) {
              * stay blocked (woken by task_deliver); task_sleep → stay blocked
              * (woken by sched_wake_sleepers when the clock reaches wake_at). */
             if (t->join_target == 0 && !t->recv_blocked && !t->sleeping)
-                sched_ready_push(s, id);
+                sched_ready_push(s, id, SCAUSE_YIELD);
         } else {
             sched_finish(s, t, r);
             /* kill-outstanding: main ending tears the rest down deterministically. */
@@ -7186,7 +7277,7 @@ static Value *vm_execute_common(EigsChunk *chunk, Env *env, int call_argc) {
          * trampoline's re-enqueue guard. */
         if (s->main_task.join_target == 0 && !s->main_task.recv_blocked &&
             !s->main_task.sleeping)
-            sched_ready_push(s, 0);
+            sched_ready_push(s, 0, SCAUSE_YIELD);
         return scheduler_trampoline(s);
     }
     /* main ran to completion without ever suspending. Record its result and,
diff --git a/src/vm.h b/src/vm.h
index 9b564614..34dc13d0 100644
--- a/src/vm.h
+++ b/src/vm.h
@@ -642,6 +642,12 @@ int   task_do_detach(int tid);       /* #530: mark fire-and-forget (reap at fini
 void   task_request_sleep(double ticks); /* current task sleeps until virtual now + ticks */
 double task_virtual_now(void);           /* current virtual-clock value (0 with no scheduler) */
 int    task_current_id(void);            /* running task id; 0 = main (incl. no scheduler) — task_self (#526) */
+/* #846 scheduler trace (builtins.c task_sched_trace). The trace is a PURE
+ * READER of the schedule: recording never touches the ready queue, the
+ * seeded PRNG, or the clock, and its entries are derived from the
+ * deterministic schedule, so they are not tape records. */
+Value *task_sched_trace_read(void);   /* list of {seq, tick, task, cause} dicts; [] when off / no scheduler */
+void   task_sched_trace_clear(void);  /* discard the recorded history (no-op without a scheduler) */
 /* Inc 4 seeded scheduling strategy (builtins.c task_sched_seed). */
 void   task_sched_set_seed(double seed); /* install a seed → seeded pick; ensures the scheduler */
 
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 6f2d4e2c..2c60afea 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -4792,6 +4792,30 @@ check_task_exit task_exit_detached_death.eigs 1 "MARK_END"         # #530: a DET
 check_task_exit task_deadlock.eigs            1 "deadlock"         # #483 leak-clean (main's suspended slice) + #509 uncaught loud
 check_task_exit task_deadlock_worker_try.eigs 1 "deadlock"         # #509: deadlock goes to MAIN; a worker's try doesn't catch it
 
+# #846 scheduler trace: a gated, off-by-default history of every task resume
+# ({seq, tick, task, cause}). The fixture pins the cause vocabulary, the FIFO
+# and seeded histories (derivations written from the scheduler's source) and
+# the sandbox fail-closed posture; the child .sh pins the two DST constraints
+# — arming it perturbs nothing (byte-identical stdout/stderr/rc across all 12
+# task programs in the tree, error paths included) and it is derived, not
+# taped (replay reproduces it, plain and under EIGS_REPLAY_STRICT=1; the
+# N-record count is unchanged and no N record names the trace). Replay is
+# checked JIT-on and EIGS_JIT_OFF=1.
+echo "[104b] Scheduler Trace (task_sched_trace, #846)"
+check_eigs_suite "task_sched_trace: causes, fifo + seeded histories, arm/disarm (#846)" test_task_sched_trace.eigs "All tests passed" 1
+ST_OUTPUT=$(bash "$TESTS_DIR/test_task_sched_trace.sh" 2>&1)
+ST_PASS=$(echo "$ST_OUTPUT" | grep -c "PASS:" || true)
+ST_FAIL=$(echo "$ST_OUTPUT" | grep -c "FAIL:" || true)
+TOTAL=$((TOTAL + ST_PASS + ST_FAIL))
+PASS=$((PASS + ST_PASS))
+FAIL=$((FAIL + ST_FAIL))
+if [ "$ST_FAIL" -gt 0 ] || [ "$ST_PASS" -eq 0 ]; then
+    echo "  FAIL: scheduler-trace purity/replay/tape checks ($ST_PASS passed, $ST_FAIL failed)"
+    echo "$ST_OUTPUT" | grep "FAIL:" | head -5
+else
+    echo "  PASS: all $ST_PASS scheduler-trace purity/replay/tape checks"
+fi
+
 # [105] Builtin contract fixes (#312 negative indices, #316 predicate
 # type-rejection, #317 min/max N-ary reduction) + #314: a directory as the
 # script path must take the clean cannot-read-file exit, not xmalloc's
diff --git a/tests/task_sched_trace_probe.eigs b/tests/task_sched_trace_probe.eigs
new file mode 100644
index 00000000..d8e9be0a
--- /dev/null
+++ b/tests/task_sched_trace_probe.eigs
@@ -0,0 +1,20 @@
+# #846 probe for tests/test_task_sched_trace.sh: a seeded 3-task yield/sleep/
+# join program that ALSO consumes a real nondeterministic input (random), so
+# the tape it records carries N records — the test asserts that arming the
+# scheduler trace adds none. Prints the trace in compact form; under
+# EIGS_REPLAY the printed trace must be byte-identical to the recording run.
+task_sched_seed of 42
+salt is random of null
+define w(tag, ticks) as:
+    task_yield of null
+    task_sleep of ticks
+    return tag
+a is task_spawn of [w, "a", 30]
+b is task_spawn of [w, "b", 10]
+c is task_spawn of [w, "c", 20]
+print of (task_join of a)
+print of (task_join of b)
+print of (task_join of c)
+print of f"salt={salt}"
+for e in task_sched_trace of null:
+    print of f"{e.seq} t={e.tick} task={e.task} {e.cause}"
diff --git a/tests/test_task_sched_trace.eigs b/tests/test_task_sched_trace.eigs
new file mode 100644
index 00000000..e10d1640
--- /dev/null
+++ b/tests/test_task_sched_trace.eigs
@@ -0,0 +1,230 @@
+# #846: the gated cooperative-scheduler trace. `task_sched_trace of 1` arms
+# it, `task_sched_trace of null` reads one {seq, tick, task, cause} entry per
+# task RESUME, `task_sched_trace of 0` disarms and clears. Every expectation
+# below was written from READING src/vm.c's scheduler (sched_ready_pop,
+# sched_wake_sleepers, sched_finish, task_do_kill, task_deliver, the
+# trampoline) before the binary ran — the FIFO cases by hand, the seeded case
+# through an independent splitmix64 model of the pick (the derivation is in
+# the seeded block's comment). The trace is a pure reader: nothing here
+# changes an interleaving, and tests/test_task_sched_trace.sh proves that
+# across whole programs (armed vs unarmed byte-identical, replay-identical,
+# zero tape records).
+# Run with EIGS_TASK_TRACE unset (the suite's environment): the first block
+# asserts the OFF-BY-DEFAULT behaviour, which that variable exists to override,
+# so a pre-armed environment turns those rows red by design, not by defect.
+load_file of "lib/test.eigs"
+
+# Render entries as "tick:name:cause" relative to `base` (the virtual clock
+# carries across cases) with task ids mapped through `names` (ids come from a
+# rotating handle cursor, so the expectations never mention a literal id).
+define fmt_trace(entries, names, base) as:
+    local out is []
+    for e in entries:
+        local nm is str of e.task
+        if has_key of [names, nm]:
+            nm is names[nm]
+        out is append of [out, f"{e.tick - base}:{nm}:{e.cause}"]
+    return out
+
+define same_trace(actual, expected, desc) as:
+    assert_eq of [str of actual, str of expected, desc]
+
+# ---- off by default: nothing is recorded, before or after tasks run ----
+assert_eq of [len of (task_sched_trace of null), 0, "unarmed: empty before any task"]
+define t0_w() as:
+    task_yield of null
+    return 1
+assert_eq of [task_join of (task_spawn of t0_w), 1, "unarmed worker runs normally"]
+assert_eq of [len of (task_sched_trace of null), 0, "unarmed: still empty after tasks ran"]
+
+# ---- FIFO (no seed): 3 tasks yield, sleep 30/10/20, main joins a, b, c ----
+# Hand derivation (ready queue in brackets, main blocked on a throughout):
+#   [a b c]  pop a  spawn  -> a yields          [b c a]
+#            pop b  spawn  -> b yields          [c a b]
+#            pop c  spawn  -> c yields          [a b c]
+#            pop a  yield  -> a sleeps 30       [b c]
+#            pop b  yield  -> b sleeps 10       [c]
+#            pop c  yield  -> c sleeps 20       []
+#   idle: clock -> 10, wake b   pop b  sleep-wake -> b done (main waits on a)
+#   idle: clock -> 20, wake c   pop c  sleep-wake -> c done
+#   idle: clock -> 30, wake a   pop a  sleep-wake -> a done -> main enqueued
+#            pop main join-release -> joins of b, c return at once; program ends
+define w3(tag, ticks) as:
+    task_yield of null
+    task_sleep of ticks
+    return tag
+task_sched_trace of 1
+base is task_now of null
+a is task_spawn of [w3, "a", 30]
+b is task_spawn of [w3, "b", 10]
+c is task_spawn of [w3, "c", 20]
+names is {"0": "main"}
+dict_set of [names, str of a, "a"]
+dict_set of [names, str of b, "b"]
+dict_set of [names, str of c, "c"]
+assert_eq of [task_join of a, "a", "fifo: a joins"]
+assert_eq of [task_join of b, "b", "fifo: b joins"]
+assert_eq of [task_join of c, "c", "fifo: c joins"]
+fifo_expected is ["0:a:spawn", "0:b:spawn", "0:c:spawn",
+                  "0:a:yield", "0:b:yield", "0:c:yield",
+                  "10:b:sleep-wake", "20:c:sleep-wake", "30:a:sleep-wake",
+                  "30:main:join-release"]
+same_trace of [fmt_trace of [task_sched_trace of null, names, base], fifo_expected,
+               "fifo yield/sleep/join history matches the hand derivation"]
+first is (task_sched_trace of null)[0]
+assert_eq of [first.seq, 0, "entries carry a 0-based seq"]
+assert_eq of [(task_sched_trace of null)[9].seq, 9, "seq is the entry index"]
+assert_eq of [first.tick, base, "tick is the virtual clock at the resume"]
+assert_eq of [first.task, a, "task is the id task_spawn returned"]
+assert_eq of [first.cause, "spawn", "cause is a string"]
+
+# ---- recv-wake: a receiver blocked on an empty mailbox, woken by task_send ----
+#   main yields -> [r main]; pop r spawn -> r blocks in task_recv (not queued)
+#   pop main yield -> task_send wakes r [r]; main joins r (blocks)
+#   pop r recv-wake -> r returns -> main enqueued; pop main join-release
+task_sched_trace of 0
+task_sched_trace of 1
+base is task_now of null
+define receiver() as:
+    local m is task_recv of null
+    return m
+r is task_spawn of receiver
+dict_set of [names, str of r, "r"]
+task_yield of null
+assert_eq of [task_send of [r, "hi"], 1, "recv-wake: message delivered"]
+assert_eq of [task_join of r, "hi", "recv-wake: receiver returns the message"]
+same_trace of [fmt_trace of [task_sched_trace of null, names, base],
+               ["0:r:spawn", "0:main:yield", "0:r:recv-wake", "0:main:join-release"],
+               "recv-wake history"]
+
+# ---- kill-release: main joins a sleeper that a sibling kills ----
+#   main joins v -> [v k]; pop v spawn -> v sleeps 100 (not queued)
+#   pop k spawn -> task_kill of v wakes the joiner (main) with an interrupt [main]
+#   -> k returns (nobody joins it yet); pop main kill-release -> join re-raises
+task_sched_trace of 0
+task_sched_trace of 1
+base is task_now of null
+define sleeper() as:
+    task_sleep of 100
+    return 1
+define killer(victim) as:
+    task_kill of victim
+    return 2
+v is task_spawn of sleeper
+k is task_spawn of [killer, v]
+dict_set of [names, str of v, "v"]
+dict_set of [names, str of k, "k"]
+kill_kind is ""
+try:
+    task_join of v
+catch e:
+    kill_kind is e.kind
+assert_eq of [kill_kind, "interrupt", "kill-release: the joiner sees the interrupt"]
+assert_eq of [task_join of k, 2, "kill-release: the killer finished"]
+same_trace of [fmt_trace of [task_sched_trace of null, names, base],
+               ["0:v:spawn", "0:k:spawn", "0:main:kill-release"],
+               "kill-release history"]
+assert_eq of [task_now of null, base, "the killed sleeper never advanced the clock"]
+
+# ---- seeded (seed 42): the same yield/sleep/join program under the PRNG pick ----
+# Derived by modelling sched_ready_pop exactly: splitmix64 state = 42, one
+# draw per pop while more than one task is ready, pick = draw % count, hole
+# compacted order-preserving (a single ready task pops FIFO with no draw), and
+# sleepers woken in spawn order when nothing is runnable. The model
+# (scratch: sched_model.py, reproduced in the commit message) gives the
+# picks b, c, a for [a b c] at seed 42 — the same permutation docs/SPEC.md's
+# seeded example prints — and every later pop happens with one task ready.
+task_sched_trace of 0
+task_sched_seed of 42
+task_sched_trace of 1
+base is task_now of null
+sa is task_spawn of [w3, "a", 30]
+sb is task_spawn of [w3, "b", 10]
+sc is task_spawn of [w3, "c", 20]
+dict_set of [names, str of sa, "a"]
+dict_set of [names, str of sb, "b"]
+dict_set of [names, str of sc, "c"]
+assert_eq of [task_join of sa, "a", "seeded: a joins"]
+assert_eq of [task_join of sb, "b", "seeded: b joins"]
+assert_eq of [task_join of sc, "c", "seeded: c joins"]
+seeded_expected is ["0:b:spawn", "0:c:spawn", "0:a:spawn",
+                    "0:b:yield", "0:c:yield", "0:a:yield",
+                    "10:b:sleep-wake", "20:c:sleep-wake", "30:a:sleep-wake",
+                    "30:main:join-release"]
+same_trace of [fmt_trace of [task_sched_trace of null, names, base], seeded_expected,
+               "seeded (42) history matches the splitmix64 model"]
+
+# ---- disarm clears; re-arm records fresh (one task ready throughout: FIFO) ----
+task_sched_trace of 0
+assert_eq of [len of (task_sched_trace of null), 0, "disarm discards the history"]
+define lone() as:
+    task_yield of null
+    return 3
+lo is task_spawn of lone
+assert_eq of [task_join of lo, 3, "disarmed worker runs"]
+assert_eq of [len of (task_sched_trace of null), 0, "disarmed: nothing recorded"]
+task_sched_trace of 1
+base is task_now of null
+lo2 is task_spawn of lone
+dict_set of [names, str of lo2, "w"]
+assert_eq of [task_join of lo2, 3, "re-armed worker runs"]
+same_trace of [fmt_trace of [task_sched_trace of null, names, base],
+               ["0:w:spawn", "0:w:yield", "0:main:join-release"],
+               "re-armed: fresh history from the re-arm point"]
+
+# ---- the argument contract ----
+bad_kind is ""
+try:
+    task_sched_trace of "on"
+catch e:
+    bad_kind is e.kind
+assert_eq of [bad_kind, "type_mismatch", "a non-number, non-null argument raises"]
+assert_eq of [type of (task_sched_trace of 1), "none", "arming returns null"]
+
+# ---- the sandbox cannot reach the host thread's trace ----
+# SANDBOX_ALLOW is a fail-CLOSED name allowlist and this builtin is not on it,
+# so a sandboxed chunk calling it is denied. That posture is what keeps the
+# arm flag — per-thread state of the HOST — out of untrusted bytecode's reach.
+# Descriptor shape and opcode numbers per tests/test_sandbox_allow.eigs.
+task_sched_trace of 0
+SB_ABI is 1
+SB_GET_NAME is 25
+SB_CONST is 0
+SB_CALL is 39
+SB_RETURN is 40
+sb is sandbox_run of [[SB_ABI, [SB_GET_NAME, 0, 0, SB_CONST, 1, 0, SB_CALL, 1, 0, SB_RETURN],
+                       ["task_sched_trace", 1]], 1000]
+assert_eq of [sb["ok"], 0, "sandbox: task_sched_trace is denied inside sandbox_run"]
+lo3 is task_spawn of lone
+assert_eq of [task_join of lo3, 3, "sandbox: the host keeps running normally"]
+assert_eq of [len of (task_sched_trace of null), 0,
+              "sandbox: the denied call did not arm the host's trace"]
+
+# ---- deadlock: main is re-enqueued to receive the catchable error (#509) ----
+# Placed last: the two mutually-blocked workers stay suspended forever. The
+# seeded pick decides which of them runs first, so this asserts the causes
+# and the final entry, not the order of the two spawns.
+task_sched_trace of 0
+task_sched_trace of 1
+dla is 0
+dlb is 0
+define dl_a as:
+    return task_join of dlb
+define dl_b as:
+    return task_join of dla
+dla is task_spawn of dl_a
+dlb is task_spawn of dl_b
+dl_kind is ""
+try:
+    task_join of dla
+catch e:
+    dl_kind is e.kind
+assert_eq of [dl_kind, "deadlock", "deadlock is delivered to main"]
+dl is task_sched_trace of null
+assert_eq of [len of dl, 3, "deadlock: two spawns then main's re-enqueue"]
+assert_eq of [dl[0].cause, "spawn", "deadlock: first entry is a spawn"]
+assert_eq of [dl[1].cause, "spawn", "deadlock: second entry is a spawn"]
+assert_eq of [dl[2].task, 0, "deadlock: main is the resumed task"]
+assert_eq of [dl[2].cause, "deadlock", "deadlock: cause names the #509 re-enqueue"]
+
+test_summary of null
diff --git a/tests/test_task_sched_trace.sh b/tests/test_task_sched_trace.sh
new file mode 100755
index 00000000..100dd833
--- /dev/null
+++ b/tests/test_task_sched_trace.sh
@@ -0,0 +1,103 @@
+#!/bin/bash
+# #846: the scheduler trace is a PURE READER of the schedule and derives from
+# it, not from the tape. Three claims, each asserted mechanically:
+#   1. Purity — arming the trace (EIGS_TASK_TRACE=1) leaves stdout, stderr and
+#      the exit code of a task program byte-identical, for every task example
+#      and task program in the tree (seeded, virtual-time, mailbox, OSR, and
+#      the six error-path programs: deadlock, kill, uncaught/detached death) —
+#      the error paths matter because kill-release and the #509 deadlock
+#      re-enqueue are causes only they reach.
+#   2. Replay — a tape recorded with the trace armed replays (EIGS_REPLAY) to
+#      the identical printed trace, JIT on and EIGS_JIT_OFF=1.
+#   3. Not a tape record — the tape's N-record count is the same whether the
+#      trace is armed or not (the probe consumes `random`, so the count is
+#      nonzero and "unchanged" is a real comparison, not 0 == 0), no `N`
+#      record in the tape read back names the trace or a cause, and
+#      EIGS_REPLAY_STRICT=1 (a desynced nondet stream is fatal there)
+#      reproduces the run and the trace unchanged.
+# Runs with cwd src/ (the runner's convention); no bare `timeout`.
+set -u
+TESTS_DIR="$(cd "$(dirname "$0")" && pwd)"
+SRC_DIR="$(cd "$TESTS_DIR/.." && pwd)/src"
+EIGS="$SRC_DIR/eigenscript"
+PASS=0; FAIL=0
+ok()   { echo "  PASS: $1"; PASS=$((PASS+1)); }
+fail() { echo "  FAIL: $1${2:+ ($2)}"; FAIL=$((FAIL+1)); }
+TMP=$(mktemp -d -t eigs_schedtrace.XXXXXX)
+trap 'rm -rf "$TMP"' EXIT
+cd "$SRC_DIR" || { echo "  FAIL: cannot cd to $SRC_DIR"; exit 1; }
+
+# ---- 1. purity across whole programs ----
+run_to() {   # $1 = out-prefix, then env assignments + program
+    local pre="$1"; shift
+    env "$@" </dev/null >"$pre.out" 2>"$pre.err"; echo $? >"$pre.rc"
+}
+for prog in ../examples/task_pipeline.eigs ../examples/task_virtual_time.eigs \
+            ../examples/task_seeded_schedule.eigs ../tests/test_tasks.eigs \
+            ../tests/test_task_sleep_order.eigs ../tests/test_task_osr.eigs \
+            ../tests/task_deadlock.eigs ../tests/task_deadlock_worker_try.eigs \
+            ../tests/task_exit_killed.eigs ../tests/task_exit_join_catch.eigs \
+            ../tests/task_exit_unjoined_death.eigs ../tests/task_exit_detached_death.eigs; do
+    name=$(basename "$prog")
+    run_to "$TMP/off" EIGS_TASK_TRACE=0 ./eigenscript "$prog"
+    run_to "$TMP/on"  EIGS_TASK_TRACE=1 ./eigenscript "$prog"
+    if cmp -s "$TMP/off.out" "$TMP/on.out" && cmp -s "$TMP/off.err" "$TMP/on.err" \
+       && cmp -s "$TMP/off.rc" "$TMP/on.rc" \
+       && { [ -s "$TMP/off.out" ] || [ -s "$TMP/off.err" ]; }; then
+        ok "purity: $name byte-identical with the trace armed (rc $(cat "$TMP/on.rc"))"
+    else
+        fail "purity: $name diverged with the trace armed" "rc off=$(cat "$TMP/off.rc") on=$(cat "$TMP/on.rc"); $(diff "$TMP/off.out" "$TMP/on.out" | head -3 | tr '\n' ' ')"
+    fi
+done
+
+# ---- 2. replay reproduces the trace; 3. the tape gains no N records ----
+PROBE=../tests/task_sched_trace_probe.eigs
+for tier in "jit-on" "jit-off"; do
+    if [ "$tier" = "jit-off" ]; then JOFF=1; else JOFF=0; fi
+    TAPE_ON="$TMP/on_$tier.tape"; TAPE_OFF="$TMP/off_$tier.tape"
+    REC=$(EIGS_JIT_OFF=$JOFF EIGS_TASK_TRACE=1 EIGS_TRACE="$TAPE_ON" ./eigenscript "$PROBE" </dev/null 2>&1); REC_RC=$?
+    REP=$(EIGS_JIT_OFF=$JOFF EIGS_TASK_TRACE=1 EIGS_REPLAY="$TAPE_ON" ./eigenscript "$PROBE" </dev/null 2>&1); REP_RC=$?
+    EIGS_JIT_OFF=$JOFF EIGS_TASK_TRACE=0 EIGS_TRACE="$TAPE_OFF" ./eigenscript "$PROBE" </dev/null >/dev/null 2>&1
+    N_ON=$(grep -c '^N ' "$TAPE_ON" 2>/dev/null); N_OFF=$(grep -c '^N ' "$TAPE_OFF" 2>/dev/null)
+    ENTRIES=$(printf '%s\n' "$REC" | grep -c ' task=')
+    # The trace must actually be there (10 resumes for this program) and carry
+    # a wake at virtual tick 30 — a replay that reproduced an EMPTY trace would
+    # otherwise pass the equality below.
+    if [ "$REC_RC" = "0" ] && [ "$REP_RC" = "0" ] && [ "$REC" = "$REP" ] \
+       && [ "$ENTRIES" = "10" ] && printf '%s\n' "$REC" | grep -q '^8 t=30 task=[0-9]* sleep-wake$'; then
+        ok "replay ($tier): recorded and replayed traces are byte-identical ($ENTRIES entries)"
+    else
+        fail "replay ($tier): trace diverged under EIGS_REPLAY" "rc $REC_RC/$REP_RC entries=$ENTRIES; $(diff <(printf '%s\n' "$REC") <(printf '%s\n' "$REP") | head -3 | tr '\n' ' ')"
+    fi
+    if [ -n "$N_ON" ] && [ "$N_ON" -gt 0 ] && [ "$N_ON" = "$N_OFF" ]; then
+        ok "tape ($tier): arming the trace adds no N records ($N_ON armed, $N_OFF unarmed)"
+    else
+        fail "tape ($tier): N-record count changed with the trace armed" "armed=$N_ON unarmed=$N_OFF"
+    fi
+    # No trace entry is ON the tape either. Only `N` records feed replay
+    # substitution, so that is the set to inspect: read the tape back and
+    # assert no N record names the trace or carries a cause string. (`A`
+    # records legitimately hold the program's own `e` binding — the history
+    # it already READ — which is an assignment delta, not a replay source.)
+    N_LINES=$(grep '^N ' "$TAPE_ON" 2>/dev/null)
+    if ! printf '%s
+' "$N_LINES" | grep -qi 'sched_trace\|sleep-wake\|join-release'; then
+        ok "tape ($tier): no N record names the trace or a cause ($N_ON N record(s): $(printf '%s' "$N_LINES" | cut -d= -f1 | tr '
+' ' '))"
+    else
+        fail "tape ($tier): an N record carries trace payload" "$(printf '%s
+' "$N_LINES" | grep -i 'sched_trace\|sleep-wake\|join-release' | head -2 | tr '
+' ' ')"
+    fi
+    # Strict replay: a tape whose nondet stream had desynced (an extra or
+    # missing record) is fatal under EIGS_REPLAY_STRICT, not silently absorbed.
+    STRICT=$(EIGS_JIT_OFF=$JOFF EIGS_TASK_TRACE=1 EIGS_REPLAY_STRICT=1 EIGS_REPLAY="$TAPE_ON" ./eigenscript "$PROBE" </dev/null 2>&1); STRICT_RC=$?
+    if [ "$STRICT_RC" = "0" ] && [ "$STRICT" = "$REC" ]; then
+        ok "strict replay ($tier): EIGS_REPLAY_STRICT=1 reproduces the run and the trace"
+    else
+        fail "strict replay ($tier): strict mode diverged" "rc=$STRICT_RC; $(diff <(printf '%s\n' "$REC") <(printf '%s\n' "$STRICT") | head -3 | tr '\n' ' ')"
+    fi
+done
+
+echo "SCHEDTRACE: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

From d02b7d46e400904b8a5d9bd0cc28a09ae3ecb764 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 20:19:48 +0000
Subject: [PATCH 11/39] tests: resolve the [99q] section-label collision from
 integration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#1115 and #1112 were developed in parallel and both landed a suite section
labelled [99q] — #1112 had renamed its own [99y] to [99q] to avoid a collision
it could see, without seeing #1115's. tools/suite_label_check.sh caught the
result on the merged tree ("label [99q] echoed at lines 5898 and 6476"), which
is the case it exists for: neither branch could have found it alone.

#1115's [99q] is already pushed, so #1112's replay_diff crash gate moves to
[136] (the [99a]-[99z] range is full).

Also corrects a comment in [99r] that cited "[99q]'s pins" for the strict
differential's assertions. That reference was already stale at a6c50fb, where
no [99q] section existed at all; it dangled harmlessly then and would now point
at a real but unrelated section. It means [99s].

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 tests/run_all_tests.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 2c60afea..410cadfb 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -5895,7 +5895,7 @@ echo ""
 # nonzero rc (124/127) still diffs into a row. The full corpus run stays a
 # CI job, not a suite section. The case count is pinned, not ">0": a gate
 # reduced to one echo satisfies "at least one case passed".
-echo "[99q] replay_diff crash gate: a signal exit is never a boundary (#1112)"
+echo "[136] replay_diff crash gate: a signal exit is never a boundary (#1112)"
 TOTAL=$((TOTAL + 1))
 RDS_OUTPUT=$(bash "$TESTS_DIR/../tools/replay_diff.sh" --selftest 2>&1); RDS_RC=$?
 RDS_OK=$(printf '%s\n' "$RDS_OUTPUT" | grep -c "  selftest ok:" || true)
@@ -5925,7 +5925,7 @@ echo ""
 # because the distinction between a fail-soft guard and a documented ANSWER is
 # not derivable from the code — `task_alive` has one of each, four lines apart.
 # The gate proves a DECISION WAS RECORDED, nothing more; whether the decision
-# is right is what [99q]'s pins assert.
+# is right is what [99s]'s pins assert.
 echo "[99r] Fail-soft classification gate (#971)"
 TOTAL=$((TOTAL + 1))
 if bash "$TESTS_DIR/../tools/failsoft_classify_check.sh" >/dev/null && \

From 636d03ee09575ca84f206d0595b2d48a11990079 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 20:22:50 +0000
Subject: [PATCH 12/39] docs: derive the builtin counts from --api and gate
 them; tick ext_net (#1118, #1119)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#1118 — README.md and docs/BUILTINS.md both claimed "250+ builtin functions
(199 core + ~60 extensions)". Measured with `eigenscript --api` on this tree:
258 core + 87 extensions = 345. The headline was technically true and the
parenthetical was wrong on both terms.

Updating the numbers alone would not have closed it: the issue measured 253
core on v0.43.0 and this tree already reads 258, because the branch adds
builtins. A hand-maintained count in prose re-drifts on the next addition, and
nothing derived it from anything. So check 8 of tools/doc_drift_check.sh now
reads the counts out of the binary's own index and compares them to the two
prose lines — mechanical-gates §1, ask the tool rather than re-count the source.

Exact rather than a floor, deliberately: the failure this closes is
UNDERSTATEMENT, which a floor tolerates by construction. The cost is one number
in two files per builtin added, and the gate prints the numbers to use.

Validated by planting each fault it claims to catch:
  doc understates (the #1118 shape)  -> DRIFT: README.md says 345 (199 core...)
  count line deleted                 -> DRIFT: BUILTINS.md has no ... count line
  binary absent                      -> DRIFT: ... cannot run — no eigenscript binary
The third matters most: an instrument that cannot run must not report success,
which is the lesson check 2 already carries about an empty `git tag`.

#1119 — ROADMAP.md still showed raw TCP/UDP sockets unchecked in two places.
#414 shipped as ext_net in PR #788 and is closed; `--api` lists the net group.
Both boxes ticked.

Closes #1118
Closes #1119

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 README.md                |  2 +-
 ROADMAP.md               |  4 ++--
 docs/BUILTINS.md         |  2 +-
 tools/doc_drift_check.sh | 48 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 6293f26f..31287a84 100644
--- a/README.md
+++ b/README.md
@@ -511,7 +511,7 @@ Full map: **[docs/README.md](docs/README.md)**. Highlights:
 - [docs/SYNTAX.md](docs/SYNTAX.md) — tutorial-style language guide
 - [docs/GRAMMAR.md](docs/GRAMMAR.md) — formal EBNF grammar
 - [docs/LANGUAGE_CONTRACT.md](docs/LANGUAGE_CONTRACT.md) — edge-case promises
-- [docs/BUILTINS.md](docs/BUILTINS.md) — 250+ builtin functions (199 core + ~60 extensions)
+- [docs/BUILTINS.md](docs/BUILTINS.md) — 345 builtin functions (258 core + 87 extensions; `eigenscript --api` prints the live index)
 - [docs/STDLIB.md](docs/STDLIB.md) — standard library guide
 - [docs/DIAGNOSTICS.md](docs/DIAGNOSTICS.md) — error format and exit codes
 - [docs/TRACE.md](docs/TRACE.md) — execution trace, deterministic replay, temporal interrogatives
diff --git a/ROADMAP.md b/ROADMAP.md
index 20c5d5db..796409ec 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -131,7 +131,7 @@ observer/deterministic-replay niche instead of diluting it.**
 - [x] `--bundle` single-file distribution, optional attached tape =
       a self-replaying bug report — shipped 0.30.0
       ([#413](https://github.com/InauguralSystems/EigenScript/issues/413))
-- [ ] `ext_net` raw TCP/UDP sockets as tape-recorded nondet inputs —
+- [x] `ext_net` raw TCP/UDP sockets as tape-recorded nondet inputs —
       record/replay networking no incumbent stdlib has
       ([#414](https://github.com/InauguralSystems/EigenScript/issues/414))
 
@@ -248,7 +248,7 @@ when picked up:
       TLS) — **deliberately deferred** per the 2026-07 survey critic:
       vendored crypto is a solo-maintainer security liability with zero
       consumers needing AEAD; revisit when one does.
-- [ ] Raw TCP/UDP sockets — now specced as tape-recorded nondet inputs,
+- [x] Raw TCP/UDP sockets — tape-recorded nondet inputs,
       liferaft as forcing function
       ([#414](https://github.com/InauguralSystems/EigenScript/issues/414))
 - [ ] Additional DB drivers (MySQL, NoSQL; SQLite folds into the #415
diff --git a/docs/BUILTINS.md b/docs/BUILTINS.md
index b9aa176c..a8f2b8f1 100644
--- a/docs/BUILTINS.md
+++ b/docs/BUILTINS.md
@@ -1,6 +1,6 @@
 # EigenScript Builtin Reference
 
-250+ builtins organized by module (199 core + ~60 extensions).
+345 builtins organized by module (258 core + 87 extensions). `eigenscript --api` prints the live index; the counts here are gated by tools/doc_drift_check.sh.
 Core builtins are always available; extension builtins (HTTP, DB, model,
 gfx, audio) require a full build or the `gfx` target.
 
diff --git a/tools/doc_drift_check.sh b/tools/doc_drift_check.sh
index 1d230f33..1ad21432 100755
--- a/tools/doc_drift_check.sh
+++ b/tools/doc_drift_check.sh
@@ -120,4 +120,52 @@ if [ "${lexer_parse_errors:-0}" -lt 6 ]; then
     drift=1
 fi
 
+# 8. The builtin/extension counts in README.md and docs/BUILTINS.md match the
+# binary's own index. These were hand-maintained prose and drifted silently for
+# several releases (#1118: the parenthetical said "199 core + ~60 extensions"
+# while `--api` reported 253 + 87), because no check derived them from anything.
+# The authoritative source is the binary, per mechanical-gates §1 — ask the tool,
+# do not re-count the source.
+#
+# Exact, not a floor: the failure this closes is UNDERSTATEMENT, which a floor
+# tolerates by construction. The cost is that adding a builtin updates one number
+# in two files, and the gate prints the numbers to use.
+#
+# Residual: it checks the two "N core + M extensions" prose lines and nothing
+# else — a doc that states a count in different words is not covered. If the
+# binary is missing the check FAILS rather than skipping: an instrument that
+# cannot run must not report success (the same lesson as check 2's empty `git tag`).
+api_bin=""
+for cand in "src/eigenscript" "build/release/eigenscript"; do
+    [ -x "$cand" ] && { api_bin="$cand"; break; }
+done
+if [ -z "$api_bin" ]; then
+    echo "DRIFT: builtin-count check cannot run — no eigenscript binary at src/ or build/release/"
+    drift=1
+else
+    api_core=$("$api_bin" --api | awk '$1 == "builtin"' | wc -l | tr -d ' ')
+    api_ext=$("$api_bin" --api | awk '$1 == "extension"' | wc -l | tr -d ' ')
+    api_total=$((api_core + api_ext))
+    if [ "$api_core" -lt 100 ] || [ "$api_ext" -lt 10 ]; then
+        echo "DRIFT: builtin-count check read an implausible --api surface (core=$api_core ext=$api_ext) — instrument broken, not a clean tree"
+        drift=1
+    else
+        for f in README.md docs/BUILTINS.md; do
+            line=$(grep -nE '[0-9]+ (builtin functions|builtins organized by module) \([0-9]+ core \+ [0-9]+ extensions' "$f" | head -1)
+            if [ -z "$line" ]; then
+                echo "DRIFT: $(basename "$f") has no 'N core + M extensions' count line for the builtin-count gate to check"
+                drift=1
+                continue
+            fi
+            doc_total=$(printf '%s' "$line" | sed -E 's/.*[^0-9]([0-9]+) (builtin functions|builtins organized by module).*/\1/')
+            doc_core=$(printf '%s' "$line" | sed -E 's/.*\(([0-9]+) core.*/\1/')
+            doc_ext=$(printf '%s'  "$line" | sed -E 's/.*\+ ([0-9]+) extensions.*/\1/')
+            if [ "$doc_core" != "$api_core" ] || [ "$doc_ext" != "$api_ext" ] || [ "$doc_total" != "$api_total" ]; then
+                echo "DRIFT: $(basename "$f") says $doc_total ($doc_core core + $doc_ext extensions); --api says $api_total ($api_core core + $api_ext extensions)"
+                drift=1
+            fi
+        done
+    fi
+fi
+
 exit $drift

From ada2381edeb56bad4bcc02478d0bed47617cce31 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 20:59:07 +0000
Subject: [PATCH 13/39] rules: the pattern-kill ban graduates to bash_guard;
 keep only the read direction here
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

It recurred on 2026-09-07 (fifth bite): `pkill -f test_sigusr1_dump.sh` in a
compound command matched its own command line and killed the invoking shell,
so the cleanup after it never ran. This note already pre-authorised the
graduation — "Four bites in one day; if it recurs, this graduates to
bash_guard" — and the agent that lost its shell had written this very rule
into its own brief hours earlier. Prose that has been read does not prevent
the next time.

hq/hooks/bash_guard.sh now denies `pkill`/`killall` at command position and
names the PID recipe in the refusal; `pkill -P <pid>` passes. This file keeps
the READ direction (polling with a process-table match), which no hook covers,
and points at the hook for the kill direction so the two cannot drift.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 .claude/rules/test-suite.md | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/.claude/rules/test-suite.md b/.claude/rules/test-suite.md
index 7ad46e4a..651b4953 100644
--- a/.claude/rules/test-suite.md
+++ b/.claude/rules/test-suite.md
@@ -113,5 +113,15 @@ paths:
   as unverified. The KILL direction is worse: `pkill -f <pattern>` matches its
   own command line and killed the invoking shell mid-compound (exit 144,
   2026-08-23 — the commit/push/PR after it silently never ran). Kill by PID,
-  never by pattern. Four bites in one day; if it recurs, this graduates to
-  bash_guard.
+  never by pattern:
+
+      ps -eo pid,cmd | awk '/<pattern>/ && !/awk/ {print $1}' | while read p; do kill "$p"; done
+
+  **This has GRADUATED to enforcement** (2026-09-07). It recurred a fifth time —
+  the same agent that had written the rule into its own brief still reached for
+  `pkill -f` and lost its shell mid-cleanup — so `bash_guard` now denies
+  `pkill`/`killall` at command position and names the PID recipe in the refusal.
+  `pkill -P <pid>` is anchored to a known parent and passes. The prose stays
+  here for the READ direction (polling with a process-table match), which no hook
+  covers; the kill direction is the hook's now, and this note should not grow a
+  second copy of it.

From 07e15a50a7a2e3ec81d35cd18982a3671f35915c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 21:47:34 +0000
Subject: [PATCH 14/39] trace: the tape carries the observer configuration
 (#1044, #1045)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A verdict — `report of x`, the six predicates, the trajectory labels
`--step` and the DAP server print — is a function of the ASSIGNMENTS and of
the observer configuration: the three thresholds, the window depth (state
default and per-binding), and the characteristic scale. The tape carried
only the assignments, so a reader rebuilt every slot at the compiled-in
defaults and confidently printed a verdict the live run never gave.

    u is 0.0
    set_observer_window of ["u", 50]
    t is 0
    loop while t < 200:
        u is 272.4 + 10.0 * (cos of (6.283185307179586 * t / 46.9))
        t is t + 1
    print of ("live u=" + (report of u))

    before: live u=oscillating   /  --step `t u`: #201 line 5 ... [diverging]
    after:  live u=oscillating   /  --step `t u`: #201 line 5 ... [oscillating]

The class is older than #1044: the same program with
`set_observer_thresholds of [0.01, 0.02, 0.1]` diverges on the v0.43.0
release binary (live `converged`, stepped `stable`) and agrees here.

Design (a) of the two the brief weighed: each knob is recorded AS AN EVENT
at the point it takes effect, so a mid-run change replays in the right
order — a binding that reads `moving` before a `set_observer_scale` and
`converged` after reads exactly that at both stops. A header/snapshot stamp
would have had to refuse that program.

  * `O cfg <dh_zero> <dh_small> <h_low> <window> <scale>` — the five
    state-level scalars, emitted BY DIFF rather than from the knob builtins:
    the writer compares the state's live configuration against what the tape
    last said, immediately before the next `L`/`A` record. The tape therefore
    carries the configuration in force by construction — one set by an
    embedder, by a second `EigsState`, or by a knob nobody remembered to
    instrument still lands on it. A knobless program writes no `O` records.
  * `O win <name> <n>` — the per-binding window override, which lives on an
    `Env` slot and so has no cheap diff; written from `set_observer_window`,
    preceded by its own frame's `S` record.
  * `tape_read.c` is the one reader (`--step` and `eigsdap` share it): it
    installs the defaults, applies every `O` record preceding the assign it
    is folding, and restores the caller's configuration at the end, so a
    reader never leaks a tape's knobs into its own state.

THE CONFIGURATION IS FOLDED TO THE STOP, NOT TO THE LAST ASSIGN. The knobs
split by when the runtime consumes them: the window and the scale are read
while a value is being RECORDED, the three thresholds (and the window again,
for the full-window certifications) while a verdict is being REPORTED. So a
knob moved after a binding's last assign and before the stop still changes
what `report of x` says there, and a fold that stopped at the last assign
dropped exactly those — the first cut of this change printed

    x is 1000.0 / d is 5.0 / loop 30x: x is x + d ; d is d * 0.99
    set_observer_thresholds of [0.01, 0.02, 0.1]
    print of ("x=" + (report of x))          # live: converged

    --step `p x`: 1130.1498133058592  [stable]     <- record on the tape,
                                                      in force, and skipped

for a nine-line program, on both the stepper and the DAP. `tape_traj_settle`
carries the cursor on to the stop position and re-reads the label, so `p`
and the DAP binding cell answer "what would `report of x` say HERE". The
`t` trajectory rows stay per-moment — a row is the label after THAT assign —
so when the settled label differs it gets a line of its own ("observer
configuration changed after the last assign — at this stop: [converged]"),
and the DAP the same as a `#now` row: the reader never lets a stale row
stand in for the present, and never relabels history either.

A CORRUPT `O` RECORD IS REFUSED, NOT INSTALLED. The reader puts these values
into its own observer state, so `O cfg ... 0 ...` divided by zero sizing the
value ring (SIGFPE) and a negative or 4e9 window asked calloc for 2^64-1
bytes (abort) — a new crash class on a data file that #413 attached-tape
bundles ship. Every field is now checked at parse time against exactly the
invariants the live builtins enforce (obs_window_arg,
builtin_set_observer_scale, builtin_set_observer_thresholds) and a record
outside them refuses the tape with exit 3, like a torn bundle archive.
Clamping was considered and rejected: a clamped window is a configuration
the recording run never had, so the label would still be a confident lie,
just a different one.

An `O win` record names a BINDING, not a name. `tape_traj_begin` takes the
`NameHist` being folded and the record is applied only when it RESOLVES to
that history (identity, not `strcmp` on the name), because one name is
routinely several bindings on one tape: two invocations of a function are
two frame instances, and a function-local shares a name with a module-level
global. Matching by name made `--step` print `oscillating` for the binding
whose live run said `diverging` — the same fail-soft shape the records exist
to remove, in the opposite direction. The writer half matters equally: the
scope transition is stamped before the `O win` record, so an override set on
a parameter before the frame has assigned anything carries its own frame's
scope and not its caller's.

Census (writes to the observer configuration on `EigsState`, grep for
`obs_dh_zero|dh_small|h_low|window|scale|win_override`): the three
`set_observer_thresholds` scalars, `set_observer_window`'s two forms,
`set_observer_scale`, the `state.c` defaults, and `observer_slot_set_window`
(one caller, `builtins.c`). All are carried. No embed-API setter exists;
if one is added, the `O cfg` diff carries it with no further work — that is
why the state scalars are emitted by diff and not from the builtins.

TRACE_FORMAT_VERSION 2 -> 3. The #411 rule applies unchanged: a v2 tape is
refused loudly by both `--step` and `EIGS_REPLAY` with exit 3 rather than
silently classified at the defaults, which is the deliberate answer to
"an old tape should still step" — a v2 tape cannot carry the knobs, so
stepping it would print exactly the wrong verdict this change removes.
`tests/fixtures/tape_v2_baseline.tape` is a REAL tape recorded by the
v0.43.0 release binary and the fixture requires the exit-3 refusal from both
surfaces.

Regression: `tests/test_tape_observer_config.sh`, suite section [42f2], 66
checks. Every case asserts that the label `--step` prints equals the label
the live run printed AND names the label it expects, so a change making both
sides equally wrong is caught; `O`-stripped copies of the same tapes are the
built-in discrimination control. Section 8 is the cross-scope set; section 9
is the post-assign set (thresholds, per-binding window, state window), each
asserted BOTH at the last stop and at a stop before the knob call so a
reader that applies every record regardless of position fails too; section
10 is the corrupt-record set. `tests/test_dap.py` gains the same assertion
on the DAP surface (binding cell + `#now` row), 35 checks.

Planted faults, each rebuilt and run:
  * settle removed (fold stops at the last assign) ->
      FAIL postthr/postwin/postdef: --step at the last stop agrees with the
        live run (live=converged step=stable, and both inversions)
      FAIL the t view names the settled label
      DAP: 2 red (binding cell, `#now` row)
  * invalid `O` record installed instead of refused ->
      FAIL corrupt O record refused with exit 3: window 0 (rc=136)
      FAIL ... window -5 / 4000000000 (rc=134, 18446744073709551615 bytes)
      + 4 more (scale 0, dh_zero >= dh_small, per-binding 0 and 999)
  * reader stops applying `O` records -> 8 red, every one the class itself
  * reader matches by NAME instead of binding identity -> exactly the two
    cross-scope cases red (xsleak, xsouter)
  * writer drops the per-binding record / the scope stamp -> 5 and 2 red

Residual: the reader walks the recorded CALL chain, so an override set on a
name a closure captured (its env parent is its definition site) may resolve
to nothing. It is then applied only if that name is unique on the whole
tape, and otherwise dropped — the stepped verdict is the default-window one,
never another binding's. Losing a knob shows a different label; applying it
to the wrong binding shows a confident wrong one, and only the second is the
shape this design refuses. Written down in docs/TRACE.md and docs/PREDICATES.md.

Follow-up to #1044/#1045: the tape carries the observer configuration

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 docs/DEBUGGING.md                    |   9 +-
 docs/PREDICATES.md                   |  36 ++
 docs/TRACE.md                        | 141 ++++++-
 src/builtins.c                       |   5 +
 src/eigenscript.h                    |   8 +
 src/eigsdap.c                        |  37 +-
 src/state.c                          |  10 +-
 src/step.c                           |  40 +-
 src/tape_read.c                      | 258 +++++++++++-
 src/tape_read.h                      |  67 +++-
 src/trace.c                          | 119 +++++-
 src/trace.h                          |   9 +-
 tests/fixtures/tape_v2_baseline.eigs |   9 +
 tests/fixtures/tape_v2_baseline.tape | 224 +++++++++++
 tests/run_all_tests.sh               |  21 +
 tests/test_dap.py                    |  85 +++-
 tests/test_tape_observer_config.sh   | 563 +++++++++++++++++++++++++++
 17 files changed, 1575 insertions(+), 66 deletions(-)
 create mode 100644 tests/fixtures/tape_v2_baseline.eigs
 create mode 100644 tests/fixtures/tape_v2_baseline.tape
 create mode 100755 tests/test_tape_observer_config.sh

diff --git a/docs/DEBUGGING.md b/docs/DEBUGGING.md
index af067062..f2ce9f5b 100644
--- a/docs/DEBUGGING.md
+++ b/docs/DEBUGGING.md
@@ -86,8 +86,13 @@ one row per assignment with the running label.
 Labels come from feeding the reconstructed numeric history through the
 same `ObserverSlot` machinery the language uses at runtime, so the
 stepper's `[converged]` is *by construction* what `report_value of x`
-would have said at that moment. Non-numeric bindings show their value
-with no label.
+would have said at that moment — under the observer configuration the tape
+recorded as being in force there, not the compiled-in defaults (the `O`
+records, [TRACE.md](TRACE.md#observer-configuration-1044-1045)). A knob moved
+after a binding's last assignment still counts: `p` answers "what would
+`report of x` say *here*", and `t`'s per-assignment rows name the settled
+label on a line of their own when it differs. Non-numeric bindings show their
+value with no label.
 
 ### Scope and honesty
 
diff --git a/docs/PREDICATES.md b/docs/PREDICATES.md
index 24d3d8fb..43819fea 100644
--- a/docs/PREDICATES.md
+++ b/docs/PREDICATES.md
@@ -263,6 +263,42 @@ first sample — the default depth allocates exactly what it did before
 #1044 — and the folding/variance tests are `O(N)` per verdict asked, not
 per assignment.
 
+## Configuration and the tape
+
+Every knob on this page — the three thresholds, the window depth in both
+its forms, and the scale — **rides the trace tape**, so a recorded run
+replayed or stepped classifies exactly as the live run did. It is carried
+as an event at the point the knob takes effect (`O cfg` / `O win` records,
+tape format v3), which is what makes a **mid-run** change reconstruct
+correctly: a binding that reads `moving` before a `set_observer_scale` and
+`converged` after reads exactly that at both stops under `--step` and in
+the DAP server. `EIGS_REPLAY` re-executes the program, so its knob calls
+run again by themselves.
+
+The reader folds the configuration up to the **stop position**, not up to the
+binding's last assignment, because the thresholds (and the window's
+full-window certifications) are consumed when a verdict is *reported*: a knob
+moved after the last assignment and before the stop changes the live verdict
+and therefore changes the stepped one too. The stepper's `p` view and the DAP
+binding cell answer "what would `report of x` say here"; the `t` trajectory
+rows stay per-moment, and name the settled label on a line of their own when
+it differs.
+
+A per-binding `O win` record names one **binding**, not a name: the reader
+resolves it along the recorded call chain and applies it to that history by
+identity, so two invocations of one function — or a function-local and a
+module-level global sharing a name — keep their own window depths.
+
+Two caveats remain, both narrow, both stated rather than papered over. (1) A
+binding the recorded call chain cannot reach — a closure over a captured
+name, whose environment parent is its definition site — resolves to nothing;
+the override is then applied only if that name is unique on the whole tape,
+and otherwise dropped, so the stepped verdict is the default-window one and
+never another binding's. (2) A tape recorded by a pre-v3 binary cannot carry
+any of this, so it is refused outright (exit 3), never classified at the
+defaults and presented as the recorded run. Both are written up in
+[TRACE.md](TRACE.md#observer-configuration-1044-1045).
+
 ## Partial-window rule (applies to all six)
 
 If the window does not yet hold enough samples, **every predicate returns
diff --git a/docs/TRACE.md b/docs/TRACE.md
index 844f2fed..a99057be 100644
--- a/docs/TRACE.md
+++ b/docs/TRACE.md
@@ -23,15 +23,17 @@ predicted-not-taken load + branch.
 
 ## Tape Format
 
-The tape is plain text, one record per line, five record kinds:
+The tape is plain text, one record per line, six record kinds:
 
 | Record | Meaning |
 |--------|---------|
-| `V <format> <runtime>` | Version header — always the first record (e.g. `V 2 0.29.0`). Stamped once per tape-open; a journal appended across sessions carries one per session. See [Format Versioning](#format-versioning-411). |
+| `V <format> <runtime>` | Version header — always the first record (e.g. `V 3 0.43.0`). Stamped once per tape-open; a journal appended across sessions carries one per session. See [Format Versioning](#format-versioning-411). |
 | `L <line>` | Source-line event (from `OP_LINE`). Adjacent duplicate lines with no `A`/`N` between them are deduped — the compiler emits per-statement LINEs and bare repeats are noise. |
 | `S <fn> <depth> <serial>` | Scope transition (#539 v2): the `A` records that follow belong to this frame instance — `<fn>` is the chunk name (`<module>`, `<lambda>`, or the function name), `<depth>` the 0-based frame depth, `<serial>` a per-thread monotonically increasing frame-instance id stamped at frame push. Emitted lazily with the same dedup discipline as `L`: only when the frame owning the next assignment differs from the last `S`, so the byte cost lands at call boundaries that actually assign. Two invocations of the same function carry different serials — their local streams never merge. Skipped on replay; folded by `--step`. |
 | `A <name>=<value>` | Assignment delta: a binding changed. Fires at **every scope** — function locals included — and is scope-qualified by the preceding `S` record, so a function-local `i` and the top-level `i` are separate streams (`--step` resolves names innermost-first along the reconstructed call chain, with shadowing). |
 | `N <fn>=<value>` | Nondeterministic builtin return — the replay-determinism substrate. |
+| `O cfg <dh_zero> <dh_small> <h_low> <window> <scale>` | Observer configuration in force (v3). Written whenever the state's observer knobs differ from what the tape last said, immediately before the next `L`/`A` record. See [Observer Configuration](#observer-configuration-1044-1045). |
+| `O win <name> <n>` | Per-binding observer window override (v3) — `set_observer_window of ["name", n]`; `n == 0` clears it. |
 
 ### Value serialization
 
@@ -147,6 +149,124 @@ its return in the same macro. A builtin that *builds* its return value
 short-circuits under replay before the value is built, so the live
 construction is neither run nor leaked.
 
+## Observer Configuration (#1044/#1045)
+
+A trajectory verdict — `report of x`, the six predicates, the trajectory
+labels `--step` and the DAP server print — is a function of the
+**assignments** and of the **observer configuration**: three thresholds
+(`set_observer_thresholds`), the window depth (`set_observer_window`, per
+state and per binding), and the characteristic scale
+(`set_observer_scale`). The tape carried the assignments and not the
+configuration, so a recorded run stepped back classified at the *state
+defaults* and printed a verdict the live run never gave:
+
+```
+u is 0.0
+set_observer_window of ["u", 50]        # a 46.9-sample period needs 50
+loop while t < 200:  u is 272.4 + 10.0 * (cos of (6.28318 * t / 46.9)) …
+print of (report of u)                  # live: oscillating
+```
+```
+$ eigenscript --step u.tape u.eigs      # before: [diverging]  ← never happened
+```
+
+A debugger that confidently prints the wrong verdict is exactly the
+fail-soft shape this language refuses, so the configuration rides the tape:
+
+- **`O cfg`** carries the five state-level scalars. It is emitted **by
+  diff**, not from the knob builtins: the writer compares the state's live
+  configuration against what the tape last said and emits a record when they
+  differ, immediately before the next `L` or `A` record. So the tape carries
+  the configuration *in force* by construction — one set by an embedder
+  before the run, by a second `EigsState`, or by a knob nobody remembered to
+  instrument still lands on the tape. A program that never moves a knob
+  writes no `O` records at all.
+- **`O win`** carries the per-binding window override, which lives on an
+  `Env` slot rather than on the state and so has no cheap diff. It is
+  written from `set_observer_window` at the point of the call, preceded by
+  its own frame's `S` record — the override belongs to the frame that
+  *resolved the name*, and that frame may not have assigned anything yet
+  (widening a parameter's window before the body writes it), so the scope
+  transition cannot be left to the next `A` record.
+- Both are recorded **as events, in place**, not stamped into the header.
+  That is the whole point: a program that changes a knob **mid-run** — one
+  phase `moving`, the next `converged` — steps back correctly at both
+  stops, which a header snapshot could only have refused.
+- `tape_read.c` is the one reader (`--step` and the DAP server share it):
+  it installs the compiled-in defaults, then applies every `O` record that
+  precedes the assign it is folding, and restores the caller's own
+  configuration when the fold ends. A reader never leaks a tape's knobs
+  into its own state.
+- **The configuration is folded to the STOP, not to the last assign.** The
+  knobs split by when the runtime consumes them: the window and the scale are
+  read while a value is being *recorded*, the three thresholds (and the window
+  again, for the full-window certifications) while a verdict is being
+  *reported*. So a knob moved after a binding's last assign and before the
+  stop still changes what `report of x` says there — and folding only up to
+  the last assign printed `stable` where the live run printed `converged`:
+
+  ```
+  x is 1000.0 / d is 5.0 … loop 30x: x is x + d ; d is d * 0.99
+  set_observer_thresholds of [0.01, 0.02, 0.1]
+  print of (report of x)                    # live: converged
+  ```
+  ```
+  $ eigenscript --step after.tape after.eigs      # `p x`
+  x = 1130.1498133058592  [stable]     ← before: the record was on the tape,
+                                          in force at the stop, and skipped
+  ```
+
+  `tape_traj_settle` walks the configuration cursor on to the stop position
+  and re-reads the label, so `p`/the DAP binding cell answer "what would
+  `report of x` say **here**". The `t` view's rows stay per-moment by
+  construction — a row is the label after *that* assign — so when the settled
+  label differs, it gets a line of its own ("observer configuration changed
+  after the last assign — at this stop: [converged]") rather than letting the
+  last row speak for the present; the DAP shows the same as a `#now` row.
+- **A corrupt `O` record is refused, not installed.** The reader puts these
+  values into its own observer state, so `O cfg … 0 …` divides by zero sizing
+  the value ring and a negative or 4e9 window asks `calloc` for 2^64−1 bytes.
+  Every field is therefore checked at parse time against exactly the
+  invariants the live builtins enforce — window in `[4, 64]` (plus the `O win
+  <name> 0` clear form), positive thresholds with `dh_zero < dh_small`,
+  positive finite scale — and a record
+  outside them refuses the tape with exit 3 (`tape observer-configuration
+  record is not one this runtime could have written …`). Tapes travel in #413
+  attached-tape bundles, so this is the torn-archive rule applied to the
+  configuration. Clamping was rejected: a clamped window is a configuration
+  the recording run never had, so the label would still be a confident lie,
+  just a different one.
+
+**Replay is unaffected**, and deliberately so: `EIGS_REPLAY` re-executes the
+program, so the program's own knob calls run again in the same order. The
+`O` records are for readers that reconstruct state *without* executing —
+the stepper, the DAP server, and anything else that folds `A` records into
+an `ObserverSlot`.
+
+**`O win` names a BINDING, not a name.** The live call resolved the binding
+innermost-first from its own frame; the reader resolves it the same way from
+the frame instance the record was written in (the tape's `S` records give the
+chain) and applies the override to that history **by identity** — never by
+name equality. This matters because one name is routinely several bindings on
+one tape: two invocations of a function are two frame instances, and a
+function-local can share a name with a module-level global. Matching by name
+made `--step` print `oscillating` for a binding whose live run said
+`diverging`, which is the same fail-soft shape the `O` records exist to
+remove. `tests/test_tape_observer_config.sh` section 8 pins all four shapes
+(leak forward, correct application, a parameter widened before its frame
+assigns, and a module-level binding assigned after the call).
+
+**Residual — a name the call chain cannot reach.** The reader walks the
+frame's `S`-record parents, which is the *call* chain; a closure's
+environment parent is its definition site instead, so an override set on a
+captured name may resolve to nothing. When it does, the reader applies the
+record only if exactly one history on the whole tape carries that name (then
+it can only mean that binding); otherwise it drops the override, and the
+stepped verdict is the default-window one. It never sprays the override
+across same-named bindings — losing a knob shows a *different* label than the
+live run, applying it to the wrong binding shows a *confident wrong* one, and
+only the second is the shape this design refuses to ship.
+
 ## Non-Replayable Builtins (issue #148)
 
 Some nondet builtins are *not* wrapped, and **fail loudly** when
@@ -265,6 +385,14 @@ everywhere else in the runtime (version-and-reject, never migrate).
 - Every tape's first record is `V <format> <runtime>`. The format integer
   (`TRACE_FORMAT_VERSION` in `src/trace.h`) bumps on **any** change to the
   tape encoding; the runtime string is the recording binary's version.
+  History: **v2** (#539) added the scope-transition `S` records; **v3**
+  (#1044/#1045 follow-up) added the observer-configuration `O` records.
+  A v2 tape cannot say what its knobs were — the calls simply are not on it
+  — so the compat decision for the bump is the standing one, and it is the
+  loud half: a v2 tape is **refused** by `--step`, by the DAP server and by
+  `EIGS_REPLAY` with exit 3, never classified at the defaults and presented
+  as the recorded run. Coverage: the `v2 (pre-O-record) tape is refused`
+  cases in `tests/test_tape_observer_config.sh`.
 - On replay, a missing header, a malformed (torn) header, a different
   format version, a different runtime version, an empty tape, or an
   unopenable `EIGS_REPLAY` path each refuse loudly — hosted replay exits
@@ -298,7 +426,14 @@ boundaries are enforced; dev builds are on their honor.
 
 Regression coverage: the `version refuse` cases in `tests/test_replay.sh`
 plant each mismatch class (format, runtime, missing header, empty file)
-and require the exit-3 refusal.
+and require the exit-3 refusal. `tests/test_tape_observer_config.sh`
+additionally carries a REAL pre-v3 tape — `tests/fixtures/tape_v2_baseline.tape`,
+recorded by the v0.43.0 release binary — and requires the same exit-3 refusal
+from both `--step` and `EIGS_REPLAY`. That refusal is the deliberate answer to
+"an old tape should still step": a v2 tape carries no `O` records, so stepping
+it would classify at the defaults and print a verdict the recorded run never
+gave. The knobs are exactly what the format bump exists for, so a tape that
+predates them is re-recorded, not reinterpreted.
 
 ## Temporal Interrogatives and `state_at`
 
diff --git a/src/builtins.c b/src/builtins.c
index 16d3bcd6..2c34373e 100644
--- a/src/builtins.c
+++ b/src/builtins.c
@@ -700,6 +700,11 @@ Value* builtin_set_observer_window(Value *arg) {
             rt_error(EK_LIMIT, 0, "set_observer_window: observer slot table full");
             return make_null();
         }
+        /* The override lives on an Env slot, so the tape writer's
+         * state-configuration diff cannot see it — record it explicitly, or a
+         * stepped tape classifies this binding at the default depth and
+         * prints a verdict the live run never gave (docs/TRACE.md). */
+        trace_obs_window_binding(name, n);
         return make_null();
     }
     int n = obs_window_arg(arg, "set_observer_window");
diff --git a/src/eigenscript.h b/src/eigenscript.h
index df7d9eb1..0e8adbd9 100644
--- a/src/eigenscript.h
+++ b/src/eigenscript.h
@@ -377,6 +377,14 @@ struct Value {
  * samples per half-window (4), and the ring counters are 8-bit. */
 #define OBSERVER_WINDOW_MIN 4
 #define OBSERVER_WINDOW_MAX 64
+/* Start-of-state values of the four scalar observer knobs. Named because the
+ * tape reader has to install exactly this configuration before replaying the
+ * tape's `O` records (docs/TRACE.md) — a second hand-written copy of the
+ * numbers in tape_read.c would be a silent divergence waiting to happen. */
+#define OBSERVER_DH_ZERO_DEFAULT  0.001
+#define OBSERVER_DH_SMALL_DEFAULT 0.01
+#define OBSERVER_H_LOW_DEFAULT    0.1
+#define OBSERVER_SCALE_DEFAULT    0.001
 /* Effective window depth of a slot (see the ObserverSlot comment). */
 int observer_slot_window(const struct ObserverSlot *s);
 /* Set / clear a binding's per-slot override (n == 0 clears). Grows the env's
diff --git a/src/eigsdap.c b/src/eigsdap.c
index e7697def..99db8612 100644
--- a/src/eigsdap.c
+++ b/src/eigsdap.c
@@ -238,7 +238,7 @@ static void append_binding_value(strbuf *sb, const NameHist *h) {
     strbuf sv;
     strbuf_init(&sv);
     strbuf_append(&sv, last ? last->value : "?");
-    const char *label = tape_classify_at(h, g_pos, NULL);
+    const char *label = tape_classify_at(&g_tape, h, g_pos, NULL);
     if (label) strbuf_append_fmt(&sv, "  [%s]", label);
     json_escape_to(sb, sv.data ? sv.data : "");
     strbuf_free(&sv);
@@ -297,14 +297,15 @@ static void handle_variables(int rseq, const char *msg) {
         int idx = ref - VR_TRAJ;
         if (idx >= 0 && idx < g_tape.nnames) {
             const NameHist *h = &g_tape.names[idx];
-            ObserverSlot s;
-            memset(&s, 0, sizeof s);
+            /* #1044/#1045 follow-up: the shared feeder installs the tape's
+             * recorded observer configuration, so the DAP's trajectory labels
+             * match the live run's and the stepper's. */
+            TapeTraj tr;
+            const char *last_label = NULL;
+            tape_traj_begin(&tr, &g_tape, h);
             for (int i = 0; i < h->n && h->a[i].step <= g_pos; i++) {
-                const char *label = NULL;
-                if (h->a[i].is_num) {
-                    observer_slot_record_value(&s, h->a[i].num);
-                    label = observer_slot_report_value(&s);
-                }
+                const char *label = tape_traj_feed(&tr, &h->a[i]);
+                if (label) last_label = label;
                 if (n) strbuf_append_char(&sb, ',');
                 strbuf_append_fmt(&sb, "{\"name\":\"#%d\",\"value\":", n + 1);
                 strbuf sv;
@@ -318,9 +319,23 @@ static void handle_variables(int rseq, const char *msg) {
                 strbuf_append(&sb, ",\"variablesReference\":0}");
                 n++;
             }
-            free(s.v_window);
-            free(s.vr_window);
-            free(s.dh_window);
+            /* Same rule as the stepper's `t` view: the rows are per-moment,
+             * so a knob moved after the last assign gets its own row rather
+             * than silently leaving the last one to speak for the stop. */
+            const char *now = tape_traj_settle(&tr, g_pos);
+            if (now && last_label && strcmp(now, last_label) != 0) {
+                if (n) strbuf_append_char(&sb, ',');
+                strbuf_append(&sb, "{\"name\":\"#now\",\"value\":");
+                strbuf sv;
+                strbuf_init(&sv);
+                strbuf_append_fmt(&sv, "observer configuration changed after "
+                                  "the last assign — at this stop: [%s]", now);
+                json_escape_to(&sb, sv.data);
+                strbuf_free(&sv);
+                strbuf_append(&sb, ",\"variablesReference\":0}");
+                n++;
+            }
+            tape_traj_end(&tr);
         }
     } else if (ref >= VR_LOCALS) {
         uint32_t serial = frame_id_to_serial(ref - VR_LOCALS);
diff --git a/src/state.c b/src/state.c
index 39fd44c7..be79d091 100644
--- a/src/state.c
+++ b/src/state.c
@@ -35,11 +35,11 @@ EigsState *eigs_state_new(void) {
     st->obs_needed = 1;
     st->obs_compile_pending = 1;
     /* Observer thresholds — same defaults as the legacy TLS globals. */
-    st->obs_dh_zero  = 0.001;
-    st->obs_dh_small = 0.01;
-    st->obs_h_low    = 0.1;
-    st->obs_window   = OBSERVER_WINDOW_N;   /* #1044 */
-    st->obs_scale    = 0.001;               /* #1045 */
+    st->obs_dh_zero  = OBSERVER_DH_ZERO_DEFAULT;
+    st->obs_dh_small = OBSERVER_DH_SMALL_DEFAULT;
+    st->obs_h_low    = OBSERVER_H_LOW_DEFAULT;
+    st->obs_window   = OBSERVER_WINDOW_N;        /* #1044 */
+    st->obs_scale    = OBSERVER_SCALE_DEFAULT;   /* #1045 */
     /* #971: strict math mode, read once from env at creation (like the JIT
      * thresholds below). Any non-empty, non-"0" value enables it. */
     st->strict = eigs_env_flag("EIGS_STRICT");
diff --git a/src/step.c b/src/step.c
index 1dfd8c73..8aed0335 100644
--- a/src/step.c
+++ b/src/step.c
@@ -46,12 +46,12 @@ static void show_stop(const Tape *t, int pos) {
     }
 }
 
-static void print_binding(int pos, const NameHist *h,
+static void print_binding(const Tape *t, int pos, const NameHist *h,
                           const char *scope_note) {
     const Assign *last = tape_latest_at(h, pos);
     int count = 0;
     for (int k = 0; k < h->n && h->a[k].step <= pos; k++) count++;
-    const char *label = tape_classify_at(h, pos, NULL);
+    const char *label = tape_classify_at(t, h, pos, NULL);
     printf("%s = %s", h->name, last->value);
     if (label) printf("  [%s]", label);
     printf("  (%d assign%s)", count, count == 1 ? "" : "s");
@@ -72,7 +72,7 @@ static void show_bindings(const Tape *t, int pos, const char *only) {
             char note[160] = "";
             if (si && si->depth > 0)
                 snprintf(note, sizeof note, "in %s", si->name);
-            print_binding(pos, h, note[0] ? note : NULL);
+            print_binding(t, pos, h, note[0] ? note : NULL);
             shown = 1;
         }
         if (!shown) printf("no binding '%s' at this point\n", only);
@@ -100,7 +100,7 @@ static void show_bindings(const Tape *t, int pos, const char *only) {
             if (shadowed) continue;
             if (nseen < (int)(sizeof(seen)/sizeof(seen[0])))
                 seen[nseen++] = h->name;
-            print_binding(pos, h, note[0] ? note : NULL);
+            print_binding(t, pos, h, note[0] ? note : NULL);
             shown++;
         }
         if (sc == 0) break;
@@ -123,31 +123,33 @@ static void show_trajectory(const Tape *t, int pos, const char *name) {
     int total = 0;
     for (int i = 0; i < h->n && h->a[i].step <= pos; i++) total++;
     printf("%s: %d assign%s\n", name, total, total == 1 ? "" : "s");
-    /* One slot fed incrementally: the label after the k-th numeric value
-     * is exactly what report_value would have said at that moment. */
-    ObserverSlot s;
-    memset(&s, 0, sizeof s);
-    int fed = 0;
+    /* One slot fed incrementally under the tape's recorded observer
+     * configuration: the label after the k-th numeric value is exactly what
+     * report_value would have said at that moment in the live run. */
+    TapeTraj tr;
+    tape_traj_begin(&tr, t, h);
     const int SHOW = 20;   /* print at most the last SHOW entries */
     int start = total > SHOW ? total - SHOW : 0;
     if (start > 0) printf("  … %d earlier assign(s) elided\n", start);
+    const char *last = NULL;
     for (int i = 0, k = 0; i < h->n && h->a[i].step <= pos; i++, k++) {
-        const char *label = NULL;
-        if (h->a[i].is_num) {
-            observer_slot_record_value(&s, h->a[i].num);
-            fed++;
-            label = observer_slot_report_value(&s);
-        }
+        const char *label = tape_traj_feed(&tr, &h->a[i]);
+        if (label) last = label;
         if (k < start) continue;
         printf("  #%-3d line %-5d %s", k + 1,
                t->recs[t->steps[h->a[i].step]].line, h->a[i].value);
         if (label) printf("   [%s]", label);
         printf("\n");
     }
-    free(s.v_window);
-    free(s.vr_window);
-    free(s.dh_window);
-    (void)fed;
+    /* Each row is the label at THAT moment. A knob moved after the last
+     * assign changes what the verdict is HERE without adding a row, so say
+     * so rather than letting the last row stand in for the present — the
+     * `p` view and the DAP already report the settled label. */
+    const char *now = tape_traj_settle(&tr, pos);
+    if (now && last && strcmp(now, last) != 0)
+        printf("  observer configuration changed after the last assign — "
+               "at this stop: [%s]\n", now);
+    tape_traj_end(&tr);
 }
 
 static void show_help(void) {
diff --git a/src/tape_read.c b/src/tape_read.c
index df69f790..f5a80152 100644
--- a/src/tape_read.c
+++ b/src/tape_read.c
@@ -70,6 +70,18 @@ static int hist_push(NameHist *h, Assign a) {
     return 1;
 }
 
+static int obscfg_push(Tape *t, const ObsCfgRec *o) {
+    if (t->nobscfg == t->obscfgcap) {
+        int nc = t->obscfgcap ? t->obscfgcap * 2 : 8;
+        ObsCfgRec *nn = realloc(t->obscfg, (size_t)nc * sizeof(ObsCfgRec));
+        if (!nn) return 0;
+        t->obscfg = nn;
+        t->obscfgcap = nc;
+    }
+    t->obscfg[t->nobscfg++] = *o;
+    return 1;
+}
+
 /* Scope-instance table + reconstruction stack (parse time). On
  * S(fn, depth, serial): if the serial is already on the stack we are
  * RETURNING into that frame — pop to it. Otherwise this is a new frame
@@ -134,6 +146,48 @@ static int vline_ok(const char *p) {
     return 1;
 }
 
+/* An `O` record is a CONFIGURATION the reader installs into its own state
+ * before it classifies, so every field has to satisfy exactly the invariants
+ * the live builtins enforce (obs_window_arg, builtin_set_observer_scale,
+ * builtin_set_observer_thresholds). A tape that says `window 0` is not a tape
+ * this runtime wrote: installing it divides by zero inside the ring-buffer
+ * sizing (`cnt % n`), and a negative or 4e9 window asks calloc for
+ * 18446744073709551615 bytes. Tapes travel — #413 attached-tape bundles ship
+ * them beside the program — so a corrupt one is refused loudly here, exactly
+ * like a torn bundle archive, and never partially applied: a half-installed
+ * configuration would print a verdict no live run gave, which is the failure
+ * class these records exist to remove.
+ *
+ * Refusal, not clamping: a clamped window is a configuration the recording
+ * run never had, so the label would still be a confident lie — just a
+ * different one. */
+static int obs_cfg_refuse(const char *why, const char *line) {
+    fprintf(stderr, "step: tape observer-configuration record is not one this "
+            "runtime could have written (%s): '%s'; refusing to step "
+            "(docs/TRACE.md)\n", why, line);
+    return 0;
+}
+
+static int obs_cfg_rec_ok(const ObsCfgRec *o, const char *line) {
+    const char *why = NULL;
+    /* `O win <name> 0` is the CLEAR form of the per-binding override and the
+     * one legal window outside the range (set_observer_window takes it the
+     * same way); the state default has no clear form. */
+    if ((o->window != 0 || o->binding == 0) &&
+        (o->window < OBSERVER_WINDOW_MIN || o->window > OBSERVER_WINDOW_MAX))
+        why = "window depth outside its [4, 64] range";
+    else if (o->binding == 0) {
+        if (!(o->dh_zero > 0.0) || !(o->dh_small > 0.0) || !(o->h_low > 0.0))
+            why = "thresholds must be positive";
+        else if (!(o->dh_zero < o->dh_small))
+            why = "dh_zero must be less than dh_small";
+        else if (!(o->scale > 0.0) || !(o->scale <= 1e300))
+            why = "scale must be positive and finite";
+    }
+    if (!why) return 1;
+    return obs_cfg_refuse(why, line);
+}
+
 /* Parse the NUL-split tape buffer into recs/steps/name histories.
  * Returns 0 on version refusal, 1 otherwise. */
 static int tape_parse(Tape *t, long len) {
@@ -194,6 +248,44 @@ static int tape_parse(Tape *t, long len) {
                 }
                 break;
             }
+            case 'O': {   /* observer configuration (v3) — folded like S: it
+                           * is not a stop event, it governs the records that
+                           * FOLLOW it, so its `rec` is the next stored index */
+                ObsCfgRec o;
+                memset(&o, 0, sizeof o);
+                o.rec = t->nrecs;
+                o.scope = cur_scope;
+                if (strncmp(p + 2, "cfg ", 4) == 0) {
+                    char *q = p + 6, *q0;
+                    int ok = 1;
+                    o.binding  = 0;
+                    q0 = q; o.dh_zero  = strtod(q, &q);        ok &= (q != q0);
+                    q0 = q; o.dh_small = strtod(q, &q);        ok &= (q != q0);
+                    q0 = q; o.h_low    = strtod(q, &q);        ok &= (q != q0);
+                    q0 = q; o.window   = (int)strtol(q, &q, 10); ok &= (q != q0);
+                    q0 = q; o.scale    = strtod(q, &q);        ok &= (q != q0);
+                    if (!ok) return obs_cfg_refuse("truncated record", p);
+                    if (!obs_cfg_rec_ok(&o, p)) return 0;
+                    obscfg_push(t, &o);
+                } else if (strncmp(p + 2, "win ", 4) == 0) {
+                    char *nm = p + 6;
+                    char *sp = strchr(nm, ' ');
+                    if (sp) {
+                        char *q = sp + 1, *q0 = q;
+                        o.binding = 1;
+                        o.window  = (int)strtol(q, &q, 10);
+                        /* validated before the name is NUL-terminated in
+                         * place, so the refusal can quote the whole line */
+                        if (q == q0) return obs_cfg_refuse("truncated record", p);
+                        if (!obs_cfg_rec_ok(&o, p)) return 0;
+                        *sp = '\0';
+                        o.name = nm;
+                        obscfg_push(t, &o);
+                    }
+                }
+                r.kind = 0;
+                break;
+            }
             case 'S': {                            /* #539 v2 scope transition */
                 char *nm = p + 2;
                 char *sp1 = strchr(nm, ' ');
@@ -260,6 +352,7 @@ void tape_free(Tape *t) {
     for (int i = 0; i < t->nnames; i++) free(t->names[i].a);
     free(t->names);
     free(t->scopes);
+    free(t->obscfg);
     free(t->src); free(t->srcbuf);
     memset(t, 0, sizeof *t);
 }
@@ -292,21 +385,160 @@ int tape_open(Tape *t, const char *tape_path, const char *src_path) {
     return 0;
 }
 
-const char *tape_classify_at(const NameHist *h, int pos, int *out_numeric) {
-    ObserverSlot s;
-    memset(&s, 0, sizeof s);
-    int fed = 0;
-    for (int i = 0; i < h->n && h->a[i].step <= pos; i++) {
-        if (!h->a[i].is_num) continue;
-        observer_slot_record_value(&s, h->a[i].num);
-        fed++;
+/* ---- observer configuration replay (#1044/#1045 follow-up) --------- */
+
+/* Install a configuration into the reader's own EigsState: the runtime's
+ * classifiers read it through the g_obs_* macros, so replaying the tape's
+ * configuration is exactly "make the state say what the recording state
+ * said". A reader with no attached state classifies at the compiled-in
+ * defaults, which is what it did before. */
+static void obs_cfg_install(const TapeObsCfg *c) {
+    if (!eigs_current || !eigs_current->state) return;
+    g_obs_dh_zero  = c->dh_zero;
+    g_obs_dh_small = c->dh_small;
+    g_obs_h_low    = c->h_low;
+    g_obs_scale    = c->scale;
+    g_obs_window   = c->window;
+}
+
+static void obs_cfg_capture(TapeObsCfg *c) {
+    if (eigs_current && eigs_current->state) {
+        c->dh_zero  = g_obs_dh_zero;
+        c->dh_small = g_obs_dh_small;
+        c->h_low    = g_obs_h_low;
+        c->scale    = g_obs_scale;
+        c->window   = g_obs_window;
+        return;
+    }
+    c->dh_zero  = OBSERVER_DH_ZERO_DEFAULT;
+    c->dh_small = OBSERVER_DH_SMALL_DEFAULT;
+    c->h_low    = OBSERVER_H_LOW_DEFAULT;
+    c->scale    = OBSERVER_SCALE_DEFAULT;
+    c->window   = OBSERVER_WINDOW_N;
+}
+
+/* The one history on the whole tape carrying `name`, or NULL when there is
+ * none or more than one. Used only as the last resort below: when a name is
+ * unambiguous across the tape, a record naming it can only mean that binding,
+ * and applying it there is a fact rather than a guess. */
+static const NameHist *obs_win_unique(const Tape *t, const char *name) {
+    const NameHist *found = NULL;
+    for (int i = 0; i < t->nnames; i++) {
+        if (strcmp(t->names[i].name, name) != 0) continue;
+        if (found) return NULL;         /* ambiguous — refuse to guess */
+        found = &t->names[i];
     }
-    const char *label = fed ? observer_slot_report_value(&s) : NULL;
-    free(s.v_window);
-    free(s.vr_window);
-    free(s.dh_window);
+    return found;
+}
+
+/* Which BINDING an `O win <name>` record named. The live call resolved the
+ * name innermost-first from its own frame, so the reader resolves it the same
+ * way, from the frame instance the record was written in (the writer stamps
+ * the scope transition before the record, so that frame is always on the tape
+ * even when it has not assigned yet).
+ *
+ * The result is an identity, not a name: the caller compares it against the
+ * history it is folding with `==`. Comparing NAMES here is what leaked a
+ * function-local override onto every other binding of that name — the exact
+ * failure class this whole change exists to close.
+ *
+ * Falls back to obs_win_unique only when the scope walk resolves to nothing
+ * at all (a binding whose history the call chain cannot reach — a closure
+ * over a captured name, whose env parent is its definition site and not its
+ * caller). NULL from both means "no binding this record can be proven to
+ * govern": the override is then dropped, never sprayed by name. */
+static const NameHist *obs_win_target(const Tape *t, const ObsCfgRec *o) {
+    uint32_t sc = o->scope;
+    for (;;) {
+        const NameHist *h = tape_hist_for((Tape *)t, o->name, sc, 0);
+        if (h) return h;
+        if (sc == 0) return obs_win_unique(t, o->name);
+        const ScopeInfo *si = tape_scope_info(t, sc);
+        sc = si ? si->parent : 0;
+    }
+}
+
+void tape_traj_begin(TapeTraj *tr, const Tape *t, const NameHist *h) {
+    memset(&tr->slot, 0, sizeof tr->slot);
+    tr->t = t;
+    tr->h = h;
+    tr->ci = 0;
+    tr->fed = 0;
+    obs_cfg_capture(&tr->saved);
+    TapeObsCfg start = { OBSERVER_DH_ZERO_DEFAULT, OBSERVER_DH_SMALL_DEFAULT,
+                         OBSERVER_H_LOW_DEFAULT, OBSERVER_SCALE_DEFAULT,
+                         OBSERVER_WINDOW_N };
+    obs_cfg_install(&start);
+}
+
+/* Apply one recorded configuration change to the fold in progress. */
+static void obs_cfg_apply(TapeTraj *tr, const ObsCfgRec *o) {
+    if (o->binding == 0) {
+        TapeObsCfg c = { o->dh_zero, o->dh_small, o->h_low, o->scale,
+                         o->window };
+        obs_cfg_install(&c);
+    } else if (tr->h && strcmp(o->name, tr->h->name) == 0) {
+        /* Identity, not name equality: the record governs exactly the
+         * binding it resolves to. Two invocations of one function are two
+         * histories with the same name, and only the one whose frame made
+         * the call carries the override. */
+        if (obs_win_target(tr->t, o) == tr->h)
+            tr->slot.win_override = (uint8_t)o->window;
+    }
+}
+
+const char *tape_traj_feed(TapeTraj *tr, const Assign *a) {
+    const Tape *t = tr->t;
+    while (tr->ci < t->nobscfg && t->obscfg[tr->ci].rec <= a->rec)
+        obs_cfg_apply(tr, &t->obscfg[tr->ci++]);
+    if (!a->is_num) return NULL;
+    observer_slot_record_value(&tr->slot, a->num);
+    tr->fed++;
+    return observer_slot_report_value(&tr->slot);
+}
+
+/* The knobs split by WHEN the runtime consumes them: the window and the
+ * scale are read while a value is being RECORDED, the three thresholds while
+ * a verdict is being REPORTED (and the window again, for the full-window
+ * certifications). So a knob moved after a binding's last assign and before
+ * the stop still changes what `report of x` says at that stop — and folding
+ * the configuration only up to the last assign dropped exactly those,
+ * printing `stable` where the live run printed `converged` for a nine-line
+ * program. Settling walks the cursor on to the stop position and re-reads
+ * the label under the configuration actually in force there.
+ *
+ * `pos` is a stop index; a record belongs to it when it precedes the first
+ * record of the NEXT stop, which is the same bound the stepper uses to list
+ * a step's events. */
+const char *tape_traj_settle(TapeTraj *tr, int pos) {
+    const Tape *t = tr->t;
+    int bound = (pos + 1 < t->nsteps) ? t->steps[pos + 1] : t->nrecs;
+    while (tr->ci < t->nobscfg && t->obscfg[tr->ci].rec < bound)
+        obs_cfg_apply(tr, &t->obscfg[tr->ci++]);
+    return tr->fed ? observer_slot_report_value(&tr->slot) : NULL;
+}
+
+void tape_traj_end(TapeTraj *tr) {
+    free(tr->slot.v_window);
+    free(tr->slot.vr_window);
+    free(tr->slot.dh_window);
+    memset(&tr->slot, 0, sizeof tr->slot);
+    obs_cfg_install(&tr->saved);
+}
+
+const char *tape_classify_at(const Tape *t, const NameHist *h, int pos,
+                             int *out_numeric) {
+    TapeTraj tr;
+    tape_traj_begin(&tr, t, h);
+    for (int i = 0; i < h->n && h->a[i].step <= pos; i++)
+        tape_traj_feed(&tr, &h->a[i]);
+    /* The label at the STOP, not at the last assign: a knob moved between
+     * the two is on the tape and was in force when the live run reported. */
+    const char *label = tape_traj_settle(&tr, pos);
+    int fed = tr.fed;   /* the label is a string literal — it outlives _end */
+    tape_traj_end(&tr);
     if (out_numeric) *out_numeric = fed;
-    return label;
+    return fed ? label : NULL;
 }
 
 const Assign *tape_latest_at(const NameHist *h, int pos) {
diff --git a/src/tape_read.h b/src/tape_read.h
index 8eed735c..0673fa12 100644
--- a/src/tape_read.h
+++ b/src/tape_read.h
@@ -22,6 +22,23 @@
 
 #include <stdint.h>
 
+/* One observer-configuration change recovered from the tape's `O` records
+ * (#1044/#1045 follow-up). `rec` is the index of the first stored record the
+ * change governs: `O` records are folded like `S` records, so the change
+ * applies from that index ONWARD (test `rec <= assign->rec`).
+ *
+ * A verdict is a function of the assignments AND of these knobs, so a reader
+ * that ignores them classifies at the state defaults and prints a label the
+ * live run never gave. See docs/TRACE.md. */
+typedef struct {
+    int      rec;
+    int      binding;       /* 0 = state-level `O cfg`; 1 = per-binding `O win` */
+    double   dh_zero, dh_small, h_low, scale;   /* binding == 0 */
+    int      window;        /* binding == 0: state default; 1: the override */
+    const char *name;       /* binding == 1: the overridden binding */
+    uint32_t scope;         /* binding == 1: frame instance the call resolved from */
+} ObsCfgRec;
+
 typedef struct {
     char kind;          /* 'L', 'A', 'N', 'V' */
     int  line;          /* L: source line */
@@ -72,6 +89,8 @@ typedef struct {
     char   **src;       /* optional source lines (1-based view) */
     int      nsrc;
     char    *srcbuf;
+    ObsCfgRec *obscfg;  /* observer-configuration changes, in tape order */
+    int      nobscfg, obscfgcap;
 } Tape;
 
 /* Read + version-check + parse a tape (and optionally its source file)
@@ -89,11 +108,55 @@ ScopeInfo *tape_scope_info(const Tape *t, uint32_t serial);
 /* Latest assign of `h` visible at position `pos`, or NULL. */
 const Assign *tape_latest_at(const NameHist *h, int pos);
 
+/* ---- Trajectory replay (#294, made configuration-faithful by the
+ * #1044/#1045 follow-up).
+ *
+ * The ONE place a tape's assigns are folded into a real ObserverSlot; `--step`
+ * and the DAP server both drive it, so the label they print cannot drift from
+ * each other or from the runtime's own classifier. It installs the observer
+ * configuration the tape recorded — the state defaults, then every `O` record
+ * up to the assign being fed — and restores the caller's configuration at
+ * tape_traj_end, so a reader never leaks a tape's knobs into its own state.
+ * tape_traj_settle then carries the configuration on to the STOP position,
+ * because a verdict is reported there and not at the last assign.
+ *
+ * Requires eigenscript.h (ObserverSlot); every caller includes it first. */
+typedef struct { double dh_zero, dh_small, h_low, scale; int window; } TapeObsCfg;
+
+typedef struct {
+    struct ObserverSlot slot;
+    TapeObsCfg   saved;     /* the caller's configuration, restored at _end */
+    const Tape  *t;
+    const NameHist *h;      /* the BINDING being folded — identity, not name:
+                             * an `O win` record is a property of one
+                             * (scope-instance, name) binding, so it may only
+                             * be applied to the history it resolves to */
+    int          ci;        /* cursor into t->obscfg */
+    int          fed;       /* numeric values folded so far */
+} TapeTraj;
+
+void        tape_traj_begin(TapeTraj *tr, const Tape *t, const NameHist *h);
+/* Fold one assign; returns the label AFTER it, or NULL for a non-numeric
+ * assign (which still advances the recorded configuration). */
+const char *tape_traj_feed(TapeTraj *tr, const Assign *a);
+/* Advance the configuration cursor to stop position `pos` and re-read the
+ * label: the thresholds (and the window's full-window certifications) are
+ * consumed when a verdict is REPORTED, so a knob moved after the binding's
+ * last assign and before the stop still governs what the live run printed
+ * there. Returns NULL when nothing numeric has been folded. Call after the
+ * feed loop, before tape_traj_end. */
+const char *tape_traj_settle(TapeTraj *tr, int pos);
+void        tape_traj_end(TapeTraj *tr);
+
 /* Feed name's numeric assigns visible at `pos` through a real
  * ObserverSlot and return the runtime's own trajectory label — NULL
  * when the binding has no numeric trajectory yet. The label is BY
- * CONSTRUCTION what `report_value of x` would have said (#294). */
-const char *tape_classify_at(const NameHist *h, int pos, int *out_numeric);
+ * CONSTRUCTION what `report_value of x` would have said (#294) at that stop,
+ * under the configuration the tape recorded as being in force there
+ * (docs/TRACE.md names the one residual: an override on a name a closure
+ * captured, which the recorded call chain cannot resolve). */
+const char *tape_classify_at(const Tape *t, const NameHist *h, int pos,
+                             int *out_numeric);
 
 /* The frame instance current at a stop position. */
 uint32_t tape_scope_at(const Tape *t, int pos);
diff --git a/src/trace.c b/src/trace.c
index 77a85ecc..15f4d20b 100644
--- a/src/trace.c
+++ b/src/trace.c
@@ -6,6 +6,9 @@
  *   L <line>                    source-line event
  *   A <name>=<value>            name-keyed assignment delta
  *   N <fn>=<value>              nondeterministic builtin return
+ *   O cfg <dh_zero> <dh_small> <h_low> <window> <scale>
+ *                               observer configuration in force (v3)
+ *   O win <name> <n>            per-binding observer window override (v3)
  *
  * Value encoding:
  *   <num>          numeric (immediate, tracked, or heap VAL_NUM)
@@ -891,12 +894,116 @@ static void tp_printf(const char *fmt, ...) {
  * scope. */
 static uint32_t g_last_scope_serial = 0;
 
+/* Stamp `S <fn> <depth> <serial>` when the innermost frame differs from the
+ * one the last S record named (by frame-instance serial, so two invocations
+ * of the same function never merge). Dedup mirrors the L-record discipline:
+ * scope transitions only cost tape bytes where a record actually needs them.
+ * Callers must already have checked trace_out_active().
+ *
+ * Two callers: every A record (a binding belongs to the frame that wrote it),
+ * and every per-binding `O win` record (an override belongs to the frame that
+ * RESOLVED the name — and that frame may not have assigned anything yet, e.g.
+ * when the call widens a parameter's window before the body writes it, so the
+ * transition cannot be left to the next A). */
+static void emit_scope_transition(void) {
+    if (!eigs_current || !eigs_current->vm || g_vm.frame_count == 0) return;
+    CallFrame *f = &g_vm.frames[g_vm.frame_count - 1];
+    if (f->call_serial == g_last_scope_serial) return;
+    g_last_scope_serial = f->call_serial;
+    tp_printf("S %s %d %u\n",
+              (f->chunk && f->chunk->name) ? f->chunk->name : "?",
+              g_vm.frame_count - 1, f->call_serial);
+}
+
+/* ---- #1044/#1045 follow-up: the observer CONFIGURATION on the tape.
+ *
+ * Every verdict the runtime prints (`report of x`, the predicates, the
+ * `--step`/DAP trajectory labels) is a function of the A records AND of five
+ * knobs — three thresholds, the window depth, the characteristic scale — plus
+ * a per-binding window override. The tape carried the assignments and not the
+ * knobs, so a stepped tape classified at the state defaults and printed a
+ * verdict the live run never gave (the phugoid `oscillating` vs `diverging`
+ * case, and the older `set_observer_thresholds` instance of the same class).
+ *
+ * Shape chosen: record the configuration AS AN EVENT at the point it takes
+ * effect, so a mid-run change replays in the right order — not a
+ * header/snapshot stamp, which would have had to refuse mid-run changes.
+ *
+ * The state-level scalars are emitted by DIFF rather than from the knob
+ * builtins: obs_cfg_sync compares the state's live configuration against what
+ * the tape last said and emits an `O cfg` record when they differ, immediately
+ * before the next L or A record. That makes the tape carry the configuration
+ * IN FORCE by construction — a configuration set by an embedder, by a second
+ * EigsState, or by a knob nobody remembered to instrument still lands on the
+ * tape. The per-binding window override (`set_observer_window of ["x", n]`)
+ * lives on an Env slot, not on the state, so it has no cheap diff and is
+ * emitted from its builtin through trace_obs_window_binding.
+ *
+ * Cost when no tape is open: nothing (both entry points return on
+ * trace_out_active). With a tape open: five compares per L/A record. */
+static double g_cfg_dh_zero  = OBSERVER_DH_ZERO_DEFAULT;
+static double g_cfg_dh_small = OBSERVER_DH_SMALL_DEFAULT;
+static double g_cfg_h_low    = OBSERVER_H_LOW_DEFAULT;
+static double g_cfg_scale    = OBSERVER_SCALE_DEFAULT;
+static int    g_cfg_window   = OBSERVER_WINDOW_N;
+
+/* Reset to the values a fresh EigsState starts with — what a reader installs
+ * before applying the tape's O records, so "no O record" means "defaults". */
+static void obs_cfg_reset(void) {
+    g_cfg_dh_zero  = OBSERVER_DH_ZERO_DEFAULT;
+    g_cfg_dh_small = OBSERVER_DH_SMALL_DEFAULT;
+    g_cfg_h_low    = OBSERVER_H_LOW_DEFAULT;
+    g_cfg_scale    = OBSERVER_SCALE_DEFAULT;
+    g_cfg_window   = OBSERVER_WINDOW_N;
+}
+
+/* Emit `O cfg` when the state's observer configuration has moved since the
+ * last one. Callers must already have checked trace_out_active(). */
+static void obs_cfg_sync(void) {
+    if (!eigs_current || !eigs_current->state) return;
+    const EigsState *st = eigs_current->state;
+    if (st->obs_dh_zero  == g_cfg_dh_zero  &&
+        st->obs_dh_small == g_cfg_dh_small &&
+        st->obs_h_low    == g_cfg_h_low    &&
+        st->obs_scale    == g_cfg_scale    &&
+        st->obs_window   == g_cfg_window) return;
+    g_cfg_dh_zero  = st->obs_dh_zero;
+    g_cfg_dh_small = st->obs_dh_small;
+    g_cfg_h_low    = st->obs_h_low;
+    g_cfg_scale    = st->obs_scale;
+    g_cfg_window   = st->obs_window;
+    /* One field per tp_printf: its staging buffer is 128 bytes and five
+     * %.17g fields in one call could silently truncate the record. */
+    tp_puts("O cfg ");
+    tp_printf("%.17g ", g_cfg_dh_zero);
+    tp_printf("%.17g ", g_cfg_dh_small);
+    tp_printf("%.17g ", g_cfg_h_low);
+    tp_printf("%d ",    g_cfg_window);
+    tp_printf("%.17g\n", g_cfg_scale);
+}
+
+/* `set_observer_window of ["x", n]` — the per-binding override, recorded at
+ * the point of the call (n == 0 clears it back to the default). The name is
+ * the one the call site resolved; a reader re-resolves it with the same
+ * innermost-first scope walk it uses for every other binding. */
+void trace_obs_window_binding(const char *name, int n) {
+    if (!trace_out_active() || !name) return;
+    obs_cfg_sync();
+    emit_scope_transition();
+    tp_puts("O win ");
+    tp_puts(name);
+    tp_printf(" %d\n", n);
+}
+
 /* #411: stamp the version header. Called once per tape-open (EIGS_TRACE
  * fopen, sink install) — a journal appended across several installs
  * carries one V record per session; replay verifies each. */
 static void emit_header(void) {
     tp_printf("V %d %s\n", TRACE_FORMAT_VERSION, EIGENSCRIPT_VERSION);
     g_last_scope_serial = 0;
+    /* A session starts from the defaults on the tape: obs_cfg_sync emits an
+     * `O cfg` for whatever the state already carries before the first L/A. */
+    obs_cfg_reset();
 }
 
 void trace_set_sink(void (*cb)(const char *, size_t, void *), void *ud) {
@@ -1530,6 +1637,7 @@ void trace_line(int line) {
     /* OP_LINE stores g_trace_current_line directly; this function is
      * only called when a tape is open (g_trace_enabled). */
     if (!trace_out_active()) return;
+    obs_cfg_sync();
     if (line == g_last_line && !g_line_dirty) return;
     tp_printf("L %d\n", line);
     g_last_line  = line;
@@ -1594,6 +1702,7 @@ static void trace_assign_ex(const char *name, EigsSlot value, int filtered, int
     if (record_prev) prev_record_assign(name, value, filtered);
 
     if (!trace_out_active()) return;
+    obs_cfg_sync();
     if (!name) name = "?";
     /* #539 v2: scope-transition record. When the innermost frame differs
      * from the one the last S record named (by frame-instance serial, so
@@ -1602,15 +1711,7 @@ static void trace_assign_ex(const char *name, EigsSlot value, int filtered, int
      * before the A record. Dedup mirrors the L-record discipline: scope
      * transitions only cost tape bytes at call boundaries that actually
      * assign. Replay skips S like A; only the stepper folds them. */
-    if (eigs_current && eigs_current->vm && g_vm.frame_count > 0) {
-        CallFrame *f = &g_vm.frames[g_vm.frame_count - 1];
-        if (f->call_serial != g_last_scope_serial) {
-            g_last_scope_serial = f->call_serial;
-            tp_printf("S %s %d %u\n",
-                      (f->chunk && f->chunk->name) ? f->chunk->name : "?",
-                      g_vm.frame_count - 1, f->call_serial);
-        }
-    }
+    emit_scope_transition();
     tp_puts("A ");
     tp_puts(name);
     tp_putc('=');
diff --git a/src/trace.h b/src/trace.h
index 3eb8e6b8..e8a39d6d 100644
--- a/src/trace.h
+++ b/src/trace.h
@@ -28,7 +28,7 @@ typedef union { double d; uint64_t u; } EigsSlot;
  * value serialization, escaping, truncation markers, the header itself.
  * Replay refuses a tape whose format or runtime version differs from the
  * running binary: version-and-reject, never migrate (docs/TRACE.md). */
-#define TRACE_FORMAT_VERSION 2   /* v2 (#539): scope-transition S records */
+#define TRACE_FORMAT_VERSION 3   /* v3 (#1044/#1045 follow-up): observer-config O records */
 
 /* 1 when EIGS_TRACE was set and a tape was successfully opened.
  * Hook sites in vm.c gate on this directly so the disabled case
@@ -200,6 +200,13 @@ int  trace_set_replay_mem(const char *bytes, size_t len, int strict);
 /* Record a source-line event. Emitted by OP_LINE. */
 void trace_line(int line);
 
+/* #1044/#1045 follow-up: record a per-binding observer window override
+ * (`set_observer_window of ["x", n]`; n == 0 clears it) as an `O win` record
+ * at the point of the call. The state-level knobs need no hook — the tape
+ * writer diffs them against the state before every L/A record — but this one
+ * lives on an Env slot and has no cheap diff. No-op when no tape is open. */
+void trace_obs_window_binding(const char *name, int n);
+
 /* Record a name-keyed assignment. The slot is captured by value
  * (NaN-boxed union, POD), so this is safe to call from any opcode
  * handler immediately before or after the store. Phase 1 records
diff --git a/tests/fixtures/tape_v2_baseline.eigs b/tests/fixtures/tape_v2_baseline.eigs
new file mode 100644
index 00000000..6cd884b5
--- /dev/null
+++ b/tests/fixtures/tape_v2_baseline.eigs
@@ -0,0 +1,9 @@
+set_observer_thresholds of [0.01, 0.02, 0.1]
+x is 1000.0
+d is 5.0
+i is 0
+loop while i < 30:
+    x is x + d
+    d is d * 0.99
+    i is i + 1
+print of ("x=" + (report of x))
diff --git a/tests/fixtures/tape_v2_baseline.tape b/tests/fixtures/tape_v2_baseline.tape
new file mode 100644
index 00000000..357db541
--- /dev/null
+++ b/tests/fixtures/tape_v2_baseline.tape
@@ -0,0 +1,224 @@
+V 2 0.43.0
+L 10
+L 1
+L 2
+S <module> 0 1
+A x=1000
+L 3
+A d=5
+L 4
+A i=0
+L 9
+L 5
+L 6
+A x=1005
+L 7
+A d=4.9500000000000002
+L 8
+A i=1
+L 5
+L 6
+A x=1009.95
+L 7
+A d=4.9005000000000001
+L 8
+A i=2
+L 5
+L 6
+A x=1014.8505
+L 7
+A d=4.8514949999999999
+L 8
+A i=3
+L 5
+L 6
+A x=1019.701995
+L 7
+A d=4.8029800499999995
+L 8
+A i=4
+L 5
+L 6
+A x=1024.50497505
+L 7
+A d=4.7549502494999993
+L 8
+A i=5
+L 5
+L 6
+A x=1029.2599252995001
+L 7
+A d=4.707400747004999
+L 8
+A i=6
+L 5
+L 6
+A x=1033.9673260465051
+L 7
+A d=4.6603267395349492
+L 8
+A i=7
+L 5
+L 6
+A x=1038.62765278604
+L 7
+A d=4.6137234721395997
+L 8
+A i=8
+L 5
+L 6
+A x=1043.2413762581796
+L 7
+A d=4.5675862374182037
+L 8
+A i=9
+L 5
+L 6
+A x=1047.8089624955978
+L 7
+A d=4.5219103750440217
+L 8
+A i=10
+L 5
+L 6
+A x=1052.3308728706418
+L 7
+A d=4.4766912712935811
+L 8
+A i=11
+L 5
+L 6
+A x=1056.8075641419352
+L 7
+A d=4.4319243585806456
+L 8
+A i=12
+L 5
+L 6
+A x=1061.2394885005158
+L 7
+A d=4.3876051149948392
+L 8
+A i=13
+L 5
+L 6
+A x=1065.6270936155106
+L 7
+A d=4.3437290638448909
+L 8
+A i=14
+L 5
+L 6
+A x=1069.9708226793555
+L 7
+A d=4.3002917732064416
+L 8
+A i=15
+L 5
+L 6
+A x=1074.271114452562
+L 7
+A d=4.2572888554743775
+L 8
+A i=16
+L 5
+L 6
+A x=1078.5284033080363
+L 7
+A d=4.2147159669196341
+L 8
+A i=17
+L 5
+L 6
+A x=1082.7431192749559
+L 7
+A d=4.1725688072504381
+L 8
+A i=18
+L 5
+L 6
+A x=1086.9156880822063
+L 7
+A d=4.1308431191779338
+L 8
+A i=19
+L 5
+L 6
+A x=1091.0465312013841
+L 7
+A d=4.0895346879861547
+L 8
+A i=20
+L 5
+L 6
+A x=1095.1360658893702
+L 7
+A d=4.0486393411062931
+L 8
+A i=21
+L 5
+L 6
+A x=1099.1847052304765
+L 7
+A d=4.0081529476952298
+L 8
+A i=22
+L 5
+L 6
+A x=1103.1928581781717
+L 7
+A d=3.9680714182182775
+L 8
+A i=23
+L 5
+L 6
+A x=1107.1609295963899
+L 7
+A d=3.9283907040360946
+L 8
+A i=24
+L 5
+L 6
+A x=1111.0893203004259
+L 7
+A d=3.8891067969957338
+L 8
+A i=25
+L 5
+L 6
+A x=1114.9784270974217
+L 7
+A d=3.8502157290257766
+L 8
+A i=26
+L 5
+L 6
+A x=1118.8286428264475
+L 7
+A d=3.8117135717355186
+L 8
+A i=27
+L 5
+L 6
+A x=1122.640356398183
+L 7
+A d=3.7735964360181633
+L 8
+A i=28
+L 5
+L 6
+A x=1126.4139528342012
+L 7
+A d=3.7358604716579817
+L 8
+A i=29
+L 5
+L 6
+A x=1130.1498133058592
+L 7
+A d=3.698501866941402
+L 8
+A i=30
+L 5
+A __loop_exit__="normal"
+L 9
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 410cadfb..dd404fb4 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -2216,6 +2216,27 @@ else
 fi
 echo ""
 
+# [42f2] Observer configuration on the tape (#1044/#1045 follow-up): the
+# knobs that decide a verdict — thresholds, window depth (state + per
+# binding), scale — ride the tape as O records, so --step and EIGS_REPLAY
+# classify exactly as the live run did. Includes the v2-tape refusal and the
+# cross-scope cases: an `O win` record governs the one BINDING it resolves
+# to, never every binding that shares its name.
+echo "[42f2] Tape Observer Configuration (68 checks)"
+OC_OUTPUT=$(bash "$TESTS_DIR/test_tape_observer_config.sh" 2>&1)
+OC_PASS=$(echo "$OC_OUTPUT" | grep -c "PASS:" || true)
+OC_FAIL=$(echo "$OC_OUTPUT" | grep -c "FAIL:" || true)
+TOTAL=$((TOTAL + OC_PASS + OC_FAIL))
+PASS=$((PASS + OC_PASS))
+FAIL=$((FAIL + OC_FAIL))
+if [ "$OC_FAIL" -gt 0 ]; then
+    echo "  FAIL: $OC_FAIL observer-configuration check(s) failed"
+    echo "$OC_OUTPUT" | grep "FAIL:" | head -5
+else
+    echo "  PASS: all $OC_PASS observer-configuration checks"
+fi
+echo ""
+
 # [42g] --bundle (#413): single-file distribution — script + eigs_modules +
 # stdlib in one executable; tape-attached bundles replay byte-identically.
 echo "[42g] Bundle (16 checks)"
diff --git a/tests/test_dap.py b/tests/test_dap.py
index ffab6045..ef9c2b23 100644
--- a/tests/test_dap.py
+++ b/tests/test_dap.py
@@ -141,7 +141,10 @@ def req(seq, command, arguments=None):
 bad_tape = os.path.join(tmpdir, "bad.tape")
 with open(tape_path) as f:
     lines = f.read().split("\n")
-lines[0] = "V 2 0.0.1-not-this-binary"
+# keep the tape's OWN format integer so this stays a RUNTIME-version test
+# after a format bump (it went 2 -> 3 with the observer-config O records)
+fmt = open(tape_path).readline().split()[1]
+lines[0] = "V %s 0.0.1-not-this-binary" % fmt
 with open(bad_tape, "w") as f:
     f.write("\n".join(lines))
 msgs, _ = converse([req(1, "initialize"),
@@ -277,6 +280,86 @@ def req(seq, command, arguments=None):
       bframes and bframes[0]["line"] in (2, 7))
 check("session exits 0", rc == 0)
 
+# ---- 4. the observer configuration a tape recorded, at the STOP ------
+# The DAP's binding cell and its trajectory children come from the same
+# tape_read fold as `--step`, and the label must be the one the LIVE run
+# printed at that stop. The knob here moves AFTER the binding's last assign:
+# the thresholds are read when a verdict is REPORTED, so the live run says
+# `converged` at line 10 and `stable` at line 8, and a reader that folds the
+# configuration only up to the last assign prints `stable` at both.
+OBS_FIXTURE = """x is 1000.0
+d is 5.0
+i is 0
+loop while i < 30:
+    x is x + d
+    d is d * 0.99
+    i is i + 1
+print of ("before=" + (report of x))
+set_observer_thresholds of [0.01, 0.02, 0.1]
+print of ("after=" + (report of x))
+"""
+obs_src = os.path.join(tmpdir, "dapobs.eigs")
+obs_tape = os.path.join(tmpdir, "dapobs.tape")
+with open(obs_src, "w") as f:
+    f.write(OBS_FIXTURE)
+live = subprocess.run([EIGS, obs_src], capture_output=True, text=True,
+                      timeout=30).stdout
+rec = subprocess.run([EIGS, obs_src], env=dict(os.environ, EIGS_TRACE=obs_tape),
+                     capture_output=True, text=True, timeout=30)
+live_after = [l.split("=", 1)[1] for l in live.splitlines()
+              if l.startswith("after=")]
+check("observer fixture recorded", rec.returncode == 0 and
+      os.path.exists(obs_tape) and live_after == ["converged"])
+
+msgs4, _ = converse([
+    req(1, "initialize"),
+    req(2, "launch", {"tape": obs_tape, "source": obs_src}),
+    req(3, "setBreakpoints",
+        {"source": {"path": obs_src}, "breakpoints": [{"line": 10}]}),
+    req(4, "configurationDone"),
+    req(5, "continue"),
+    req(6, "stackTrace"),
+    req(7, "disconnect"),
+])
+r = resp(msgs4, 6)
+oframes = r["body"]["stackFrames"] if r and r["success"] else []
+check("DAP stops on the line after the knob call",
+      len(oframes) == 1 and oframes[0]["line"] == 10)
+ofid = oframes[0]["id"] if oframes else 1
+msgs5, _ = converse([
+    req(1, "initialize"),
+    req(2, "launch", {"tape": obs_tape, "source": obs_src}),
+    req(3, "setBreakpoints",
+        {"source": {"path": obs_src}, "breakpoints": [{"line": 10}]}),
+    req(4, "configurationDone"),
+    req(5, "continue"),
+    req(6, "variables", {"variablesReference": 1000000 + ofid}),
+    req(7, "disconnect"),
+])
+r = resp(msgs5, 6)
+ovs = {v["name"]: v for v in (r["body"]["variables"] if r and r["success"] else [])}
+check("DAP labels x with the verdict the live run gave at that stop",
+      "x" in ovs and "[converged]" in ovs["x"]["value"])
+tref = ovs["x"]["variablesReference"] if "x" in ovs else 0
+msgs6, _ = converse([
+    req(1, "initialize"),
+    req(2, "launch", {"tape": obs_tape, "source": obs_src}),
+    req(3, "setBreakpoints",
+        {"source": {"path": obs_src}, "breakpoints": [{"line": 10}]}),
+    req(4, "configurationDone"),
+    req(5, "continue"),
+    req(6, "variables", {"variablesReference": tref}),
+    req(7, "disconnect"),
+])
+r = resp(msgs6, 6)
+okids = r["body"]["variables"] if r and r["success"] else []
+check("DAP trajectory names the settled label in its own row",
+      bool(okids) and okids[-1]["name"] == "#now"
+      and "[converged]" in okids[-1]["value"])
+check("DAP trajectory rows stay per-moment",
+      len(okids) >= 2 and "[stable]" in okids[-2]["value"])
+
+
 # ---- results ----------------------------------------------------------
 if SANITIZER_HITS:
     print("  FAIL: sanitizer report in adapter stderr")
diff --git a/tests/test_tape_observer_config.sh b/tests/test_tape_observer_config.sh
new file mode 100755
index 00000000..c65b5c6b
--- /dev/null
+++ b/tests/test_tape_observer_config.sh
@@ -0,0 +1,563 @@
+#!/bin/bash
+# Observer configuration on the trace tape (#1044/#1045 follow-up).
+#
+# A verdict (`report of x`, the predicates, the `--step`/DAP trajectory
+# labels) is a function of the ASSIGNMENTS and of the observer configuration:
+# the three thresholds (set_observer_thresholds), the window depth
+# (set_observer_window, state default and per-binding), and the
+# characteristic scale (set_observer_scale). The tape used to carry only the
+# assignments, so a stepped tape classified at the state defaults and printed
+# a verdict the live run never gave.
+#
+# Every case here is the SAME assertion: the label `--step` prints equals the
+# label the live run printed, for a program that moves a knob. Each case also
+# names the label it expects, so a change that makes both sides equally wrong
+# is caught too. `O`-stripped copies of the same tapes are the built-in
+# discrimination control — they must reproduce the divergence.
+#
+# Run directly or from run_all_tests.sh. Prints PASS:/FAIL: lines and a
+# summary. Exit code: 0 if all pass, 1 if any fail.
+
+set -u
+TESTS_DIR="$(cd "$(dirname "$0")" && pwd)"
+SRC_DIR="$(cd "$TESTS_DIR/.." && pwd)/src"
+EIGS="$SRC_DIR/eigenscript"
+
+PASS=0
+FAIL=0
+TMPDIR=$(mktemp -d -t eigs_obscfg.XXXXXX)
+trap 'rm -rf "$TMPDIR"' EXIT
+
+ok()   { echo "  PASS: $1"; PASS=$((PASS+1)); }
+fail() { echo "  FAIL: $1${2:+ ($2)}"; FAIL=$((FAIL+1)); }
+
+if [ ! -x "$EIGS" ]; then
+    echo "  FAIL: eigenscript binary not found at $EIGS"
+    echo "OBSCFG: 0 passed, 1 failed"
+    exit 1
+fi
+
+# step_label <tape> <src> <binding> <commands...> -> the label `p <binding>`
+# printed, e.g. "oscillating"
+step_label() {
+    local tape=$1 src=$2 name=$3; shift 3
+    printf '%s\n' "$@" "p $name" q \
+        | "$EIGS" --step "$tape" "$src" 2>/dev/null \
+        | grep -E "^$name = " | tail -1 \
+        | sed -n 's/.*\[\([a-z]*\)\].*/\1/p'
+}
+
+# ---- case driver -------------------------------------------------------
+# knob_case <label> <binding> <expected> <src-file> <step-commands...>
+# Records the tape, compares live vs --step vs EIGS_REPLAY, and proves the
+# case discriminates by re-stepping an O-stripped copy of the same tape.
+knob_case() {
+    local what=$1 name=$2 want=$3 src=$4; shift 4
+    local tape="$TMPDIR/$what.tape"
+    local live replay stepped stripped
+    live=$("$EIGS" "$src" 2>/dev/null | tail -1 | sed 's/.*=//')
+    EIGS_TRACE="$tape" "$EIGS" "$src" >/dev/null 2>&1
+    replay=$(EIGS_REPLAY="$tape" "$EIGS" "$src" 2>/dev/null | tail -1 | sed 's/.*=//')
+    stepped=$(step_label "$tape" "$src" "$name" "$@")
+
+    [ "$live" = "$want" ] \
+        && ok "$what: live verdict is $want" \
+        || fail "$what: live verdict is $want" "got '$live'"
+    [ "$stepped" = "$live" ] \
+        && ok "$what: --step agrees with the live run" \
+        || fail "$what: --step agrees with the live run" "live=$live step=$stepped"
+    [ "$replay" = "$live" ] \
+        && ok "$what: EIGS_REPLAY agrees with the live run" \
+        || fail "$what: EIGS_REPLAY agrees with the live run" "live=$live replay=$replay"
+
+    grep -v '^O ' "$tape" > "$tape.noO"
+    stripped=$(step_label "$tape.noO" "$src" "$name" "$@")
+    [ -n "$stripped" ] && [ "$stripped" != "$live" ] \
+        && ok "$what: dropping the O records reproduces the divergence" \
+        || fail "$what: dropping the O records reproduces the divergence" \
+                "stripped=$stripped live=$live"
+}
+
+# ---- 1. set_observer_window of ["u", n] — the per-binding override.
+# The critic's phugoid reproducer: a 46.9-sample period cannot fold inside
+# the default 10-wide window, so the live run widens u's window to 50 and
+# reads `oscillating`; a tape that does not carry the override classifies
+# the same 200 samples at depth 10 and says `diverging`.
+cat > "$TMPDIR/win.eigs" <<'EOF'
+u is 0.0
+set_observer_window of ["u", 50]
+t is 0
+loop while t < 200:
+    u is 272.4 + 10.0 * (cos of (6.283185307179586 * t / 46.9))
+    t is t + 1
+print of ("u=" + (report of u))
+EOF
+knob_case win u oscillating "$TMPDIR/win.eigs" "s 700"
+
+# ---- 2. set_observer_window of n — the state default, same trajectory.
+cat > "$TMPDIR/windef.eigs" <<'EOF'
+set_observer_window of 50
+u is 0.0
+t is 0
+loop while t < 200:
+    u is 272.4 + 10.0 * (cos of (6.283185307179586 * t / 46.9))
+    t is t + 1
+print of ("u=" + (report of u))
+EOF
+knob_case windef u oscillating "$TMPDIR/windef.eigs" "s 700"
+
+# ---- 3. set_observer_thresholds — the PRE-EXISTING instance of this class
+# (it needs neither #1044 nor #1045). Relative steps of ~0.0044 sit under a
+# raised dh_zero of 0.01, so the live run certifies `converged`; at the
+# default dh_zero of 0.001 the same steps read `stable`.
+cat > "$TMPDIR/thr.eigs" <<'EOF'
+set_observer_thresholds of [0.01, 0.02, 0.1]
+x is 1000.0
+d is 5.0
+i is 0
+loop while i < 30:
+    x is x + d
+    d is d * 0.99
+    i is i + 1
+print of ("x=" + (report of x))
+EOF
+knob_case thr x converged "$TMPDIR/thr.eigs" "s 400"
+
+# ---- 4. set_observer_scale — a trajectory inside the characteristic scale.
+# With scale 0.1 every step is 5e-4 of the scale and the value certifies;
+# at the default 1e-3 the same steps are ~4% of |x| and read `moving`.
+cat > "$TMPDIR/scale.eigs" <<'EOF'
+set_observer_scale of 0.1
+x is 0.0
+d is 0.00005
+i is 0
+loop while i < 30:
+    x is x + d
+    d is d * 0.99
+    i is i + 1
+print of ("x=" + (report of x))
+EOF
+knob_case scale x converged "$TMPDIR/scale.eigs" "s 400"
+
+# ---- 5. a MID-RUN knob change: the two phases of one binding classify
+# differently, and the stepper must reproduce BOTH. This is what a
+# header/snapshot design could not do, and it is why the configuration is
+# recorded as an event at the point it takes effect.
+MID="$TMPDIR/mid.eigs"
+cat > "$MID" <<'EOF'
+x is 0.0
+d is 0.00005
+i is 0
+loop while i < 20:
+    x is x + d
+    d is d * 0.99
+    i is i + 1
+print of ("phase1 x=" + (report of x))
+set_observer_scale of 0.1
+j is 0
+loop while j < 20:
+    x is x + d
+    d is d * 0.99
+    j is j + 1
+print of ("phase2 x=" + (report of x))
+EOF
+MID_TAPE="$TMPDIR/mid.tape"
+MID_LIVE=$("$EIGS" "$MID" 2>/dev/null)
+EIGS_TRACE="$MID_TAPE" "$EIGS" "$MID" >/dev/null 2>&1
+P1_LIVE=$(echo "$MID_LIVE" | sed -n 's/^phase1 x=//p')
+P2_LIVE=$(echo "$MID_LIVE" | sed -n 's/^phase2 x=//p')
+P2_STEP=$(step_label "$MID_TAPE" "$MID" x "s 1000")
+P1_STEP=$(step_label "$MID_TAPE" "$MID" x "s 1000" "jb 8")
+
+[ "$P1_LIVE" = "moving" ] && [ "$P2_LIVE" = "converged" ] \
+    && ok "mid-run: the live run's two phases differ (moving -> converged)" \
+    || fail "mid-run: the live run's two phases differ (moving -> converged)" \
+            "p1=$P1_LIVE p2=$P2_LIVE"
+[ "$P1_STEP" = "$P1_LIVE" ] \
+    && ok "mid-run: --step reproduces the pre-change verdict" \
+    || fail "mid-run: --step reproduces the pre-change verdict" \
+            "live=$P1_LIVE step=$P1_STEP"
+[ "$P2_STEP" = "$P2_LIVE" ] \
+    && ok "mid-run: --step reproduces the post-change verdict" \
+    || fail "mid-run: --step reproduces the post-change verdict" \
+            "live=$P2_LIVE step=$P2_STEP"
+
+# ---- 6. the tape says what it carries: the records are on it, and the
+# `O cfg` record round-trips the exact doubles (%.17g).
+grep -q '^O win u 50$' "$TMPDIR/win.tape" \
+    && ok "tape carries the per-binding O win record" \
+    || fail "tape carries the per-binding O win record"
+grep -q '^O cfg 0.01 0.02 ' "$TMPDIR/thr.tape" \
+    && ok "tape carries the state-level O cfg record" \
+    || fail "tape carries the state-level O cfg record" \
+            "$(grep '^O ' "$TMPDIR/thr.tape" | head -1)"
+grep -q '^O cfg .* 50 ' "$TMPDIR/windef.tape" \
+    && ok "O cfg carries the state window depth" \
+    || fail "O cfg carries the state window depth" \
+            "$(grep '^O ' "$TMPDIR/windef.tape" | head -1)"
+# a program that touches no knob must not grow a single byte of O records
+cat > "$TMPDIR/plain.eigs" <<'EOF'
+x is 1
+for i in range of 5:
+    x is x * 2
+EOF
+EIGS_TRACE="$TMPDIR/plain.tape" "$EIGS" "$TMPDIR/plain.eigs" >/dev/null 2>&1
+grep -q '^O ' "$TMPDIR/plain.tape" \
+    && fail "a knobless program records no O records" \
+    || ok "a knobless program records no O records"
+
+# ---- 7. #411 version/compat path. The `O` records are an ENCODING change,
+# so TRACE_FORMAT_VERSION went 2 -> 3 and the rule is the standing one:
+# version-and-reject, never migrate. A v2 tape — one recorded by any earlier
+# binary, whose knob calls are simply not on it — is refused loudly by both
+# the stepper and replay rather than silently classified at the defaults.
+head -1 "$TMPDIR/thr.tape" | grep -q '^V 3 ' \
+    && ok "tapes written by this build stamp format v3" \
+    || fail "tapes written by this build stamp format v3" \
+            "$(head -1 "$TMPDIR/thr.tape")"
+
+V2="$TMPDIR/v2.tape"
+sed "1s/^V 3 /V 2 /" "$TMPDIR/thr.tape" > "$V2"
+echo q | "$EIGS" --step "$V2" "$TMPDIR/thr.eigs" >/dev/null 2>"$TMPDIR/v2.err"
+RC=$?
+[ "$RC" -eq 3 ] && grep -q "tape format v2" "$TMPDIR/v2.err" \
+    && ok "a v2 (pre-O-record) tape is refused by --step with exit 3" \
+    || fail "a v2 (pre-O-record) tape is refused by --step with exit 3" \
+            "rc=$RC $(head -1 "$TMPDIR/v2.err")"
+
+EIGS_REPLAY="$V2" "$EIGS" "$TMPDIR/thr.eigs" >/dev/null 2>"$TMPDIR/v2r.err"
+RC=$?
+[ "$RC" -eq 3 ] && grep -q "format v2" "$TMPDIR/v2r.err" \
+    && ok "a v2 (pre-O-record) tape is refused by EIGS_REPLAY with exit 3" \
+    || fail "a v2 (pre-O-record) tape is refused by EIGS_REPLAY with exit 3" \
+            "rc=$RC $(head -1 "$TMPDIR/v2r.err")"
+
+# The two checks above rewrite this build's own header, which proves the
+# refusal but not that a REAL pre-v3 tape looks the way we assume. So the
+# suite also carries one: tests/fixtures/tape_v2_baseline.tape was recorded
+# by the v0.43.0 release binary (whose tapes carry no `O` records at all) on
+# tape_v2_baseline.eigs, which raises dh_zero and certifies `converged`. The
+# deviation from "an old tape still steps" is DELIBERATE and is the #411
+# rule: a v2 tape cannot carry the configuration, so stepping it would print
+# a default-classified verdict the recorded run never gave — the exact
+# failure this change removes. Refuse loudly, re-record.
+V2REAL="$TESTS_DIR/fixtures/tape_v2_baseline.tape"
+V2SRC="$TESTS_DIR/fixtures/tape_v2_baseline.eigs"
+head -1 "$V2REAL" | grep -q '^V 2 ' \
+    && ok "the checked-in baseline tape really is format v2" \
+    || fail "the checked-in baseline tape really is format v2" \
+            "$(head -1 "$V2REAL")"
+echo q | "$EIGS" --step "$V2REAL" "$V2SRC" >/dev/null 2>"$TMPDIR/v2b.err"
+RC=$?
+[ "$RC" -eq 3 ] && grep -q "tape format v2" "$TMPDIR/v2b.err" \
+    && ok "a REAL baseline-recorded v2 tape is refused by --step with exit 3" \
+    || fail "a REAL baseline-recorded v2 tape is refused by --step with exit 3" \
+            "rc=$RC $(head -1 "$TMPDIR/v2b.err")"
+EIGS_REPLAY="$V2REAL" "$EIGS" "$V2SRC" >/dev/null 2>"$TMPDIR/v2br.err"
+RC=$?
+[ "$RC" -eq 3 ] && grep -q "format v2" "$TMPDIR/v2br.err" \
+    && ok "a REAL baseline-recorded v2 tape is refused by EIGS_REPLAY with exit 3" \
+    || fail "a REAL baseline-recorded v2 tape is refused by EIGS_REPLAY with exit 3" \
+            "rc=$RC $(head -1 "$TMPDIR/v2br.err")"
+# ...and the program it was recorded from is the pre-existing
+# set_observer_thresholds instance of the class: re-record on this build and
+# the stepped label matches the live one (the baseline's did not).
+knob_case v2reg x converged "$V2SRC" "s 400"
+
+# ---- 8. CROSS-SCOPE: an `O win` record is a property of ONE binding, not of
+# a NAME. Every case here is a tape on which the same name has more than one
+# history, so a reader that matches `O win u 50` by name alone prints a
+# verdict the live run never gave — for the binding that never asked to be
+# widened. Each program is asserted at its LAST stop (`s 99999`), which needs
+# no hard-coded step index, and each pins the OPPOSITE label from its
+# neighbour, so a reader that ignores the record and a reader that sprays it
+# everywhere are both caught.
+#
+# The `--step` label and the DAP server's come from the same
+# tape_traj_begin/feed, so this covers both surfaces.
+
+# xscope_case <label> <expected> <src-file>
+xscope_case() {
+    local what=$1 want=$2 src=$3
+    local tape="$TMPDIR/$what.tape"
+    local live stepped
+    live=$("$EIGS" "$src" 2>/dev/null | tail -1 | sed 's/.*=//')
+    EIGS_TRACE="$tape" "$EIGS" "$src" >/dev/null 2>&1
+    stepped=$(step_label "$tape" "$src" u "s 99999")
+    [ "$live" = "$want" ] \
+        && ok "$what: live verdict is $want" \
+        || fail "$what: live verdict is $want" "got '$live'"
+    [ "$stepped" = "$live" ] \
+        && ok "$what: --step agrees with the live run at the last stop" \
+        || fail "$what: --step agrees with the live run at the last stop" \
+                "live=$live step=$stepped"
+}
+
+# (a) one function, two invocations, only the FIRST widens its window. The
+# second frame's `u` is a different binding with the same name: it must read
+# the default-window verdict. Name matching leaks the override forward and
+# prints `oscillating` here.
+cat > "$TMPDIR/xsleak.eigs" <<'EOF'
+define run(m, wide) as:
+    local u is 0.0
+    local t is 0
+    if wide > 0:
+        set_observer_window of ["u", 50]
+    loop while t < m:
+        u is 272.4 + 10.0 * (cos of (6.283185307179586 * t / 46.9))
+        t is t + 1
+    return report of u
+print of ("wide=" + (run of [200, 1]))
+print of ("u=" + (run of [200, 0]))
+EOF
+xscope_case xsleak diverging "$TMPDIR/xsleak.eigs"
+
+# (b) the same program with the order swapped: now the LAST frame is the one
+# that widened, so the override must be applied — the control proving (a) is
+# not green merely because the reader dropped the record.
+cat > "$TMPDIR/xsapply.eigs" <<'EOF'
+define run(m, wide) as:
+    local u is 0.0
+    local t is 0
+    if wide > 0:
+        set_observer_window of ["u", 50]
+    loop while t < m:
+        u is 272.4 + 10.0 * (cos of (6.283185307179586 * t / 46.9))
+        t is t + 1
+    return report of u
+print of ("plain=" + (run of [200, 0]))
+print of ("u=" + (run of [200, 1]))
+EOF
+xscope_case xsapply oscillating "$TMPDIR/xsapply.eigs"
+XSAPPLY_STRIP=$(grep -v '^O ' "$TMPDIR/xsapply.tape" > "$TMPDIR/xsapply.noO"; \
+                step_label "$TMPDIR/xsapply.noO" "$TMPDIR/xsapply.eigs" u "s 99999")
+[ "$XSAPPLY_STRIP" = "diverging" ] \
+    && ok "xsapply: dropping the O records reproduces the divergence" \
+    || fail "xsapply: dropping the O records reproduces the divergence" \
+            "stripped=$XSAPPLY_STRIP"
+
+# (c) the override is set on a PARAMETER, before the frame has assigned
+# anything, while a module-level `u` of its own is already on the tape. The
+# scope transition is stamped by the record itself, so the reader resolves
+# the name from the frame that made the call — without it the record carries
+# the module's scope and resolves to the module's `u`, and the parameter's
+# window is silently lost.
+cat > "$TMPDIR/xsparam.eigs" <<'EOF'
+define run(u) as:
+    set_observer_window of ["u", 50]
+    local s is 0
+    loop while s < 200:
+        u is 272.4 + 10.0 * (cos of (6.283185307179586 * s / 46.9))
+        s is s + 1
+    return report of u
+u is 0.0
+t is 0
+loop while t < 200:
+    u is 272.4 + 10.0 * (cos of (6.283185307179586 * t / 46.9))
+    t is t + 1
+print of ("mod=" + (report of u))
+print of ("u=" + (run of [0.0]))
+EOF
+xscope_case xsparam oscillating "$TMPDIR/xsparam.eigs"
+grep -q '^S run ' "$TMPDIR/xsparam.tape" && \
+  [ "$(grep -n '^S run \|^O win u 50$' "$TMPDIR/xsparam.tape" | head -2 | \
+       sed -n '1s/:.*//p')" -lt \
+    "$(grep -n '^O win u 50$' "$TMPDIR/xsparam.tape" | sed -n '1s/:.*//p')" ] \
+    && ok "xsparam: the O win record is preceded by its own frame's S record" \
+    || fail "xsparam: the O win record is preceded by its own frame's S record" \
+            "$(grep -n '^S \|^O ' "$TMPDIR/xsparam.tape" | head -4 | tr '\n' ' ')"
+
+# (d) a function-local `u` widens its window; a module-level `u` with the
+# same trajectory is assigned AFTER the call, so the `O win` record precedes
+# its assigns and a name-matching reader applies it to the module binding.
+cat > "$TMPDIR/xsouter.eigs" <<'EOF'
+define inner() as:
+    local u is 0.0
+    set_observer_window of ["u", 50]
+    local t is 0
+    loop while t < 200:
+        u is 272.4 + 10.0 * (cos of (6.283185307179586 * t / 46.9))
+        t is t + 1
+    return report of u
+print of ("inner=" + (inner of []))
+u is 0.0
+t is 0
+loop while t < 200:
+    u is 272.4 + 10.0 * (cos of (6.283185307179586 * t / 46.9))
+    t is t + 1
+print of ("u=" + (report of u))
+EOF
+xscope_case xsouter diverging "$TMPDIR/xsouter.eigs"
+
+# ---- 9. POST-ASSIGN knob changes. The knobs split by when the runtime reads
+# them: the window and the scale are consumed while a value is RECORDED, the
+# three thresholds (and the window again, for the full-window certifications)
+# while a verdict is REPORTED. So a knob moved AFTER a binding's last assign
+# and before the stop still changes what `report of x` says there — and a
+# reader that folds the configuration only up to the last assign drops
+# exactly those and prints a confident wrong label.
+#
+# stop_label <tape> <src> <binding> <commands...> is step_label; each case
+# below asserts the label at a stop BEFORE the knob call and at the LAST
+# stop, so a reader that applies every record regardless of position is
+# caught by the first assertion and one that applies none by the second.
+
+# post_case <label> <binding> <before> <after> <before-line> <src-file>
+post_case() {
+    local what=$1 name=$2 want1=$3 want2=$4 line=$5 src=$6
+    local tape="$TMPDIR/$what.tape"
+    local live1 live2 step1 step2 stripped
+    live1=$("$EIGS" "$src" 2>/dev/null | sed -n 's/^before=//p')
+    live2=$("$EIGS" "$src" 2>/dev/null | sed -n "s/^$name=//p")
+    EIGS_TRACE="$tape" "$EIGS" "$src" >/dev/null 2>&1
+    step2=$(step_label "$tape" "$src" "$name" "s 99999")
+    step1=$(step_label "$tape" "$src" "$name" "s 99999" "jb $line")
+
+    [ "$live1" = "$want1" ] && [ "$live2" = "$want2" ] \
+        && ok "$what: the live run's verdict moves ($want1 -> $want2)" \
+        || fail "$what: the live run's verdict moves ($want1 -> $want2)" \
+                "before=$live1 after=$live2"
+    [ "$step2" = "$live2" ] \
+        && ok "$what: --step at the last stop agrees with the live run" \
+        || fail "$what: --step at the last stop agrees with the live run" \
+                "live=$live2 step=$step2"
+    [ "$step1" = "$live1" ] \
+        && ok "$what: --step BEFORE the knob call still reads the old verdict" \
+        || fail "$what: --step BEFORE the knob call still reads the old verdict" \
+                "live=$live1 step=$step1"
+    grep -v '^O ' "$tape" > "$tape.noO"
+    stripped=$(step_label "$tape.noO" "$src" "$name" "s 99999")
+    [ -n "$stripped" ] && [ "$stripped" != "$live2" ] \
+        && ok "$what: dropping the O records reproduces the divergence" \
+        || fail "$what: dropping the O records reproduces the divergence" \
+                "stripped=$stripped live=$live2"
+}
+
+# (a) set_observer_thresholds AFTER the loop — the pre-existing instance of
+# the class, in the shape that survived the first fix: the record is on the
+# tape and precedes the stop, and the thresholds are read at REPORT time.
+cat > "$TMPDIR/postthr.eigs" <<'EOF'
+x is 1000.0
+d is 5.0
+i is 0
+loop while i < 30:
+    x is x + d
+    d is d * 0.99
+    i is i + 1
+print of ("before=" + (report of x))
+set_observer_thresholds of [0.01, 0.02, 0.1]
+print of ("x=" + (report of x))
+EOF
+post_case postthr x stable converged 8 "$TMPDIR/postthr.eigs"
+
+# (b) the per-binding window, moved after the last assign: a full 10-window
+# certifies `converged`, and widening to 50 leaves the same ten samples a
+# PARTIAL window, which can only say `stable`.
+cat > "$TMPDIR/postwin.eigs" <<'EOF'
+x is 1000.0
+d is 0.0001
+i is 0
+loop while i < 30:
+    x is x + d
+    d is d * 0.99
+    i is i + 1
+print of ("before=" + (report of x))
+set_observer_window of ["x", 50]
+print of ("x=" + (report of x))
+EOF
+post_case postwin x converged stable 8 "$TMPDIR/postwin.eigs"
+
+# (c) the same through the state default (`O cfg`, not `O win`).
+cat > "$TMPDIR/postdef.eigs" <<'EOF'
+x is 1000.0
+d is 0.0001
+i is 0
+loop while i < 30:
+    x is x + d
+    d is d * 0.99
+    i is i + 1
+print of ("before=" + (report of x))
+set_observer_window of 50
+print of ("x=" + (report of x))
+EOF
+post_case postdef x converged stable 8 "$TMPDIR/postdef.eigs"
+
+# The `t` view's rows are per-moment by construction, so the settled label
+# gets its own line rather than letting the last row speak for the stop.
+TRAJ=$(printf 's 99999\nt x\nq\n' | "$EIGS" --step "$TMPDIR/postthr.tape" \
+       "$TMPDIR/postthr.eigs" 2>/dev/null | tail -1)
+case "$TRAJ" in
+  *"configuration changed after the last assign"*"[converged]"*)
+        ok "the t view names the settled label when the knob moved after it" ;;
+  *)    fail "the t view names the settled label when the knob moved after it" \
+             "$TRAJ" ;;
+esac
+TRAJ=$(printf 's 99999\nt x\nq\n' | "$EIGS" --step "$TMPDIR/thr.tape" \
+       "$TMPDIR/thr.eigs" 2>/dev/null | tail -1)
+case "$TRAJ" in
+  *"configuration changed"*)
+        fail "no such note when the configuration did not move" "$TRAJ" ;;
+  *)    ok "no such note when the configuration did not move" ;;
+esac
+
+# ---- 10. A CORRUPT `O` record is refused, not installed. The reader
+# installs these values into its own observer state, so a window of 0 divides
+# by zero sizing the ring and a negative one asks calloc for 2^64-1 bytes.
+# Tapes travel in #413 attached-tape bundles, so a record this runtime could
+# not have written is refused loudly like a torn archive — clamping would
+# classify under a configuration the recording run never had, which is the
+# same confident lie in a new costume.
+corrupt_case() {
+    local what=$1 sedexpr=$2 src=$3 tape=$4
+    sed "$sedexpr" "$tape" > "$TMPDIR/corrupt.tape"
+    printf 's 99999\np x\nt x\nq\n' \
+        | "$EIGS" --step "$TMPDIR/corrupt.tape" "$src" \
+          >/dev/null 2>"$TMPDIR/corrupt.err"
+    local rc=$?
+    [ "$rc" -eq 3 ] && grep -q "observer-configuration record" "$TMPDIR/corrupt.err" \
+        && ok "corrupt O record refused with exit 3: $what" \
+        || fail "corrupt O record refused with exit 3: $what" \
+                "rc=$rc $(head -1 "$TMPDIR/corrupt.err")"
+}
+corrupt_case "window 0"        's/^O cfg \(.*\) [0-9]* \(.*\)$/O cfg \1 0 \2/'  "$TMPDIR/thr.eigs" "$TMPDIR/thr.tape"
+corrupt_case "window -5"       's/^O cfg \(.*\) [0-9]* \(.*\)$/O cfg \1 -5 \2/' "$TMPDIR/thr.eigs" "$TMPDIR/thr.tape"
+corrupt_case "window 4000000000" 's/^O cfg \(.*\) [0-9]* \(.*\)$/O cfg \1 4000000000 \2/' "$TMPDIR/thr.eigs" "$TMPDIR/thr.tape"
+corrupt_case "scale 0"         's/^O cfg \(.*\) \(.*\)$/O cfg \1 0/'             "$TMPDIR/thr.eigs" "$TMPDIR/thr.tape"
+corrupt_case "dh_zero >= dh_small" 's/^O cfg [^ ]* /O cfg 9 /'                    "$TMPDIR/thr.eigs" "$TMPDIR/thr.tape"
+corrupt_case "truncated cfg"   's/^O cfg .*/O cfg 0.01/'                          "$TMPDIR/thr.eigs" "$TMPDIR/thr.tape"
+corrupt_case "per-binding window -1" 's/^O win u .*/O win u -1/'                    "$TMPDIR/win.eigs" "$TMPDIR/win.tape"
+corrupt_case "per-binding window 999" 's/^O win u .*/O win u 999/'                 "$TMPDIR/win.eigs" "$TMPDIR/win.tape"
+# ...and a well-formed tape is still accepted after all that (the refusal is
+# the record's, not the reader having stopped reading O records at all).
+[ "$(step_label "$TMPDIR/win.tape" "$TMPDIR/win.eigs" u "s 700")" = "oscillating" ] \
+    && ok "a well-formed O record is still accepted" \
+    || fail "a well-formed O record is still accepted"
+
+# `O win <name> 0` is the CLEAR form, not a corrupt window: a program that
+# widens a binding and then clears it must step exactly as it ran, and the
+# validation above must not refuse the record that expresses it.
+cat > "$TMPDIR/clear.eigs" <<'EOF'
+u is 0.0
+set_observer_window of ["u", 50]
+t is 0
+loop while t < 200:
+    u is 272.4 + 10.0 * (cos of (6.283185307179586 * t / 46.9))
+    t is t + 1
+print of ("wide=" + (report of u))
+set_observer_window of ["u", 0]
+print of ("u=" + (report of u))
+EOF
+CLEAR_LIVE=$("$EIGS" "$TMPDIR/clear.eigs" 2>/dev/null | sed -n 's/^u=//p')
+EIGS_TRACE="$TMPDIR/clear.tape" "$EIGS" "$TMPDIR/clear.eigs" >/dev/null 2>&1
+CLEAR_STEP=$(step_label "$TMPDIR/clear.tape" "$TMPDIR/clear.eigs" u "s 99999")
+grep -q '^O win u 0$' "$TMPDIR/clear.tape" \
+    && ok "the per-binding CLEAR is recorded as O win <name> 0" \
+    || fail "the per-binding CLEAR is recorded as O win <name> 0" \
+            "$(grep '^O ' "$TMPDIR/clear.tape" | tr '\n' ' ')"
+[ -n "$CLEAR_STEP" ] && [ "$CLEAR_STEP" = "$CLEAR_LIVE" ] \
+    && ok "--step honours the CLEAR record (both $CLEAR_LIVE)" \
+    || fail "--step honours the CLEAR record" \
+            "live=$CLEAR_LIVE step=$CLEAR_STEP"
+
+echo "OBSCFG: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

From 0b35229c759b699890ac1403f31c6a4133d99169 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 16:46:53 +0000
Subject: [PATCH 15/39] repl: a failed multi-line unit no longer swallows the
 line that closed it (#1109)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The REPL's block rules make an unindented non-blank line BOTH the terminator
of an open block and part of the same compiled unit. That is right when the
unit runs, and wrong when it does not: a tokenize/parse/compile failure threw
the whole buffer away, and the closing line — a statement the user typed and
that never ran — went with it.

Minimal repro (piped REPL, baseline v0.43.0 / a6c50fb):

    $ printf 'define f(@) as:\nx is 1\nprint of x\n' | src/eigenscript
    eigs> ...   Syntax error line 1: unexpected character '@'
    eigs> Error line 1: undefined variable 'x'
         1 | print of x
           |          ^
      at <module> (line 1)

`x is 1` was eaten by the failed define, so `print of x` had nothing to read.
After:

    eigs> ...   Syntax error line 1: unexpected character '@'
    => 1
    eigs> 1

The issue's #1102 consequence goes with it: the reservation program pasted
into the REPL lost its `x is 1`, so `report of x` saw one assignment and
answered `equilibrium`; it now answers `moving`.

Fix: `repl_eval_buffer` reports whether the unit NEVER RAN (tokenize, parse or
compile error) through a new `failed` out-param — a runtime error does not
qualify, because then the closing line executed with the unit. The per-line
block rules, duplicated in the piped loop and the interactive editor loop,
move into one `ReplAccum` + `repl_feed_line`; when a never-ran unit was closed
by an unindented line, that line is re-fed through the same rules as the start
of the next unit. It may open a block of its own, and `exit`/`quit` matching
moved into the shared feed so a re-fed `exit` is honoured rather than eaten.

Behaviour on every other path is unchanged. A differential over 21 piped REPL
transcripts against the baseline binary is byte-identical on 17 (simple lines,
valid blocks closed by a blank line AND by an unindented line, top-level parse
errors, nested blocks, exit/quit forms, EOF mid-block, runtime errors) and
differs only on the 4 failed-multi-line-unit cases this fixes.

Regression tests (tests/test_repl.sh, 6 piped checks; tests/test_repl.py, 2 pty
checks) pin: the issue repro; a VALID block closed by an unindented line still
compiling as ONE unit, byte-exact; a failed unit closed by a BLANK line
reporting once with no spurious empty unit; two consecutive failed units each
reporting once with both closing lines surviving; the #1102 pasted program; and
a re-fed `exit` still ending the session. Planted fault (`failed && 0 &&
terminator`, i.e. the re-feed removed): 4 of the 8 go red, the two controls
that must not depend on the re-feed stay green.

Closes #1109

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 docs/SYNTAX.md         |  27 +++++-
 src/repl.c             | 210 ++++++++++++++++++++++++-----------------
 tests/run_all_tests.sh |   2 +-
 tests/test_repl.py     |  36 +++++++
 tests/test_repl.sh     |  71 ++++++++++++++
 5 files changed, 256 insertions(+), 90 deletions(-)

diff --git a/docs/SYNTAX.md b/docs/SYNTAX.md
index 54355c6c..ace7475b 100644
--- a/docs/SYNTAX.md
+++ b/docs/SYNTAX.md
@@ -159,7 +159,32 @@ eigs> double of 21
 ```
 
 Multi-line input (functions, loops, conditionals) is detected automatically
-when a line ends with `:`. A blank line ends the block.
+when a line ends with `:`. A blank line ends the block. So does an unindented
+non-blank line — that line is part of the same unit and runs with the block:
+
+```
+eigs> if 2 > 1:
+...       total is 51 + 6
+... total + 1
+=> 58
+```
+
+If such a unit fails to tokenize, parse or compile, nothing in it ran, so the
+unindented line that closed it is **re-fed as the start of the next unit**
+rather than discarded with the block (#1109). It goes back through the same
+rules, so it may open a block of its own:
+
+```
+eigs> define f(@) as:
+... x is 1
+Syntax error line 1: unexpected character '@'
+=> 1
+eigs> print of x
+1
+```
+
+The same rules apply to piped (non-tty) input, which is the REPL path the
+test suite drives.
 
 ## Conditionals
 
diff --git a/src/repl.c b/src/repl.c
index d7b12e75..afac3e0e 100644
--- a/src/repl.c
+++ b/src/repl.c
@@ -43,7 +43,8 @@
  * Output bytes are identical to the pre-#392 inline code; the one change
  * is free_ast on the parse-error path (parse returns a partial tree on
  * error — cf. #214 — which the old loop leaked). */
-static int repl_eval_buffer(Env *env, strbuf *input) {
+static int repl_eval_buffer(Env *env, strbuf *input, int *failed) {
+    *failed = 0;
     /* Skip empty input */
     char *check = input->data;
     while (*check == ' ' || *check == '\t' || *check == '\n' || *check == '\r') check++;
@@ -52,6 +53,7 @@ static int repl_eval_buffer(Env *env, strbuf *input) {
     g_parse_errors = 0;
     TokenList tl = tokenize(input->data);
     if (g_parse_errors > 0) {
+        *failed = 1;
         free_tokenlist(&tl);
         return 0;
     }
@@ -60,6 +62,7 @@ static int repl_eval_buffer(Env *env, strbuf *input) {
     ASTNode *ast = parse(&tl);
     parser_set_caret_source(NULL);
     if (g_parse_errors > 0) {
+        *failed = 1;
         free_ast(ast);
         free_tokenlist(&tl);
         return 0;
@@ -76,6 +79,7 @@ static int repl_eval_buffer(Env *env, strbuf *input) {
     eigs_obs_enable_runtime();   /* #915: via the helper, so a mid-run flip records the gap */
     EigsChunk *repl_chunk = compile_ast(ast, env, input->data);
     if (g_parse_errors > 0) {   /* e.g. an un-encodable jump/loop offset */
+        *failed = 1;
         fprintf(stderr, "%d compile error(s) — line not run\n", g_parse_errors);
         chunk_free(repl_chunk);
         free_tokenlist(&tl);
@@ -110,65 +114,123 @@ static int repl_eval_buffer(Env *env, strbuf *input) {
     return 0;
 }
 
-/* ---- piped / non-tty path: the original fgets loop ---- */
-
-static void repl_plain(Env *env) {
-    char line_buf[4096];
-    strbuf input;
-    strbuf_init(&input);
-    int continuation = 0;
+/* ---- shared line accumulation (#1109) ----
+ * Both input paths hand raw lines to one accumulator, so the multi-line
+ * rules live in exactly one place: a line ending in ':' opens a block; a
+ * blank line closes it; an unindented non-blank line closes it AND joins the
+ * same unit. `exit`/`quit` are matched here too, so a line re-fed after a
+ * failed unit is recognised exactly like a freshly typed one.
+ *
+ * The bug this structure fixes: the closing unindented line is part of the
+ * accumulated unit, so when that unit fails to tokenize/parse/compile it was
+ * thrown away with the rest of the buffer and never ran. `repl_feed_line`
+ * keeps it and re-feeds it as the start of the next unit.
+ */
+typedef struct {
+    Env    *env;
+    strbuf  input;
+    int     continuation;
+} ReplAccum;
+
+static void repl_accum_init(ReplAccum *st, Env *env) {
+    st->env = env;
+    st->continuation = 0;
+    strbuf_init(&st->input);
+}
 
-    while (1) {
-        printf(continuation ? "...   " : "eigs> ");
-        fflush(stdout);
+static void repl_accum_reset(ReplAccum *st) {
+    st->input.len = 0;
+    st->input.data[0] = '\0';
+}
 
-        if (!fgets(line_buf, sizeof(line_buf), stdin)) {
-            printf("\n");
-            break;
-        }
+/* `exit`/`quit` as a REPL command: top level only, leading blanks skipped,
+ * the whole rest of the line must be the word plus its newline. Same rule
+ * both paths carried before (the editor's lines are newline-normalized by
+ * the caller, so one predicate now serves both). */
+static int repl_is_exit_command(const char *line) {
+    while (*line == ' ' || *line == '\t') line++;
+    return strcmp(line, "exit\n")   == 0 || strcmp(line, "quit\n")   == 0 ||
+           strcmp(line, "exit\r\n") == 0 || strcmp(line, "quit\r\n") == 0;
+}
 
-        /* Exit commands */
-        if (!continuation) {
-            char *trimmed = line_buf;
-            while (*trimmed == ' ' || *trimmed == '\t') trimmed++;
-            if (strcmp(trimmed, "exit\n") == 0 || strcmp(trimmed, "quit\n") == 0 ||
-                strcmp(trimmed, "exit\r\n") == 0 || strcmp(trimmed, "quit\r\n") == 0) {
-                break;
-            }
-        }
+/* Feed one raw input line (trailing newline included) into the accumulator,
+ * running the unit when the line completes it. Returns 1 when the REPL must
+ * stop (`exit`/`quit`, or `exit of N` inside the unit). */
+static int repl_feed_line(ReplAccum *st, const char *line) {
+    /* Both callers read lines into a 4096-byte buffer, so a line that closed
+     * a block always fits here. Static, not stack: same PR #361 rule as
+     * EdState — the REPL is single-threaded and this loop never re-enters. */
+    static char refeed[4096];
 
-        int len = strlen(line_buf);
-        strbuf_append_n(&input, line_buf, (size_t)len);
-
-        /* Multi-line detection */
-        if (!continuation) {
-            /* Check if line ends with colon (block opener) */
-            char *end = line_buf + len - 1;
-            while (end > line_buf && (*end == '\n' || *end == '\r' || *end == ' ')) end--;
-            if (*end == ':') {
-                continuation = 1;
-                continue;
+    for (;;) {
+        if (!st->continuation && repl_is_exit_command(line)) return 1;
+
+        size_t off = st->input.len;      /* where this line starts in the unit */
+        size_t len = strlen(line);
+        strbuf_append_n(&st->input, line, len);
+
+        int terminator = 0;              /* closed an open block and joined it */
+        if (!st->continuation) {
+            /* Block opener: last non-blank byte is ':' */
+            const char *end = line + len;
+            while (end > line && (end[-1] == '\n' || end[-1] == '\r' || end[-1] == ' ')) end--;
+            if (end > line && end[-1] == ':') {
+                st->continuation = 1;
+                return 0;
             }
         } else {
-            /* In continuation: blank line or unindented line ends block */
-            char *trimmed = line_buf;
+            const char *trimmed = line;
             while (*trimmed == ' ' || *trimmed == '\t') trimmed++;
             if (*trimmed == '\n' || *trimmed == '\r' || *trimmed == '\0') {
-                continuation = 0;
-                /* fall through to execute */
-            } else if (line_buf[0] == ' ' || line_buf[0] == '\t') {
-                continue; /* still indented, keep accumulating */
+                st->continuation = 0;    /* blank line: run the block */
+            } else if (line[0] == ' ' || line[0] == '\t') {
+                return 0;                /* still indented, keep accumulating */
             } else {
-                continuation = 0;
-                /* unindented non-blank: end of block */
+                st->continuation = 0;    /* unindented: ends the block + included */
+                terminator = 1;
             }
         }
 
-        if (repl_eval_buffer(env, &input)) break;
-        input.len = 0;
-        input.data[0] = '\0';
+        int failed = 0;
+        int stop = repl_eval_buffer(st->env, &st->input, &failed);
+
+        /* #1109: a unit that never ran must not swallow the line that closed
+         * it. Re-feed that line as the start of the next unit — it may open a
+         * block of its own, so it goes back through the same rules. Only the
+         * never-ran failures qualify (tokenize/parse/compile): once the unit
+         * executed, the closing line executed with it. */
+        int redo = (!stop && failed && terminator &&
+                    st->input.len > off && st->input.len - off < sizeof(refeed));
+        if (redo) {
+            size_t n = st->input.len - off;
+            memcpy(refeed, st->input.data + off, n);
+            refeed[n] = '\0';
+        }
+        repl_accum_reset(st);
+        if (stop) return 1;
+        if (!redo) return 0;
+        line = refeed;
     }
-    strbuf_free(&input);
+}
+
+/* ---- piped / non-tty path: the original fgets loop ---- */
+
+static void repl_plain(Env *env) {
+    char line_buf[4096];
+    ReplAccum st;
+    repl_accum_init(&st, env);
+
+    while (1) {
+        printf(st.continuation ? "...   " : "eigs> ");
+        fflush(stdout);
+
+        if (!fgets(line_buf, sizeof(line_buf), stdin)) {
+            printf("\n");
+            break;
+        }
+        if (repl_feed_line(&st, line_buf)) break;
+    }
+    strbuf_free(&st.input);
 }
 
 /* ---- interactive tty path: the line editor ---- */
@@ -604,62 +666,34 @@ static void repl_interactive(Env *env) {
     atexit(raw_off);   /* never leave the terminal raw, whatever the exit path */
 
     char line[ED_BUF];
+    static char fed[ED_BUF + 2];   /* the line plus the newline the accumulator expects */
     static EdState ed;             /* ~12 KiB: static, not stack (PR #361 rule) */
-    strbuf input;
-    strbuf_init(&input);
-    int continuation = 0;
+    ReplAccum st;
+    repl_accum_init(&st, env);
 
     for (;;) {
         if (raw_on() == -1) break;
-        int len = ed_readline(env, &ed, continuation ? "...   " : "eigs> ", line);
+        int len = ed_readline(env, &ed, st.continuation ? "...   " : "eigs> ", line);
         raw_off();     /* cooked during eval: scripts may read stdin; SIGINT works */
 
         if (len == RL_EOF) break;
         if (len == RL_CANCEL) {
-            continuation = 0;
-            input.len = 0;
-            input.data[0] = '\0';
+            st.continuation = 0;
+            repl_accum_reset(&st);
             continue;
         }
 
         if (len > 0) hist_add_mem(line);
 
-        /* Exit commands (top level only, same rule as the piped path) */
-        if (!continuation) {
-            char *trimmed = line;
-            while (*trimmed == ' ' || *trimmed == '\t') trimmed++;
-            if (strcmp(trimmed, "exit") == 0 || strcmp(trimmed, "quit") == 0) break;
-        }
-
-        strbuf_append_n(&input, line, (size_t)len);
-        strbuf_append_n(&input, "\n", 1);
-
-        /* Multi-line block rules, identical to the piped path */
-        if (!continuation) {
-            int e = len;
-            while (e > 0 && line[e - 1] == ' ') e--;
-            if (e > 0 && line[e - 1] == ':') {
-                continuation = 1;
-                continue;
-            }
-        } else {
-            char *trimmed = line;
-            while (*trimmed == ' ' || *trimmed == '\t') trimmed++;
-            if (*trimmed == '\0') {
-                continuation = 0;            /* blank line: run the block */
-            } else if (line[0] == ' ' || line[0] == '\t') {
-                continue;                    /* still indented, accumulate */
-            } else {
-                continuation = 0;            /* unindented: ends + included */
-            }
-        }
-
-        if (repl_eval_buffer(env, &input)) break;
-        input.len = 0;
-        input.data[0] = '\0';
+        /* Newline-normalize, then run the same accumulator as the piped path
+         * (exit/quit, block rules and #1109 re-feed all live there). */
+        memcpy(fed, line, (size_t)len);
+        fed[len] = '\n';
+        fed[len + 1] = '\0';
+        if (repl_feed_line(&st, fed)) break;
     }
 
-    strbuf_free(&input);
+    strbuf_free(&st.input);
     hist_save();
     hist_free();
 }
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index dd404fb4..8d124406 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -2255,7 +2255,7 @@ fi
 echo ""
 
 # [42c] REPL (#392): piped transcript byte-exact + pty-driven line editor
-echo "[42c] REPL editor & piped transcript (16 checks)"
+echo "[42c] REPL editor & piped transcript (24 checks)"
 RE_OUTPUT=$(bash "$TESTS_DIR/test_repl.sh" 2>&1)
 RE_PASS=$(echo "$RE_OUTPUT" | grep -c "PASS:" || true)
 RE_FAIL=$(echo "$RE_OUTPUT" | grep -c "FAIL:" || true)
diff --git a/tests/test_repl.py b/tests/test_repl.py
index cef01695..cc98955c 100644
--- a/tests/test_repl.py
+++ b/tests/test_repl.py
@@ -259,6 +259,40 @@ def test_multiline_block():
     report(ok and rc == 0, "':' opens a block, blank line runs it", f"rc={rc}")
 
 
+def test_refeed_after_failed_block():
+    """#1109: the line that closes a failed multi-line unit is not swallowed."""
+    r = Repl()
+    ok = r.expect(b"eigs> ")
+    r.send(b"define f(@) as:\r")        # '@' is not a legal parameter
+    ok = ok and r.expect(b"...   ")
+    r.send(b"rf is 4242\r")             # unindented: closes the unit, which fails
+    ok = ok and r.expect(b"unexpected character")
+    ok = ok and r.expect(b"=> 4242")     # re-fed and run, not eaten
+    r.send(b"rf + 1\r")
+    ok = ok and r.expect(b"=> 4243")     # '4243' cannot come from an echo
+    r.send(b"exit\r")
+    rc = r.close()
+    report(ok and rc == 0, "failed block does not swallow its closing line (#1109)",
+           f"rc={rc}")
+
+
+def test_valid_block_closed_by_unindented_line():
+    """#1109 control: a VALID block closed by an unindented line is one unit."""
+    r = Repl()
+    ok = r.expect(b"eigs> ")
+    r.send(b"if 2 > 1:\r")
+    ok = ok and r.expect(b"...   ")
+    r.send(b"    ub is 51 + 6\r")
+    r.send(b"ub + 1\r")                  # unindented: closes the block, same unit
+    ok = ok and r.expect(b"=> 58")       # the joined unit's value
+    r.send(b"ub\r")
+    ok = ok and r.expect(b"=> 57")       # the block really ran
+    r.send(b"exit\r")
+    rc = r.close()
+    report(ok and rc == 0, "valid block closed by an unindented line stays one unit (#1109)",
+           f"rc={rc}")
+
+
 def test_temporal_on_session_bindings():
     r = Repl()
     ok = r.expect(b"eigs> ")
@@ -323,6 +357,8 @@ def main():
               test_history_recall, test_history_draft_parking,
               test_tab_completion_binding, test_tab_completion_builtin,
               test_ctrl_c_cancels, test_ctrl_d_eof, test_multiline_block,
+              test_refeed_after_failed_block,
+              test_valid_block_closed_by_unindented_line,
               test_temporal_on_session_bindings, test_history_file,
               test_plain_mode_hook):
         try:
diff --git a/tests/test_repl.sh b/tests/test_repl.sh
index 49e9e0a5..ad7c9377 100644
--- a/tests/test_repl.sh
+++ b/tests/test_repl.sh
@@ -45,6 +45,77 @@ else
     fail "REPL piped parse error recovery" "out='$OUT'"
 fi
 
+# ---- 1b. #1109: a failed multi-line unit must not swallow its closing line ----
+# The unindented line that closes a block is part of the same unit. When the
+# unit never runs (tokenize/parse/compile error) that line used to vanish; it
+# is now re-fed as the start of the next unit.
+
+# The issue's repro: the error prints AND `x is 1` / `print of x` still run.
+OUT=$(printf 'define f(@) as:\nx is 1\nprint of x\nexit\n' | "$EIGS" 2>&1)
+if echo "$OUT" | grep -q "unexpected character '@'" \
+   && echo "$OUT" | grep -q "=> 1" \
+   && echo "$OUT" | grep -qx "eigs> 1" \
+   && ! echo "$OUT" | grep -q "undefined variable 'x'"; then
+    ok "REPL failed multi-line unit re-feeds its closing line (#1109)"
+else
+    fail "REPL #1109 re-feed" "out='$OUT'"
+fi
+
+# Control (a): a VALID block closed by an unindented line is still ONE unit —
+# byte-exact, so the re-feed cannot have leaked into the success path.
+OUT=$(printf 'define f(a) as:\n    return a * 2\nprint of (f of 21)\nexit\n' | "$EIGS" 2>/dev/null)
+RC=$?
+EXPECTED=$(printf "EigenScript %s\nType 'exit' or Ctrl-D to quit.\n\neigs> ...   ...   42\neigs> " "$VER")
+if [ "$RC" = "0" ] && [ "$OUT" = "$EXPECTED" ]; then
+    ok "REPL valid block closed by an unindented line stays one unit (#1109 control)"
+else
+    fail "REPL valid unindent-closed block" "rc=$RC out='$OUT'"
+fi
+
+# Control (b): a failed unit closed by a BLANK line reports once and does not
+# manufacture a spurious empty unit (nothing is re-fed — there is no line to
+# lose), and the next line still runs.
+OUT=$(printf 'define f(@) as:\n\nprint of "after"\nexit\n' | "$EIGS" 2>&1)
+ERRS=$(echo "$OUT" | grep -c "unexpected character '@'" || true)
+if [ "$ERRS" = "1" ] && echo "$OUT" | grep -qx "eigs> after"; then
+    ok "REPL blank-line-closed failed unit reports once, no empty unit (#1109 control)"
+else
+    fail "REPL blank-closed failed unit" "errs=$ERRS out='$OUT'"
+fi
+
+# Control (c): two consecutive failed units each report once, and both closing
+# lines survive (x and y are both bound, so the third line prints 3).
+OUT=$(printf 'define f(@) as:\nx is 1\ndefine g(@) as:\ny is 2\nprint of (x + y)\nexit\n' | "$EIGS" 2>&1)
+ERRS=$(echo "$OUT" | grep -c "unexpected character '@'" || true)
+if [ "$ERRS" = "2" ] && echo "$OUT" | grep -qx "eigs> 3"; then
+    ok "REPL two consecutive failed units each report once (#1109 control)"
+else
+    fail "REPL two failed units" "errs=$ERRS out='$OUT'"
+fi
+
+# The #1102 program pasted into the REPL: the reservation error prints, and the
+# `x is 1` line it used to eat now runs — so `report of x` sees two assignments
+# and answers `moving`, not the one-assignment `equilibrium`.
+OUT=$(printf 'define report(v) as:\n    return "mine"\nx is 1\nx is 2\nprint of (report of x)\nexit\n' | "$EIGS" 2>&1)
+if echo "$OUT" | grep -q "reserved observer form" \
+   && echo "$OUT" | grep -q "=> 1" \
+   && echo "$OUT" | grep -qx "eigs> moving"; then
+    ok "REPL #1102 reservation program: error shown and the following lines run (#1109)"
+else
+    fail "REPL #1102 pasted program" "out='$OUT'"
+fi
+
+# The re-fed line goes through the whole line rule, `exit` included: a failed
+# unit closed by `exit` now honours it instead of eating it.
+printf 'define f(@) as:\nexit\nprint of "AFTER"\n' | "$EIGS" >/dev/null 2>&1
+RC=$?
+OUT=$(printf 'define f(@) as:\nexit\nprint of "AFTER"\n' | "$EIGS" 2>&1)
+if [ "$RC" = "0" ] && ! echo "$OUT" | grep -q "AFTER"; then
+    ok "REPL re-fed 'exit' still ends the session (#1109 control)"
+else
+    fail "REPL re-fed exit" "rc=$RC out='$OUT'"
+fi
+
 # ---- 2. interactive editor on a pty ----
 if command -v python3 >/dev/null 2>&1; then
     python3 test_repl.py 2>&1 | grep -E "^(PASS|FAIL):"

From f8745782e9e57f9830692b1cd1aa610a4df53b45 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 17:49:46 +0000
Subject: [PATCH 16/39] tensor: accept buffers wherever a flat numeric list is
 accepted; zeros of n returns a buffer (#1093)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Part 1 — every tensor builtin in src/builtins_tensor.c that takes a flat
numeric list now takes a VAL_BUFFER in the same position, and returns a
buffer when EVERY tensor operand was a buffer (a list otherwise). Nested
2-D list inputs keep list semantics; a shaped buffer is the buffer form of a
2-D tensor. Converted through the shared helpers (tensor_dims,
tensor_to_flat, tensor_total, tensor_flatten_recursive, tensor_unary,
tensor_elementwise) plus a new flat_to_like that rebuilds a shape-preserving
result in the input's container — so each operation has ONE implementation
rather than a buffer copy beside a list copy (add's and relu's duplicated
buffer fast paths were deleted, not extended).

Part 2 — `zeros of n` (scalar n) returns a buffer: `type of` is `buffer`,
`print of` shows `<buffer:n>`, 8 bytes per element instead of a boxed Value
plus a slot pointer. `zeros of [rows, cols]` still returns the nested list.
`zeros_like` mirrors its argument's container. `set_at`/`get_at` take a
buffer too (1-D, or `[row, col]` on a shaped one), because that is the first
thing a `zeros of n` consumer reaches for; a bad index there reports the same
diagnostic the `[]` operator already gives for a buffer.

Guard census (the count is an instrument reading, not a target): 38
`type != VAL_LIST` guards before AND after. 15 are the ARGUMENT ENVELOPE —
`arg` is the argument list `[a, b]`, never a tensor operand, so a buffer can
never appear there. 13 converted. 1 (`shape`) already accepted buffers. 9 are
nested-2-D-LIST structure guards asserting that an element is a row; they keep
their list meaning because the shaped-buffer case is handled in the VAL_BUFFER
branch added above each function. 15 + 13 + 1 + 9 = 38.

Minimal repro, baseline v0.43.0 binary -> after:
  b is buffer of 4  (1,2,3,4)
  mean of b                     0     -> 2.5
  sqrt of b                     0     -> <buffer:4>
  negative of b                 0     -> <buffer:4>
  add of [b, 1]                 0     -> <buffer:4>
  multiply of [b, 2]            0     -> <buffer:4>
  subtract of [b, b]            0     -> <buffer:4>
  softmax of b                  null  -> <buffer:4>
  leaky_relu of b               null  -> <buffer:4>
  gather of [b, 2]              0     -> 3
  zeros_like of b               0     -> <buffer:4>
  type of (zeros of 4)          list  -> buffer

Regression test: tests/test_tensor_buffer_inputs.eigs, wired as suite section
[93b], 99 checks. Every check is a list/buffer PAIR whose flattened numeric
output must be byte-identical, plus the container assertion where a buffer
input must yield a buffer output. Planted-fault proof: removing the
VAL_BUFFER branch in tensor_unary turns 8 checks red (sqrt/exp/log/negative,
numbers and container); reverting `zeros of n` to the list turns 5 red
including a hard error on `reshape of (zeros of 6)`.

List inputs are unchanged: 55 list-only tensor calls — including the empty
tensor and the wrong-type fail-soft answers — are byte-identical against the
pre-change binary in default mode; under EIGS_STRICT=1 the only difference is
one guard message now naming buffers. Wrong types stay loud in both modes.

Sweep. tests/test_sandbox_budget.eigs case 4 rewritten: at 8 bytes/element and
a 10M cap, one `zeros` call can charge at most 80 MB and can no longer exceed
the 256 MiB default budget, so the old assertion was passing through the
boundary result-scan refusal instead of the byte budget. The bomb is now four
maximal allocations and the assertion names the memory diagnostic; the old
zeros(9M) case is kept, pinning the new mechanism. tests/observer_corpus
golden for dynamics__solve recaptured: only the printed rendering of three
`zeros`-built vectors moved — verified element-wise identical against the
pre-change binary, every iteration count unchanged — and the cost is recorded
in the corpus README.

Docs: SPEC.md (a `zeros of n` subsection and the container rule under shaped
buffers, both with executed examples), COMPARISON.md (a numeric-array section
against NumPy), BUILTINS.md (a tensor-section preamble stating the container
rule plus the zeros / zeros_like / matmul / gather / set_at / get_at rows),
llms.txt, README.md.

Residual: ouroboros' AOT mirror hardcodes the old answer.
aot/compile.eigs:882-892 (`is_buf_create`) excludes `zeros` from the buffer
class with the comment "`zeros` does NOT create a buffer -- in this VM it is a
tensor builtin returning a LIST, every time"; aot/aot_rt.h:897 repeats it.
Both remain SAFE after this change (the boxed path and aot_any_len /
aot_any_at already dispatch on VAL_BUFFER), but the AOT will not deliver
ouroboros#170's 12.4x until `is_buf_create` re-admits the scalar `zeros of n`
form at the next pin bump. Not edited here.

Closes #1093

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 README.md                                     |   5 +
 docs/BUILTINS.md                              |  37 +-
 docs/COMPARISON.md                            |  41 ++
 docs/SPEC.md                                  |  65 ++-
 docs/llms.txt                                 |  11 +
 src/builtins.c                                |  80 +++
 src/builtins_tensor.c                         | 455 ++++++++++++++----
 src/lsp_builtin_index.h                       |   4 +-
 tests/observer_corpus/README.md               |  16 +
 .../golden/dynamics__solve.out                |   6 +-
 tests/run_all_tests.sh                        |  10 +
 tests/test_sandbox_budget.eigs                |  26 +-
 tests/test_tensor_buffer_inputs.eigs          | 248 ++++++++++
 13 files changed, 901 insertions(+), 103 deletions(-)
 create mode 100644 tests/test_tensor_buffer_inputs.eigs

diff --git a/README.md b/README.md
index 31287a84..a9bc6200 100644
--- a/README.md
+++ b/README.md
@@ -272,6 +272,11 @@ Builtins: `matmul`, `add`, `subtract`, `multiply`, `divide`, `softmax`,
 `log_softmax`, `relu`, `leaky_relu`, `zeros`, `random_normal`, `shape`,
 `numerical_grad`, `sgd_update`, `tensor_save`, `tensor_load`.
 
+Each of them takes a nested list, a flat list, or a flat numeric **`buffer`**,
+and returns a buffer when every tensor operand was one. `zeros of n` returns a
+buffer (`zeros of [rows, cols]` still returns the nested list) — numeric work
+wants the flat container, and that is the name it reaches for.
+
 EigenScript numbers are finite by construction. Operations that would create
 `NaN` return `0`; operations that would overflow to infinity saturate at
 `+/-1e308`; domain-limited functions clamp their inputs where appropriate
diff --git a/docs/BUILTINS.md b/docs/BUILTINS.md
index a8f2b8f1..e2e91acb 100644
--- a/docs/BUILTINS.md
+++ b/docs/BUILTINS.md
@@ -71,8 +71,8 @@ numeric fast paths used by reassignment and `unobserved` blocks.
 | `append` | `append of [list, item]` | Append item to list (mutates list) |
 | `concat` | `concat of [a, b]` | Concatenate two lists into new list |
 | `range` | `range of n` or `range of [start, end]` | Generate integer list [0..n) or [start..end) |
-| `set_at` | `set_at of [list, index, value]` | Set element at index (mutates list); negative indices count from the end, like `[]` |
-| `get_at` | `get_at of [list, index]` | Get element at index; negative indices count from the end, like `[]` |
+| `set_at` | `set_at of [list, index, value]` | Set element at index (mutates list); negative indices count from the end, like `[]`. Also takes a **buffer** in the first position — `set_at of [buf, i, v]`, or `set_at of [shaped_buf, row, col, v]` — where a non-number value is refused (`cannot store str in a buffer`) |
+| `get_at` | `get_at of [list, index]` | Get element at index; negative indices count from the end, like `[]`. Also takes a **buffer**: `get_at of [buf, i]`, or `get_at of [shaped_buf, row, col]` |
 | `copy_into` | `copy_into of [dest, offset, src]` | Copy src elements into dest starting at offset — a list into a list, or a buffer / list of numbers into a buffer. Returns dest. Wrong arity, a non-number offset (the doc used to list `[dest, src, offset]`, the code has always read `[dest, offset, src]`), a bad type, or a non-number element bound for a buffer RAISES (#1069; it silently returned null) |
 | `list_slice` | `list_slice of [list, start, end]` | New list with the elements of [start, end) — dual of `copy_into`. Negative indices count from the end, like `[]`; bounds then clamp to [0, len]. `start >= end` gives `[]`. Never raises on bounds |
 | `num_copy` | `num_copy of value` | Create independent copy of numeric value |
@@ -453,6 +453,25 @@ automatically at exit.
 
 ## Tensor Math
 
+**Numeric work wants a `buffer`.** A tensor argument (`t`, `a`, `b`, `matrix`)
+is any of: a number, a flat list of numbers, a nested list of lists (the 2-D
+tensor), or a **`buffer`** — flat `double[]`, one 8-byte element instead of a
+boxed `Value` per number, and the container the JIT and the AOT compile
+against. Every builtin in this section that accepts a flat numeric list accepts
+a buffer in the same position; a 1-D buffer reads as a 1-D tensor and a shaped
+buffer (`buffer of [r, c]`, `reshape of [buf, r, c]`) as its `r x c` 2-D
+tensor. The numbers are identical either way.
+
+**Container of the result**: a builtin that returns a tensor returns a
+*buffer* when **every** tensor operand was a buffer, and a *list* otherwise
+(so mixing a buffer with a list yields a list). Reductions (`sum`, `mean`,
+`norm`) return a number from either. `shape` always returns a list.
+
+**`zeros of n` returns a buffer** (#1093, breaking — it used to return a list);
+`zeros of [rows, cols]` still returns the nested list. Reach for
+`zeros of n` / `buffer of n` for numeric vectors and keep lists for
+heterogeneous or nested data.
+
 ### Arithmetic
 
 | Name | Signature | Description |
@@ -480,22 +499,22 @@ automatically at exit.
 
 | Name | Signature | Description |
 |------|-----------|-------------|
-| `matmul` | `matmul of [a, b]` | Matrix multiplication |
-| `gather` | `gather of [matrix, indices, dim]` | Gather rows/columns by index |
+| `matmul` | `matmul of [a, b]` | Matrix multiplication. Two shaped buffers multiply on the flat data and give a buffer; a 1-D left operand gives a 1-D result. Mixed list/buffer operands give a list |
+| `gather` | `gather of [matrix, indices, dim]` | Gather one element per row by index. `matrix` may be a shaped buffer and `indices` a list or a buffer; a shaped-buffer `matrix` gives a buffer. `gather of [vec, i]` on a 1-D tensor returns element `i` |
 
 ### Reductions
 
 | Name | Signature | Description |
 |------|-----------|-------------|
-| `mean` | `mean of t` | Average of all elements |
-| `sum` | `sum of t` | Sum of all elements |
+| `mean` | `mean of t` | Average of all elements (list, nested list or buffer) |
+| `sum` | `sum of t` | Sum of all elements (list, nested list or buffer) |
 
 ### Construction
 
 | Name | Signature | Description |
 |------|-----------|-------------|
-| `zeros` | `zeros of [rows, cols]` or `zeros of n` | Create zero tensor |
-| `zeros_like` | `zeros_like of t` | Create zero tensor matching shape |
+| `zeros` | `zeros of n` or `zeros of [rows, cols]` | `zeros of n` returns a **buffer** of `n` zeros (`type of` is `buffer`, `print of` shows `<buffer:n>`); `zeros of [rows, cols]` returns the nested-list 2-D tensor. Breaking change in #1093 — `zeros of n` used to return a list; write `[0 for i in range of n]` if you need that. Both spellings cap at 10,000,000 elements and charge the sandbox budget |
+| `zeros_like` | `zeros_like of t` | Zero tensor matching `t`'s shape **and container**: a buffer gives a buffer (shape preserved), a list gives a list, a number gives `0.0` |
 | `random_normal` | `random_normal of [rows, cols, scale]` | Gaussian random tensor |
 | `shape` | `shape of t` | Return dimensions as list |
 | `reshape` | `reshape of [buffer, rows, cols]` | New numeric buffer with the same data reinterpreted as `rows`×`cols` (requires `rows*cols == count`; `null` otherwise) |
@@ -504,7 +523,7 @@ automatically at exit.
 
 | Name | Signature | Description |
 |------|-----------|-------------|
-| `tensor_save` | `tensor_save of [tensor, "path"]` | Save tensor to binary file (preserves observer state) |
+| `tensor_save` | `tensor_save of [tensor, "path"]` | Save a list or buffer tensor to a binary file (preserves observer state) |
 | `tensor_load` | `tensor_load of "path"` | Load tensor from binary file (restores observer state) |
 
 ### Gradients & SGD
diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md
index 4e72bd97..3a59e3ef 100644
--- a/docs/COMPARISON.md
+++ b/docs/COMPARISON.md
@@ -163,6 +163,47 @@ print of (map of [xs, (v) => v * 10])
 [10, 20, 30, 40, 50]
 ```
 
+## Numeric arrays: the list is not the fast container
+
+Python separates a `list` of boxed objects from a NumPy array of raw doubles,
+and you pick one per use. EigenScript draws the same line between `list` and
+`buffer` — and `zeros of n` hands you the flat one, because numeric code
+reaches for that name first (#1093).
+
+Python:
+
+```python
+import numpy as np
+z = np.zeros(4)              # flat float64 array
+z[1] = 2.5
+print(type(z).__name__, z.sum())
+xs = [0] * 4                 # a boxed list, when you want one
+print(type(xs).__name__, sum(xs))
+```
+
+EigenScript — no import, and every tensor builtin takes either container:
+
+```eigenscript
+z is zeros of 4
+z[1] is 2.5
+print of (type of z)
+print of (sum of z)
+xs is [0 for i in range of 4]
+print of (type of xs)
+print of (sum of xs)
+```
+```output
+buffer
+2.5
+list
+0
+```
+
+`zeros of [rows, cols]` still builds the nested list (the 2-D tensor form);
+`buffer of [rows, cols]` and `reshape of [buf, rows, cols]` build the
+flat-backed matrix. `matmul`, `softmax`, `sum`, `mean`, `norm`, `gather` and
+the rest accept either, and hand back a buffer when every operand was one.
+
 ## Dictionaries / objects
 
 JavaScript:
diff --git a/docs/SPEC.md b/docs/SPEC.md
index 44a7b712..dcb7546c 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -93,7 +93,7 @@ EigenScript is dynamically typed. The runtime types are:
 | `str` | immutable byte string | `"text"` |
 | `list` | mutable ordered sequence | `[1, 2, 3]` |
 | `dict` | mutable string-keyed map | `{"k": 1}` |
-| `buffer` | flat mutable array of nums | `buffer of 8` |
+| `buffer` | flat mutable array of nums | `buffer of 8`, `zeros of 8` |
 | `fn` | user-defined function / closure | `define` / `(x) => x` |
 | `builtin` | native function | `print` |
 | `none` | the null value | `null` |
@@ -1886,6 +1886,41 @@ print of s
 5.5
 ```
 
+### `zeros of n` is a buffer
+
+`zeros of n` is the same flat container under the name numeric code reaches
+for first: it returns a **buffer** of `n` zeros, not a list of `n` boxed
+numbers. `zeros of [rows, cols]` is unchanged — that spelling still builds the
+nested-list tensor, because 2-D list code indexes rows. `zeros_like of t`
+mirrors its argument's container: a buffer in gives a buffer out, a list in
+gives a list out.
+
+```eigenscript
+z is zeros of 4
+print of (type of z)
+print of z
+z[1] is 2.5
+print of (sum of z)
+m is zeros of [2, 3]
+print of (type of m)
+print of m
+print of (type of (zeros_like of z))
+```
+```output
+buffer
+<buffer:4>
+2.5
+list
+[[0, 0, 0], [0, 0, 0]]
+buffer
+```
+
+This is a **breaking change** (#1093). Before it, `zeros of n` answered a list:
+`type of (zeros of 4)` was `list` and `print of` showed `[0, 0, 0, 0]`. Code
+that genuinely needs the list form spells it out — `[0 for i in range of n]` —
+and code that only indexes, assigns, iterates, reduces or passes the vector to
+a tensor builtin needs no change, because a buffer supports all of those.
+
 ### Reductions
 
 `sum of a` returns the total of a buffer's (or tensor's) elements, and
@@ -1947,6 +1982,34 @@ so `matmul of [vec, mat]` returns a 1-D result); `add` and `relu` are
 elementwise. The result is identical to the nested-list tensor form, so storing
 weights as shaped buffers is purely a performance choice.
 
+Every tensor builtin that accepts a flat numeric list accepts a buffer in the
+same position, and returns a buffer when **every** tensor operand was a buffer:
+`add`/`subtract`/`multiply`/`divide`/`pow`, `sqrt`/`exp`/`log`/`negative`,
+`matmul`, `softmax`/`log_softmax`/`relu`/`leaky_relu`, `gather`, `shape`,
+`zeros_like`, `tensor_save`, and the `numerical_grad`/`sgd_update` family
+(including the `_rows`/`_cols` variants, whose index vector may also be a
+buffer). Mixing a buffer with a list yields a list. The reductions
+(`sum`, `mean`, `norm`) return a number from either container. A 1-D buffer
+reads as a 1-D tensor and a shaped buffer as its `rows x cols` 2-D tensor, so
+the numbers agree element for element with the equivalent list.
+
+```eigenscript
+l is [1.0, 4.0, 9.0]
+b is buf_from_list of l
+print of (sqrt of l)
+print of ((sqrt of b)[2])
+print of (type of (sqrt of b))
+print of (type of (add of [b, l]))
+print of (mean of b)
+```
+```output
+[1, 2, 3]
+3
+buffer
+list
+4.666666666666667
+```
+
 ```eigenscript
 w is buffer of [2, 2]
 w[0] is 1
diff --git a/docs/llms.txt b/docs/llms.txt
index 124fdde1..c40ea25e 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -136,6 +136,17 @@ print of ("sqrt(2) = " + (str of (newton_sqrt of 2)))   # sqrt(2) = 1.4142135623
   (`0x1p4`) are parse errors. No `mod` keyword — the operator is `%`.
 - f-strings interpolate: `f"step {i}: {report of x}"`. Escapes: `\n \t \r \\ \" \{ \}`.
 
+## Numeric vectors: `buffer`, not `list`
+
+- `buffer of n` (and `zeros of n`, which returns a **buffer**) is the flat
+  `double[]` container: index/slice/iterate like a list, numbers only, and the
+  fast path for the JIT and the AOT. `str of` a buffer is `<buffer:n>`.
+- `zeros of [rows, cols]` still builds the nested LIST tensor; `buffer of
+  [r, c]` / `reshape of [buf, r, c]` build the flat-backed matrix.
+- Every tensor builtin (`add` … `pow`, `sqrt`/`exp`/`log`/`negative`, `matmul`,
+  `softmax`, `relu`, `sum`/`mean`/`norm`, `gather`, `zeros_like`) takes either
+  container and returns a buffer iff every tensor operand was one.
+
 ## Lists, dicts, control flow (quick shapes)
 
 ```eigenscript
diff --git a/src/builtins.c b/src/builtins.c
index 2c34373e..b5173ca9 100644
--- a/src/builtins.c
+++ b/src/builtins.c
@@ -4123,6 +4123,26 @@ static int at_index(Value *idx_val, int count, const char *what,
     return 1;
 }
 
+/* #1093: the buffer twin of at_index — same negative-from-the-end rule, but
+ * the diagnostic `b[i]` and `buf_get` already use for a buffer, so `set_at of
+ * [buf, 9, v]` and `buf[9]` do not report the same fault two different ways. */
+static int buf_at_index(Value *idx_val, int count, int *out) {
+    if (!idx_val || idx_val->type != VAL_NUM) {
+        rt_error(EK_VALUE, 0, "buffer index must be a number, got %s",
+                 val_type_name(idx_val ? idx_val->type : VAL_NULL));
+        return 0;
+    }
+    int idx = (int)idx_val->data.num;
+    if (idx < 0) idx += count;
+    if (idx < 0 || idx >= count) {
+        rt_error(EK_INDEX, 0, "buffer index %d out of range (length %d)",
+                 (int)idx_val->data.num, count);
+        return 0;
+    }
+    *out = idx;
+    return 1;
+}
+
 Value* builtin_set_at(Value *arg) {
     if (!arg || arg->type != VAL_LIST) {
         rt_error(EK_TYPE, 0, "set_at requires [list, index, value] or "
@@ -4130,6 +4150,44 @@ Value* builtin_set_at(Value *arg) {
         return make_null();
     }
     int argc = arg->data.list.count;
+    /* #1093: `zeros of n` is a buffer now, so the indexed accessors take one
+     * in the container position — 1-D on any buffer, [row, col] on a shaped
+     * one. A non-number value is refused with buf_set's message rather than
+     * silently type-punned. `at_index`'s negative-from-the-end rule applies
+     * to buffers too. */
+    if ((argc == 3 || argc == 4) && arg->data.list.items[0]
+        && arg->data.list.items[0]->type == VAL_BUFFER) {
+        Value *buf = arg->data.list.items[0];
+        Value *val = arg->data.list.items[argc == 3 ? 2 : 3];
+        int64_t off;
+        if (argc == 3) {
+            int idx;
+            if (!buf_at_index(arg->data.list.items[1], buf->data.buffer.count,
+                              &idx)) return make_null();
+            off = idx;
+        } else if (argc == 4 && buf->data.buffer.rows > 0) {
+            int row, col;
+            if (!buf_at_index(arg->data.list.items[1], buf->data.buffer.rows,
+                              &row)) return make_null();
+            if (!buf_at_index(arg->data.list.items[2], buf->data.buffer.cols,
+                              &col)) return make_null();
+            off = (int64_t)row * buf->data.buffer.cols + col;
+        } else {
+            rt_error(EK_TYPE, 0, "set_at: [buffer, row, col, value] needs a "
+                     "shaped buffer (see reshape)");
+            return make_null();
+        }
+        if (!val || val->type != VAL_NUM) {
+            rt_error(EK_TYPE, 0, "cannot store %s in a buffer (buffers hold numbers)",
+                     val_type_name(val ? val->type : VAL_NULL));
+            return make_null();
+        }
+        buf->data.buffer.data[off] = val->data.num;
+        /* Direct child of the arg vector — the borrow protocol (#720,
+         * vm_borrow_compensate) compensates at the call site, exactly as for
+         * the list path's `return list`. */
+        return buf;
+    }
     if (argc == 3) {
         /* 1D: set_at of [list, index, value] */
         Value *list = arg->data.list.items[0];
@@ -4201,6 +4259,28 @@ Value* builtin_get_at(Value *arg) {
         return make_null();
     }
     int argc = arg->data.list.count;
+    /* #1093: same buffer reading as set_at above. */
+    if ((argc == 2 || argc == 3) && arg->data.list.items[0]
+        && arg->data.list.items[0]->type == VAL_BUFFER) {
+        Value *buf = arg->data.list.items[0];
+        if (argc == 2) {
+            int idx;
+            if (!buf_at_index(arg->data.list.items[1], buf->data.buffer.count,
+                              &idx)) return make_null();
+            return make_num(buf->data.buffer.data[idx]);
+        }
+        if (argc == 3 && buf->data.buffer.rows > 0) {
+            int row, col;
+            if (!buf_at_index(arg->data.list.items[1], buf->data.buffer.rows,
+                              &row)) return make_null();
+            if (!buf_at_index(arg->data.list.items[2], buf->data.buffer.cols,
+                              &col)) return make_null();
+            return make_num(buf->data.buffer.data[(int64_t)row * buf->data.buffer.cols + col]);
+        }
+        rt_error(EK_TYPE, 0, "get_at: [buffer, row, col] needs a shaped buffer "
+                 "(see reshape)");
+        return make_null();
+    }
     if (argc == 2) {
         Value *list = arg->data.list.items[0];
         if (!list || list->type != VAL_LIST) {
diff --git a/src/builtins_tensor.c b/src/builtins_tensor.c
index da22c36f..230448b8 100644
--- a/src/builtins_tensor.c
+++ b/src/builtins_tensor.c
@@ -134,6 +134,16 @@ static Value* make_buffer_like(Value *a) {   /* same count + shape as a */
 
 /* --- Tensor helper: detect dimensions --- */
 static int tensor_dims(Value *v, int *rows, int *cols) {
+    /* #1093: a VAL_BUFFER is a flat numeric tensor — shaped (rows>0) reads as
+     * a rows x cols 2-D tensor, unshaped as a 1-D row vector. Same reading
+     * buf_dims uses, so the buffer fast paths and this generic path agree. */
+    if (v && v->type == VAL_BUFFER) {
+        if (v->data.buffer.count == 0) return 0;
+        if (v->data.buffer.rows > 0) {
+            *rows = v->data.buffer.rows; *cols = v->data.buffer.cols; return 2;
+        }
+        *rows = 1; *cols = v->data.buffer.count; return 1;
+    }
     if (!v || v->type != VAL_LIST || v->data.list.count == 0) return 0;
     Value *first = v->data.list.items[0];
     if (first->type == VAL_NUM) {
@@ -161,6 +171,10 @@ static double* tensor_to_flat(Value *v, int *rows, int *cols) {
         return NULL;
     }
     double *out = xcalloc_array(total, sizeof(double));
+    if (v->type == VAL_BUFFER) {          /* #1093: already flat */
+        memcpy(out, v->data.buffer.data, total * sizeof(double));
+        return out;
+    }
     if (ndim == 1) {
         for (int i = 0; i < *cols; i++)
             out[i] = (v->data.list.items[i]->type == VAL_NUM) ? v->data.list.items[i]->data.num : 0.0;
@@ -195,10 +209,30 @@ static Value* flat_to_tensor_1d(double *data, int len) {
     return out;
 }
 
+/* --- Tensor helper (#1093): rebuild a shape-preserving result in the SAME
+ * container the input arrived in. A buffer input yields a buffer (1-D stays
+ * 1-D, shaped stays shaped); anything else yields the nested-list tensor the
+ * builtins have always produced. Returns NULL only when the sandbox refuses
+ * the buffer allocation (callers hand back make_null). --- */
+static Value* flat_to_like(Value *src, double *data, int rows, int cols) {
+    if (src && src->type == VAL_BUFFER) {
+        Value *out = (src->data.buffer.rows > 0) ? make_shaped_buffer(rows, cols)
+                                                 : make_shaped_buffer(0, cols);
+        if (!out) return NULL;
+        int n = out->data.buffer.count;
+        if (n > rows * cols) n = rows * cols;
+        memcpy(out->data.buffer.data, data, (size_t)n * sizeof(double));
+        return out;
+    }
+    return (rows == 1) ? flat_to_tensor_1d(data, cols)
+                       : flat_to_tensor_2d(data, rows, cols);
+}
+
 /* --- Tensor helper: count total elements recursively --- */
 static int tensor_total(Value *v) {
     if (!v) return 0;
     if (v->type == VAL_NUM) return 1;
+    if (v->type == VAL_BUFFER) return v->data.buffer.count;   /* #1093 */
     if (v->type != VAL_LIST) return 0;
     int total = 0;
     for (int i = 0; i < v->data.list.count; i++)
@@ -210,6 +244,11 @@ static int tensor_total(Value *v) {
 static void tensor_flatten_recursive(Value *v, double *out, int *idx) {
     if (!v) return;
     if (v->type == VAL_NUM) { out[(*idx)++] = v->data.num; return; }
+    if (v->type == VAL_BUFFER) {                              /* #1093 */
+        for (int i = 0; i < v->data.buffer.count; i++)
+            out[(*idx)++] = v->data.buffer.data[i];
+        return;
+    }
     if (v->type != VAL_LIST) return;
     for (int i = 0; i < v->data.list.count; i++)
         tensor_flatten_recursive(v->data.list.items[i], out, idx);
@@ -223,6 +262,73 @@ static double op_mul(double a, double b) { return num_guard(a * b); }
 static double op_div(double a, double b) { return (b == 0.0) ? 0.0 : num_guard(a / b); }
 static double op_pow(double a, double b) { return num_guard(pow(a, b)); }
 
+/* #1093: materialise a buffer as the nested-list tensor of the same shape, so
+ * a MIXED buffer/list pair falls back to the list path (and yields a list). */
+static Value* buf_as_tensor_list(Value *b) {
+    if (b->data.buffer.rows > 0)
+        return flat_to_tensor_2d(b->data.buffer.data,
+                                 b->data.buffer.rows, b->data.buffer.cols);
+    return flat_to_tensor_1d(b->data.buffer.data, b->data.buffer.count);
+}
+
+/* #1093: elementwise over two buffers. The broadcast cases and their
+ * precedence mirror the nested-list branch below (a row vector matching cols
+ * wins over one matching rows), so a shaped buffer and the equivalent nested
+ * list produce byte-identical numbers. */
+static Value* buf_elementwise(Value *a, Value *b, BinOpFn fn) {
+    double *ad = a->data.buffer.data, *bd = b->data.buffer.data;
+    int an = a->data.buffer.count, bn = b->data.buffer.count;
+    int a_mat = a->data.buffer.rows > 0, b_mat = b->data.buffer.rows > 0;
+
+    if (a_mat && !b_mat) {
+        int rows = a->data.buffer.rows, cols = a->data.buffer.cols;
+        if ((int64_t)rows * cols > 10000000) return make_null();
+        if (bn == cols || bn == rows) {
+            Value *out = make_shaped_buffer(rows, cols);
+            if (!out) return make_null();
+            for (int r = 0; r < rows; r++)
+                for (int c = 0; c < cols; c++)
+                    out->data.buffer.data[r * cols + c] =
+                        fn(ad[r * cols + c], (bn == cols) ? bd[c] : bd[r]);
+            return out;
+        }
+    }
+    if (!a_mat && b_mat) {
+        int rows = b->data.buffer.rows, cols = b->data.buffer.cols;
+        if ((int64_t)rows * cols > 10000000) return make_null();
+        if (an == cols || an == rows) {
+            Value *out = make_shaped_buffer(rows, cols);
+            if (!out) return make_null();
+            for (int r = 0; r < rows; r++)
+                for (int c = 0; c < cols; c++)
+                    out->data.buffer.data[r * cols + c] =
+                        fn((an == cols) ? ad[c] : ad[r], bd[r * cols + c]);
+            return out;
+        }
+    }
+    if (an == bn) {                      /* same length: keep a's shape */
+        Value *out = make_buffer_like(a);
+        if (!out) return make_null();
+        for (int i = 0; i < an; i++) out->data.buffer.data[i] = fn(ad[i], bd[i]);
+        return out;
+    }
+    /* Mismatched lengths truncate to the shorter operand, as the list path does. */
+    int n = an < bn ? an : bn;
+    Value *out = make_shaped_buffer(0, n);
+    if (!out) return make_null();
+    for (int i = 0; i < n; i++) out->data.buffer.data[i] = fn(ad[i], bd[i]);
+    return out;
+}
+
+static Value* buf_scalar_elementwise(Value *buf, double sc, BinOpFn fn, int buf_left) {
+    Value *out = make_buffer_like(buf);
+    if (!out) return make_null();
+    for (int i = 0; i < buf->data.buffer.count; i++)
+        out->data.buffer.data[i] = buf_left ? fn(buf->data.buffer.data[i], sc)
+                                            : fn(sc, buf->data.buffer.data[i]);
+    return out;
+}
+
 static Value* tensor_elementwise(Value *a, Value *b, BinOpFn fn) {
     /* Shared by add/subtract/multiply/divide/pow (and by its own recursion on
      * nested elements), so the guard names that surface rather than one call. */
@@ -233,6 +339,29 @@ static Value* tensor_elementwise(Value *a, Value *b, BinOpFn fn) {
     if (a->type == VAL_NUM && b->type == VAL_NUM)
         return make_num(fn(a->data.num, b->data.num));
 
+    /* #1093 buffers are flat numeric tensors. Buffer-only operands compute on
+     * the flat doubles and return a buffer; a buffer MIXED with a list is
+     * materialised as a list first, so the result follows the list container
+     * (the rule: a buffer out iff every tensor operand was a buffer). */
+    if (a->type == VAL_BUFFER && b->type == VAL_BUFFER)
+        return buf_elementwise(a, b, fn);
+    if (a->type == VAL_BUFFER && b->type == VAL_NUM)
+        return buf_scalar_elementwise(a, b->data.num, fn, 1);
+    if (a->type == VAL_NUM && b->type == VAL_BUFFER)
+        return buf_scalar_elementwise(b, a->data.num, fn, 0);
+    if (a->type == VAL_BUFFER && b->type == VAL_LIST) {
+        Value *al = buf_as_tensor_list(a);
+        Value *res = tensor_elementwise(al, b, fn);
+        val_decref(al);
+        return res;
+    }
+    if (a->type == VAL_LIST && b->type == VAL_BUFFER) {
+        Value *bl = buf_as_tensor_list(b);
+        Value *res = tensor_elementwise(a, bl, fn);
+        val_decref(bl);
+        return res;
+    }
+
     /* scalar broadcast to list */
     if (a->type == VAL_NUM && b->type == VAL_LIST) {
         Value *out = make_list(b->data.list.count);
@@ -310,28 +439,19 @@ static Value* tensor_elementwise(Value *a, Value *b, BinOpFn fn) {
         return out;
     }
     /* Every NUM/LIST combination exits above, so reaching here means an
-     * operand is neither a number nor a list — a string, a dict, a buffer
-     * (`add of [buffer, list]` lands here). That is the wrong-type case, and
-     * 0.0 was indistinguishable from a real elementwise result. */
+     * operand is neither a number, a list nor a buffer — a string, a dict, a
+     * function. That is the wrong-type case, and 0.0 was indistinguishable
+     * from a real elementwise result. */
     ARG_GUARD(1, "add/subtract/multiply/divide/pow",
-              "numbers or lists as operands", make_num(0.0));
+              "numbers, lists or buffers as operands", make_num(0.0));
 }
 
 /* ==== BUILTIN: add ==== */
 Value* builtin_tensor_add(Value *arg) {
     if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2) return make_null();
-    Value *a = arg->data.list.items[0];
-    Value *b = arg->data.list.items[1];
-    /* flat-buffer fast path: same-shape elementwise, in place */
-    if (a->type == VAL_BUFFER && b->type == VAL_BUFFER &&
-        a->data.buffer.count == b->data.buffer.count) {
-        Value *res = make_buffer_like(a);
-        if (!res) return make_null();
-        for (int i = 0; i < a->data.buffer.count; i++)
-            res->data.buffer.data[i] = op_add(a->data.buffer.data[i], b->data.buffer.data[i]);
-        return res;
-    }
-    return tensor_elementwise(a, b, op_add);
+    /* #1093: the buffer fast path moved into tensor_elementwise, so all five
+     * elementwise builtins share one implementation. */
+    return tensor_elementwise(arg->data.list.items[0], arg->data.list.items[1], op_add);
 }
 
 /* ==== BUILTIN: subtract ==== */
@@ -362,6 +482,14 @@ Value* builtin_tensor_pow(Value *arg) {
 typedef double (*UnaryOpFn)(double);
 static Value* tensor_unary(Value *v, UnaryOpFn fn) {
     if (v->type == VAL_NUM) return make_num(fn(v->data.num));
+    /* #1093: a buffer is a flat numeric tensor — same kernel, buffer out. */
+    if (v->type == VAL_BUFFER) {
+        Value *out = make_buffer_like(v);
+        if (!out) return make_null();
+        for (int i = 0; i < v->data.buffer.count; i++)
+            out->data.buffer.data[i] = fn(v->data.buffer.data[i]);
+        return out;
+    }
     if (v->type == VAL_LIST) {
         Value *out = make_list(v->data.list.count);
         for (int i = 0; i < v->data.list.count; i++)
@@ -372,7 +500,8 @@ static Value* tensor_unary(Value *v, UnaryOpFn fn) {
      * list — `sqrt of "hello"` was 0, the exact laundering #971 names. Shared
      * by sqrt/exp/log/negative and by its own recursion, so the guard names
      * that surface rather than one call. */
-    ARG_GUARD(1, "sqrt/exp/log/negative", "a number or a list", make_num(0.0));
+    ARG_GUARD(1, "sqrt/exp/log/negative", "a number, a list or a buffer",
+              make_num(0.0));
 }
 
 /* #865: `sqrt of -1` returns 0, which is indistinguishable from `sqrt of 0`.
@@ -490,13 +619,9 @@ Value* builtin_tensor_softmax(Value *arg) {
     double *flat = tensor_to_flat(arg, &rows, &cols);
     if (!flat) return make_null();
     ne_softmax_buf(flat, rows, cols);
-    Value *result;
-    if (rows == 1)
-        result = flat_to_tensor_1d(flat, cols);
-    else
-        result = flat_to_tensor_2d(flat, rows, cols);
+    Value *result = flat_to_like(arg, flat, rows, cols);   /* #1093 */
     free(flat);
-    return result;
+    return result ? result : make_null();
 }
 
 /* ==== BUILTIN: log_softmax ==== */
@@ -520,13 +645,9 @@ Value* builtin_tensor_log_softmax(Value *arg) {
         if (!(flat[i] > 0.0)) g_math_flags |= EIGS_MATH_INVALID;   /* #865 / #1041 */
         flat[i] = log(flat[i] > 0.0 ? flat[i] : 1e-10);
     }
-    Value *result;
-    if (rows == 1)
-        result = flat_to_tensor_1d(flat, cols);
-    else
-        result = flat_to_tensor_2d(flat, rows, cols);
+    Value *result = flat_to_like(tensor, flat, rows, cols);   /* #1093 */
     free(flat);
-    return result;
+    return result ? result : make_null();
 }
 
 /* ==== BUILTIN: relu ==== */
@@ -537,28 +658,16 @@ Value* builtin_tensor_relu(Value *arg) {
         double x = arg->data.num;
         return make_num(x < 0.0 ? 0.0 : x);
     }
-    /* flat-buffer fast path: in-place clamp, shape preserved */
-    if (arg && arg->type == VAL_BUFFER) {
-        Value *res = make_buffer_like(arg);
-        if (!res) return make_null();
-        for (int i = 0; i < arg->data.buffer.count; i++) {
-            double x = arg->data.buffer.data[i];
-            res->data.buffer.data[i] = (x < 0.0) ? 0.0 : x;
-        }
-        return res;
-    }
+    /* #1093: buffers go through the same flatten path and come back as
+     * buffers via flat_to_like — one implementation, not two. */
     int rows, cols;
     double *flat = tensor_to_flat(arg, &rows, &cols);
     if (!flat) return make_null();
     for (int i = 0; i < rows * cols; i++)
         if (flat[i] < 0.0) flat[i] = 0.0;
-    Value *result;
-    if (rows == 1)
-        result = flat_to_tensor_1d(flat, cols);
-    else
-        result = flat_to_tensor_2d(flat, rows, cols);
+    Value *result = flat_to_like(arg, flat, rows, cols);
     free(flat);
-    return result;
+    return result ? result : make_null();
 }
 
 /* ==== BUILTIN: leaky_relu ==== */
@@ -574,13 +683,9 @@ Value* builtin_tensor_leaky_relu(Value *arg) {
     if (!flat) return make_null();
     for (int i = 0; i < rows * cols; i++)
         if (flat[i] < 0.0) flat[i] *= 0.01;
-    Value *result;
-    if (rows == 1)
-        result = flat_to_tensor_1d(flat, cols);
-    else
-        result = flat_to_tensor_2d(flat, rows, cols);
+    Value *result = flat_to_like(arg, flat, rows, cols);   /* #1093 */
     free(flat);
-    return result;
+    return result ? result : make_null();
 }
 
 /* ==== BUILTIN: mean ==== */
@@ -593,8 +698,9 @@ Value* builtin_tensor_mean(Value *arg) {
      * tagged fs:EMPTY, which would have blessed the laundering permanently),
      * so the type half is hoisted out. Non-strict is byte-identical: both
      * halves still answer 0.0. Closes the main half of #1008. */
-    ARG_GUARD(arg && arg->type != VAL_NUM && arg->type != VAL_LIST,
-              "mean", "a number or a list of numbers", make_num(0.0));
+    ARG_GUARD(arg && arg->type != VAL_NUM && arg->type != VAL_LIST
+              && arg->type != VAL_BUFFER,   /* #1093 */
+              "mean", "a number, a list of numbers or a buffer", make_num(0.0));
     int total = tensor_total(arg);
     /* fs:EMPTY nothing to average, and the division below would be 0/0. The
      * non-tensor case is gone (guarded above), so this line now carries one
@@ -629,8 +735,9 @@ Value* builtin_tensor_sum(Value *arg) {
      * tagged fs:EMPTY, which would have blessed the laundering permanently),
      * so the type half is hoisted out. Non-strict is byte-identical: both
      * halves still answer 0.0. Closes the main half of #1008. */
-    ARG_GUARD(arg && arg->type != VAL_NUM && arg->type != VAL_LIST,
-              "sum", "a number or a list of numbers", make_num(0.0));
+    ARG_GUARD(arg && arg->type != VAL_NUM && arg->type != VAL_LIST
+              && arg->type != VAL_BUFFER,   /* #1093 */
+              "sum", "a number, a list of numbers or a buffer", make_num(0.0));
     int total = tensor_total(arg);
     /* fs:EMPTY 0.0 is the additive identity this loop would accumulate over
      * zero elements. The non-tensor case is guarded above, so `sum of []` is
@@ -662,8 +769,9 @@ Value* builtin_tensor_norm(Value *arg) {
      * tagged fs:EMPTY, which would have blessed the laundering permanently),
      * so the type half is hoisted out. Non-strict is byte-identical: both
      * halves still answer 0.0. Closes the main half of #1008. */
-    ARG_GUARD(arg && arg->type != VAL_NUM && arg->type != VAL_LIST,
-              "norm", "a number or a list of numbers", make_num(0.0));
+    ARG_GUARD(arg && arg->type != VAL_NUM && arg->type != VAL_LIST
+              && arg->type != VAL_BUFFER,   /* #1093 */
+              "norm", "a number, a list of numbers or a buffer", make_num(0.0));
     int total = tensor_total(arg);
     /* fs:EMPTY the L2 norm over zero elements is sqrt(0) = 0, exactly what the
      * loop below would produce. The non-tensor case is guarded above. */
@@ -682,18 +790,23 @@ Value* builtin_tensor_norm(Value *arg) {
 #define TENSOR_LIST_ELEM_BYTES (sizeof(Value) + sizeof(Value *))
 
 /* ==== BUILTIN: zeros ==== */
+/* zeros of n → a BUFFER of n zeros (#1093); zeros of [rows, cols] → 2D list */
 Value* builtin_tensor_zeros(Value *arg) {
     if (!arg) return make_null();
-    /* zeros of n → 1D list of n zeros */
+    /* #1093 (breaking, documented): `zeros of n` is the FLAT numeric
+     * container — a VAL_BUFFER of n doubles, not a list of n boxed numbers.
+     * `zeros of [rows, cols]` below is unchanged and still builds the nested
+     * list tensor. Consumers reach for `zeros` because it is the natural name
+     * (dynamics' `x is zeros of n`, iLambdaAi's `b is zeros of (w * w)`), and
+     * the list cost a Value per element on the VM and 12.4x on the AOT
+     * (ouroboros#170). make_shaped_buffer carries the sandbox charge, which
+     * is now 8 bytes/element instead of TENSOR_LIST_ELEM_BYTES. */
     if (arg->type == VAL_NUM) {
         int64_t n64 = (int64_t)arg->data.num;
         if (n64 < 0) n64 = 0;
         if (n64 > 10000000) n64 = 10000000;  /* #292: cap like fill/buffer (was uncapped → x_oom/abort) */
-        int n = (int)n64;
-        if (!sandbox_charge((size_t)n * TENSOR_LIST_ELEM_BYTES)) return make_null();
-        Value *out = make_list(n);
-        for (int i = 0; i < n; i++) list_append_owned(out, make_num(0.0));
-        return out;
+        Value *out = make_shaped_buffer(0, (int)n64);
+        return out ? out : make_null();
     }
     /* zeros of [rows, cols] → 2D */
     if (arg->type == VAL_LIST && arg->data.list.count >= 2
@@ -722,6 +835,7 @@ Value* builtin_tensor_zeros(Value *arg) {
 }
 
 /* ==== BUILTIN: zeros_like ==== */
+/* zeros_like of t → zeros matching t's shape AND container (buffer→buffer) */
 Value* builtin_tensor_zeros_like(Value *arg) {
     if (!arg) return make_null();
     /* fs:LITERAL a number is a valid argument and this IS the value being
@@ -734,10 +848,34 @@ Value* builtin_tensor_zeros_like(Value *arg) {
             list_append_owned(out, builtin_tensor_zeros_like(arg->data.list.items[i]));
         return out;
     }
-    /* Both shapes zeros_like can mirror exit above, so `arg` is neither a
-     * number nor a list (a string, a dict — or a BUFFER, whose zero should be
-     * a zero buffer, not the scalar 0.0 this used to hand back). */
-    ARG_GUARD(1, "zeros_like", "a number or a list", make_num(0.0));
+    /* #1093: a buffer's zero is a zero BUFFER of the same shape, not the
+     * scalar 0.0 the guard below used to hand back. */
+    if (arg->type == VAL_BUFFER) {
+        Value *out = make_buffer_like(arg);
+        return out ? out : make_null();
+    }
+    /* Every shape zeros_like can mirror exits above, so `arg` is none of them
+     * (a string, a dict, a function). */
+    ARG_GUARD(1, "zeros_like", "a number, a list or a buffer", make_num(0.0));
+}
+
+/* #1093: an index vector is a flat numeric tensor, so it may be a list or a
+ * buffer. A non-numeric list element reads as -1, the out-of-range sentinel
+ * the index loops already skip on. */
+static int flat_count(Value *v) {
+    if (!v) return 0;
+    if (v->type == VAL_LIST) return v->data.list.count;
+    if (v->type == VAL_BUFFER) return v->data.buffer.count;
+    return 0;
+}
+static int flat_is_vector(Value *v) {
+    return v && (v->type == VAL_LIST || v->type == VAL_BUFFER);
+}
+static int flat_index_at(Value *v, int i) {
+    if (v->type == VAL_LIST)
+        return (v->data.list.items[i]->type == VAL_NUM)
+             ? (int)v->data.list.items[i]->data.num : -1;
+    return (int)v->data.buffer.data[i];
 }
 
 /* ==== BUILTIN: gather ==== */
@@ -746,6 +884,33 @@ Value* builtin_tensor_gather(Value *arg) {
     if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2) return make_null();
     Value *tensor = arg->data.list.items[0];
     Value *indices = arg->data.list.items[1];
+    /* #1093: a buffer tensor. A shaped (2-D) buffer with one index per row
+     * selects one element per row and yields a buffer; an unshaped (1-D)
+     * buffer with a scalar index yields that element. Out-of-range and
+     * wrong-shape readings mirror the list branches below: 0.0 per row for a
+     * bad index, and the trailing 0.0 for a scalar index off the end. */
+    if (tensor->type == VAL_BUFFER) {
+        if (indices->type == VAL_NUM && tensor->data.buffer.rows == 0) {
+            int idx = (int)indices->data.num;
+            if (idx >= 0 && idx < tensor->data.buffer.count)
+                return make_num(tensor->data.buffer.data[idx]);
+        } else if (flat_is_vector(indices)) {
+            int shaped = tensor->data.buffer.rows > 0;
+            int rows = shaped ? tensor->data.buffer.rows : tensor->data.buffer.count;
+            int cols = shaped ? tensor->data.buffer.cols : 0;
+            int icount = flat_count(indices);
+            int n = rows < icount ? rows : icount;
+            Value *out = make_shaped_buffer(0, n);
+            if (!out) return make_null();
+            for (int i = 0; i < n; i++) {
+                int idx = flat_index_at(indices, i);
+                out->data.buffer.data[i] =
+                    (shaped && idx >= 0 && idx < cols)
+                    ? tensor->data.buffer.data[(int64_t)i * cols + idx] : 0.0;
+            }
+            return out;
+        }
+    }
     /* Simple case: 2D tensor, 1D indices → select one element per row */
     if (tensor->type == VAL_LIST && indices->type == VAL_LIST) {
         int n = tensor->data.list.count < indices->data.list.count
@@ -970,6 +1135,28 @@ Value* builtin_numerical_grad(Value *arg) {
     double eps = (arg->data.list.items[2]->type == VAL_NUM) ? arg->data.list.items[2]->data.num : 0.001;
     if (eps <= 0) eps = 0.001;
 
+    /* #1093: a buffer param is a flat numeric tensor — perturb the doubles in
+     * place and return a gradient buffer of the same shape. */
+    if (param->type == VAL_BUFFER) {
+        Value *grad = make_buffer_like(param);
+        if (!grad) return make_null();
+        Value *bnul = make_null();
+        for (int i = 0; i < param->data.buffer.count; i++) {
+            double old_val = param->data.buffer.data[i];
+            param->data.buffer.data[i] = old_val + eps;
+            Value *lp = call_eigs_fn(loss_fn, bnul);
+            double loss_plus = (lp && lp->type == VAL_NUM) ? lp->data.num : 0.0;
+            if (lp) val_decref(lp);
+            param->data.buffer.data[i] = old_val - eps;
+            Value *lm = call_eigs_fn(loss_fn, bnul);
+            double loss_minus = (lm && lm->type == VAL_NUM) ? lm->data.num : 0.0;
+            if (lm) val_decref(lm);
+            param->data.buffer.data[i] = old_val;
+            grad->data.buffer.data[i] = (loss_plus - loss_minus) / (2.0 * eps);
+        }
+        val_decref(bnul);
+        return grad;
+    }
     if (param->type != VAL_LIST) return make_null();
     Value *nul = make_null();   /* shared arg for loss_fn calls */
 
@@ -1047,6 +1234,14 @@ Value* builtin_sgd_update(Value *arg) {
     Value *grad = arg->data.list.items[1];
     double lr = (arg->data.list.items[2]->type == VAL_NUM) ? arg->data.list.items[2]->data.num : 0.01;
 
+    /* #1093: both operands flat buffers — update the doubles in place. */
+    if (param->type == VAL_BUFFER && grad->type == VAL_BUFFER) {
+        int len = param->data.buffer.count < grad->data.buffer.count
+                ? param->data.buffer.count : grad->data.buffer.count;
+        for (int i = 0; i < len; i++)
+            param->data.buffer.data[i] -= lr * grad->data.buffer.data[i];
+        return param;
+    }
     if (param->type != VAL_LIST || grad->type != VAL_LIST) return param;
 
     int is_2d = (param->data.list.count > 0 && param->data.list.items[0]->type == VAL_LIST);
@@ -1097,7 +1292,38 @@ Value* builtin_numerical_grad_rows(Value *arg) {
     double eps = (arg->data.list.items[3]->type == VAL_NUM) ? arg->data.list.items[3]->data.num : 0.001;
     if (eps <= 0) eps = 0.001;
 
-    if (matrix->type != VAL_LIST || row_indices->type != VAL_LIST) return make_null();
+    /* #1093: a shaped buffer is the flat 2-D matrix and the index vector may
+     * be a list or a buffer. The gradient comes back in the same container,
+     * zero for every row not named. */
+    if (matrix->type == VAL_BUFFER && matrix->data.buffer.rows > 0
+        && flat_is_vector(row_indices)) {
+        int brows = matrix->data.buffer.rows, bcols = matrix->data.buffer.cols;
+        Value *bgrad = make_buffer_like(matrix);
+        if (!bgrad) return make_null();
+        Value *bnul = make_null();
+        int nidx = flat_count(row_indices);
+        for (int ri = 0; ri < nidx; ri++) {
+            int r = flat_index_at(row_indices, ri);
+            if (r < 0 || r >= brows) continue;
+            for (int c = 0; c < bcols; c++) {
+                int64_t k = (int64_t)r * bcols + c;
+                double old_val = matrix->data.buffer.data[k];
+                matrix->data.buffer.data[k] = old_val + eps;
+                Value *lp = call_eigs_fn(loss_fn, bnul);
+                double loss_plus = (lp && lp->type == VAL_NUM) ? lp->data.num : 0.0;
+                if (lp) val_decref(lp);
+                matrix->data.buffer.data[k] = old_val - eps;
+                Value *lm = call_eigs_fn(loss_fn, bnul);
+                double loss_minus = (lm && lm->type == VAL_NUM) ? lm->data.num : 0.0;
+                if (lm) val_decref(lm);
+                matrix->data.buffer.data[k] = old_val;
+                bgrad->data.buffer.data[k] = (loss_plus - loss_minus) / (2.0 * eps);
+            }
+        }
+        val_decref(bnul);
+        return bgrad;
+    }
+    if (matrix->type != VAL_LIST || !flat_is_vector(row_indices)) return make_null();
 
     int rows = matrix->data.list.count;
     if (rows == 0 || matrix->data.list.items[0]->type != VAL_LIST) return make_null();
@@ -1114,9 +1340,8 @@ Value* builtin_numerical_grad_rows(Value *arg) {
     }
 
     /* Only compute gradients for specified rows */
-    for (int ri = 0; ri < row_indices->data.list.count; ri++) {
-        int r = (row_indices->data.list.items[ri]->type == VAL_NUM)
-              ? (int)row_indices->data.list.items[ri]->data.num : -1;
+    for (int ri = 0; ri < flat_count(row_indices); ri++) {
+        int r = flat_index_at(row_indices, ri);
         if (r < 0 || r >= rows) continue;
 
         Value *row = matrix->data.list.items[r];
@@ -1154,12 +1379,28 @@ Value* builtin_sgd_update_rows(Value *arg) {
     Value *row_indices = arg->data.list.items[2];
     double lr = (arg->data.list.items[3]->type == VAL_NUM) ? arg->data.list.items[3]->data.num : 0.01;
 
-    if (matrix->type != VAL_LIST || grad->type != VAL_LIST || row_indices->type != VAL_LIST)
+    /* #1093: shaped-buffer matrix + shaped-buffer gradient, index vector as a
+     * list or a buffer — update the named rows' doubles in place. */
+    if (matrix->type == VAL_BUFFER && grad->type == VAL_BUFFER
+        && matrix->data.buffer.rows > 0 && flat_is_vector(row_indices)) {
+        int brows = matrix->data.buffer.rows, bcols = matrix->data.buffer.cols;
+        if (grad->data.buffer.rows < brows) brows = grad->data.buffer.rows;
+        if (grad->data.buffer.cols < bcols) bcols = grad->data.buffer.cols;
+        int nidx = flat_count(row_indices);
+        for (int ri = 0; ri < nidx; ri++) {
+            int r = flat_index_at(row_indices, ri);
+            if (r < 0 || r >= brows) continue;
+            for (int c = 0; c < bcols; c++)
+                matrix->data.buffer.data[(int64_t)r * matrix->data.buffer.cols + c] -=
+                    lr * grad->data.buffer.data[(int64_t)r * grad->data.buffer.cols + c];
+        }
+        return matrix;
+    }
+    if (matrix->type != VAL_LIST || grad->type != VAL_LIST || !flat_is_vector(row_indices))
         return matrix;
 
-    for (int ri = 0; ri < row_indices->data.list.count; ri++) {
-        int r = (row_indices->data.list.items[ri]->type == VAL_NUM)
-              ? (int)row_indices->data.list.items[ri]->data.num : -1;
+    for (int ri = 0; ri < flat_count(row_indices); ri++) {
+        int r = flat_index_at(row_indices, ri);
         if (r < 0 || r >= matrix->data.list.count || r >= grad->data.list.count) continue;
 
         Value *mrow = matrix->data.list.items[r];
@@ -1192,7 +1433,36 @@ Value* builtin_numerical_grad_cols(Value *arg) {
     double eps = (arg->data.list.items[3]->type == VAL_NUM) ? arg->data.list.items[3]->data.num : 0.001;
     if (eps <= 0) eps = 0.001;
 
-    if (matrix->type != VAL_LIST || col_indices->type != VAL_LIST) return make_null();
+    /* #1093: shaped-buffer matrix, list-or-buffer index vector. */
+    if (matrix->type == VAL_BUFFER && matrix->data.buffer.rows > 0
+        && flat_is_vector(col_indices)) {
+        int brows = matrix->data.buffer.rows, bcols = matrix->data.buffer.cols;
+        Value *bgrad = make_buffer_like(matrix);
+        if (!bgrad) return make_null();
+        Value *bnul = make_null();
+        int nidx = flat_count(col_indices);
+        for (int ci = 0; ci < nidx; ci++) {
+            int col = flat_index_at(col_indices, ci);
+            if (col < 0 || col >= bcols) continue;
+            for (int r = 0; r < brows; r++) {
+                int64_t k = (int64_t)r * bcols + col;
+                double old_val = matrix->data.buffer.data[k];
+                matrix->data.buffer.data[k] = old_val + eps;
+                Value *lp = call_eigs_fn(loss_fn, bnul);
+                double loss_plus = (lp && lp->type == VAL_NUM) ? lp->data.num : 0.0;
+                if (lp) val_decref(lp);
+                matrix->data.buffer.data[k] = old_val - eps;
+                Value *lm = call_eigs_fn(loss_fn, bnul);
+                double loss_minus = (lm && lm->type == VAL_NUM) ? lm->data.num : 0.0;
+                if (lm) val_decref(lm);
+                matrix->data.buffer.data[k] = old_val;
+                bgrad->data.buffer.data[k] = (loss_plus - loss_minus) / (2.0 * eps);
+            }
+        }
+        val_decref(bnul);
+        return bgrad;
+    }
+    if (matrix->type != VAL_LIST || !flat_is_vector(col_indices)) return make_null();
 
     int rows = matrix->data.list.count;
     if (rows == 0 || matrix->data.list.items[0]->type != VAL_LIST) return make_null();
@@ -1209,9 +1479,8 @@ Value* builtin_numerical_grad_cols(Value *arg) {
     }
 
     /* Only compute gradients for specified columns, across all rows */
-    for (int ci = 0; ci < col_indices->data.list.count; ci++) {
-        int col = (col_indices->data.list.items[ci]->type == VAL_NUM)
-                ? (int)col_indices->data.list.items[ci]->data.num : -1;
+    for (int ci = 0; ci < flat_count(col_indices); ci++) {
+        int col = flat_index_at(col_indices, ci);
         if (col < 0 || col >= cols) continue;
 
         for (int r = 0; r < rows; r++) {
@@ -1257,15 +1526,30 @@ Value* builtin_sgd_update_cols(Value *arg) {
     Value *col_indices = arg->data.list.items[2];
     double lr = (arg->data.list.items[3]->type == VAL_NUM) ? arg->data.list.items[3]->data.num : 0.01;
 
-    if (matrix->type != VAL_LIST || grad->type != VAL_LIST || col_indices->type != VAL_LIST)
+    /* #1093: shaped-buffer matrix + gradient, list-or-buffer index vector. */
+    if (matrix->type == VAL_BUFFER && grad->type == VAL_BUFFER
+        && matrix->data.buffer.rows > 0 && flat_is_vector(col_indices)) {
+        int brows = matrix->data.buffer.rows;
+        if (grad->data.buffer.rows < brows) brows = grad->data.buffer.rows;
+        int nidx = flat_count(col_indices);
+        for (int ci = 0; ci < nidx; ci++) {
+            int col = flat_index_at(col_indices, ci);
+            if (col < 0 || col >= matrix->data.buffer.cols
+                || col >= grad->data.buffer.cols) continue;
+            for (int r = 0; r < brows; r++)
+                matrix->data.buffer.data[(int64_t)r * matrix->data.buffer.cols + col] -=
+                    lr * grad->data.buffer.data[(int64_t)r * grad->data.buffer.cols + col];
+        }
+        return matrix;
+    }
+    if (matrix->type != VAL_LIST || grad->type != VAL_LIST || !flat_is_vector(col_indices))
         return matrix;
 
     int rows = matrix->data.list.count < grad->data.list.count
              ? matrix->data.list.count : grad->data.list.count;
 
-    for (int ci = 0; ci < col_indices->data.list.count; ci++) {
-        int col = (col_indices->data.list.items[ci]->type == VAL_NUM)
-                ? (int)col_indices->data.list.items[ci]->data.num : -1;
+    for (int ci = 0; ci < flat_count(col_indices); ci++) {
+        int col = flat_index_at(col_indices, ci);
         if (col < 0) continue;
 
         for (int r = 0; r < rows; r++) {
@@ -1289,8 +1573,9 @@ Value* builtin_tensor_save(Value *arg) {
               "tensor_save", "[tensor, path]", make_num(0));
     Value *tensor = arg->data.list.items[0];
     Value *path_val = arg->data.list.items[1];
-    ARG_GUARD(!tensor || tensor->type != VAL_LIST || !path_val || path_val->type != VAL_STR,
-              "tensor_save", "[a list tensor, a string path]", make_num(0));
+    ARG_GUARD(!tensor || (tensor->type != VAL_LIST && tensor->type != VAL_BUFFER)
+              || !path_val || path_val->type != VAL_STR,   /* #1093 */
+              "tensor_save", "[a list or buffer tensor, a string path]", make_num(0));
 
     int rows, cols;
     int ndim = tensor_dims(tensor, &rows, &cols);
diff --git a/src/lsp_builtin_index.h b/src/lsp_builtin_index.h
index 9e7ed6da..bbbf0dfb 100644
--- a/src/lsp_builtin_index.h
+++ b/src/lsp_builtin_index.h
@@ -344,8 +344,8 @@ static const char *builtin_docs[][2] = {
     {"write", "write of value — output without trailing newline"},
     {"write_bytes", "write_bytes of [path, data, append?] — write raw bytes to a file."},
     {"write_text", "write_text of [\"path\", text] → 1 on success, 0 on failure."},
-    {"zeros", "zeros of n → 1D list of n zeros"},
-    {"zeros_like", "zeros_like — builtin; see docs/BUILTINS.md"},
+    {"zeros", "zeros of n → a BUFFER of n zeros (#1093); zeros of [rows, cols] → 2D list"},
+    {"zeros_like", "zeros_like of t → zeros matching t's shape AND container (buffer→buffer)"},
     {"zlib_deflate", "zlib_deflate — builtin; see docs/BUILTINS.md"},
     {"zlib_inflate", "zlib_inflate — builtin; see docs/BUILTINS.md"},
     {0, 0}
diff --git a/tests/observer_corpus/README.md b/tests/observer_corpus/README.md
index 504509d8..b0735c98 100644
--- a/tests/observer_corpus/README.md
+++ b/tests/observer_corpus/README.md
@@ -43,6 +43,22 @@ trajectory over a growing container). Keep at least one container-observing
 program in the corpus — a scalar-only corpus is silently narrower than it
 looks.
 
+## Golden recapture note (#1093, 2026-09-07)
+
+`dynamics__solve` diverged when `zeros of n` became a flat buffer: its three
+result vectors are built with `zeros` and printed through an f-string, so
+`[0.999…, …]` became `<buffer:3>`. **Only the rendering moved.** Element-wise
+against the pre-change binary the numbers are byte-identical
+(`{rj[0][0]} {rj[0][1]} {rj[0][2]}` and the two siblings agree to the last
+digit), and every iteration count in the golden (19 / 17 / 14 / 24) is
+unchanged — so the observer-driven stopping behaviour this corpus exists to
+watch did not move. The golden was recaptured for those three lines only.
+
+Cost to record: those three lines no longer carry the solvers' numeric values,
+so the corpus watches their convergence *counts* but not their *results*. When
+`dynamics` next refreshes `solve.eigs` it should print the elements (or
+`buf_to_list`) so the numeric signal comes back.
+
 ## Sources (same-owner repos; vendored with provenance)
 - **dynamics** — `solve`/`physics`/`life`: real solvers and trajectory demos
   using `report`, the six predicates, `unobserved`, and `prev`.
diff --git a/tests/observer_corpus/golden/dynamics__solve.out b/tests/observer_corpus/golden/dynamics__solve.out
index 217b65d4..47715aa8 100644
--- a/tests/observer_corpus/golden/dynamics__solve.out
+++ b/tests/observer_corpus/golden/dynamics__solve.out
@@ -2,13 +2,13 @@
 every loop runs until `report of change` is settled and HOLDs — the observer,
 not a magnitude tolerance, decides when to stop. (iters include the hold)
 
-Jacobi        Ax=b -> [0.9999999981373549, 0.9999999962747097, 0.9999999981373549]
+Jacobi        Ax=b -> <buffer:3>
               19 iters
-Gauss-Seidel  Ax=b -> [0.9999999999999978, 0.9999999999999989, 0.9999999999999998]
+Gauss-Seidel  Ax=b -> <buffer:3>
               17 iters  (fresh values -> fewer than Jacobi)
 
 Power iteration dominant eigenvalue -> 2  (14 iters, expect ~2)
 
-PageRank stationary distribution -> [0.39998372395833337, 0.20003255208333334, 0.39998372395833337]  (24 iters)
+PageRank stationary distribution -> <buffer:3>  (24 iters)
 
 DONE
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 8d124406..9881b280 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -5621,6 +5621,16 @@ else
 fi
 echo ""
 
+echo "[93b] Tensor builtins on buffers (#1093)"
+# #1093: every tensor builtin that accepts a flat numeric list accepts a
+# VAL_BUFFER in the same position, and returns a buffer where the input was a
+# buffer. Each check is a list/buffer PAIR whose numeric output must be
+# byte-identical, so reverting any one converted guard turns that pair red.
+# Also pins Part 2: `zeros of n` is a buffer, `zeros of [r, c]` stays a list.
+check_eigs_suite "tensor builtins accept buffers; zeros of n is a buffer" \
+    "test_tensor_buffer_inputs.eigs" "TENSOR_BUFFER_INPUTS_ALL_PASS" 99
+echo ""
+
 echo "[94] --pkg dispatcher (7 checks)"
 # Phase 1a of the package design: --pkg dispatcher, manifest read/write,
 # help, list, add (manifest-only — git fetch is Phase 1b), unknown
diff --git a/tests/test_sandbox_budget.eigs b/tests/test_sandbox_budget.eigs
index ac21ef92..30dde295 100644
--- a/tests/test_sandbox_budget.eigs
+++ b/tests/test_sandbox_budget.eigs
@@ -351,9 +351,29 @@ ok_fill is (sandbox_run of [fill_desc of 1000000, 1000000, 1000])["ok"]
 assert_eq of [ok_fill, 0, "budget: fill(1M) under 1000-byte budget -> {ok:0}"]
 
 # --- 4. The DEFAULT budget (no max_bytes arg) bounds an otherwise-uncapped bomb,
-#        so it returns {ok:0} instead of x_oom/abort ---
-ok_default is (sandbox_run of [zeros_desc of 9000000, 1000000])["ok"]
-assert_eq of [ok_default, 0, "budget: default budget bounds zeros(9M) -> {ok:0}, no abort"]
+#        so it returns {ok:0} instead of x_oom/abort.
+#        #1093: `zeros of n` is a flat BUFFER now — 8 bytes/element instead of
+#        sizeof(Value)+sizeof(Value*), and capped at 10M elements, so a single
+#        `zeros` call can charge at most 80 MB and can no longer reach the
+#        256 MiB default on its own. The bomb is therefore four maximal
+#        allocations whose CUMULATIVE charge crosses the default, and the
+#        assertion now names the memory diagnostic: a bare `zeros(9M)` is still
+#        refused, but by the boundary result-scan (pinned separately below),
+#        and reading that refusal as "the byte budget held" would be wrong. ---
+big_alloc_desc is [ABI, [GET_NAME,0,0, CONST,1,0, CALL,1,0, POP,
+                         GET_NAME,0,0, CONST,1,0, CALL,1,0, POP,
+                         GET_NAME,0,0, CONST,1,0, CALL,1,0, POP,
+                         GET_NAME,0,0, CONST,1,0, CALL,1,0, POP,
+                         CONST,2,0, RETURN], ["zeros", 10000000, 0]]
+sr_default is sandbox_run of [big_alloc_desc, 1000000]
+assert_eq of [sr_default["ok"], 0, "budget: default budget bounds 4x zeros(10M) -> {ok:0}, no abort"]
+assert_true of [(index_of of [sr_default["error"]["message"], "memory budget exceeded"]) >= 0,
+                "budget: the default-budget refusal is the MEMORY diagnostic, not a boundary one"]
+# #1093: the old zeros(9M) bomb is still refused under the default budget, but
+# now at the result boundary (a 9M-element buffer exceeds the callable-scan
+# node budget). Pinned so the change of MECHANISM stays visible.
+sr_zeros9 is sandbox_run of [zeros_desc of 9000000, 1000000]
+assert_eq of [sr_zeros9["ok"], 0, "budget: zeros(9M) under the default budget is still refused"]
 
 # --- 5. CUMULATIVE (F2): two fills that each fit but together exceed the budget.
 #        fill(60k) result stays under the boundary result-scan budget
diff --git a/tests/test_tensor_buffer_inputs.eigs b/tests/test_tensor_buffer_inputs.eigs
new file mode 100644
index 00000000..9a617680
--- /dev/null
+++ b/tests/test_tensor_buffer_inputs.eigs
@@ -0,0 +1,248 @@
+# #1093 Part 1 — tensor builtins accept VAL_BUFFER wherever they accept a flat
+# numeric list, and return a buffer where the input was a buffer.
+#
+# Every check is a PAIR: the same call run on a list tensor and on the
+# equivalent buffer tensor. The numeric output must be byte-identical (both
+# sides are flattened to the same ";"-joined decimal string), and where the
+# issue says a buffer input yields a buffer output, the container is asserted
+# too. Nested (2-D) LIST inputs keep their list semantics — the 2-D pairs use a
+# shaped buffer (`reshape of [buf, r, c]`) against a nested list.
+#
+# Before this change the buffer half of each pair answered 0, null, or the
+# scalar 0.0 (see the issue's 38-guard census); reverting any one guard turns
+# that pair's "numbers match" assertion red.
+
+load_file of "lib/test.eigs"
+
+# ---- flatten either container to one comparable string ----
+define flat_str(v) as:
+    s is ""
+    if (type of v) == "buffer":
+        for i in range of (len of v):
+            s is s + (str of v[i]) + ";"
+        return s
+    if (type of v) == "list":
+        for i in range of (len of v):
+            e is v[i]
+            if (type of e) == "list":
+                for j in range of (len of e):
+                    s is s + (str of e[j]) + ";"
+            else:
+                s is s + (str of e) + ";"
+        return s
+    return "scalar:" + (str of v)
+
+# name, list-side result, buffer-side result, want_buffer (1/0)
+define pair(name, lres, bres, want_buffer) as:
+    assert_eq of [(flat_str of bres), (flat_str of lres), name + ": list/buffer numbers identical"]
+    if want_buffer == 1:
+        assert_eq of [(type of bres), "buffer", name + ": buffer in -> buffer out"]
+    else:
+        assert_eq of [(type of bres), (type of lres), name + ": container matches the list side"]
+
+# ---- operands: 1-D ----
+la is [1.0, 2.0, 3.0, 4.0]
+lb is [0.5, 1.0, 1.5, 2.0]
+ba is buf_from_list of la
+bb is buf_from_list of lb
+
+# ---- operands: 2-D (nested list vs shaped buffer) ----
+l2 is [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
+b2 is reshape of [buf_from_list of [1.0, 2.0, 3.0, 4.0, 5.0, 6.0], 2, 3]
+l3 is [[1.0, 0.0], [0.0, 1.0], [1.0, 1.0]]
+b3 is reshape of [buf_from_list of [1.0, 0.0, 0.0, 1.0, 1.0, 1.0], 3, 2]
+
+# ============ elementwise binaries (5 builtins) ============
+pair of ["add",      (add of [la, lb]),      (add of [ba, bb]),      1]
+pair of ["subtract", (subtract of [la, lb]), (subtract of [ba, bb]), 1]
+pair of ["multiply", (multiply of [la, lb]), (multiply of [ba, bb]), 1]
+pair of ["divide",   (divide of [la, lb]),   (divide of [ba, bb]),   1]
+pair of ["pow",      (pow of [la, lb]),      (pow of [ba, bb]),      1]
+
+# scalar broadcast, both operand orders
+pair of ["add scalar-right", (add of [la, 10.0]), (add of [ba, 10.0]), 1]
+pair of ["divide scalar-left", (divide of [100.0, la]), (divide of [100.0, ba]), 1]
+
+# 2-D row-vector broadcast (the neural bias shape): matrix + row vector
+pair of ["add 2-D + row bias", (add of [l2, [10.0, 20.0, 30.0]]),
+         (add of [b2, (buf_from_list of [10.0, 20.0, 30.0])]), 1]
+
+# MIXED buffer/list: every tensor operand must be a buffer for a buffer out,
+# so this one deliberately yields a LIST and still matches numerically.
+mixed is add of [ba, lb]
+assert_eq of [(flat_str of mixed), (flat_str of (add of [la, lb])), "add mixed buffer/list: numbers identical"]
+assert_eq of [(type of mixed), "list", "add mixed buffer/list: list container wins"]
+
+# ============ elementwise unaries (4 builtins) ============
+pair of ["sqrt",     (sqrt of la),     (sqrt of ba),     1]
+pair of ["exp",      (exp of la),      (exp of ba),      1]
+pair of ["log",      (log of la),      (log of ba),      1]
+pair of ["negative", (negative of la), (negative of ba), 1]
+
+# ============ matmul ============
+pair of ["matmul 2-D", (matmul of [l2, l3]), (matmul of [b2, b3]), 1]
+# 1-D left operand keeps the 1-D result shape on both sides
+pair of ["matmul 1-D x 2-D", (matmul of [[1.0, 2.0, 3.0], l3]),
+         (matmul of [(buf_from_list of [1.0, 2.0, 3.0]), b3]), 1]
+
+# ============ shape-preserving activations (4 builtins) ============
+pair of ["softmax 1-D",     (softmax of la),     (softmax of ba),     1]
+pair of ["softmax 2-D",     (softmax of l2),     (softmax of b2),     1]
+pair of ["log_softmax",     (log_softmax of la), (log_softmax of ba), 1]
+sgn is [-2.0, -0.5, 0.0, 3.0]
+bsgn is buf_from_list of sgn
+pair of ["relu",            (relu of sgn),       (relu of bsgn),      1]
+pair of ["leaky_relu",      (leaky_relu of sgn), (leaky_relu of bsgn), 1]
+
+# ============ reductions to a scalar (3 builtins) ============
+assert_eq of [(sum of ba),  (sum of la),  "sum: list/buffer identical"]
+assert_eq of [(mean of ba), (mean of la), "mean: list/buffer identical"]
+assert_eq of [(norm of ba), (norm of la), "norm: list/buffer identical"]
+assert_eq of [(sum of b2),  (sum of l2),  "sum 2-D: list/buffer identical"]
+assert_eq of [(mean of b2), (mean of l2), "mean 2-D: list/buffer identical"]
+
+# ============ shape ============
+pair of ["shape 1-D", (shape of la), (shape of ba), 0]
+pair of ["shape 2-D", (shape of l2), (shape of b2), 0]
+
+# ============ zeros_like ============
+pair of ["zeros_like 1-D", (zeros_like of la), (zeros_like of ba), 1]
+pair of ["zeros_like 2-D", (zeros_like of l2), (zeros_like of b2), 1]
+
+# ============ gather ============
+# 2-D tensor + one index per row
+pair of ["gather 2-D", (gather of [l2, [2, 0]]), (gather of [b2, [2, 0]]), 1]
+# index vector may itself be a buffer
+pair of ["gather 2-D buffer indices", (gather of [l2, [2, 0]]),
+         (gather of [b2, (buf_from_list of [2, 0])]), 1]
+# 1-D tensor + scalar index -> the element
+assert_eq of [(gather of [ba, 2]), (gather of [la, 2]), "gather 1-D scalar index"]
+
+# ============ reshape (buffer-native) ============
+rs is reshape of [ba, 2, 2]
+assert_eq of [(type of rs), "buffer", "reshape: buffer stays a buffer"]
+assert_eq of [(flat_str of rs), (flat_str of ba), "reshape: payload preserved"]
+assert_eq of [(str of (shape of rs)), "[2, 2]", "reshape: shape applied"]
+
+# ============ tensor_save / tensor_load ============
+tpath is "/tmp/eigs_1093_tensor_buffer.bin"
+assert_eq of [(tensor_save of [ba, tpath]), 1, "tensor_save accepts a buffer"]
+reloaded is tensor_load of tpath
+assert_eq of [(flat_str of reloaded), (flat_str of la), "tensor_save/load buffer round trip"]
+remove_file of tpath
+
+# ============ numerical_grad / sgd_update ============
+gl is [1.0, 2.0, 3.0]
+gb is buf_from_list of [1.0, 2.0, 3.0]
+define loss_l as:
+    return sum of (multiply of [gl, gl])
+define loss_b as:
+    return sum of (multiply of [gb, gb])
+pair of ["numerical_grad 1-D", (numerical_grad of [loss_l, gl, 0.001]),
+         (numerical_grad of [loss_b, gb, 0.001]), 1]
+
+ul is [1.0, 2.0, 3.0]
+ub is buf_from_list of [1.0, 2.0, 3.0]
+gradl is [0.5, 0.5, 0.5]
+gradb is buf_from_list of [0.5, 0.5, 0.5]
+pair of ["sgd_update 1-D", (sgd_update of [ul, gradl, 0.1]),
+         (sgd_update of [ub, gradb, 0.1]), 1]
+
+# ============ numerical_grad_rows / sgd_update_rows ============
+ml is [[1.0, 2.0], [3.0, 4.0]]
+mb is reshape of [buf_from_list of [1.0, 2.0, 3.0, 4.0], 2, 2]
+define mloss_l as:
+    return sum of (multiply of [ml, ml])
+define mloss_b as:
+    return sum of (multiply of [mb, mb])
+pair of ["numerical_grad_rows", (numerical_grad_rows of [mloss_l, ml, [0], 0.001]),
+         (numerical_grad_rows of [mloss_b, mb, [0], 0.001]), 1]
+pair of ["numerical_grad_cols", (numerical_grad_cols of [mloss_l, ml, [1], 0.001]),
+         (numerical_grad_cols of [mloss_b, mb, [1], 0.001]), 1]
+
+srl is [[1.0, 2.0], [3.0, 4.0]]
+srb is reshape of [buf_from_list of [1.0, 2.0, 3.0, 4.0], 2, 2]
+sgl is [[0.5, 0.5], [0.5, 0.5]]
+sgb is reshape of [buf_from_list of [0.5, 0.5, 0.5, 0.5], 2, 2]
+pair of ["sgd_update_rows", (sgd_update_rows of [srl, sgl, [1], 0.1]),
+         (sgd_update_rows of [srb, sgb, [1], 0.1]), 1]
+
+scl is [[1.0, 2.0], [3.0, 4.0]]
+scb is reshape of [buf_from_list of [1.0, 2.0, 3.0, 4.0], 2, 2]
+scgl is [[0.25, 0.25], [0.25, 0.25]]
+scgb is reshape of [buf_from_list of [0.25, 0.25, 0.25, 0.25], 2, 2]
+pair of ["sgd_update_cols", (sgd_update_cols of [scl, scgl, [0], 0.1]),
+         (sgd_update_cols of [scb, scgb, [0], 0.1]), 1]
+
+# ============ set_at / get_at on buffers (#1093) ============
+# `zeros of n` is a buffer now, so the indexed accessors must take one — and
+# must report a bad index the way the `[]` operator already does, not with a
+# second wording for the same fault.
+sa is buffer of 3
+set_at of [sa, 0, 1.5]
+assert_eq of [(get_at of [sa, 0]), 1.5, "set_at/get_at on a 1-D buffer"]
+set_at of [sa, 0 - 1, 3.5]
+assert_eq of [(get_at of [sa, 0 - 1]), 3.5, "set_at/get_at negative index counts from the end"]
+ss is reshape of [buf_from_list of [1.0, 2.0, 3.0, 4.0], 2, 2]
+set_at of [ss, 1, 0, 9.0]
+assert_eq of [(get_at of [ss, 1, 0]), 9.0, "set_at/get_at [row, col] on a shaped buffer"]
+assert_eq of [(get_at of [ss, 0, 1]), 2.0, "get_at [row, col] reads row-major"]
+caught1 is ""
+try:
+    set_at of [sa, 0, "x"]
+catch e1:
+    caught1 is e1.message
+assert_eq of [caught1, "cannot store str in a buffer (buffers hold numbers)",
+              "set_at refuses a non-number loudly"]
+caught2 is ""
+try:
+    print of (get_at of [sa, 9])
+catch e2:
+    caught2 is e2.message
+caught3 is ""
+try:
+    print of sa[9]
+catch e3:
+    caught3 is e3.message
+assert_eq of [caught2, "buffer index 9 out of range (length 3)", "get_at out of range is loud"]
+assert_eq of [caught3, caught2, "get_at and [] report the same out-of-range fault identically"]
+
+# ============ #1093 Part 2: zeros of n IS a buffer ============
+z is zeros of 4
+assert_eq of [(type of z), "buffer", "zeros of n returns a buffer"]
+assert_eq of [(str of z), "<buffer:4>", "zeros of n prints as <buffer:N>"]
+assert_eq of [(len of z), 4, "zeros of n has n elements"]
+assert_eq of [z[0], 0.0, "zeros of n is zero-filled"]
+z2 is zeros of [2, 3]
+assert_eq of [(type of z2), "list", "zeros of [r, c] stays a nested list"]
+assert_eq of [(type of z2[0]), "list", "zeros of [r, c] rows are lists"]
+assert_eq of [(len of z2[0]), 3, "zeros of [r, c] column count"]
+assert_eq of [(type of (zeros_like of (zeros of 4))), "buffer", "zeros_like of a buffer is a buffer"]
+assert_eq of [(type of (zeros_like of (zeros of [2, 2]))), "list", "zeros_like of a list is a list"]
+
+# The bar's chained cases: these were errors while zeros returned a list only
+# for the list side and buffers were rejected by the tensor layer.
+assert_eq of [(sum of (zeros of 5)), 0.0, "sum of (zeros of n)"]
+assert_eq of [(mean of (zeros of 5)), 0.0, "mean of (zeros of n)"]
+assert_eq of [(norm of (zeros of 5)), 0.0, "norm of (zeros of n)"]
+assert_eq of [(type of (reshape of [(zeros of 6), 2, 3])), "buffer", "reshape of (zeros of n)"]
+zm is matmul of [(reshape of [(zeros of 6), 2, 3]), (reshape of [(zeros of 6), 3, 2])]
+assert_eq of [(str of (shape of zm)), "[2, 2]", "matmul of reshaped zeros"]
+
+# ============ ouroboros#170's motivating case ============
+# A 200k-element numeric map. `zeros of n` and `buffer of n` must now agree
+# element for element — that equality is what makes `zeros` safe to make fast.
+N is 200000
+zv is zeros of N
+bv is buffer of N
+i is 0
+loop while i < N:
+    zv[i] is i * 0.5
+    bv[i] is i * 0.5
+    i is i + 1
+assert_eq of [(type of zv), "buffer", "200k map: zeros of n is a buffer"]
+assert_eq of [(sum of zv), (sum of bv), "200k map: zeros of n == buffer of n"]
+assert_eq of [(norm of zv), (norm of bv), "200k map: norm agrees"]
+
+test_summary of null
+print of "TENSOR_BUFFER_INPUTS_ALL_PASS"

From 49b33aa342b34c81616b687b1ed4819d95f3aeae Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 08:41:09 +0000
Subject: [PATCH 17/39] observer gate: resolve literal imports at compile time;
 match names on OP_GET_NAME, not string data (#1046, #915)

The write-path gate (#915) armed on the PRESENCE of any `import` (OP_IMPORT
sat in opcode_is_observer_reader) and on any string constant spelling an
observer builtin's name (const_pool_names_observer matched the whole pool).
Both were conservative stand-ins for scans nobody had written; both cost
read-free programs their gate.

Repro (issue rows, baseline v0.43.0 binary, EIGS_OBS_GATE_STATS=1):
    D:     msg is "report" + 200k-frame write loop        -> obs-gate: observed
    imp_b: import linalg (never used) + the same loop     -> obs-gate: observed
    ctl:   host with pre-import history; import probe     -> observed / diverging
After (this build), n=5 medians, wall seconds, under load (~1.4 avg), provisional:
    A  loads wlib only        0.035 -> 0.035  unobserved -> unobserved
    B  + load_file dead read  0.049 -> 0.051  observed   -> observed   (per-function liveness, out of scope)
    C  + load_file control    0.036 -> 0.037  unobserved -> unobserved
    D  msg is "report"        0.051 -> 0.030  observed   -> unobserved (row A is 0.035)
    imp_a no import           0.023 -> 0.019  unobserved -> unobserved
    imp_b + import linalg     0.032 -> 0.021  observed   -> unobserved (row imp_a is 0.019)
    ctl   import reader       diverging -> diverging, observed both sides (rc=0)

What changed:
  * src/builtins_host.c: eigs_import_resolve() -- the ONE `import NAME`
    resolver (project-first, then stdlib, #821/#904/#1056), extracted from
    the inline logic in the OP_IMPORT handler. #915 deferred the import half
    because a second resolver would drift (#737); now there is one, and both
    the handler and the gate's eager pass call it. Its path scratch lives on
    the heap: it runs inside vm_execute, which recurses on nested imports,
    and -fstack-usage measured the stack version at 28,800 bytes per frame
    against 112 now (the C-stack rule; tools/embed_stack_soak.sh green).
    The freestanding profile gets a stub that resolves nothing.
  * src/vm.c OP_IMPORT: calls the shared resolver (the collision warning is
    unchanged, driven by the `shadowed` out-param), and gains the same
    outcome guard builtin_load_file has: a module that reads observer state
    while the gate was closed for this program's earlier assignments RAISES
    ("import: '<name>' reads observer state ...") instead of answering a
    rest value. This is what makes the compile-time scan sound against a
    module rewritten or shadowed between scan and import.
  * src/chunk.c: OP_IMPORT leaves the reader set (vm.h marks it obs:NONE;
    the sync gate's exemption is spent and removed). chunk_scan_static_loads
    hands OP_IMPORT targets to the visitor (is_import=1) next to literal
    load_file targets. The constant-pool string match is replaced by
    chunk_name_loads_observer_builtin: OP_GET_NAME operands only -- the one
    binding-load opcode. Verified with EIGS_DUMP_BC: a string literal, dict
    key or printed literal is CONST; `local r is observe` is GET_NAME; a
    field access `tbl.eval` is DOT_GET (a field name on a user value -- it
    armed the keyword-table fixture until the population was narrowed to
    GET_NAME); `define observe` is a binder. OBS_BUILTINS is unchanged and
    mirrored name-for-name by OBS_NAMES in compiler.c, where the AST scan
    needs `report`/`report_value` (the parser spells `report of x` as a
    relation headed by that IDENT).
  * src/compiler.c: the eager pass's load list carries a kind; AST_IMPORT
    is noted instead of arming; import entries resolve through
    eigs_import_resolve and are parsed and scanned transitively like
    literal loads (nested imports anchored at the module's own directory,
    mixed import/load_file chains included); a provider-served module
    (embed source provider) stays conservative. for_loop_reads_observer
    keeps its pre-change answer for an import in a loop body (#1062 tier
    decision). Circular and self imports terminate in the pass (memo +
    depth cap) and the runtime's existing circular-dependency error is
    unchanged.
  * tools/obs_reader_sync_check.sh: EXEMPT="OP_INTERROGATE", SWITCH_FLOOR 16,
    selftest rows updated (11/11).
  * docs/OBSERVER.md: "What arms the gate -- the rule, precisely" (five
    numbered conditions, each executed), import named in the
    refuse-instead-of-answer section, the stale "compiled twice" residual
    corrected (parse-only since #1031).

Regression test: tests/test_obs_gate_import.sh, suite section [99u+], 19
checks pinned by count (12/19 on the baseline binary): unused stdlib
import, string literal, keyword table, alias of observe/eval/classify
(still arm), user-defined observe + field named eval (do not), --lint
verdict, EIGS_OBS_FORCE, the check-40 invariant on the VALUE (host history
visible to an imported reader: diverging), a reader two imports down,
project-first shadowing and eigs.json project-root resolution through the
shared resolver, an import inside an uncalled function, an unresolvable
import (open), a module rewritten between scan and import (raises), a
clean project import (runs, closed).
Planted faults, each rebuilt and run: OP_IMPORT back in the reader set ->
3 red + sync gate red; CONST matched again -> 4 red; import guard removed
-> "silent:equilibrium"; no eager import scan and no guard -> 8 red
including `equilibrium` where the truth is `diverging` (the #861 inversion
suite check 40 guards).

Corpus oracle: tools/observer_gate_diff.sh capture base1/base12 (baseline
binary, the determinism reference) and mine2 (this build); compare base1
mine2 -> 497 deterministic programs, 0 mismatches after normalising by
hand the two #1115 artifacts of an out-of-tree baseline binary (the
exe-dir substring in resolver error text, 5 programs; the project-vs-
stdlib import-shadow warning that fires only because the baseline's
stdlib is not the worktree's lib/, 2 programs). Raw compare: 7
mismatches, all of that shape; nothing else moved.

Suites: release 4249/4249, 0 failed; ASan (detect_leaks=1) full suite,
leak tally unchanged (0); freestanding-check OK; embed_stack_soak OK;
obs_reader_sync_check + selftest, obs_marker_check + selftest green.

Residuals: row B (a load_file'd module with a DEAD read) stays observed --
per-function liveness, out of scope. ouroboros src/frontend.eigs does not
lint on v0.43.0 at all (E005 at line 2300, a bare `report`, reserved by
#1110); its line-56 keyword table holds the six PREDICATE keywords, which
are opcode forms and were never in the name list, so the table never
armed anything on either binary -- the arming #1046's comment 5 measured
was the two first-class builtin loads at 2300/2308 (`_env_set_local of
[env, "observe", observe]`), genuine aliases that must arm. With both
patched out the file lints `unobserved` on the baseline AND this build;
with only 2300 patched it lints `observed` on both, correctly.
Provider-served imports (embed) stay conservative. No chunk is reused
between the eager pass and the import: since #1031 the pass parses and
scans an AST it then frees, so a literal module is parsed twice and
compiled once (#1031 stays open for chunk reuse).

Closes #1046
Closes #915

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 docs/OBSERVER.md               |  77 ++++++++++++---
 src/builtins_host.c            |  65 +++++++++++++
 src/chunk.c                    | 107 +++++++++++++++------
 src/compiler.c                 |  56 +++++++++--
 src/eigenscript.h              |   8 ++
 src/vm.c                       |  94 +++++++++----------
 src/vm.h                       |   9 +-
 tests/run_all_tests.sh         |  25 +++++
 tests/test_obs_gate_import.sh  | 166 +++++++++++++++++++++++++++++++++
 tools/obs_reader_sync_check.sh |  36 +++----
 10 files changed, 526 insertions(+), 117 deletions(-)
 create mode 100755 tests/test_obs_gate_import.sh

diff --git a/docs/OBSERVER.md b/docs/OBSERVER.md
index 9b65b982..2c8e53c8 100644
--- a/docs/OBSERVER.md
+++ b/docs/OBSERVER.md
@@ -570,6 +570,56 @@ observer state pays nothing for it; a program that does is unaffected.
 Both follow the tree's flag convention: any non-empty value that does not
 start with `0` turns the control on, so `=0` and `=` leave it off.
 
+### What arms the gate — the rule, precisely
+
+The decision is made once per compiled unit, in `compile_ast`, and is
+monotonic per interpreter state: once any unit arms it, every later unit in
+that state records. A unit arms the gate when **any** of the following holds;
+otherwise it does not, and nothing else does.
+
+1. **A reader opcode** anywhere in the unit, including in functions that are
+   never called: the interrogatives (`report of x`, `report_value`,
+   `trajectory of x`, `where is x`, ...), a predicate (`converged`,
+   `diverging of x`, ...), an observer-conditioned loop. The set is
+   `opcode_is_observer_reader()` in `src/chunk.c`, pinned against the
+   `obs:READS` markers by `tools/obs_reader_sync_check.sh`.
+2. **A binding-load of an observer builtin's name** — `OP_GET_NAME` whose
+   operand is `observe`, `classify`, `state_at`, `get_observer_thresholds`,
+   `eval` or `record_history` (`report`, `report_value` and `trajectory` are
+   listed for symmetry but cannot be loaded as values). This is the aliased
+   form: `local r is observe` then `r of x` emits no reader opcode. `eval`
+   and `record_history` are here because they open the channel at run time
+   from a string or a call, so their presence is the only signal.
+   **String data never arms** (#1046): `msg is "report"`, a keyword table
+   `["converged", "report", ...]`, a dict key `{"observe": 1}`, a printed
+   literal are all `OP_CONST` and are not consulted; neither is a field
+   access spelled like a builtin (`tbl.eval` is a `DOT_GET` on a user value)
+   nor a user `define observe(...)` (a binder). Until v0.43.0 the scan matched
+   the whole constant pool, so the string forms cost a program its gate.
+3. **A literal load target the unit cannot clear.** `load_file of "<literal>"`
+   and `import NAME` are resolved *at the importer's compile time* with the
+   same resolver the runtime uses (`resolve_eigenscript_file_from` and
+   `eigs_import_resolve` respectively — project-first, then stdlib, anchored
+   at the containing file's directory and the `eigs.json` project root), then
+   parsed and scanned by rules 1-3 transitively. The unit arms if any module
+   it reaches would, or if a target cannot be resolved, cannot be read, is
+   not a regular file, exceeds the speculative budget, or nests past the
+   depth cap. Until v0.43.0 the *presence* of an `import` armed the unit
+   unconditionally (`+49..84%` for one unused `import linalg`); the import
+   half of #915 is closed by #1046.
+4. **A non-literal load** — `load_file of (computed)`, an alias of
+   `load_file`, an `import` served by an embedder's source provider — makes
+   the unit opaque and arms it.
+5. **A forced or unknowable context**: `EIGS_OBS_FORCE=1`; a chunk assembled
+   from a descriptor rather than compiled; the REPL, where line N+1 can read a
+   binding from line N; more than one live thread during the eager pass.
+
+The two literal loaders carry the same run-time guard: if the module compiled
+at the load or import reads observer state and the gate was closed while the
+program's earlier assignments ran, the load raises (see the next section)
+rather than answering a rest value. A module scanned clean at compile time
+and rewritten before it runs is the case that guard exists for.
+
 ### When the gate refuses instead of answering
 
 The gate decides at COMPILE time, and a few constructs can make that decision
@@ -583,9 +633,10 @@ load_file: 'x.eigs' reads observer state, but the observer gate was closed when
 this program's earlier assignments ran — they have no recorded history...
 ```
 
-You will see this if a program **rewrites a module between the compile and the
-load**, or creates a nearer file that **shadows** the one the compile-time scan
-resolved. Both loaders search the containing file's directory, the
+(`import` raises the same way, naming the module.) You will see this if a
+program **rewrites a module between the compile and the load**, or creates a
+nearer file that **shadows** the one the compile-time scan resolved. Both
+loaders search the containing file's directory, the
 `eigs_modules` walk, the nearest `eigs.json` project root, then the executable
 and HOME stdlib roots (absolute paths are used as-is). For example, a newly
 created sibling can replace a project-root or stdlib target. Changing the
@@ -598,9 +649,10 @@ always safe — it restores the pre-gate behaviour exactly.
 
 ### When the gate declines to look
 
-To decide before the program runs, the gate compiles literally-loaded modules
-itself — including ones reached only from a function that is never called, since
-a `load_file` inside an uncalled function still contributes to the answer. That
+To decide before the program runs, the gate parses and scans literally-loaded
+and literally-imported modules itself — including ones reached only from a
+function that is never called, since a `load_file` or `import` inside an
+uncalled function still contributes to the answer. That
 work is speculative, so it is bounded: a per-thread cumulative ceiling on how
 many bytes the pass may read on the program's behalf, plus a rejection of
 anything that is not a regular file (a FIFO target once hung the compiler
@@ -635,10 +687,9 @@ across calls; opted-in evals reject later observer-reading units conservatively
 when an earlier unit ran unobserved. `EIGS_OBS_FORCE=1` from the start avoids
 that gap. Retained compiled functions can keep the eval gate open.
 
-Separately, every literally-loaded module is compiled **twice** — once by the
-gate to learn one bit, once for real by `load_file`, which has no module cache
-by design. Measured on `lib/ui.eigs`: 0.12-0.15s for the literal spelling that
-gates closed against 0.05-0.07s for a computed spelling that skips the pass, so
-a program that loads a large tree and does little work can pay more than it
-saves. The fix is to hand the eagerly-compiled chunk to `load_file` instead of
-discarding it; the budget above bounds the cost meanwhile.
+Separately, every literally-loaded or literally-imported module is **parsed
+twice** — once by the gate's pass (which since #1031 answers from the AST and
+compiles nothing), once for real by `load_file` (no module cache by design) or
+by the first `import` (cached thereafter). The pass hands nothing to the
+loader: the AST it scans is freed, and the runtime parse is the one that
+runs. The speculative budget above bounds the cost.
diff --git a/src/builtins_host.c b/src/builtins_host.c
index 21c39e82..33e77072 100644
--- a/src/builtins_host.c
+++ b/src/builtins_host.c
@@ -43,6 +43,14 @@ int resolve_eigenscript_file_from_ex(const char *base, const char *path,
     return 0;
 }
 
+int eigs_import_resolve(const char *base, const char *name,
+                        char *resolved, size_t resolved_cap,
+                        char *shadowed, size_t shadowed_cap) {
+    (void)base; (void)name; (void)resolved; (void)resolved_cap;
+    if (shadowed && shadowed_cap) shadowed[0] = '\0';
+    return 0;   /* nothing resolves without a filesystem */
+}
+
 #else /* host profile */
 
 #include <termios.h>
@@ -1014,6 +1022,63 @@ int resolve_eigenscript_file_from(const char *base, const char *path,
     return resolve_eigenscript_file_from_ex(base, path, resolved, resolved_cap, NULL);
 }
 
+/* #1046: THE import resolver. `import NAME` used to be resolved INLINE in the
+ * OP_IMPORT handler (vm.c), which is why #915 shipped with the import half of
+ * the observer gate open: the gate's compile-time pass needed to find the
+ * module an import will run, and a second copy of that logic would have been
+ * a resolver free to drift from the first (#737). Now both callers ask this
+ * one function, so the file the gate inspects is the file the import runs.
+ *
+ * The chain (#821/#904/#1056): the PROJECT request `<name>.eigs` and the
+ * STDLIB request `lib/<name>.eigs` are both probed through
+ * resolve_eigenscript_file_from_ex; a project hit that came from an installed
+ * stdlib root is the stdlib wearing a project-shaped request and is demoted;
+ * project wins over stdlib. Returns 1 with `resolved` filled. `shadowed`
+ * (optional) receives the realpath of a stdlib module that a GENUINELY
+ * distinct project file shadows, else "" -- the caller decides whether to
+ * warn (the VM does, once per name; the gate's pass never does). */
+int eigs_import_resolve(const char *base, const char *name,
+                        char *resolved, size_t resolved_cap,
+                        char *shadowed, size_t shadowed_cap) {
+    /* HEAP, not stack. This runs inside vm_execute's OP_IMPORT handler, and
+     * vm_execute recurses on nested imports; ~28 KiB of path scratch per
+     * level is the shape .claude/rules/c-runtime-memory.md's C-stack rule
+     * (and tools/embed_stack_soak.sh's 64 KiB rlimit) exists to catch. */
+    struct { char request[4096]; char stdlib_buf[8192]; char ureal[8192]; char sreal[8192]; } *b;
+    int user_origin = EIGS_RESOLVE_PROJECT;
+    int rc = 0;
+    if (shadowed && shadowed_cap) shadowed[0] = '\0';
+    if (!name || !resolved || resolved_cap == 0) return 0;
+    b = malloc(sizeof *b);
+    if (!b) return 0;   /* unresolvable is the conservative answer everywhere this is asked */
+
+    snprintf(b->request, sizeof(b->request), "%.1024s.eigs", name);
+    int user_hit = resolve_eigenscript_file_from_ex(base, b->request, resolved, resolved_cap,
+                                                     &user_origin);
+    snprintf(b->request, sizeof(b->request), "lib/%.1024s.eigs", name);
+    int stdlib_hit = resolve_eigenscript_file_from_ex(base, b->request, b->stdlib_buf,
+                                                       sizeof(b->stdlib_buf), NULL);
+    if (user_hit && stdlib_hit && user_origin == EIGS_RESOLVE_STDLIB_ROOT)
+        user_hit = 0;
+    if (!user_hit && !stdlib_hit) goto done;
+    rc = 1;
+    if (!user_hit) {
+        snprintf(resolved, resolved_cap, "%s", b->stdlib_buf);
+        goto done;
+    }
+    if (stdlib_hit && shadowed && shadowed_cap) {
+        /* Same-file double hit is possible (a chain step that resolves both
+         * request shapes to one path after symlinks) -- only a genuinely
+         * forked resolution is a collision. */
+        if (!realpath(resolved, b->ureal)) snprintf(b->ureal, sizeof(b->ureal), "%s", resolved);
+        if (!realpath(b->stdlib_buf, b->sreal)) snprintf(b->sreal, sizeof(b->sreal), "%s", b->stdlib_buf);
+        if (strcmp(b->ureal, b->sreal) != 0) snprintf(shadowed, shadowed_cap, "%s", b->sreal);
+    }
+done:
+    free(b);
+    return rc;
+}
+
 Value* builtin_load_file(Value *arg) {
     if (!arg || arg->type != VAL_STR) {
         rt_error(EK_TYPE, 0, "load_file requires a string path argument");
diff --git a/src/chunk.c b/src/chunk.c
index 3b391fe5..798f1378 100644
--- a/src/chunk.c
+++ b/src/chunk.c
@@ -1081,14 +1081,28 @@ void chunk_scan_leaf_accessor(EigsChunk *c) {
  * Two populations are checked:
  *   1. Reader OPCODES — the direct forms (`report of x`, a bare predicate,
  *      `trajectory of x`, `where is x`, an observer-conditioned loop).
- *   2. Reader BUILTIN NAMES in the constant pool — the indirect forms. These
- *      are ordinary bindings, so `local r is report` then `r of x` compiles to
- *      GET_NAME "report" + CALL and emits no reader opcode at all. Matching the
- *      name catches the alias. It also matches an unrelated string that merely
- *      spells "report", which costs a program its gate and is the safe way to
- *      be wrong.
+ *   2. Reader BUILTIN NAMES as the operand of OP_GET_NAME — the indirect
+ *      forms. These are ordinary bindings, so `local r is observe` then
+ *      `r of x` compiles to GET_NAME "observe" + CALL and emits no reader
+ *      opcode at all. Matching the name on the binding-LOAD opcode catches
+ *      the alias.
+ *
+ *      NOT the constant pool as a whole (#1046). This used to match any
+ *      string constant spelling one of the names, so `msg is "report"` — a
+ *      CONST, pure data — armed every assignment in the state (+48% on a
+ *      200k-frame write loop). Verified against the emitter with
+ *      EIGS_DUMP_BC: a string literal, a dict key and a printed literal are
+ *      CONST (VR_CONST); the alias is GET_NAME. And not every VR_NAME
+ *      operand either: OP_DOT_GET's operand is a FIELD name on whatever value
+ *      is on the stack (`tbl.eval` on a user dict — executed, it armed the
+ *      keyword-table fixture), the SET_* family are stores and binders, and
+ *      the *_NAME observer opcodes are readers the opcode scan already
+ *      covers. The builtin VALUE can only enter a program through GET_NAME
+ *      (a dict or module that holds it was filled by one), so GET_NAME is
+ *      the population — the one binding-load opcode in op_verify_operands.
  */
-static int const_pool_names_observer(const EigsChunk *chunk) {
+static int chunk_step_ip(const EigsChunk *chunk, int i);   /* defined below */
+static int chunk_name_loads_observer_builtin(const EigsChunk *chunk) {
     /* Names reachable only as BUILTINS; the opcode forms are covered by the
      * opcode scan above.
      *
@@ -1102,6 +1116,15 @@ static int const_pool_names_observer(const EigsChunk *chunk) {
      * is deliberately over-broad: a name here that is not a reader costs a
      * program its gate, which is the safe direction. */
     static const char *OBS_BUILTINS[] = {
+        /* `report` / `report_value` cannot reach a VR_NAME operand today:
+         * since #1102/#1110 they are reserved observer forms (any binding or
+         * first-class use is parse error E005; suite [42a] pins it), and
+         * `report of x` compiles to OP_REPORT_NAME, which the opcode scan
+         * covers. They stay listed anyway — this list is mirrored NAME FOR
+         * NAME by OBS_NAMES in compiler.c, where the AST scan needs them
+         * (the parser spells `report of x` as a relation headed by the IDENT
+         * "report"), and a matching entry here costs nothing: a string
+         * literal is a CONST, never a VR_NAME, so it cannot false-positive. */
         "observe", "report", "report_value", "trajectory", "classify",
         "state_at", "get_observer_thresholds",
         /* `eval` compiles a NEW unit at runtime from a string that need not
@@ -1116,13 +1139,12 @@ static int const_pool_names_observer(const EigsChunk *chunk) {
          * any other use of the name makes the unit opaque there. See that
          * comment for the three recorded failures that shape the rule.
          *
-         * OP_IMPORT is handled in the opcode switch above: it is an opcode with
-         * a bare-name operand, so it never appears in the constant pool as a
-         * string and a name list cannot see it at all. Its resolution is
-         * project-first-then-stdlib against a per-module resolve dir (vm.c
-         * CASE(IMPORT)); replicating that here would be a second copy of a
-         * resolver free to drift from the first, which is the #737 failure. So
-         * import stays conservative and #915's `import` half stays open. */
+         * `import` is not a name at all: OP_IMPORT carries its target as a
+         * VR_NAME operand and chunk_scan_static_loads hands that target to the
+         * eager pass, which resolves it through eigs_import_resolve — the SAME
+         * function the OP_IMPORT handler calls (#1046; the second-resolver
+         * drift that kept #915's import half open is gone because there is
+         * one resolver now). A module the pass cannot resolve arms the unit. */
         "eval",
         /* `record_history` sets g_trace_obs_hist — half of what opens the
          * observer channel — at RUNTIME, and it has NO opcode form, so its name
@@ -1133,11 +1155,20 @@ static int const_pool_names_observer(const EigsChunk *chunk) {
          * then CLOSES it again mid-program, so the channel can flicker. */
         "record_history", NULL
     };
-    for (int i = 0; i < chunk->const_count; i++) {
-        const char *s = chunk->const_interns ? chunk->const_interns[i] : NULL;
-        if (!s) continue;
-        for (int k = 0; OBS_BUILTINS[k]; k++)
-            if (strcmp(s, OBS_BUILTINS[k]) == 0) return 1;
+    if (!chunk->const_interns) return 0;
+    int i = 0;
+    while (i < chunk->code_len) {
+        if (chunk->code[i] == OP_GET_NAME) {
+            if (i + 3 > chunk->code_len) return 1;         /* truncated: observe */
+            /* LITTLE-endian, as read_u16 reads it (vm.c). */
+            int v = chunk->code[i + 1] | (chunk->code[i + 2] << 8);
+            if (v < 0 || v >= chunk->const_count) return 1;   /* malformed: observe */
+            const char *s = chunk->const_interns[v];
+            if (s)
+                for (int b = 0; OBS_BUILTINS[b]; b++)
+                    if (strcmp(s, OBS_BUILTINS[b]) == 0) return 1;
+        }
+        i = chunk_step_ip(chunk, i);
     }
     return 0;
 }
@@ -1149,7 +1180,7 @@ int chunk_reads_observer(const EigsChunk *chunk) {
      * its opcode stream is caller-supplied. Do not gate it. */
     if (!chunk->compiler_scanned) return 1;
     if (chunk_has_reader_opcode(chunk)) return 1;
-    if (const_pool_names_observer(chunk)) return 1;
+    if (chunk_name_loads_observer_builtin(chunk)) return 1;
     for (int f = 0; f < chunk->fn_count; f++)
         if (chunk_reads_observer(chunk->functions[f])) return 1;
     return 0;
@@ -1173,13 +1204,23 @@ int chunk_reads_observer(const EigsChunk *chunk) {
  * So the descriptor sites ask this instead, BEFORE running: does the chunk I am
  * about to execute read observer state while the gate is closed? If so, raise —
  * the same outcome guard builtin_load_file uses, for the same reason. */
-static int chunk_step_ip(const EigsChunk *chunk, int i);   /* defined below */
-
 /* THE reader set. One home, and it is the one tools/obs_reader_sync_check.sh
  * extracts and pins against the obs:READS markers in vm.h. Every consumer
  * asks this question rather than restating the list — a fourth restatement had
  * already diverged (OP_LOOP_STALL_CHECK) before anyone noticed. */
 int opcode_is_observer_reader(uint8_t op) {
+    /* OP_IMPORT is NOT a reader (#1046; marked obs:NONE in vm.h). It sat in
+     * this switch from #915 to v0.43.0 because a module compiled at RUNTIME
+     * flips the bit too late to have observed this unit's earlier assignments
+     * — the ordering hazard, not a read. A literal import target is now
+     * resolved and scanned before line 1 runs, exactly like a literal
+     * `load_file` (chunk_scan_static_loads below), and the OP_IMPORT handler
+     * raises if the module it compiles reads while the gate was closed (the
+     * same outcome guard builtin_load_file has). Suite check 40 and
+     * tests/test_obs_gate_import.sh hold the line: a host's pre-import
+     * history must stay visible to an imported reader. (The comment lives
+     * ABOVE the switch on purpose: the sync gate's demotion selftest plants
+     * against the switch's tail shape, `return 1;` / `default: return 0;`.) */
     switch ((OpCode)op) {
         case OP_INTERROGATE:
         case OP_INTERROGATE_NAMED:
@@ -1197,7 +1238,6 @@ int opcode_is_observer_reader(uint8_t op) {
         case OP_OBSERVE_VALUE_SLOT:
         case OP_OBSERVE_VALUE_NAME:
         case OP_LOOP_STALL_CHECK:
-        case OP_IMPORT:
             return 1;
         default: return 0;
     }
@@ -1335,7 +1375,8 @@ static int const_pool_index_of(const EigsChunk *chunk, const char *name) {
 }
 
 int chunk_scan_static_loads(const EigsChunk *chunk,
-                            void (*visit)(const char *path, void *ud), void *ud) {
+                            void (*visit)(const char *path, int is_import, void *ud),
+                            void *ud) {
     if (!chunk) return 1;
     if (!chunk->compiler_scanned) return 1;   /* unscanned chunk — see #830 above */
 
@@ -1358,8 +1399,12 @@ int chunk_scan_static_loads(const EigsChunk *chunk,
      * observer bit 0 -> 1, which is precisely "the gate closed on stale
      * evidence". That check is on the OUTCOME and needs no enumeration. */
 
+    /* #1046: `import NAME` is the second literal shape. OP_IMPORT's only
+     * operand IS the module name (a VR_NAME index), so there is no computed
+     * form to refuse — every import is literal by construction. The walk
+     * below runs whenever the unit holds either shape. */
     int lf = const_pool_index_of(chunk, "load_file");
-    if (lf >= 0) {
+    {
         int i = 0;
         while (i < chunk->code_len) {
             uint8_t op = chunk->code[i];
@@ -1367,11 +1412,19 @@ int chunk_scan_static_loads(const EigsChunk *chunk,
             VerifyRole roles[3];
             if (op != OP_LINE && op < OP_COUNT) nops = op_verify_operands(op, roles);
 
+            if (op == OP_IMPORT) {
+                if (nops != 1 || i + 3 > chunk->code_len) return 1;
+                int v = chunk->code[i + 1] | (chunk->code[i + 2] << 8);
+                if (v < 0 || v >= chunk->const_count || !chunk->const_interns ||
+                    !chunk->const_interns[v]) return 1;
+                if (visit) visit(chunk->const_interns[v], 1, ud);
+            }
+
             /* Operands are LITTLE-endian (read_u16, vm.c) — the same order the
              * verifier reads them in above. Getting this backwards reads a
              * garbage constant index and silently answers "not this shape". */
             int names_lf = 0;
-            if (i + 1 + 2 * nops <= chunk->code_len) {
+            if (lf >= 0 && i + 1 + 2 * nops <= chunk->code_len) {
                 for (int k = 0; k < nops; k++) {
                     if (roles[k] != VR_NAME) continue;
                     int off = i + 1 + 2 * k;
@@ -1393,7 +1446,7 @@ int chunk_scan_static_loads(const EigsChunk *chunk,
                 if (c + 2 >= chunk->code_len || chunk->code[c] != OP_CALL) return 1;
                 int argc = chunk->code[c + 1] | (chunk->code[c + 2] << 8);
                 if (argc != 1) return 1;
-                if (visit) visit(k->data.str, ud);
+                if (visit) visit(k->data.str, 0, ud);
                 /* Fall through to the normal step: the CONST/CALL are walked
                  * again harmlessly (neither names `load_file`). */
             }
diff --git a/src/compiler.c b/src/compiler.c
index de6d4036..df493516 100644
--- a/src/compiler.c
+++ b/src/compiler.c
@@ -3434,16 +3434,20 @@ enum { OBS_GATE_MAX_LOADS = 64, OBS_GATE_MAX_DEPTH = 8 };
 typedef struct {
     char **paths;
     char **bases;              /* directory of the file containing each load */
+    unsigned char *kinds;      /* #1046: 1 = `import NAME`, 0 = literal load_file */
     const char *base;          /* borrowed while collecting one file */
     int count, cap, overflow;
+    int import_seen;           /* any import noted, even past the cap */
 } ObsLoadList;
 
-static void obs_gate_note_load(const char *path, void *ud) {
+static void obs_gate_note_load(const char *path, int is_import, void *ud) {
     /* Collect into a bounded, owned list; resolving here would re-enter the
      * compiler while chunk_scan_static_loads is still walking the chunk. */
     ObsLoadList *L = ud;
+    if (is_import) L->import_seen = 1;
     if (L->count >= L->cap) { L->overflow = 1; return; }  /* caller treats as opaque */
     if (L->bases) L->bases[L->count] = xstrdup(L->base);
+    if (L->kinds) L->kinds[L->count] = (unsigned char)(is_import != 0);
     L->paths[L->count++] = xstrdup(path);
 }
 
@@ -3613,19 +3617,30 @@ void eigs_obs_memo_release(void) { obs_memo_clear(); g_obs_spec_bytes = 0; }
  * to load_file (compile_ast numbers module slots from the env it is given,
  * and the scan env is not load_file's), so the pass answers from the AST
  * alone. Two rules, each the AST form of the chunk rule it replaces:
- *   reader  -- chunk_reads_observer: an interrogative, a predicate, an
- *              import, or ANY occurrence of an observer builtin's name
- *              (OBS_BUILTINS in chunk.c, mirrored here by name); a loop whose
- *              condition reads a predicate is covered by the predicate node.
+ *   reader  -- chunk_reads_observer: an interrogative, a predicate, or an
+ *              observer builtin's name used AS A NAME (an AST_IDENT --
+ *              OBS_BUILTINS in chunk.c, mirrored here by name; a string
+ *              literal spelling one is AST_STR and never arms, #1046); a loop
+ *              whose condition reads a predicate is covered by the predicate
+ *              node.
  *   loads   -- chunk_scan_static_loads: `load_file` may appear ONLY as the
  *              callee of a call (an AST_RELATION node -- the parser's spelling
  *              of `f of arg`) whose argument is a string literal (or
  *              an unparenthesised one-element list holding one); that path is
  *              appended to the load list. Any other occurrence of the name
- *              makes the unit opaque, exactly as the chunk scan does.
+ *              makes the unit opaque, exactly as the chunk scan does. An
+ *              `import NAME` (AST_IMPORT) is appended as an import-kind entry
+ *              (#1046) -- its target is a bare name, literal by construction.
  * Both are conservative in the safe direction: a stray name arms the gate
  * (observed, slower), never the reverse. Returns 1 when the module must arm. */
 static int obs_ast_name_is_observer_builtin(const char *nm) {
+    /* Mirrors OBS_BUILTINS in chunk.c, name for name. `report` / `report_value`
+     * are load-bearing HERE even though they are reserved forms (#1102): the
+     * parser spells `report of x` as an AST_RELATION whose callee is the
+     * IDENT "report" (compile_node then emits OP_REPORT_NAME), so this list is
+     * how the AST scan sees an interrogation. Executed: with the two names
+     * dropped, a host importing a module whose only read was `report of x`
+     * compiled `unobserved` and the import-time guard had to raise. */
     static const char *OBS_NAMES[] = {
         "observe", "report", "report_value", "trajectory", "classify",
         "state_at", "get_observer_thresholds", "eval", "record_history", NULL };
@@ -3644,6 +3659,11 @@ static int for_loop_reads_observer(ASTNode *node) {
     for (int i = 0; i < node->data.forloop.body_count && !r; i++)
         if (obs_ast_scan(node->data.forloop.body[i], &L)) r = 1;
     if (!r && node->data.forloop.iter && obs_ast_scan(node->data.forloop.iter, &L)) r = 1;
+    /* #1046: an `import` in the body no longer arms the scan by itself, but
+     * for THIS question it keeps its pre-#1046 answer -- a module imported
+     * from a top-level loop body shares the host's scope and could read the
+     * binder, so the loop stays on the CLEAR tier as before. */
+    if (!r && L.import_seen) r = 1;
     for (int i = 0; i < L.count; i++) free(L.paths[i]);
     free(L.paths);
     return r;
@@ -3655,7 +3675,10 @@ static int obs_ast_scan_d(ASTNode *n, ObsLoadList *L, int depth) {
      * inside the muted window). Past the limit the unit is opaque. */
     if (depth > COMPILE_MAX_DEPTH) return 1;
     switch (n->type) {
-    case AST_INTERROGATE: case AST_PREDICATE: case AST_IMPORT: return 1;
+    case AST_INTERROGATE: case AST_PREDICATE: return 1;
+    case AST_IMPORT:   /* #1046: resolved and scanned by the caller's loop, like a literal load */
+        obs_gate_note_load(n->data.import.module_name, 1, L);
+        return 0;
     case AST_IDENT:
         if (strcmp(n->data.ident.name, "load_file") == 0) return 1;   /* not the call shape below */
         return obs_ast_name_is_observer_builtin(n->data.ident.name);
@@ -3670,7 +3693,7 @@ static int obs_ast_scan_d(ASTNode *n, ObsLoadList *L, int depth) {
                      arg->data.list.elems[0]->type == AST_STR)
                 lit = arg->data.list.elems[0];
             if (!lit || !lit->data.str) return 1;
-            obs_gate_note_load(lit->data.str, L);
+            obs_gate_note_load(lit->data.str, 0, L);
             return 0;
         }
         return obs_ast_scan_d(fn, L, depth + 1) || obs_ast_scan_d(arg, L, depth + 1);
@@ -3750,6 +3773,7 @@ static void obs_gate_resolve_static_loads(EigsChunk *chunk) {
     if (g_obs_gate_depth >= OBS_GATE_MAX_DEPTH) { eigs_obs_enable_runtime(); return; }
 
     L.bases = xcalloc_array(OBS_GATE_MAX_LOADS, sizeof(char *));
+    L.kinds = xcalloc_array(OBS_GATE_MAX_LOADS, sizeof(unsigned char));
     L.base = chunk->src && chunk->src->resolve_dir
                  ? chunk->src->resolve_dir : eigs_current_file_dir();
 
@@ -3800,7 +3824,20 @@ static void obs_gate_resolve_static_loads(EigsChunk *chunk) {
          * why a green release suite and a green ASan suite could not see it —
          * and it is the same defect class as the #ifdef-vs-#if mistake this file
          * already records, made a second time while fixing the first. */
-        int resolved_ok = resolve_eigenscript_file_from(L.bases[i], L.paths[i], resolved, 8192);
+        int resolved_ok;
+        if (L.kinds[i]) {
+            /* #1046: `import NAME`. An embedder's source provider is consulted
+             * FIRST by OP_IMPORT and serves source that is not a file; a
+             * provider-served module is not scanned here and arms the unit
+             * (conservative, and the shape that has no stat identity for the
+             * memo or budget anyway). Otherwise resolve through
+             * eigs_import_resolve -- THE resolver the OP_IMPORT handler calls,
+             * project-first then stdlib -- so what is scanned is what runs. */
+            if (eigs_source_lookup(L.paths[i])) { eigs_obs_enable_runtime(); break; }
+            resolved_ok = eigs_import_resolve(L.bases[i], L.paths[i], resolved, 8192, NULL, 0);
+        } else {
+            resolved_ok = resolve_eigenscript_file_from(L.bases[i], L.paths[i], resolved, 8192);
+        }
 #else
         int resolved_ok = 0;
 #endif
@@ -3914,6 +3951,7 @@ static void obs_gate_resolve_static_loads(EigsChunk *chunk) {
         free(L.bases[i]);
     }
     free(L.bases);
+    free(L.kinds);
 }
 
 EigsChunk *compile_ast(ASTNode *ast, Env *env, const char *src) {
diff --git a/src/eigenscript.h b/src/eigenscript.h
index 0e8adbd9..c7c39eb0 100644
--- a/src/eigenscript.h
+++ b/src/eigenscript.h
@@ -1719,6 +1719,14 @@ int resolve_eigenscript_file_from(const char *base, const char *path,
 int resolve_eigenscript_file_from_ex(const char *base, const char *path,
                                       char *resolved, size_t resolved_cap,
                                       int *origin);
+/* #1046: the ONE `import NAME` resolver -- project-first, then stdlib --
+ * shared by OP_IMPORT (vm.c) and the observer gate's compile-time pass
+ * (compiler.c). `shadowed` (optional) receives the stdlib path a distinct
+ * project file shadows, else "". Hosted; the freestanding stub resolves
+ * nothing. */
+int eigs_import_resolve(const char *base, const char *name,
+                        char *resolved, size_t resolved_cap,
+                        char *shadowed, size_t shadowed_cap);
 Value* eigs_json_parse_value(const char *s, int *pos);
 /* #777: the ONLY entry point for a top-level (non-recursive) JSON parse.
  * Clears both thread-local parse flags (g_json_parse_err,
diff --git a/src/vm.c b/src/vm.c
index 0d06d198..354762fc 100644
--- a/src/vm.c
+++ b/src/vm.c
@@ -5900,6 +5900,7 @@ static Value *vm_run_ex(EigsChunk *chunk, Env *env, Task *resume,
         if (!source) {
             char request[4096];
             char path_buf[8192];
+            char shadowed[8192];
 
             extern char *read_file_util(const char *path, long *size);
 
@@ -5907,62 +5908,30 @@ static Value *vm_run_ex(EigsChunk *chunk, Env *env, Task *resume,
              * even when called after the importing/loading frame returns. */
             const char *resolve_base = eigs_current_file_dir();
 
-            /* #821: PROJECT-FIRST resolution. The user module `<name>.eigs`
-             * (script-relative, plus the chain's other locations and the
-             * eigs_modules walk) is tried BEFORE the stdlib's
-             * `lib/<name>.eigs`. The stdlib namespace grows over time, so
-             * under stdlib-first a new stdlib module could silently capture
-             * an existing project's import (dynamics' physics.eigs,
-             * F-DYN-8). Both requests are always probed: a name matching
-             * both is a collision worth a diagnostic whichever way
-             * resolution goes. */
-            char stdlib_buf[8192];
-            int user_origin = EIGS_RESOLVE_PROJECT;
-            snprintf(request, sizeof(request), "%.1024s.eigs", name);
-            int user_hit = resolve_eigenscript_file_from_ex(resolve_base, request,
-                                                             path_buf, sizeof(path_buf),
-                                                             &user_origin);
-            snprintf(request, sizeof(request), "lib/%.1024s.eigs", name);
-            int stdlib_hit = resolve_eigenscript_file_from_ex(resolve_base, request,
-                                                               stdlib_buf, sizeof(stdlib_buf),
-                                                               NULL);
-
-            /* #904: the bare `<name>.eigs` request also probes the installed
-             * stdlib roots, so on a machine that has run `make install` EVERY
-             * stdlib import came back with a "project" hit at
-             * `~/.local/lib/eigenscript/<name>.eigs` — a phantom collision
-             * (spurious warning on every import) AND a resolution bug: the
-             * installed copy won over the stdlib shipped with the binary
-             * being run, and over a bundle's own extracted lib/. A stdlib-root
-             * hit is the stdlib arm; it is never the project arm. */
-            if (user_hit && stdlib_hit && user_origin == EIGS_RESOLVE_STDLIB_ROOT)
-                user_hit = 0;
-
-            if (!user_hit && !stdlib_hit) {
+            /* #821: PROJECT-FIRST resolution, #904: a stdlib-root hit on the
+             * bare request is the stdlib arm. Both live in eigs_import_resolve
+             * (#1046) -- the ONE resolver, shared with the observer gate's
+             * compile-time pass in compiler.c, so the module the gate scanned
+             * before line 1 ran is the module compiled here. Resolving inline
+             * in this handler is what kept #915's import half open: a second
+             * copy would drift (#737). Do not re-inline it. */
+            if (!eigs_import_resolve(resolve_base, name, path_buf, sizeof(path_buf),
+                                     shadowed, sizeof(shadowed))) {
                 snprintf(request, sizeof(request), "%.1024s.eigs and lib/%.1024s.eigs", name, name);
                 eigs_file_resolve_error("import", resolve_base, request, current_line);
                 vm_push(make_null());
                 DISPATCH();
             }
-            if (user_hit && stdlib_hit &&
-                import_collision_first_report(name)) {
-                /* Same-file double hit is possible (e.g. a chain step that
-                 * resolves both request shapes to one path after symlinks) —
-                 * only a genuinely forked resolution is a collision. */
-                char ureal[8192], sreal[8192];
+            if (shadowed[0] && import_collision_first_report(name)) {
+                char ureal[8192];
                 if (!realpath(path_buf, ureal))
                     snprintf(ureal, sizeof(ureal), "%s", path_buf);
-                if (!realpath(stdlib_buf, sreal))
-                    snprintf(sreal, sizeof(sreal), "%s", stdlib_buf);
-                if (strcmp(ureal, sreal) != 0)
-                    fprintf(stderr, "Warning: import '%s' matches both a "
-                            "project file and a stdlib module — using '%s', "
-                            "shadowing '%s' (project-first; rename the file "
-                            "to use the stdlib module)\n",
-                            name, ureal, sreal);
+                fprintf(stderr, "Warning: import '%s' matches both a "
+                        "project file and a stdlib module — using '%s', "
+                        "shadowing '%s' (project-first; rename the file "
+                        "to use the stdlib module)\n",
+                        name, ureal, shadowed);
             }
-            if (!user_hit)
-                memcpy(path_buf, stdlib_buf, sizeof(path_buf));
 
             /* Module cache: canonicalize to absolute path so two different
              * importers (different cwds, different relative paths) hash to
@@ -6056,6 +6025,16 @@ static Value *vm_run_ex(EigsChunk *chunk, Env *env, Task *resume,
          * keeps top-level writes in the caller's current scope). */
         int saved_import_toplevel = g_compile_import_toplevel;
         g_compile_import_toplevel = 1;
+        /* #1046: the observer gate may have CLOSED on evidence gathered when
+         * the importing unit was compiled -- its eager pass resolved this
+         * literal import through the same resolver and scanned the module
+         * then. The module scanned and the module compiled now are two reads
+         * with the whole program in between; see builtin_load_file for the
+         * two shapes (rewrite, shadow) and for why the predicate is the
+         * module's OWN verdict against the sticky history-gap flag rather
+         * than a one-shot bit transition. ACQUIRE pairs with
+         * eigs_obs_enable's store order. */
+        int obs_before_module = obs_flag_load_acquire(obs_needed);
         EigsChunk *mod_chunk = compile_ast(ast, mod_env, source);
         g_compile_module_boundary = saved_boundary;
         g_compile_import_toplevel = saved_import_toplevel;
@@ -6063,6 +6042,25 @@ static Value *vm_run_ex(EigsChunk *chunk, Env *env, Task *resume,
          * eval must inherit its executing function's retained source directory,
          * even when that function is called by this imported module. */
         memcpy(g_import_resolve_dir, saved_resolve_dir, sizeof(saved_resolve_dir));
+        if (mod_chunk && chunk_reads_observer(mod_chunk) &&
+            (!obs_before_module || g_obs_history_gap)) {
+            obs_flag_store(obs_history_gap, 1);
+            g_parse_errors = saved_errors;
+            chunk_free(mod_chunk);
+            g_load_env = saved_load;
+            free_ast(ast);
+            free_tokenlist(&tl);
+            free(source);
+            env_decref(mod_env);
+            rt_error(EK_IO, current_line,
+                "import: '%s' reads observer state, but the observer gate was "
+                "closed when this program's earlier assignments ran — they have no "
+                "recorded history, so an observer query about them would answer a "
+                "rest value rather than the truth. Re-run with EIGS_OBS_FORCE=1.",
+                name);
+            vm_push(make_null());
+            DISPATCH();
+        }
         if (g_parse_errors > 0) {
             g_parse_errors = saved_errors;
             chunk_free(mod_chunk);
diff --git a/src/vm.h b/src/vm.h
index 34dc13d0..fab878f9 100644
--- a/src/vm.h
+++ b/src/vm.h
@@ -687,13 +687,16 @@ int        chunk_reads_observer(const EigsChunk *chunk);
  * tools/obs_reader_sync_check.sh. Ask this; never restate the list. */
 int        opcode_is_observer_reader(uint8_t op);
 int        chunk_has_reader_opcode(const EigsChunk *chunk);
-/* #915: hand every STRING-LITERAL `load_file` target in this chunk to `visit`.
+/* #915: hand every STRING-LITERAL `load_file` target (is_import=0) and every
+ * `import NAME` target (is_import=1, #1046) in this chunk to `visit`.
  * Returns 1 if the unit is OPAQUE — it uses the name `load_file` in any shape
  * this scan does not recognize. An opaque unit must be treated as observing.
  * This does NOT check resolver parity between compile time and run time; that
- * is enforced at the load itself (builtin_load_file). See the definition. */
+ * is enforced at the load itself (builtin_load_file / OP_IMPORT). See the
+ * definition. */
 int        chunk_scan_static_loads(const EigsChunk *chunk,
-                                   void (*visit)(const char *path, void *ud),
+                                   void (*visit)(const char *path, int is_import,
+                                                 void *ud),
                                    void *ud);
 const char *op_name(uint8_t op);
 /* Verify an assembled (untrusted) chunk's bytecode is in-bounds before the VM
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 9881b280..ad633cd7 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -4655,6 +4655,31 @@ fi
 rm -rf "$OBS_GATE_TMP"
 echo ""
 
+# [99u+] Observer gate, the `import` half (#1046 / #915). OP_IMPORT left the
+# reader set: a literal import target is resolved at the importer's compile
+# time through eigs_import_resolve (the ONE resolver OP_IMPORT calls) and
+# scanned like a literal load_file target, and the constant-pool string
+# match became a match on OP_GET_NAME operands, so string DATA never arms.
+# The fixture pins both halves AND the invariant #915's last comment names:
+# a host's pre-import history stays visible to an imported reader, asserted
+# on the VALUE (diverging), plus the import-time raise for a module rewritten
+# between scan and import. Count pinned like [42a]: a check added or deleted
+# without moving the number goes red here.
+echo "[99u+] Observer gate: import half + string data (#1046)"
+OBSIMP_OUT=$(bash "$TESTS_DIR/test_obs_gate_import.sh" 2>&1); OBSIMP_RC=$?
+OBSIMP_PASS=$(echo "$OBSIMP_OUT" | grep -c "^PASS:" || true)
+OBSIMP_FAIL=$(echo "$OBSIMP_OUT" | grep -c "^FAIL:" || true)
+TOTAL=$((TOTAL + 1))
+if [ "$OBSIMP_RC" -eq 0 ] && [ "$OBSIMP_PASS" -eq 19 ] && [ "$OBSIMP_FAIL" -eq 0 ]; then
+    PASS=$((PASS + 1))
+    echo "  PASS: all $OBSIMP_PASS import-gate checks"
+else
+    FAIL=$((FAIL + 1))
+    echo "  FAIL: observer gate import half (rc=$OBSIMP_RC, $OBSIMP_PASS/19 checks passed)"
+    echo "$OBSIMP_OUT" | grep -E "^FAIL:|SUMMARY" | sed 's/^/    /'
+fi
+echo ""
+
 # [100] Worker-thread JIT lifetime (#296). A shared chunk that gets hot and
 # JIT-compiles ON a worker must not leave chunk->jit_code dangling when that
 # worker exits (its per-thread JIT code arena is munmap'd at detach). Crashed
diff --git a/tests/test_obs_gate_import.sh b/tests/test_obs_gate_import.sh
new file mode 100755
index 00000000..22c092cc
--- /dev/null
+++ b/tests/test_obs_gate_import.sh
@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# #1046 / #915 (the `import` half): the observer write-path gate no longer arms
+# on the PRESENCE of an `import`, nor on string DATA that spells an observer
+# builtin's name. A literal `import NAME` is resolved at the importer's compile
+# time through eigs_import_resolve — the ONE resolver the OP_IMPORT handler
+# calls — and the module is scanned (transitively) like a literal `load_file`
+# target; the constant-pool string match became a match on NAME-LOAD operands.
+#
+# Every "closed" verdict here requires rc=0 AND the program's own stdout marker
+# AND an `unobserved` stats line (the round-10 vacuity rule from [99u]); every
+# answer-shaped verdict carries rc discipline (a crash is died-rcN, never a
+# PASS). The invariant that must not break — #915's last comment, suite check
+# 40 — is asserted on the VALUE: a host's pre-import history must stay
+# visible to an imported reader (`diverging`, never `equilibrium`).
+#
+# Runs with cwd src/ (the runner's convention); every path below is absolute.
+set -u
+TESTS_DIR="$(cd "$(dirname "$0")" && pwd)"
+EIGS="${EIGS:-$TESTS_DIR/../src/eigenscript}"
+EIGS="$(cd "$(dirname "$EIGS")" && pwd)/$(basename "$EIGS")"   # fixtures cd; keep it absolute
+T=$(mktemp -d)
+trap 'rm -rf "$T"' EXIT
+pass=0; fail=0
+check() { # name expected got
+    if [ "$2" = "$3" ]; then pass=$((pass+1)); echo "PASS: $1"
+    else fail=$((fail+1)); echo "FAIL: $1 — expected '$2', got '$3'"; fi
+}
+# No bare `timeout` (macOS legs have none): the runner's own probe.
+tmo() { if command -v timeout >/dev/null 2>&1; then timeout 60 "$@"
+        elif command -v gtimeout >/dev/null 2>&1; then gtimeout 60 "$@"
+        else "$@"; fi; }
+# verdict DIR FILE MARKER -> closed | open | died-rcN | no-output | no-evidence
+verdict() {
+    local err out rc; err=$(mktemp)
+    out=$(cd "$1" && EIGS_OBS_GATE_STATS=1 tmo "$EIGS" "$2" 2>"$err"); rc=$?
+    if [ "$rc" -ne 0 ]; then rm -f "$err"; echo "died-rc$rc"; return; fi
+    if ! printf '%s' "$out" | grep -q -- "$3"; then rm -f "$err"; echo no-output; return; fi
+    if grep -q 'obs-gate: observed' "$err"; then rm -f "$err"; echo open; return; fi
+    if grep -q 'obs-gate: unobserved' "$err"; then rm -f "$err"; echo closed; return; fi
+    rm -f "$err"; echo no-evidence
+}
+# answer DIR FILE -> first stdout line, or died-rcN
+answer() {
+    local out rc
+    out=$(cd "$1" && tmo "$EIGS" "$2" 2>/dev/null); rc=$?
+    if [ "$rc" -ne 0 ]; then echo "died-rc$rc"; return; fi
+    printf '%s\n' "$out" | head -1
+}
+
+WLOOP='define wloop(n) as:
+    local u is 0.0
+    local i is 0
+    loop while i < n:
+        u is 280.0 + (sin of (i * 0.01))
+        i is i + 1
+    print of f"w {i}"
+wloop of (2000)
+'
+mkdir -p "$T/p/lib" "$T/p/sub" "$T/p/mid"
+printf '%s' "$WLOOP" > "$T/p/w.eigs"
+# 1. control: the write loop alone gates closed and runs.
+check "control: a read-free write loop gates closed" closed "$(verdict "$T/p" w.eigs "w 2000")"
+# 2. the issue's comment-3 row: + `import linalg`, never used. Was `observed`
+#    (+49..84%) because OP_IMPORT sat in the reader set.
+{ printf 'import linalg\n'; printf '%s' "$WLOOP"; } > "$T/p/w_imp.eigs"
+check "an unused stdlib import no longer arms the gate" closed "$(verdict "$T/p" w_imp.eigs "w 2000")"
+# 3. the issue's row D: `msg is "report"` — a string constant, pure data.
+{ printf 'msg is "report"\n'; printf '%s' "$WLOOP"; } > "$T/p/w_str.eigs"
+check "a string literal spelling 'report' no longer arms the gate" closed "$(verdict "$T/p" w_str.eigs "w 2000")"
+# 4. the ouroboros frontend.eigs:56 shape: a keyword table naming EVERY observer
+#    builtin and predicate as string data, plus a dict keyed by them.
+{ printf '_keywords is ["is", "of", "observe", "report", "report_value", "trajectory", "classify", "state_at", "get_observer_thresholds", "eval", "record_history", "converged", "stable", "improving", "oscillating", "diverging", "equilibrium", "when", "where", "why", "how"]\n_tbl is {"observe": 1, "eval": 2, "report": 3}\nprint of f"{len of _keywords} {_tbl.eval}"\n'; printf '%s' "$WLOOP"; } > "$T/p/w_kw.eigs"
+check "a keyword table of observer names (string data) gates closed" closed "$(verdict "$T/p" w_kw.eigs "w 2000")"
+# 5-6. The ALIAS forms still arm: a name-load of the builtin, whatever it is
+#    bound to. This is the population the string match was over-approximating.
+{ printf 'local r is observe\n'; printf '%s' "$WLOOP"; } > "$T/p/w_alias.eigs"
+check "a first-class load of 'observe' still arms (alias)" open "$(verdict "$T/p" w_alias.eigs "w 2000")"
+{ printf 'local e is eval\n'; printf '%s' "$WLOOP"; } > "$T/p/w_eval.eigs"
+check "a first-class load of 'eval' still arms" open "$(verdict "$T/p" w_eval.eigs "w 2000")"
+# 7a. The population is the binding-LOAD opcode, not every name operand: a
+#    user function NAMED observe is a SET_FN_NAME_LOCAL "observe" (a binder,
+#    and it shadows the builtin), and a dict FIELD spelled eval is a DOT_GET
+#    "eval" on a user value — neither loads the builtin, neither arms.
+{ printf 'define observe(v) as:\n    return v\ntbl is {"eval": 1}\nprint of (tbl.eval)\n'; printf '%s' "$WLOOP"; } > "$T/p/w_def.eigs"
+check "a user-defined observe plus a field named eval gate closed (no builtin load)" closed "$(verdict "$T/p" w_def.eigs "w 2000")"
+# 7b. ...but the same program that ALSO loads the builtin by name arms.
+{ printf 'define observe(v) as:\n    return v\nlocal f is classify\n'; printf '%s' "$WLOOP"; } > "$T/p/w_def2.eigs"
+check "the same program with a builtin name-load (classify) arms" open "$(verdict "$T/p" w_def2.eigs "w 2000")"
+# 8. --lint never resolves or reads modules; the keyword-table program lints
+#    unobserved (the #1046 comment-5 bar), and lint touches nothing else.
+LINT_OUT=$(cd "$T/p" && EIGS_OBS_GATE_STATS=1 tmo "$EIGS" --lint w_kw.eigs 2>&1); LINT_RC=$?
+if [ "$LINT_RC" -ne 0 ]; then LINT_V="died-rc$LINT_RC"
+elif printf '%s' "$LINT_OUT" | grep -q 'obs-gate: unobserved'; then LINT_V=unobserved
+else LINT_V=other; fi
+check "--lint reports the keyword-table program unobserved" unobserved "$LINT_V"
+# 9. EIGS_OBS_FORCE=1 still reopens the gate on the import program (the
+#    baseline arm for any measurement).
+FORCE_OUT=$(cd "$T/p" && EIGS_OBS_FORCE=1 EIGS_OBS_GATE_STATS=1 tmo "$EIGS" w_imp.eigs 2>&1); FORCE_RC=$?
+if [ "$FORCE_RC" -ne 0 ]; then FORCE_V="died-rc$FORCE_RC"
+elif printf '%s' "$FORCE_OUT" | grep -q 'obs-gate: observed'; then FORCE_V=observed; else FORCE_V=other; fi
+check "EIGS_OBS_FORCE=1 reopens the gate on the import program" observed "$FORCE_V"
+
+# ---- the invariant: a host's pre-import history stays visible ----------
+HOST='x is 1.0
+for i in range of 40:
+    x is x * 2.0
+'
+# 10. The check-40 shape: the imported module READS. Asserted on the VALUE.
+printf 'print of (report of x)\nverdict is 1.0\n' > "$T/p/lib/probe.eigs"
+{ printf '%s' "$HOST"; printf 'import probe\n'; } > "$T/p/host.eigs"
+check "an imported reader sees the host's pre-import history (diverging)" diverging "$(answer "$T/p" host.eigs)"
+# 11. ...and the gate's own verdict for that host is OPEN before line 1 ran
+#     (the eager scan, not a late runtime flip — a late flip would have RAISED
+#     through the import guard and check 10 would read died-rc1).
+check "the host importing a reader compiles observed" open "$(verdict "$T/p" host.eigs diverging)"
+# 12. TRANSITIVE: host -> mid (clean) -> inner (reads), through nested imports
+#     anchored at the module's own directory.
+printf 'print of (report of x)\n' > "$T/p/mid/inner.eigs"
+printf 'import inner\n' > "$T/p/mid/mid.eigs"
+{ printf '%s' "$HOST"; printf 'import mid\n'; } > "$T/p/host_deep.eigs"
+# mid.eigs must resolve from host's dir: put a copy where `import mid` finds it.
+cp "$T/p/mid/mid.eigs" "$T/p/mid.eigs"; cp "$T/p/mid/inner.eigs" "$T/p/inner.eigs"
+check "a reader TWO imports down still sees the host's history" diverging "$(answer "$T/p" host_deep.eigs)"
+# 13. RESOLVER PARITY, project-first: a project file named like a stdlib module
+#     (`linalg.eigs`, which READS) must be the one the eager pass scans. A
+#     stdlib-first pass would scan lib/linalg.eigs (read-free), close the gate,
+#     and the import guard would raise (died-rc1) — never `diverging`.
+printf 'print of (report of x)\n' > "$T/p/sub/linalg.eigs"
+{ printf '%s' "$HOST"; printf 'import linalg\n'; } > "$T/p/sub/host_shadow.eigs"
+check "project-first: a shadowing project module is what the pass scans" diverging "$(answer "$T/p/sub" host_shadow.eigs)"
+# 14. RESOLVER PARITY, project root: eigs.json marks $T/p as the root, so a
+#     host in a subdirectory resolves `import rootmod` to $T/p/rootmod.eigs.
+printf '{"name": "obs-gate-import-fixture"}\n' > "$T/p/eigs.json"
+printf 'print of (report of x)\n' > "$T/p/rootmod.eigs"
+{ printf '%s' "$HOST"; printf 'import rootmod\n'; } > "$T/p/sub/host_root.eigs"
+check "project-root (eigs.json) resolution: the pass finds the root module" diverging "$(answer "$T/p/sub" host_root.eigs)"
+# 15. UNREACHABLE code still counts: an import inside a function nobody calls
+#     is scanned (the pass walks chunk->functions), so the host arms.
+{ printf 'define never() as:\n    import probe\n    return 0\n'; printf '%s' "$WLOOP"; } > "$T/p/w_dead.eigs"
+check "an import of a reader inside an uncalled function still arms" open "$(verdict "$T/p" w_dead.eigs "w 2000")"
+# 16. An UNRESOLVABLE import cannot be scanned, so it cannot be cleared: the
+#     decision is `observed` (the import itself then fails at runtime, as
+#     before — this asserts the DECISION, from the stats line).
+{ printf 'import no_such_module_1046\n'; printf '%s' "$WLOOP"; } > "$T/p/w_missing.eigs"
+MISS_ERR=$(cd "$T/p" && EIGS_OBS_GATE_STATS=1 tmo "$EIGS" w_missing.eigs 2>&1 >/dev/null)
+check "an unresolvable import keeps the gate open (conservative)" 1 "$(printf '%s\n' "$MISS_ERR" | grep -c 'obs-gate: observed')"
+# 17. STALE MODULE: the file scanned at compile time is rewritten before the
+#     import runs. The gate closed on stale evidence and the history is gone;
+#     OP_IMPORT must RAISE (the load_file guard, mirrored), never answer a
+#     rest value. Without the guard this prints `equilibrium`, rc=0.
+printf 'define helper(a) as:\n    return a\n' > "$T/p/lib/later.eigs"
+{ printf '%s' "$HOST"; printf 'write_text of ["%s/lib/later.eigs", "print of (report of x)\\n"]\nimport later\nprint of "unreachable"\n' "$T/p"; } > "$T/p/host_stale.eigs"
+STALE_OUT=$(cd "$T/p" && tmo "$EIGS" host_stale.eigs 2>&1); STALE_RC=$?
+if [ "$STALE_RC" -ne 0 ] && printf '%s' "$STALE_OUT" | grep -q "import: 'later' reads observer state"; then STALE_V=raised
+elif [ "$STALE_RC" -eq 0 ]; then STALE_V="silent:$(printf '%s\n' "$STALE_OUT" | head -1)"
+else STALE_V="died-rc$STALE_RC"; fi
+check "a module rewritten between scan and import RAISES (no silent rest value)" raised "$STALE_V"
+# 18. Positive control for the shared resolver: an ordinary clean import still
+#     resolves and runs through eigs_import_resolve, and the whole program
+#     gates closed.
+printf 'define twice(a) as:\n    return a * 2\nprint of "mod"\n' > "$T/p/mymod.eigs"
+printf 'import mymod\nprint of (mymod.twice of 21)\n' > "$T/p/use_mymod.eigs"
+check "a clean project import resolves, runs, and gates closed" closed "$(verdict "$T/p" use_mymod.eigs 42)"
+
+echo "SUMMARY: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]
diff --git a/tools/obs_reader_sync_check.sh b/tools/obs_reader_sync_check.sh
index 3dbaa719..e725f1ed 100755
--- a/tools/obs_reader_sync_check.sh
+++ b/tools/obs_reader_sync_check.sh
@@ -46,11 +46,13 @@
 #   * It does not check that a marker's verdict is CORRECT. That rests on the
 #     handler having been read; obs_marker_check.sh owns "was a verdict
 #     recorded", and the reading for the initial 94 is on #972.
-#   * It does not see readers reached through the CONSTANT POOL (an aliased
-#     `local r is report` emits no reader opcode at all). That population is
-#     OBS_BUILTINS in the same function and is checked by suite section [99u]
-#     check 4, behaviourally. (It said [99n] — that is the VM operand-width
-#     comment-drift gate, #958. A pointer in a waiver is load-bearing, §6.)
+#   * It does not see readers reached through a NAME-LOAD operand (an aliased
+#     `local r is observe` emits no reader opcode at all). That population is
+#     OBS_BUILTINS in the same file (matched on VR_NAME operands since #1046,
+#     never on string data) and is checked by suite section [99u] check 4 and
+#     tests/test_obs_gate_import.sh, behaviourally. (It said [99n] — that is
+#     the VM operand-width comment-drift gate, #958. A pointer in a waiver is
+#     load-bearing, §6.)
 #   * The stronger design is to GENERATE the C set from the markers, the way
 #     tools/gen_lsp_builtin_index.sh generates its header — then the rule has
 #     one home and this gate is unnecessary. Filed rather than implied.
@@ -89,7 +91,7 @@ MARKER_TOOL="${MARKER_TOOL:-tools/obs_marker_check.sh}"
 # diagnosed in one read). No self-test row asserts them, deliberately: a row
 # that cannot fail for its own reason is decoration.
 READS_FLOOR="${READS_FLOOR:-15}"
-SWITCH_FLOOR="${SWITCH_FLOOR:-17}"
+SWITCH_FLOOR="${SWITCH_FLOOR:-16}"
 
 # The pinned exemptions: opcodes the C switch treats as readers although the
 # markers do not. Each must be PRESENT in the switch and ABSENT from the marker
@@ -100,15 +102,15 @@ SWITCH_FLOOR="${SWITCH_FLOOR:-17}"
 #                   since #262 Step E observer state is binding-keyed and a bare
 #                   value has no binding. Kept in the switch anyway: it costs a
 #                   program its gate and being wrong in that direction is safe.
-#   OP_IMPORT       not an observer reader at all. It is in the switch because
-#                   it compiles a NEW unit at runtime whose own scan arrives too
-#                   late to have observed this unit's earlier assignments — the
-#                   ordering hazard, not a read. Its literal-target sibling
-#                   `load_file` is handled by chunk_scan_static_loads instead;
-#                   import's resolution is project-first-then-stdlib against a
-#                   per-module dir and replicating it would be a second resolver
-#                   free to drift (#737), so it stays conservative.
-EXEMPT="OP_INTERROGATE OP_IMPORT"
+#   (OP_IMPORT was the second exemption from #915 to v0.43.0: not a reader,
+#   listed because a module compiled at runtime arms too late to have observed
+#   the importer's earlier assignments. #1046 resolves literal import targets
+#   at the importer's compile time through eigs_import_resolve — the ONE
+#   resolver the OP_IMPORT handler also calls — and scans them like literal
+#   `load_file` targets, so the exemption is spent and removed. The line it
+#   held is still held: suite check 40 and tests/test_obs_gate_import.sh
+#   assert the host's pre-import history stays visible to an imported reader.)
+EXEMPT="OP_INTERROGATE"
 
 # ---- extraction -------------------------------------------------------------
 #
@@ -299,13 +301,13 @@ PYEOF
     gate_with_fault() { # name -> writes $tmp/<name>.faultgate.sh
         cp "$real_gate" "$tmp/$1.faultgate.sh"
         case "$1" in
-          D) sedi 's|^EXEMPT="OP_INTERROGATE OP_IMPORT"|EXEMPT="OP_INTERROGATE OP_IMPORT OP_ADD"|' "$tmp/$1.faultgate.sh" ;;
+          D) sedi 's|^EXEMPT="OP_INTERROGATE"|EXEMPT="OP_INTERROGATE OP_ADD"|' "$tmp/$1.faultgate.sh" ;;
         esac
     }
     gut() { # name -> writes $tmp/<name>.gate.sh
         cp "$real_gate" "$tmp/$1.gate.sh"
         case "$1" in
-          D) sedi 's|^EXEMPT="OP_INTERROGATE OP_IMPORT"|EXEMPT="OP_INTERROGATE OP_IMPORT OP_ADD"|' "$tmp/$1.gate.sh" ;;
+          D) sedi 's|^EXEMPT="OP_INTERROGATE"|EXEMPT="OP_INTERROGATE OP_ADD"|' "$tmp/$1.gate.sh" ;;
         esac
         case "$1" in
           E) sedi 's|\*) note_fail "opcode \$op is marked obs:READS.*|*) : ;;|' "$tmp/$1.gate.sh" ;;

From 60613341c3176d5fa8355ebacdf4722de81a2afc Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 19:33:38 +0000
Subject: [PATCH 18/39] lib/ui: dropdown/combobox open lists render in the
 overlay pass; grid's row-label gutter folded into its rect (#859)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The #823 containment clip had four registry opt-outs. Two were real debt:
dropdown and combobox drew their open lists in-tree (so the list could not
be clipped without erasing it, and any later sibling painted over it), and
grid drew its row-label gutter to the LEFT of its own x. Both are gone.

Open lists now ride the `_render_popups` overlay pass that #565 built for
menu_bar pull-downs: `_render_dropdown` / `_render_combobox` draw only the
closed box (and stamp the absolute origin the overlay reads), and
`_render_dropdown_popup` / `_render_combobox_popup` paint the list after
the whole tree walk with no clip active. Hit-testing follows the paint:
`_find_open_popup_at` — already consulted before the tree walk for
mousedown and mousemove — gained dropdown/combobox branches, and the two
`_hit_test_*` functions no longer extend the widget's in-tree bounds,
which would have handed a click that visually landed on the list to
whatever sibling the list covers. `app_loop` runs the overlay pass for
each visible modal too, so a dropdown inside a dialog keeps its list; the
pass and the popup hit-test follow only the ACTIVE tab panel, matching
render and _hit_test.

Two adjacent bugs fell out and are fixed here: `_mousedown_dropdown`
selected by `hover_index`, so a mouse-only click with no preceding
mousemove selected nothing (the #577 defect, fixed for combobox and
menu_bar but never for dropdown) — it now selects by the click's own y
through the shared `_dropdown_item_at`, which also stops forgetting the
2px gap below the box.

grid: the gutter is inside the rect. `_grid_gutter` is `row_label_w` when
`row_labels` is set and 0 otherwise; `_grid_measure` restamps `w` from it
and is registered as the grid's `measure` hook, which `render` calls
BEFORE pushing the containment clip (and `_layout` calls on its pass), so
a box derived from content is never clipped to a rect it has outgrown.
Cells start at `x + row_label_w`, labels draw at `x`, the mouse paths
offset by the gutter and a click in the gutter is not a cell click.
`grid_cell_origin of widget` is the public accessor for cell (0, 0).

Registry opt-outs are now exactly `menu` (a floating popup placed in
window coordinates) and `dialog` (a full-screen dim), and a fixture
enumerates them.

Minimal repro (stubbed gfx, recording the draw stream — panel at (10,10)
200x60 holding an open dropdown, later sibling panel at (10,60)):

  before: list_first=11 sib_first=17 -> the list is drawn BEFORE the later
          sibling, under an active clip of [10, 10, 200, 60] (the panel
          crops it at y=70); clip_optouts = combobox, dialog, dropdown,
          grid, menu
  after:  list_first=19 sib_first=15 -> the list is drawn AFTER the
          sibling with clip = null; clip_optouts = dialog, menu

What the regression tests pin:
- [63] tests/test_ui.eigs, new "#859 overlay pass" section (565 -> 613
  checks): the opt-out enumeration is exactly menu + dialog; the later
  sibling's draws precede the list's; the list records with no active
  clip and its rect runs past the panel edge; the anchor box now records
  under a clip of its own rect; the same for combobox; a vacuity control
  (no `_render_popups` -> no list drawn at all); the overlay works with no
  `_layout` pass; a hidden tab's list is neither painted nor hit-tested,
  with the active-tab control beside it; a click on the overlaid list
  selects on the DROPDOWN while the button underneath sees nothing (with
  the list-closed control proving the button is reachable); mouse-only
  selection, outside-click close, escape close; grid cell (0,0) origin,
  clip, nothing drawn left of x, gutter clicks, `grid_cell_origin`, and
  the measure hook widening the box before the first frame's clip.
- [132] tests/test_ui_containment_gfx.eigs (9 -> 25 checks, real pixels
  through the SDL software renderer): the list is painted over a canvas
  sibling and past the panel's bottom edge; a driven mousedown selects on
  the dropdown while the canvas under it never fires; the grid's cell
  (0,0) is painted at x + row_label_w with nothing painted left of x; and
  a planted fault that re-registers the pre-#859 in-tree render turns both
  the z-order and the escape probe red.

Planted faults executed against the real gates: in-tree list -> [63] 7
red, [132] 3 red; `_find_open_popup_at`'s dropdown branch removed -> [63]
4 red, [132] 2 red; grid gutter reverted -> [63] 6 red, [132] 3 red.

Residual: DeslanStudio's drum view maps its own pixels with
`g._ax + step * cell_w`, which is no longer the cell origin. Its
`test_drum_view.eigs` is the one consumer test this moves; a two-line
migration (`DV_GRID_X 76 -> 16`, and the test's click helper reading
`grid_cell_origin`) was applied to a scratch copy and took all 24 of its
test files green. eigen-sheet does not use lib/ui and its suite is green
against this build.

Closes #859

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 docs/STDLIB.md                     |  35 +++-
 examples/deslan_shell.eigs         |   3 +-
 examples/drums_demo.eigs           |   4 +-
 lib/ui.eigs                        |  25 ++-
 lib/ui_layout.eigs                 |   6 +
 lib/ui_w_data.eigs                 |  65 +++++--
 lib/ui_w_input.eigs                |  62 +++---
 lib/ui_w_menu.eigs                 | 126 ++++++++++---
 tests/run_all_tests.sh             |  29 +--
 tests/test_ui.eigs                 | 293 ++++++++++++++++++++++++++++-
 tests/test_ui_containment_gfx.eigs | 128 +++++++++++++
 11 files changed, 682 insertions(+), 94 deletions(-)

diff --git a/docs/STDLIB.md b/docs/STDLIB.md
index 8b393328..7dde43b4 100644
--- a/docs/STDLIB.md
+++ b/docs/STDLIB.md
@@ -514,10 +514,17 @@ its own rect, so **widget drawing is contained**: a `canvas` `on_paint`
 cannot spill over surrounding chrome, and a child wider than its parent
 (the classic overflowing side-panel label) crops at the parent's edge.
 A custom paint routine that needs a tighter clip pushes its own — it
-composes with the widget clip automatically. Widgets whose render
-legitimately leaves the rect (`dropdown`/`combobox` open lists, `menu`,
-`dialog`'s dim overlay, `grid`'s row-label gutter) opt out via their
-registry entry (`"clip": 0`).
+composes with the widget clip automatically. Exactly two widgets opt out
+via their registry entry (`"clip": 0`), and both are positioned in window
+coordinates rather than inside a parent: `menu` (a floating popup placed
+by `show_menu`) and `dialog` (a full-screen dim behind a centred panel).
+Everything else is contained. A widget that must paint past its own rect
+draws in the **overlay pass** instead of opting out — `_render_popups`
+runs after the whole tree walk, with no clip active, so an open
+`dropdown`/`combobox` list and a `menu_bar` pull-down sit above later
+siblings and past a clipped ancestor's edge (#565, #859). `app_loop` runs
+that pass for the root and for each visible modal; a hand-rolled render
+loop must call `_render_popups` itself or open lists will not appear.
 
 **Widget constructors, by family** (each returns a plain dict; see the
 module header for the full argument list):
@@ -563,7 +570,10 @@ opens inward), and the open/close state, including hovering across
 titles while open. Its pull-down is drawn by an overlay pass *after* the
 tree walk and hit-tested before it, so it sits above whatever it covers
 no matter where the bar lives in the tree — the z-order a shell used to
-hand-roll by adding every `menu` last to the root.
+hand-roll by adding every `menu` last to the root. `dropdown` and
+`combobox` open lists ride the same pass (#859), so a list opened inside
+a `scroll_panel` or a dock region is no longer cropped at that
+ancestor's edge and no longer painted over by a later sibling.
 
 **`chart(id, x, y, w, h)` is an x-y plot** (#819) — data coordinates on
 both axes, not y-vs-index. Everything else is set on the returned dict.
@@ -701,8 +711,19 @@ Notes on widget state, where the toolkit could otherwise shadow yours:
   it 0 and mouse/keyboard report `(row, col)` without touching `cells` —
   for an app whose model is the source of truth (undo history, pattern
   switching, randomize), so both sides don't keep copies that drift.
-  `row_label_w` (60) and `row_label_scale` (1) size the row-label gutter,
-  which is drawn to the *left* of the grid's `x`, outside its own bounds.
+  `row_label_w` (60) and `row_label_scale` (1) size the row-label gutter.
+  The gutter is **inside** the widget rect (#859): set `row_labels` and
+  the grid's `w` grows by `row_label_w` the next time it is laid out or
+  drawn, cell
+  (0, 0) starts at `x + row_label_w`, and nothing is ever drawn left of
+  `x`. With `row_labels` unset the gutter is 0 and the geometry is the
+  historical `cols * cell_w`. A click in the gutter is not a cell click.
+  `grid_cell_origin of widget` returns the absolute `[x, y]` of cell
+  (0, 0) — use it instead of assuming the cells start at the widget's
+  `_ax` (they do not once row labels are set). The widening runs through
+  the registry's `measure` hook, which `render` calls before pushing the
+  containment clip and `_layout` calls on its own pass, so a box derived
+  from content is never clipped to a rect it has outgrown.
 - **`piano_keyboard` is a horizontal trigger strip**, not a piano-roll
   pitch sidebar: a click fires `on_note(w, note, 1)` and the release
   fires `on_note(w, note, 0)` — including when the pointer leaves the key
diff --git a/examples/deslan_shell.eigs b/examples/deslan_shell.eigs
index b8ea6a11..b13ff0d8 100644
--- a/examples/deslan_shell.eigs
+++ b/examples/deslan_shell.eigs
@@ -279,7 +279,8 @@ ui.add_child of [mix, master]
 drums is ui.panel of ["drums_tab", 0, 0, WINDOW_W, tab_h - 28]
 drums.border is null
 
-drum_grid is ui.grid of ["dg", 80, 50, 16, 8, 36, 30, on_drum_cell]
+# x accounts for the row-label gutter, inside the grid rect since #859.
+drum_grid is ui.grid of ["dg", 20, 50, 16, 8, 36, 30, on_drum_cell]
 drum_grid.row_labels is ["Kick", "Snare", "HiHat", "Clap", "808", "Perc", "Rim", "Clave"]
 
 # Default pattern
diff --git a/examples/drums_demo.eigs b/examples/drums_demo.eigs
index e9513f60..589ddfdb 100644
--- a/examples/drums_demo.eigs
+++ b/examples/drums_demo.eigs
@@ -91,7 +91,9 @@ ui.add_child of [toolbar, ui.radio_group of ["pattern", 514, 12, ["1", "2", "3",
 ui.add_child of [toolbar, ui.editable_label of ["pat_name", 630, 15, "My Pattern", on_name_commit]]
 
 # Grid
-drum_grid is ui.grid of ["drum_grid", 70, 60, 16, 8, 38, 32, on_cell]
+# x accounts for the row-label gutter, which lives INSIDE the grid rect
+# since #859 (the grid is row_label_w wider and the cells start there).
+drum_grid is ui.grid of ["drum_grid", 10, 60, 16, 8, 38, 32, on_cell]
 drum_grid.row_labels is ["Kick", "Snare", "HiHat", "Clap", "808", "Perc", "Rim", "Clave"]
 
 # Set some default pattern
diff --git a/lib/ui.eigs b/lib/ui.eigs
index 0c601de6..a04ea847 100644
--- a/lib/ui.eigs
+++ b/lib/ui.eigs
@@ -190,17 +190,28 @@ define render(widget, ox, oy) as:
     ax is ox + widget.x
     ay is oy + widget.y
     entry is _widget_registry[widget.type]
+    if entry != null and entry.measure != null:
+        # A widget whose own box is derived from its content restamps it
+        # HERE, before the containment clip is pushed from widget.w
+        # (#859). _layout does the same on its pass, which is what a
+        # container lays out against; this covers the frame in which the
+        # content changed, and a hand-rolled loop that never calls
+        # _layout at all — otherwise the clip would be a rect the render
+        # has already outgrown, and the overflow is silently erased.
+        entry.measure of widget
     if entry != null and entry.render != null:
         # Containment (#823): every widget draws under a clip of its own
         # rect, intersected with its ancestors' via the ui_draw clip
         # stack — canvas on_paint included, so a paint callback cannot
         # spill over surrounding chrome, and a child wider than its
         # parent (the dynamics side-panel label) crops at the parent
-        # edge. A registry entry opts out with "clip": 0 — reserved for
-        # widgets whose render legitimately leaves the rect (dropdown /
-        # combobox open lists, the floating menu, dialog's full-screen
-        # dim). Their escape from ANCESTOR clips still ends at whatever
-        # clip is active when they render.
+        # edge. A registry entry opts out with "clip": 0 — since #859
+        # exactly TWO do: `menu` (a floating popup positioned in window
+        # coordinates by show_menu) and `dialog` (a full-screen dim behind
+        # a centred panel). Everything else, dropdown and combobox and
+        # grid included, is contained; a widget that needs to paint past
+        # its own rect draws in the _render_popups overlay pass instead of
+        # opting out of containment.
         if entry.clip != null and entry.clip == 0:
             entry.render of [widget, ax, ay]
         else:
@@ -917,6 +928,10 @@ define app_loop(root, on_key, on_tick) as:
             if mdlg.visible == 1:
                 _layout of [mdlg, 0, 0]
                 render of [mdlg, 0, 0]
+                # A dropdown hosted by a dialog draws its open list in the
+                # overlay pass like any other (#859), so the modal subtree
+                # needs its own pass — root's does not reach it.
+                _render_popups of mdlg
         _render_tooltip of null
         _render_toasts of null
         _render_dnd of null
diff --git a/lib/ui_layout.eigs b/lib/ui_layout.eigs
index 2e6bc900..3b398906 100644
--- a/lib/ui_layout.eigs
+++ b/lib/ui_layout.eigs
@@ -25,6 +25,12 @@ define _layout(widget, ox, oy) as:
         # stamped itself, and remeasuring would silently overwrite it.
         if widget.auto_size != 0:
             _label_measure of widget
+    if widget.type == "grid":
+        # The row-label gutter lives INSIDE the grid's rect (#859), so the
+        # box a container lays out against — and the containment clip
+        # render() pushes — must include it. Restamped every pass because
+        # apps assign row_labels after construction.
+        _grid_measure of widget
     if widget.type == "hbox":
         _layout_box of [widget, 1]
     elif widget.type == "vbox":
diff --git a/lib/ui_w_data.eigs b/lib/ui_w_data.eigs
index 503b06c7..ce96f5cd 100644
--- a/lib/ui_w_data.eigs
+++ b/lib/ui_w_data.eigs
@@ -81,9 +81,14 @@ define grid(id, x, y, cols, rows, cell_w, cell_h, on_cell) as:
         # instead of both sides keeping a copy that can drift.
         "owns_cells": 1,
         "row_labels": null,
-        # The row-label gutter is drawn to the LEFT of the widget's x, so
-        # it sits outside the widget's own bounds; these make its width
-        # and text scale configurable rather than hardcoded (#572).
+        # The row-label gutter is INSIDE the widget rect (#859): when
+        # row_labels is set the widget is row_label_w wider and cell (0,0)
+        # starts at x + row_label_w, so nothing is ever drawn left of x
+        # and the grid is contained like every other widget. With no row
+        # labels the gutter is 0 and the geometry is unchanged. `w` is
+        # restamped by _grid_measure on each layout pass — assigning
+        # row_labels after construction takes effect on the next frame,
+        # the same rule label's auto-measure follows (#561).
         "row_label_w": 60,
         "row_label_scale": 1,
         "col_highlight": -1,
@@ -240,10 +245,38 @@ define _render_item_list(widget, ax, ay) as:
         sb_y is ay + floor of (widget.scroll_y * (widget.h - sb_h) / (total_h - widget.h))
         gfx_rrect of [ax + widget.w - 6, sb_y, 4, sb_h, 2, 80, 80, 100]
 
+# Width of the row-label gutter carved out of the LEFT of the widget rect
+# — 0 when the grid has no row labels (#859).
+
+define _grid_gutter(widget) as:
+    if widget.row_labels == null:
+        return 0
+    return widget.row_label_w
+
+# The widget's own width follows its gutter. Registered as the grid's
+# `measure` hook, so render() restamps it BEFORE pushing the containment
+# clip, and _layout restamps it for the containers that lay out against
+# it — a grid that gains row labels at runtime widens instead of having
+# its cells clipped away by a rect it has outgrown.
+
+define _grid_measure(widget) as:
+    widget.w is (_grid_gutter of widget) + widget.cols * widget.cell_w
+    return null
+
+# Public: absolute [x, y] of cell (0, 0) — the widget origin plus the
+# row-label gutter (#859). An app that maps its own pixel coordinates to
+# cells (a headless driver, a custom overlay) reads this instead of
+# assuming the cells start at the widget's x, which stopped being true
+# when the gutter moved inside the rect.
+
+define grid_cell_origin(widget) as:
+    return [widget._ax + (_grid_gutter of widget), widget._ay]
+
 define _render_grid(widget, ax, ay) as:
+    gut is _grid_gutter of widget
     for r in range of widget.rows:
         for c in range of widget.cols:
-            cx is ax + c * widget.cell_w
+            cx is ax + gut + c * widget.cell_w
             cy is ay + r * widget.cell_h
             # Cell color
             cell_val is widget.cells[r][c]
@@ -262,15 +295,15 @@ define _render_grid(widget, ax, ay) as:
                 else:
                     gc is [35, 35, 48]
             gfx_rrect of [cx + 1, cy + 1, widget.cell_w - 2, widget.cell_h - 2, 2, gc[0], gc[1], gc[2]]
-    # Row labels — drawn in a gutter left of the widget's x (#572)
+    # Row labels — drawn in the gutter at the LEFT of the widget rect
+    # (#572 sized it; #859 folded it inside the rect)
     if widget.row_labels != null:
         lscale is widget.row_label_scale
-        lgw is widget.row_label_w
         lh is text_height of lscale
         for r in range of widget.rows:
             if r < (len of widget.row_labels):
                 ly is ay + r * widget.cell_h + floor of ((widget.cell_h - lh) / 2)
-                gfx_text of [ax - lgw, ly, widget.row_labels[r], _theme.text_dim[0], _theme.text_dim[1], _theme.text_dim[2], lscale]
+                gfx_text of [ax, ly, widget.row_labels[r], _theme.text_dim[0], _theme.text_dim[1], _theme.text_dim[2], lscale]
 
 # ---- Mousemove functions ----
 
@@ -298,8 +331,13 @@ define _mousemove_item_list(hit, root, mx, my) as:
     hit.hover_index is floor of ((my - abs_y + hit.scroll_y) / hit.item_h)
 
 define _mousemove_grid(hit, root, mx, my) as:
-    abs_x is hit._ax
+    abs_x is hit._ax + (_grid_gutter of hit)
     abs_y is hit._ay
+    if mx < abs_x:
+        # In the row-label gutter — no cell under the pointer (#859)
+        hit.hover_col is 0 - 1
+        hit.hover_row is 0 - 1
+        return null
     hit.hover_col is floor of ((mx - abs_x) / hit.cell_w)
     hit.hover_row is floor of ((my - abs_y) / hit.cell_h)
 
@@ -377,8 +415,11 @@ define _mousedown_item_list(hit, root, mx, my, ev) as:
                 hit.on_select of hit
 
 define _mousedown_grid(hit, root, mx, my, ev) as:
-    abs_x is hit._ax
+    abs_x is hit._ax + (_grid_gutter of hit)
     abs_y is hit._ay
+    if mx < abs_x:
+        # A click in the row-label gutter is not a cell click (#859)
+        return null
     gc is floor of ((mx - abs_x) / hit.cell_w)
     gr is floor of ((my - abs_y) / hit.cell_h)
     if gc >= 0 and gc < hit.cols and gr >= 0 and gr < hit.rows:
@@ -484,11 +525,7 @@ _register_widget of ["item_list", {
 }]
 
 _register_widget of ["grid", {
-    # clip 0: the row-label gutter is documented to draw LEFT of the
-    # grid's x, outside its own bounds (docs/STDLIB.md) — the #823
-    # containment clip would erase it. Fold the gutter into the rect
-    # before removing this opt-out.
-    "clip": 0,
+    "measure": _grid_measure,
     "render": _render_grid,
     "hit_test": null,
     "on_mousedown": _mousedown_grid,
diff --git a/lib/ui_w_input.eigs b/lib/ui_w_input.eigs
index 15e123ed..89c6bdee 100644
--- a/lib/ui_w_input.eigs
+++ b/lib/ui_w_input.eigs
@@ -128,6 +128,10 @@ define _render_spinbox(widget, ax, ay) as:
     gfx_text of [ax + widget.w - 15, ay + 5, "+", _theme.text_color[0], _theme.text_color[1], _theme.text_color[2], _theme.font_scale]
 
 define _render_combobox(widget, ax, ay) as:
+    # Stamp the absolute origin the overlay pass draws the open list from
+    # (#859) — see the note in _render_dropdown.
+    widget._ax is ax
+    widget._ay is ay
     if widget.hover == 1:
         cbg is _theme.dropdown_hover
     else:
@@ -155,29 +159,44 @@ define _render_combobox(widget, ax, ay) as:
         cx_pos is ax + 6 + widget.cursor * _theme.char_w
         if cx_pos < ax + widget.w - 20:
             gfx_line of [cx_pos, ay + 4, cx_pos, ay + widget.h - 4, _theme.accent[0], _theme.accent[1], _theme.accent[2]]
-    # Dropdown when open
-    if widget.open == 1:
-        item_h is 24
-        menu_h is (len of widget.filtered) * item_h
-        if menu_h > 200:
-            menu_h is 200
-        if menu_h > 0:
-            gfx_rrect of [ax, ay + widget.h + 2, widget.w, menu_h, _theme.radius_sm, _theme.menu_bg[0], _theme.menu_bg[1], _theme.menu_bg[2]]
-            for i in range of (len of widget.filtered):
-                iy is ay + widget.h + 2 + i * item_h
-                if iy < ay + widget.h + 2 + menu_h:
-                    if i == widget.hover_index:
-                        gfx_rrect of [ax + 2, iy, widget.w - 4, item_h, _theme.radius_sm, _theme.menu_hover[0], _theme.menu_hover[1], _theme.menu_hover[2]]
-                    _draw_text_clipped of [ax + 8, iy + 5, widget.w - 16, widget.filtered[i], _theme.text_color, _theme.font_scale]
+    # The OPEN LIST is not drawn here (#859) — _render_popups paints it
+    # after the tree walk so it sits above later siblings and past a
+    # clipped ancestor's edge. See _render_dropdown's note.
+
+# Absolute rect of the open list — [x, y, w, h], height capped at the
+# historical 200px scroll bound.
+
+define _combobox_popup_rect(widget) as:
+    menu_h is (len of widget.filtered) * 24
+    if menu_h > 200:
+        menu_h is 200
+    return [widget._ax, widget._ay + widget.h + 2, widget.w, menu_h]
+
+define _render_combobox_popup(widget) as:
+    if widget.open != 1:
+        return null
+    if widget._ax == null:
+        return null
+    r is _combobox_popup_rect of widget
+    menu_h is r[3]
+    if menu_h <= 0:
+        return null
+    px is r[0]
+    py is r[1]
+    item_h is 24
+    gfx_rrect of [px, py, r[2], menu_h, _theme.radius_sm, _theme.menu_bg[0], _theme.menu_bg[1], _theme.menu_bg[2]]
+    for i in range of (len of widget.filtered):
+        iy is py + i * item_h
+        if iy < py + menu_h:
+            if i == widget.hover_index:
+                gfx_rrect of [px + 2, iy, r[2] - 4, item_h, _theme.radius_sm, _theme.menu_hover[0], _theme.menu_hover[1], _theme.menu_hover[2]]
+            _draw_text_clipped of [px + 8, iy + 5, r[2] - 16, widget.filtered[i], _theme.text_color, _theme.font_scale]
+
+# Only the closed box (#859) — the open list is hit-tested above the
+# whole tree by _find_open_popup_at, not by extending in-tree bounds.
 
 define _hit_test_combobox(widget, ax, ay, mx, my) as:
-    total_h is widget.h
-    if widget.open == 1:
-        drop_h is (len of widget.filtered) * 24
-        if drop_h > 200:
-            drop_h is 200
-        total_h is widget.h + drop_h + 2
-    if _point_in_rect of [mx, my, ax, ay, widget.w, total_h]:
+    if _point_in_rect of [mx, my, ax, ay, widget.w, widget.h]:
         return widget
     return null
 
@@ -579,7 +598,6 @@ _register_widget of ["spinbox", {
 }]
 
 _register_widget of ["combobox", {
-    "clip": 0,
     "render": _render_combobox,
     "hit_test": _hit_test_combobox,
     "on_mousedown": _mousedown_combobox,
diff --git a/lib/ui_w_menu.eigs b/lib/ui_w_menu.eigs
index cc19f737..1cfdbe8b 100644
--- a/lib/ui_w_menu.eigs
+++ b/lib/ui_w_menu.eigs
@@ -120,6 +120,13 @@ define tabs(id, x, y, w, h, tab_names, on_tab) as:
 # ---- Render functions ----
 
 define _render_dropdown(widget, ax, ay) as:
+    # The overlay pass draws the open list from _ax/_ay (#859), so stamp
+    # them from the render walk itself rather than trusting the last
+    # _layout: app_loop lays out every frame, but a hand-rolled render
+    # need not, and a list that silently stopped drawing would be a worse
+    # failure than the z-order bug this replaced.
+    widget._ax is ax
+    widget._ay is ay
     if widget.hover == 1:
         dbg is _theme.dropdown_hover
     else:
@@ -136,16 +143,36 @@ define _render_dropdown(widget, ax, ay) as:
     arrow_y is ay + 8
     gfx_line of [arrow_x, arrow_y, arrow_x + 4, arrow_y + 6, _theme.dropdown_arrow[0], _theme.dropdown_arrow[1], _theme.dropdown_arrow[2]]
     gfx_line of [arrow_x + 8, arrow_y, arrow_x + 4, arrow_y + 6, _theme.dropdown_arrow[0], _theme.dropdown_arrow[1], _theme.dropdown_arrow[2]]
-    # Open menu
-    if widget.open == 1:
-        item_h is 24
-        menu_h is (len of widget.items) * item_h
-        gfx_rrect of [ax, ay + widget.h + 2, widget.w, menu_h, _theme.radius_sm, _theme.menu_bg[0], _theme.menu_bg[1], _theme.menu_bg[2]]
-        for i in range of (len of widget.items):
-            iy is ay + widget.h + 2 + i * item_h
-            if i == widget.hover_index:
-                gfx_rrect of [ax + 2, iy, widget.w - 4, item_h, _theme.radius_sm, _theme.menu_hover[0], _theme.menu_hover[1], _theme.menu_hover[2]]
-            _draw_text_clipped of [ax + 8, iy + 5, widget.w - 16, widget.items[i], _theme.text_color, _theme.font_scale]
+    # The OPEN LIST is not drawn here (#859). It is an overlay:
+    # _render_popups paints it after the whole tree walk, so it sits above
+    # later siblings and escapes a clipped ancestor's edge (scroll_panel,
+    # dock region) — the same move #565 made for menu_bar pull-downs. What
+    # is left is the closed box, which is clipped like every other widget.
+
+# Absolute rect of the open list — [x, y, w, h]. The overlay pass runs
+# outside the tree walk, so there is no ox/oy to add: it reads the cached
+# absolute origin, exactly as menu_bar's popup does (#565).
+
+define _dropdown_popup_rect(widget) as:
+    return [widget._ax, widget._ay + widget.h + 2, widget.w, (len of widget.items) * 24]
+
+define _render_dropdown_popup(widget) as:
+    if widget.open != 1:
+        return null
+    if widget._ax == null:
+        return null
+    if (len of widget.items) == 0:
+        return null
+    r is _dropdown_popup_rect of widget
+    px is r[0]
+    py is r[1]
+    item_h is 24
+    gfx_rrect of [px, py, r[2], r[3], _theme.radius_sm, _theme.menu_bg[0], _theme.menu_bg[1], _theme.menu_bg[2]]
+    for i in range of (len of widget.items):
+        iy is py + i * item_h
+        if i == widget.hover_index:
+            gfx_rrect of [px + 2, iy, r[2] - 4, item_h, _theme.radius_sm, _theme.menu_hover[0], _theme.menu_hover[1], _theme.menu_hover[2]]
+        _draw_text_clipped of [px + 8, iy + 5, r[2] - 16, widget.items[i], _theme.text_color, _theme.font_scale]
 
 define _render_menu(widget, ax, ay) as:
     if widget.visible == 1:
@@ -338,11 +365,13 @@ define _render_tabs(widget, ax, ay) as:
 
 # ---- Hit test functions ----
 
+# Only the closed box (#859). The open list is an overlay, so it is
+# hit-tested by _find_open_popup_at ABOVE the tree walk — extending the
+# widget's in-tree bounds here would hand the click to whatever later
+# sibling the list is painted over.
+
 define _hit_test_dropdown(widget, ax, ay, mx, my) as:
-    total_h is widget.h
-    if widget.open == 1:
-        total_h is widget.h + (len of widget.items) * 24 + 2
-    if _point_in_rect of [mx, my, ax, ay, widget.w, total_h]:
+    if _point_in_rect of [mx, my, ax, ay, widget.w, widget.h]:
         return widget
     return null
 
@@ -368,14 +397,24 @@ define _hit_test_menu(widget, ax, ay, mx, my) as:
 
 # ---- Mousemove functions ----
 
+# Which open-list item sits under my — -1 for none. Shared by the hover
+# and mousedown paths so a mouse-only click selects the item it landed on
+# rather than whatever hover_index happened to hold, the way combobox's
+# _combobox_item_at already does (#577). The list starts 2px below the
+# box, which the old inline math forgot.
+
+define _dropdown_item_at(widget, my) as:
+    rel_y is my - widget._ay - widget.h - 2
+    if rel_y < 0:
+        return 0 - 1
+    idx is floor of (rel_y / 24)
+    if idx >= (len of widget.items):
+        return 0 - 1
+    return idx
+
 define _mousemove_dropdown(hit, root, mx, my) as:
     if hit.open == 1:
-        abs_y is hit._ay
-        rel_y is my - abs_y - hit.h
-        if rel_y >= 0:
-            hit.hover_index is floor of (rel_y / 24)
-        else:
-            hit.hover_index is -1
+        hit.hover_index is _dropdown_item_at of [hit, my]
 
 define _mousemove_menu(hit, root, mx, my) as:
     abs_y is hit._ay
@@ -394,9 +433,13 @@ define _mousemove_tabs(hit, root, mx, my) as:
 define _mousedown_dropdown(hit, root, mx, my, ev) as:
     if hit.enabled == 1:
         if hit.open == 1:
-            # Click on open menu — select item
-            if hit.hover_index >= 0 and hit.hover_index < (len of hit.items):
-                hit.selected is hit.hover_index
+            # Select the item the click actually landed on (#577/#859) —
+            # under plain dispatch no mousemove need precede the click, so
+            # hover_index cannot be trusted as the selection.
+            idx is _dropdown_item_at of [hit, my]
+            if idx >= 0:
+                hit.hover_index is idx
+                hit.selected is idx
                 if hit.on_change != null:
                     hit.on_change of hit
             hit.open is 0
@@ -550,15 +593,33 @@ define _find_open_popup_at(widget, mx, my) as:
             if _point_in_rect of [mx, my, pos[0], pos[1], p.w, menu_h]:
                 return widget
         return null
+    # An open dropdown / combobox list is painted by the same overlay
+    # pass (#859), so it takes the pointer above the whole tree too.
+    if widget.type == "dropdown":
+        if widget.open == 1 and widget._ax != null:
+            dr is _dropdown_popup_rect of widget
+            if _point_in_rect of [mx, my, dr[0], dr[1], dr[2], dr[3]]:
+                return widget
+        return null
+    if widget.type == "combobox":
+        if widget.open == 1 and widget._ax != null:
+            cr is _combobox_popup_rect of widget
+            if _point_in_rect of [mx, my, cr[0], cr[1], cr[2], cr[3]]:
+                return widget
+        return null
     if _is_container of widget.type:
         for i in range of (len of widget.children):
             r is _find_open_popup_at of [widget.children[i], mx, my]
             if r != null:
                 return r
     if widget.type == "tabs":
-        for i in range of (len of widget.tab_panels):
-            if widget.tab_panels[i] != null:
-                r is _find_open_popup_at of [widget.tab_panels[i], mx, my]
+        # ACTIVE panel only — render and _hit_test both show just that one,
+        # so an overlay from a hidden tab would be a popup with nothing
+        # behind it (#859).
+        if widget.active < (len of widget.tab_panels):
+            tp is widget.tab_panels[widget.active]
+            if tp != null:
+                r is _find_open_popup_at of [tp, mx, my]
                 if r != null:
                     return r
     if widget.type == "splitter":
@@ -577,13 +638,19 @@ define _render_popups(widget) as:
         return null
     if widget.type == "menu_bar":
         _render_menu_bar_popup of widget
+    elif widget.type == "dropdown":
+        _render_dropdown_popup of widget
+    elif widget.type == "combobox":
+        _render_combobox_popup of widget
     elif _is_container of widget.type:
         for i in range of (len of widget.children):
             _render_popups of widget.children[i]
     elif widget.type == "tabs":
-        for i in range of (len of widget.tab_panels):
-            if widget.tab_panels[i] != null:
-                _render_popups of widget.tab_panels[i]
+        # Only the ACTIVE panel is on screen, so only its popups are
+        # (#859) — the tree walk in render() shows no other panel.
+        if widget.active < (len of widget.tab_panels):
+            if widget.tab_panels[widget.active] != null:
+                _render_popups of widget.tab_panels[widget.active]
     elif widget.type == "splitter":
         if widget.panel_a != null:
             _render_popups of widget.panel_a
@@ -609,7 +676,6 @@ define _close_menus(widget) as:
 # ---- Registration ----
 
 _register_widget of ["dropdown", {
-    "clip": 0,
     "render": _render_dropdown,
     "hit_test": _hit_test_dropdown,
     "on_mousedown": _mousedown_dropdown,
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index ad633cd7..a9fd5120 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -3375,12 +3375,16 @@ else
 fi
 echo ""
 
-# [132] UI containment render-decode oracle (#823 — probe-gated: needs a
-# gfx build). The stubbed [63] suite proves containment on RECORDED clip
-# state; this section proves it on real pixels: the actual SDL software
-# renderer (dummy video driver) draws an escaping canvas on_paint and an
-# overflowing label, and gfx_read decodes the back buffer. Includes its
-# own planted fault (registry clip opt-out must turn the probe red).
+# [132] UI containment render-decode oracle (#823/#859 — probe-gated:
+# needs a gfx build). The stubbed [63] suite proves containment and the
+# overlay z-order on RECORDED clip/draw state; this section proves them on
+# real pixels: the actual SDL software renderer (dummy video driver) draws
+# an escaping canvas on_paint, an overflowing label, an open dropdown list
+# over a later sibling and past its panel's edge, and a grid whose
+# row-label gutter is inside its rect — and gfx_read decodes the back
+# buffer. Includes its own planted faults (the registry clip opt-out, and
+# re-registering the pre-#859 in-tree list render, must turn the probes
+# red).
 UC_PROBE_FILE=$(mktemp /tmp/eigs_uc_probe_XXXXXX.eigs)
 cat > "$UC_PROBE_FILE" <<'PROBE'
 print of (gfx_text_width of ["m", 1])
@@ -3389,17 +3393,18 @@ UC_PROBE_OUT=$(./eigenscript "$UC_PROBE_FILE" 2>&1)
 rm -f "$UC_PROBE_FILE"
 
 if ! echo "$UC_PROBE_OUT" | grep -q "undefined variable"; then
-    echo "[132] UI Containment Render-Decode Oracle (9 checks)"
+    echo "[132] UI Containment Render-Decode Oracle"
     UC_OUTPUT=$(SDL_VIDEODRIVER=dummy ./eigenscript ../tests/test_ui_containment_gfx.eigs 2>&1); UC_RC=$?
+    UC_N=$(derive_count "$UC_OUTPUT" 25 "[132] UI Containment Render-Decode Oracle")
     if rc_ok "$UC_RC" "$UC_OUTPUT" && echo "$UC_OUTPUT" | grep -q "All tests passed"; then
-        TOTAL=$((TOTAL + 9))
-        PASS=$((PASS + 9))
-        echo "  PASS: real-pixel containment + planted fault"
+        TOTAL=$((TOTAL + UC_N))
+        PASS=$((PASS + UC_N))
+        echo "  PASS: real-pixel containment + overlay z-order + planted faults ($UC_N checks)"
     elif echo "$UC_OUTPUT" | grep -q "^SKIP:"; then
         echo "  SKIP: $(echo "$UC_OUTPUT" | grep "^SKIP:" | head -1)"
     else
-        TOTAL=$((TOTAL + 9))
-        FAIL=$((FAIL + 9))
+        TOTAL=$((TOTAL + UC_N))
+        FAIL=$((FAIL + UC_N))
         echo "  FAIL: ui containment oracle"
         echo "$UC_OUTPUT" | grep -iE "assert|error|FAIL" | head -5
     fi
diff --git a/tests/test_ui.eigs b/tests/test_ui.eigs
index 2283c1ad..6c3e77e0 100644
--- a/tests/test_ui.eigs
+++ b/tests/test_ui.eigs
@@ -2726,14 +2726,303 @@ render of [cc823, 0, 0]
 _gfx_rec is 0
 assert_true of [(_rect823_eq of [(_clip823_at of [7, 8, 9]), 20, 30, 100, 80]) == 1, "#823 restoring the registration restores containment"]
 
-# ---- opt-outs stay opt-outs: dropdown's open list is unclipped ----
+# ---- the anchor widget IS clipped now (#859) ----
+# dropdown used to opt out of containment because its open list drew
+# in-tree, below the widget rect. The list moved to the overlay pass, so
+# the box is contained like everything else.
 dd823 is dropdown of ["dd823", 5, 5, 120, ["alpha", "beta"], 0, null]
 dd823.open is 1
 _gfx_log is []
 _gfx_rec is 1
 render of [dd823, 0, 0]
 _gfx_rec is 0
-assert_eq of [_count_kind of "clip", 0, "#823 dropdown renders its open list without a widget clip (registry opt-out)"]
+assert_eq of [_count_kind of "clip", 2, "#859 an OPEN dropdown still renders its box under a widget clip (push + pop)"]
+
+# ============================================================
+# #859 — dropdown / combobox open lists render in the overlay pass
+# ============================================================
+# #565 moved menu_bar pull-downs out of the tree walk into
+# _render_popups; #859 does the same for the dropdown and combobox open
+# lists. Two things follow and both are asserted below: the list is
+# painted AFTER every later sibling (z-order), and it is painted with no
+# ancestor clip active, so it escapes the panel edge that used to crop
+# it. The anchor widgets lose their "clip": 0 opt-out, and grid loses
+# its own by folding the row-label gutter inside its rect.
+print of "--- #859 overlay pass: dropdown/combobox lists, grid gutter ---"
+
+# Section 18 (#594) rebound gfx_rrect to a shade-capturing stub and never
+# put it back, so from there on the log carries no rrect entries — and
+# every widget box in this section is an rrect. Restore the recorder.
+define gfx_rrect(args) as:
+    _gfx_note of ["rrect", args]
+    return null
+
+# First recorded rect/rrect whose ORIGIN lies in [x0,y0)..[x1,y1), with
+# the clip active at that moment. i = -1 when nothing matched.
+define _find859(x0, y0, x1, y1) as:
+    local act is null
+    for i in range of (len of _gfx_log):
+        local e is _gfx_log[i]
+        if e[0] == "clip":
+            act is e[1]
+        elif e[0] == "rrect" or e[0] == "rect":
+            local a is e[1]
+            if a[0] >= x0 and a[0] < x1 and a[1] >= y0 and a[1] < y1:
+                return {"i": i, "clip": act, "args": a}
+    return {"i": 0 - 1, "clip": act, "args": null}
+
+# Smallest x any primitive of any kind recorded (x is arg 0 for rect,
+# rrect, line and text alike).
+define _minx859() as:
+    local best is 1000000
+    for i in range of (len of _gfx_log):
+        local e is _gfx_log[i]
+        if e[0] != "clip":
+            if e[1][0] < best:
+                best is e[1][0]
+    return best
+
+# ---- the containment opt-outs are exactly menu + dialog ----
+opt859 is []
+for k859 in keys of _widget_registry:
+    e859 is _widget_registry[k859]
+    if e859.clip != null and e859.clip == 0:
+        append of [opt859, k859]
+sort of opt859
+assert_eq of [len of opt859, 2, "#859 exactly two registry entries opt out of the containment clip"]
+assert_eq of [opt859[0], "dialog", "#859 dialog keeps its opt-out (full-screen dim)"]
+assert_eq of [opt859[1], "menu", "#859 menu keeps its opt-out (floating popup)"]
+
+# ---- dropdown: z-order and escape from the ancestor clip ----
+# panel (10,10,200x60) holds the dropdown at (5,5); the open list spans
+# y 41..113, so it runs past the panel's bottom edge at y=70 AND under a
+# later sibling that starts at y=60.
+r859 is panel of ["r859", 0, 0, 400, 300]
+p859 is panel of ["p859", 10, 10, 200, 60]
+dd859 is dropdown of ["dd859", 5, 5, 120, ["alpha", "beta", "gamma"], 0, null]
+add_child of [p859, dd859]
+sib859 is panel of ["sib859", 10, 60, 200, 120]
+add_child of [r859, p859]
+add_child of [r859, sib859]
+_layout of [r859, 0, 0]
+dd859.open is 1
+
+_gfx_log is []
+_gfx_rec is 1
+render of [r859, 0, 0]
+_render_popups of r859
+_gfx_rec is 0
+
+dlist859 is _find859 of [15, 41, 16, 42]
+dsib859 is _find859 of [10, 60, 11, 61]
+dbox859 is _find859 of [15, 15, 16, 16]
+assert_true of [dlist859.i >= 0, "#859 the open dropdown list is drawn"]
+assert_true of [dsib859.i >= 0, "#859 the later sibling is drawn"]
+assert_true of [dsib859.i < dlist859.i, "#859 the later sibling's draws PRECEDE the open list's (overlay z-order)"]
+assert_eq of [dlist859.clip, null, "#859 the open list draws with no ancestor clip active"]
+assert_true of [dlist859.args[1] + dlist859.args[3] > 70, "#859 the list rect extends past the panel's bottom edge"]
+assert_true of [(_rect823_eq of [dbox859.clip, 15, 15, 120, 24]) == 1, "#859 the dropdown BOX draws under a clip of its own rect (opt-out gone)"]
+
+# Vacuity control: the list exists ONLY because of the overlay pass.
+_gfx_log is []
+_gfx_rec is 1
+render of [r859, 0, 0]
+_gfx_rec is 0
+assert_eq of [(_find859 of [15, 41, 16, 42]).i, 0 - 1, "#859 without _render_popups the tree walk draws no list at all"]
+
+# The overlay reads the absolute origin the RENDER stamped, so a
+# hand-rolled loop that never calls _layout still gets its list.
+nl859 is panel of ["nl859", 0, 0, 400, 300]
+ndd859 is dropdown of ["ndd859", 15, 15, 120, ["a", "b"], 0, null]
+add_child of [nl859, ndd859]
+ndd859.open is 1
+_gfx_log is []
+_gfx_rec is 1
+render of [nl859, 0, 0]
+_render_popups of nl859
+_gfx_rec is 0
+assert_true of [(_find859 of [15, 41, 16, 42]).i >= 0, "#859 the overlay works with no _layout pass — render stamps the origin"]
+
+# An open list in a NON-ACTIVE tab panel is not on screen, so it must not
+# be painted over the active one either.
+tb859 is tabs of ["tb859", 0, 0, 300, 200, ["one", "two"], null]
+tp859a is panel of ["tp859a", 0, 0, 300, 170]
+tp859b is panel of ["tp859b", 0, 0, 300, 170]
+hdd859 is dropdown of ["hdd859", 15, 15, 120, ["a", "b"], 0, null]
+add_child of [tp859b, hdd859]
+append of [tb859.tab_panels, tp859a]
+append of [tb859.tab_panels, tp859b]
+tb859.active is 0
+_layout of [tb859, 0, 0]
+hdd859.open is 1
+_gfx_log is []
+_gfx_rec is 1
+render of [tb859, 0, 0]
+_render_popups of tb859
+_gfx_rec is 0
+assert_eq of [(_find859 of [15, 69, 16, 70]).i, 0 - 1, "#859 a hidden tab's open list is not painted over the active tab"]
+assert_eq of [_find_open_popup_at of [tb859, 40, 80], null, "#859 ... and it does not steal the pointer either"]
+# Control: the same list IS painted and IS hit-testable once its tab is
+# the active one — otherwise the two assertions above are vacuous.
+tb859.active is 1
+_layout of [tb859, 0, 0]
+_gfx_log is []
+_gfx_rec is 1
+render of [tb859, 0, 0]
+_render_popups of tb859
+_gfx_rec is 0
+assert_true of [(_find859 of [15, 69, 16, 70]).i >= 0, "#859 control: the list IS painted when its tab is active"]
+assert_true of [(_find_open_popup_at of [tb859, 40, 80]) != null, "#859 control: and it IS hit-tested when its tab is active"]
+
+# ---- combobox: same two properties ----
+c859 is panel of ["c859", 0, 0, 400, 300]
+cp859 is panel of ["cp859", 10, 10, 200, 60]
+cb859 is combobox of ["cb859", 5, 5, 120, ["alpha", "beta", "gamma"], null]
+add_child of [cp859, cb859]
+csib859 is panel of ["csib859", 10, 60, 200, 120]
+add_child of [c859, cp859]
+add_child of [c859, csib859]
+_layout of [c859, 0, 0]
+cb859.open is 1
+cb859.filtered is cb859.items
+
+_gfx_log is []
+_gfx_rec is 1
+render of [c859, 0, 0]
+_render_popups of c859
+_gfx_rec is 0
+
+clist859 is _find859 of [15, 41, 16, 42]
+csibr859 is _find859 of [10, 60, 11, 61]
+cbox859 is _find859 of [15, 15, 16, 16]
+assert_true of [clist859.i >= 0, "#859 the open combobox list is drawn"]
+assert_true of [csibr859.i < clist859.i, "#859 combobox: the later sibling's draws precede the list's"]
+assert_eq of [clist859.clip, null, "#859 combobox: the open list draws with no ancestor clip active"]
+assert_true of [clist859.args[1] + clist859.args[3] > 70, "#859 combobox: the list rect extends past the panel's bottom edge"]
+assert_true of [(_rect823_eq of [cbox859.clip, 15, 15, 120, 24]) == 1, "#859 the combobox BOX draws under a clip of its own rect (opt-out gone)"]
+
+# ---- interaction: the click lands on the DROPDOWN, not the sibling ----
+# The button sits under the open list. A click at (40, 90) is inside
+# BOTH; the overlay must win, and the button must not even see it.
+i859 is panel of ["i859", 0, 0, 400, 300]
+ip859 is panel of ["ip859", 10, 10, 200, 60]
+idd859 is dropdown of ["idd859", 5, 5, 120, ["alpha", "beta", "gamma"], 0, null]
+add_child of [ip859, idd859]
+ibtn_clicks is [0]
+define i859_click(w) as:
+    ibtn_clicks[0] is ibtn_clicks[0] + 1
+ibtn859 is button of ["ibtn859", 10, 60, 200, 40, "under", i859_click]
+add_child of [i859, ip859]
+add_child of [i859, ibtn859]
+_layout of [i859, 0, 0]
+
+# Control first: with the list CLOSED the very same click DOES reach the
+# button — otherwise the assertion below would pass over an empty scene.
+_ui.last_click_id is ""
+dispatch of [i859, {"type": "mousedown", "x": 40, "y": 90, "button": 1}]
+assert_eq of [ibtn859.pressed, 1, "#859 control: with the list closed the click reaches the button underneath"]
+dispatch of [i859, {"type": "mouseup", "x": 40, "y": 90, "button": 1}]
+assert_eq of [ibtn_clicks[0], 1, "#859 control: and the button fires"]
+
+_ui.last_click_id is ""
+dispatch of [i859, {"type": "mousedown", "x": 40, "y": 20, "button": 1}]
+assert_eq of [idd859.open, 1, "#859 clicking the closed box opens the list"]
+# Hover follows the overlay too: item 2 spans y 89..112.
+dispatch of [i859, {"type": "mousemove", "x": 40, "y": 90}]
+assert_eq of [idd859.hover_index, 2, "#859 mousemove over the overlaid list hovers the dropdown item"]
+assert_eq of [ibtn859.hover, 0, "#859 the sibling under the list gets no hover"]
+_ui.last_click_id is ""
+dispatch of [i859, {"type": "mousedown", "x": 40, "y": 90, "button": 1}]
+assert_eq of [idd859.selected, 2, "#859 the click selects on the DROPDOWN, not the sibling"]
+assert_eq of [idd859.open, 0, "#859 selecting closes the list"]
+assert_eq of [ibtn859.pressed, 0, "#859 the sibling under the open list never saw the click"]
+assert_eq of [ibtn_clicks[0], 1, "#859 the sibling's on_click did not fire"]
+
+# Selection by the click's own y, with no mousemove first (the #577 rule,
+# which dropdown never had): reopen and click item 0 directly.
+_ui.last_click_id is ""
+dispatch of [i859, {"type": "mousedown", "x": 40, "y": 20, "button": 1}]
+idd859.hover_index is 0 - 1
+_ui.last_click_id is ""
+dispatch of [i859, {"type": "mousedown", "x": 40, "y": 45, "button": 1}]
+assert_eq of [idd859.selected, 0, "#859 a mouse-only click selects the item it landed on"]
+
+# Outside-click still closes without selecting.
+_ui.last_click_id is ""
+dispatch of [i859, {"type": "mousedown", "x": 40, "y": 20, "button": 1}]
+assert_eq of [idd859.open, 1, "#859 the list reopens"]
+_ui.last_click_id is ""
+dispatch of [i859, {"type": "mousedown", "x": 350, "y": 260, "button": 1}]
+assert_eq of [idd859.open, 0, "#859 a click outside the overlay closes the list"]
+assert_eq of [idd859.selected, 0, "#859 the outside click changed no selection"]
+
+# Escape closes it through the keyboard route.
+_ui.last_click_id is ""
+dispatch of [i859, {"type": "mousedown", "x": 40, "y": 20, "button": 1}]
+assert_eq of [idd859.open, 1, "#859 the list reopens for the keyboard case"]
+handle_key of [i859, {"type": "keydown", "key": "escape", "shift": 0, "ctrl": 0, "alt": 0}]
+assert_eq of [idd859.open, 0, "#859 escape closes the open list"]
+
+# ---- grid: the row-label gutter is INSIDE the widget rect ----
+g859 is grid of ["g859", 30, 20, 4, 3, 20, 20, null]
+gp859 is panel of ["gp859", 0, 0, 400, 300]
+add_child of [gp859, g859]
+_layout of [gp859, 0, 0]
+assert_eq of [g859.w, 80, "#859 with no row labels the grid keeps its historical width"]
+g859.row_labels is ["a", "b", "c"]
+_layout of [gp859, 0, 0]
+assert_eq of [g859.w, 140, "#859 the grid rect widens to hold its row-label gutter"]
+
+_gfx_log is []
+_gfx_rec is 1
+render of [g859, 0, 0]
+_gfx_rec is 0
+# cell (0,0) is drawn inset by 1px from its origin, so origin x = 90 is
+# widget.x (30) + row_label_w (60).
+cell859 is _find859 of [91, 21, 92, 22]
+assert_true of [cell859.i >= 0, "#859 cell (0,0) origin is the widget's x + row_label_w"]
+assert_true of [(_rect823_eq of [cell859.clip, 30, 20, 140, 60]) == 1, "#859 the grid draws under a clip of its own rect (opt-out gone)"]
+assert_eq of [_minx859 of null, 30, "#859 nothing is drawn left of the grid's x — the labels live in the gutter"]
+
+# The measure hook runs inside render(), so a grid that gains row labels
+# and is drawn WITHOUT a layout pass still gets a clip wide enough for
+# its cells — the frame does not silently lose them.
+nm859 is grid of ["nm859", 30, 20, 4, 3, 20, 20, null]
+nm859._ax is 30
+nm859._ay is 20
+nm859.row_labels is ["a", "b", "c"]
+_gfx_log is []
+_gfx_rec is 1
+render of [nm859, 0, 0]
+_gfx_rec is 0
+assert_eq of [nm859.w, 140, "#859 render() restamps the grid box before clipping it"]
+nmc859 is _find859 of [91, 21, 92, 22]
+assert_true of [(_rect823_eq of [nmc859.clip, 30, 20, 140, 60]) == 1, "#859 the clip covers the widened rect on the very first frame"]
+
+# The mouse follows the gutter: a click left of the first column is not a
+# cell click, and cell (0,0) starts at x + row_label_w.
+groot859 is panel of ["groot859", 0, 0, 400, 300]
+gm859 is grid of ["gm859", 30, 20, 4, 3, 20, 20, null]
+gm859.row_labels is ["a", "b", "c"]
+add_child of [groot859, gm859]
+_layout of [groot859, 0, 0]
+_ui.last_click_id is ""
+dispatch of [groot859, {"type": "mousedown", "x": 40, "y": 25, "button": 1}]
+assert_eq of [gm859.cells[0][0], 0, "#859 a click in the row-label gutter toggles no cell"]
+_ui.last_click_id is ""
+dispatch of [groot859, {"type": "mousedown", "x": 95, "y": 25, "button": 1}]
+assert_eq of [gm859.cells[0][0], 1, "#859 a click at x + row_label_w toggles cell (0,0)"]
+
+# The public accessor an app maps pixels through, so nothing has to
+# re-derive the gutter offset.
+gco859 is grid_cell_origin of gm859
+assert_eq of [gco859[0], 90, "#859 grid_cell_origin x is the widget x plus the gutter"]
+assert_eq of [gco859[1], 20, "#859 grid_cell_origin y is the widget y"]
+gm859.row_labels is null
+_layout of [groot859, 0, 0]
+gco859b is grid_cell_origin of gm859
+assert_eq of [gco859b[0], 30, "#859 with no row labels the cell origin is the widget x"]
+assert_eq of [gm859.w, 80, "#859 dropping the row labels narrows the rect back"]
 
 # ============================================================
 # Summary
diff --git a/tests/test_ui_containment_gfx.eigs b/tests/test_ui_containment_gfx.eigs
index ae416977..ae9b92eb 100644
--- a/tests/test_ui_containment_gfx.eigs
+++ b/tests/test_ui_containment_gfx.eigs
@@ -90,5 +90,133 @@ _widget_registry["canvas"].clip is null
 _draw_scene of null
 assert_true of [(_is_rogue of (gfx_read of [30, 30])) == 0, "#823 restoring the registration restores containment"]
 
+# ============================================================
+# #859 — the open list is an OVERLAY, on real pixels
+# ============================================================
+# [63] proves the z-order and the missing ancestor clip on the RECORDED
+# draw stream. Here the real SDL renderer paints the scene and gfx_read
+# decodes the back buffer: the list must survive being painted after a
+# sibling that covers it, and must survive past the edge of the panel
+# whose clip used to crop it. Planted fault at the end: re-registering a
+# render that draws the list IN-TREE (the pre-#859 body) must turn both
+# probes red.
+
+define _is_col(px, c) as:
+    if px == null:
+        return 0
+    if px[0] == c[0] and px[1] == c[1] and px[2] == c[2]:
+        return 1
+    return 0
+
+_sib_col is [200, 30, 30]
+
+define _sib_paint(w, ax, ay) as:
+    gfx_rect of [ax, ay, w.w, w.h, 200, 30, 30]
+
+# panel (20,20,200x40): its clip ends at y = 60. The dropdown sits at
+# (25,25); its open list spans y 51..123 and x 25..145 — past the panel
+# edge, and under a canvas sibling added AFTER it that spans y 80..180.
+root859 is panel of ["root859", 0, 0, 400, 300]
+p859 is panel of ["p859", 20, 20, 200, 40]
+dd859 is dropdown of ["dd859", 5, 5, 120, ["a", "b", "c"], 0, null]
+add_child of [p859, dd859]
+sib859 is canvas of ["sib859", 20, 80, 200, 100, _sib_paint, null]
+add_child of [root859, p859]
+add_child of [root859, sib859]
+_layout of [root859, 0, 0]
+dd859.open is 1
+dd859.hover_index is 0 - 1
+
+define _scene859(with_overlay) as:
+    gfx_clear of [9, 9, 9]
+    render of [root859, 0, 0]
+    if with_overlay == 1:
+        _render_popups of root859
+
+_scene859 of 1
+# The scene is not vacuous: the sibling really did paint where the list
+# does NOT reach (the list's right edge is x = 145).
+assert_true of [(_is_col of [(gfx_read of [180, 100]), _sib_col]) == 1, "#859 the sibling canvas IS painted beside the list"]
+assert_true of [(_is_col of [(gfx_read of [100, 100]), _theme.menu_bg]) == 1, "#859 the open list is painted OVER the later sibling"]
+assert_true of [(_is_col of [(gfx_read of [100, 70]), _theme.menu_bg]) == 1, "#859 the open list is painted PAST the panel's bottom edge"]
+
+# Control: without the overlay pass the tree walk paints no list at all.
+_scene859 of 0
+assert_true of [(_is_col of [(gfx_read of [100, 100]), _theme.menu_bg]) == 0, "#859 with no overlay pass those pixels are not the list's"]
+
+# ---- planted fault: draw the list IN-TREE again (the pre-#859 body) ----
+define _render_dropdown_intree(widget, ax, ay) as:
+    _draw_rbox of [ax, ay, widget.w, widget.h, _theme.radius_sm, _theme.dropdown_bg, _theme.panel_border]
+    if widget.open == 1:
+        item_h is 24
+        menu_h is (len of widget.items) * item_h
+        gfx_rrect of [ax, ay + widget.h + 2, widget.w, menu_h, _theme.radius_sm, _theme.menu_bg[0], _theme.menu_bg[1], _theme.menu_bg[2]]
+
+_prev859 is _widget_registry["dropdown"].render
+_widget_registry["dropdown"].render is _render_dropdown_intree
+_widget_registry["dropdown"].clip is 0
+_scene859 of 0
+assert_true of [(_is_col of [(gfx_read of [100, 100]), _theme.menu_bg]) == 0, "#859 planted fault: drawn in-tree, the sibling COVERS the list (z-order probe red)"]
+assert_true of [(_is_col of [(gfx_read of [100, 70]), _theme.menu_bg]) == 0, "#859 planted fault: drawn in-tree, the panel clip CROPS the list (escape probe red)"]
+_widget_registry["dropdown"].render is _prev859
+_widget_registry["dropdown"].clip is null
+_scene859 of 1
+assert_true of [(_is_col of [(gfx_read of [100, 100]), _theme.menu_bg]) == 1, "#859 restoring the overlay render restores both properties"]
+
+# ---- the click lands on the DROPDOWN, not the sibling it covers ----
+# Same scene, driven headlessly through dispatch while the real renderer
+# is live: the pointer is over pixels the list owns, so the dropdown must
+# take the click and the canvas underneath must not see it.
+sib_clicks859 is [0]
+define _sib_mouse(w, ev) as:
+    sib_clicks859[0] is sib_clicks859[0] + 1
+sib859.on_mouse is _sib_mouse
+_ui.last_click_id is ""
+dd859.open is 1
+dd859.hover_index is 0 - 1
+_scene859 of 1
+# item 2 ("c") spans y 99..122 — inside the sibling canvas (y 80..180).
+dispatch of [root859, {"type": "mousedown", "x": 100, "y": 105, "button": 1}]
+assert_eq of [dd859.selected, 2, "#859 the click on the overlaid list selects on the DROPDOWN"]
+assert_eq of [sib_clicks859[0], 0, "#859 the canvas under the open list never saw the click"]
+assert_eq of [dd859.open, 0, "#859 selecting closes the list"]
+_scene859 of 1
+assert_true of [(_is_col of [(gfx_read of [100, 105]), _sib_col]) == 1, "#859 with the list closed those pixels are the sibling's again"]
+# Control: the canvas really is under that point and really does take a
+# click when nothing is drawn over it.
+_ui.last_click_id is ""
+dispatch of [root859, {"type": "mousedown", "x": 100, "y": 105, "button": 1}]
+dispatch of [root859, {"type": "mouseup", "x": 100, "y": 105, "button": 1}]
+assert_true of [sib_clicks859[0] > 0, "#859 control: with no list over it the canvas DOES see the click"]
+sib859.on_mouse is null
+
+# ---- grid: the row-label gutter is inside the rect, on real pixels ----
+g859 is grid of ["g859", 240, 20, 3, 3, 20, 20, null]
+g859.row_labels is ["a", "b", "c"]
+gr859 is panel of ["gr859", 0, 0, 400, 300]
+add_child of [gr859, g859]
+_layout of [gr859, 0, 0]
+assert_eq of [g859.w, 120, "#859 the grid rect holds gutter + cells"]
+
+define _count_nonbg(x0, y0, x1, y1) as:
+    local n is 0
+    local yy is y0
+    loop while yy < y1:
+        local xx is x0
+        loop while xx < x1:
+            local px is gfx_read of [xx, yy]
+            if px != null:
+                if px[0] != 9 or px[1] != 9 or px[2] != 9:
+                    n is n + 1
+            xx is xx + 1
+        yy is yy + 1
+    return n
+
+gfx_clear of [9, 9, 9]
+render of [g859, 0, 0]
+assert_true of [(_is_col of [(gfx_read of [305, 25]), g859.color_off]) == 1, "#859 cell (0,0) is painted at x + row_label_w"]
+assert_eq of [_count_nonbg of [180, 20, 240, 80], 0, "#859 nothing is painted left of the grid's x"]
+assert_true of [(_count_nonbg of [240, 20, 300, 80]) > 0, "#859 the row labels are painted inside the gutter"]
+
 gfx_close of null
 test_summary of null

From b2df35a6d0b38e5bebf74e20e55721bcee00d49e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 19:34:49 +0000
Subject: [PATCH 19/39] autograd: reverse-mode tape on shaped buffers +
 matmul_at/matmul_bt/scatter_add (#973)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two ML consumers had each hand-rolled reverse-mode backprop (Tidepool's DQN
in train.eigs:210-408, iLambdaAi's transformer rules in src/model_train.c)
because the substrate shipped only finite-difference `numerical_grad`.
This promotes the shared primitive into the stdlib.

lib/autograd.eigs — a Wengert-list (tape) autograd over the f64 tensor
builtins on shaped buffers: ag_tape / ag_leaf / ag_const, ops ag_matmul,
ag_add, ag_sub, ag_mul, ag_scale, ag_relu, ag_leaky_relu, ag_softmax,
ag_log_softmax, ag_gather, ag_norm, ag_sum, ag_mean, ag_softmax_ce, and
ag_backward / ag_grad / ag_value / ag_sgd_step / ag_sgd_step_clipped.
vjp rules: matmul (dA = dY·Bᵀ, dB = Aᵀ·dY), add/bias (sum over the batch
axis), relu/leaky_relu (mask), softmax / log_softmax / CE (p − onehot),
gather (scatter_add), norm, sum/mean. Leaf values are the caller's buffers
(ag_sgd_step updates in place); a node used twice accumulates; constants
get no gradient. `ag_` prefix so load_file never shadows the builtins.

C prerequisites (src/builtins_tensor.c, always-compiled f64 buffer path;
the f32 twins in model_train.c only exist under EIGENSCRIPT_EXT_MODEL):
  - matmul_at (aᵀ·b) and matmul_bt (a·bᵀ): same i-k-j tiling as
    ne_matmul_buf, so byte-identical to `matmul` of the explicitly
    transposed operand; buffers and nested lists; #512 raise discipline.
  - scatter_add of [dst, indices, values]: gather's in-place dual (per-row
    on a shaped dst, flat on a 1-D dst); every index validated before
    anything is written, so a raise leaves dst untouched. Length mismatches
    RAISE (value) rather than truncating to the shorter side — dropping a
    gradient entry silently is the same wrong-number class that makes an
    out-of-range index raise.
  - buffer paths the tape needed and consumers had hand-rolled around:
    subtract/multiply/divide on buffers, [rows×cols]±[cols] bias broadcast
    and scalar broadcast for all four arithmetic ops (mismatches RAISE,
    they answered a silent 0 before), softmax/log_softmax/leaky_relu/mean
    on buffers, gather on a shaped buffer (out-of-range raises), and
    numerical_grad on a buffer parameter (the gradient-check oracle).
  - log_softmax of a 2-D LIST used to answer for row 0 only: its
    `[tensor, dim]` form fired on "first element is a list", which every
    2-D tensor satisfies. Found by the buffer/list differential; now only
    exactly [list, number] is the dim form.
Registered, SANDBOX_ALLOW'd (pure compute), lsp_builtin_index regenerated.

Repro (baseline v0.43.0, probe over a 2x3 shaped buffer w):
  matmul_at/matmul_bt/scatter_add -> undefined variable
  softmax/log_softmax/leaky_relu/numerical_grad of w -> null
  subtract/multiply/gather of w, add of [w, bias] -> 0
  import autograd -> module not found
After: every one returns a buffer; `import autograd` trains.

Regression tests:
  tests/test_autograd.eigs (185 checks): every vjp rule vs numerical_grad
    within 1e-4 relative + 1e-6 absolute (worst measured 5e-6, most ~1e-10;
    tolerance rationale in the file header), batch axis on every reduction,
    accumulation, const/untouched leaves; a 2-layer softmax-CE MLP trained
    by the tape (loss 1.22 -> 0.0028 in 150 steps, 14/14 windows decreasing,
    100% train accuracy); the Tidepool DQN shape 433->64->32->6 batch 32
    through one backward with gradient shapes asserted and db3 checked
    against the hand-rolled per-action reduction.
  tests/test_tensor_buffer_ops.eigs (78 checks): matmul_at/matmul_bt
    byte-identical to matmul of the transposed list operand (35x33 crosses
    the 32-wide tile), scatter_add vs the list loop and gather's dual,
    buffer elementwise/softmax/log_softmax/leaky_relu/mean vs the list
    path, numerical_grad buffer vs list, the log_softmax 2-D pin, raises
    (out-of-range, wrong types, and both length-mismatch forms).
  tests/test_sandbox_allow.eigs: the three new names reachable in the sandbox.
Planted faults (executed on this tree, then restored):
  A. dB sign flipped in ag_matmul's vjp -> test_autograd: Tests: 185 |
     Pass: 175 | Fail: 10 — matmul dB, matmul(1-D x) dW, relu∘add dW,
     softmax_ce dW, gather∘matmul dW, norm dW (every element off), and the
     MLP stops training (final loss, window descent, accuracy) plus the DQN
     step no longer lowers the TD loss.
  B. scatter_add overwrites instead of accumulating -> test_tensor_buffer_ops:
     Tests: 76 | Pass: 74 | Fail: 2 (the repeated-index accumulate checks).
  C. scatter_add back to min(ni, nv) truncation -> test_tensor_buffer_ops:
     Tests: 78 | Pass: 76 | Fail: 2 (both length-mismatch raises).
  D. docs/ARCHITECTURE.md lib-module count back to 77 -> tools/
     doc_drift_check.sh exits 1 and suite sections [99v]/[99p] FAIL.

Docs: STDLIB.md (index row + lib/autograd section with a gated example),
BUILTINS.md (three new rows, buffer notes on the touched builtins,
numerical_grad buffers), SPEC.md shaped-buffers paragraph, llms.txt, and
ARCHITECTURE.md's raw lib/ module count 77 -> 78 (the doc-drift gate,
check 6, fails the suite otherwise — this module is the 78th).

Round 2 — the broadcast class inside the tape's own vjp rules.

`ag_add`/`ag_sub` reduced a broadcast operand's gradient over the batch
axis; `ag_mul` did not. `ag_mul of [t, x, bias]` answered an unreduced
[rows x cols] gradient for a [cols] parameter, and `ag_sgd_step` then
stepped that parameter with the first `cols` entries of it — a silent wrong
number produced by the module whose reason to exist is removing that class.

Repro (x = [2x3] leaf, v = [3] leaf, loss = sum(x * v)):
  tape  g(v) = 0.5 1 1.5 2 2.5 3   shape [2,3], 6 elements
  numerical  = 2.5 3.5 4.5         shape [3]
  ag_sgd_step of [vn, 0.1] -> v = 0.95 1.15 1.35, not 0.75 0.9 1.05
After: tape g(v) = 2.5 3.5 4.5, shape [3]; the step lands on 0.75 0.9 1.05.

Root: the reduction was inline in the add/sub branch rather than a shared
rule, so a rule added later could not inherit it. `_ag_reduce_to of
[who, pv, g]` now owns it and mirrors buffer_elementwise's shape rules
exactly — scalar operand -> `sum of g`; equal element count -> g (copied
into the operand's shape when the ranks differ, since elementwise is flat
and the values already are the gradient); one-row operand whose column
count matches -> column sums; anything else -> THROW. ag_add, ag_sub and
ag_mul route both deltas through it in both operand orders. A
scalar-valued node (from ag_sum / ag_mean / ag_norm / ag_softmax_ce) as an
elementwise operand now works instead of dying downstream with "cannot
apply '/' to buffer and num".

The class swept, rule by rule:
  ag_add / ag_sub / ag_mul   broadcastable -> reduced (this fix)
  ag_scale                   k is documented as a NUMBER; a buffer k
                             broadcasts and can make the result a different
                             shape from `a` (measured: a=[4], k=[5x4] ->
                             value [5,4]), so it now THROWS
  ag_matmul                  no broadcast form: matmul of [[5x4],[4]] raises
                             "incompatible shapes (5x4 · 1x4)" in the forward
                             pass, and both vjp products are shape-determined
                             by the matmul contract
  relu / leaky_relu / softmax / log_softmax / gather / norm / sum / mean /
  softmax_ce                 one tensor operand; each vjp allocates its delta
                             from that operand's own shape, so no broadcast
                             reduction is reachable
  (the module has no ag_div / ag_pow to check)

ag_sgd_step and ag_sgd_step_clipped are the backstop: both now THROW on a
non-buffer leaf and on a gradient whose element count is not the
parameter's, instead of stepping the first `len of grad` entries.

tests/test_autograd.eigs section 4 (185 checks, was 101; placed last so
sections 1-3 draw the same seeded stream as before): add / sub / mul each
checked against numerical_grad in BOTH operand orders on BOTH operands with
a [5x4] and a [4], plus a scalar-node operand for mul and add; 20
ag_sgd_step steps on a [4] broadcast parameter, each lowering the loss and
converging to the analytic optimum (v[j] = mean_i (T-D)[i][j]) within 0.1%;
and the refusals — matmul's, the forward elementwise mismatch, ag_scale's
tensor k, and both step functions' shape guard.
Planted faults (executed on this tree, then restored, green after each):
  E. ag_mul's reduction dropped -> 185 checks, 6 FAIL: both mul broadcast
     operands wrong element count (20 vs 4), wrong rank (2 vs 1) and every
     element off numerical_grad; then the scalar-node case dies in ag_mean.
  F. ag_add/ag_sub's reduction dropped -> 10 FAIL (bias(add) db,
     sub(bias broadcast) dv, softmax_ce db — count, rank and values) and the
     new ag_sgd_step guard stops the MLP instead of mistraining it.
  G. the ag_sgd_step / ag_sgd_step_clipped shape guard removed ->
     185 | Pass: 183 | Fail: 2 (both refusal checks).
  H. ag_scale's tensor-k guard removed -> 185 | Pass: 184 | Fail: 1
     ("no raise, answered shape [5, 4]").
docs/STDLIB.md gains a Broadcasting paragraph, updated ag_add/ag_mul/
ag_scale/ag_sgd_step rows, and a second gated example (the column-sum
gradient [5, 7, 9] of sum(x * s)) — run by suite [89]/[90].

Residuals: consumers are not edited. Tidepool would drop its hand-rolled
`transpose` (train.eigs:97) and `add_bias` (:123) and replace the manual
dw3/db3/dw2/db2/dw1/db1 chain (:292-364) with ag_matmul/ag_add/ag_relu +
ag_backward + ag_sgd_step_clipped — but its Huber-clipped TD gradient seeds
the q node directly, and `ag_backward` only seeds ones, so full adoption
also wants either an `ag_huber` node or a backward entry point that takes a
caller-supplied seed. iLambdaAi's transformer backward lives in
src/model_train.c on f32 and stays hand-written; a tape for it needs either
an f32 tape or moving that model to f64 buffers.

Closes #973

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
(cherry picked from commit 4a0af5a27f80357a3003e06e92ce883ddf23c2d3)
---
 docs/ARCHITECTURE.md                 |   2 +-
 docs/BUILTINS.md                     |  34 +-
 docs/COMPARISON.md                   |   6 +
 docs/SPEC.md                         |  43 +-
 docs/STDLIB.md                       | 111 +++++
 docs/llms.txt                        |   6 +-
 lib/autograd.eigs                    | 468 ++++++++++++++++++
 src/builtins.c                       |   4 +
 src/builtins_internal.h              |   3 +
 src/builtins_tensor.c                | 470 ++++++++++++++++--
 src/lsp_builtin_index.h              |   3 +
 tests/run_all_tests.sh               |  11 +
 tests/test_autograd.eigs             | 680 +++++++++++++++++++++++++++
 tests/test_misc_builtins.eigs        |  20 +-
 tests/test_sandbox_allow.eigs        |  17 +-
 tests/test_tensor_buffer_inputs.eigs |  23 +
 tests/test_tensor_buffer_ops.eigs    | 241 ++++++++++
 17 files changed, 2088 insertions(+), 54 deletions(-)
 create mode 100644 lib/autograd.eigs
 create mode 100644 tests/test_autograd.eigs
 create mode 100644 tests/test_tensor_buffer_ops.eigs

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 87d2d033..705d9711 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -256,7 +256,7 @@ The minimal build (`make build`) sets all flags to 0. The full build
 
 ## Standard Library
 
-The 77 modules in `lib/` are pure EigenScript — no C code. They are loaded at
+The 78 modules in `lib/` are pure EigenScript — no C code. They are loaded at
 runtime via `load_file of "lib/module.eigs"`. Both loaders use absolute paths
 as-is; relative paths search the containing file's directory, the `eigs_modules`
 walk, the nearest `eigs.json` project root, then the executable-relative and
diff --git a/docs/BUILTINS.md b/docs/BUILTINS.md
index e2e91acb..63dcbeee 100644
--- a/docs/BUILTINS.md
+++ b/docs/BUILTINS.md
@@ -483,6 +483,23 @@ heterogeneous or nested data.
 | `pow` | `pow of [base, exp]` | Element-wise exponentiation; overflow saturates |
 | `negative` | `negative of t` | Element-wise negation |
 
+All five arithmetic builtins take shaped **buffers** wherever they take a flat
+numeric list (#1093/#973), through **one** implementation — the same
+`tensor_elementwise` shape algebra, container for container, so every rule
+below reads the same for buffers and lists: two operands of equal count are
+combined elementwise (keeping the first's shape); a `[rows × cols]` operand
+with a `[cols]` one broadcasts the vector over every row and with a `[rows]`
+one applies it per row, in either operand order (the bias shape
+`add of [x @ W, b]`); a number broadcasts over every element; operands of
+unequal, non-broadcastable length **truncate to the shorter** as they always
+have (the one place the two containers still differ: buffers truncate flat, so
+`add of [buf[5×4], buf[3]]` is `[3]` where the same shapes as lists are
+`[3, 4]` — neither is a meaningful answer, both are pinned in
+`tests/test_autograd.eigs`); a non-numeric partner (a string, a dict) answers
+`0` and raises under `EIGS_STRICT=1`. Before #1093 only equal-count `add` had a buffer path and
+every other buffer case answered a silent `0`. Same `num_guard` kernels
+either way, so the numbers are byte-identical.
+
 ### Functions
 
 | Name | Signature | Description |
@@ -490,23 +507,26 @@ heterogeneous or nested data.
 | `sqrt` | `sqrt of t` | Element-wise square root; negative input returns 0 |
 | `exp` | `exp of t` | Element-wise e^x; overflow saturates |
 | `log` | `log of t` | Element-wise natural log. Positive input, however small, is exact (`log of 1e-15` = -34.538…); a non-positive or NaN element sets the `invalid` math flag and stands in for ln(1e-10) = -23.025… (#865, #1041) — never -inf |
-| `softmax` | `softmax of t` | Row-wise softmax normalization (a scalar is the one-element case → `1.0`) |
-| `log_softmax` | `log_softmax of t` | Row-wise log(softmax) (a scalar → `log(1)` = `0.0`) |
-| `relu` | `relu of t` | Element-wise max(0, x) (accepts a scalar) |
-| `leaky_relu` | `leaky_relu of t` | Element-wise max(0.01x, x) (accepts a scalar) |
+| `softmax` | `softmax of t` | Row-wise softmax normalization (a scalar is the one-element case → `1.0`). A shaped buffer computes row-wise on its shape and returns a buffer of the same shape (a 1-D buffer is one row) — #973 |
+| `log_softmax` | `log_softmax of t` | Row-wise log(softmax) (a scalar → `log(1)` = `0.0`); buffers as for `softmax`. The `[tensor, dim]` form is recognised only as exactly `[list, number]` — it used to fire on every 2-D list and answer for row 0 alone (#973) |
+| `relu` | `relu of t` | Element-wise max(0, x) (accepts a scalar; buffers keep their shape) |
+| `leaky_relu` | `leaky_relu of t` | Element-wise max(0.01x, x) (accepts a scalar; buffers keep their shape — #973) |
 
 ### Linear Algebra
 
 | Name | Signature | Description |
 |------|-----------|-------------|
 | `matmul` | `matmul of [a, b]` | Matrix multiplication. Two shaped buffers multiply on the flat data and give a buffer; a 1-D left operand gives a 1-D result. Mixed list/buffer operands give a list |
-| `gather` | `gather of [matrix, indices, dim]` | Gather one element per row by index. `matrix` may be a shaped buffer and `indices` a list or a buffer; a shaped-buffer `matrix` gives a buffer. `gather of [vec, i]` on a 1-D tensor returns element `i` |
+| `matmul_at` | `matmul_at of [a, b]` | `aᵀ·b` without materialising the transpose: `a` is `(m × k)`, `b` is `(m × n)`, result `(k × n)` — the weight gradient `dW = Xᵀ·dY` of a linear layer. Buffers and nested lists; byte-identical to `matmul` of the explicitly transposed operand (same tiled kernel order). Two 1-D operands give their `(k × n)` outer product. Shape/type/size errors raise like `matmul` (#973) |
+| `matmul_bt` | `matmul_bt of [a, b]` | `a·bᵀ`: `a` is `(m × k)`, `b` is `(n × k)`, result `(m × n)` — the input gradient `dX = dY·Wᵀ`. A 1-D left operand is a row vector and yields a 1-D result, as for `matmul` (#973) |
+| `gather` | `gather of [matrix, indices, dim]` | Gather one element per row: `out[i] = matrix[i][indices[i]]`. `matrix` may be a shaped buffer and `indices` a list or a buffer; a shaped-buffer `matrix` gives a buffer. `gather of [vec, i]` on a 1-D tensor returns element `i`. An **out-of-range index raises `index_range`** — in every form, list or buffer (#973/#1093, settled at integration: there is no element there, and `scatter_add` raises on the same index). A row that is not a row (a 1-D tensor in the per-row form) still answers `0.0` for that row |
+| `scatter_add` | `scatter_add of [dst, indices, values]` | The gradient of `gather`, accumulated **in place** into the buffer `dst` (returned). A shaped `[rows × cols]` dst does `dst[i][indices[i]] += values[i]` per row; a 1-D dst does the flat `dst[indices[j]] += values[j]`. `values` is a buffer, a list of numbers, or one number broadcast to every index; repeats accumulate. Lengths must line up exactly — a non-scalar `values` shorter or longer than `indices`, or a per-row `dst` whose row count differs from the index count, raises `value` rather than truncating (a dropped gradient entry is a silent wrong number). Every index is validated **before** anything is written, so a raise (`index_range`, `value`, or `type_mismatch` for a non-buffer dst / non-numeric index or value) leaves `dst` untouched (#973) |
 
 ### Reductions
 
 | Name | Signature | Description |
 |------|-----------|-------------|
-| `mean` | `mean of t` | Average of all elements (list, nested list or buffer) |
+| `mean` | `mean of t` | Average of all elements (list, nested list or buffer; an empty buffer or list is `0.0`) |
 | `sum` | `sum of t` | Sum of all elements (list, nested list or buffer) |
 
 ### Construction
@@ -530,7 +550,7 @@ heterogeneous or nested data.
 
 | Name | Signature | Description |
 |------|-----------|-------------|
-| `numerical_grad` | `numerical_grad of [loss_fn, params, eps]` | Finite-difference gradient |
+| `numerical_grad` | `numerical_grad of [loss_fn, params, eps]` | Central finite-difference gradient. `params` is a 1-D/2-D list **or a shaped buffer** (#973: each element is perturbed in place and restored; the gradient comes back with the parameter's shape). O(params) forward passes — the gradient-check oracle for `lib/autograd.eigs`, not a training path |
 | `numerical_grad_rows` | `numerical_grad_rows of [loss_fn, params, eps, rows]` | Gradient for specific rows |
 | `numerical_grad_cols` | `numerical_grad_cols of [loss_fn, params, eps, cols]` | Gradient for specific columns |
 | `sgd_update` | `sgd_update of [params, grad, lr]` | In-place SGD: params -= lr * grad |
diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md
index 3a59e3ef..d8505c28 100644
--- a/docs/COMPARISON.md
+++ b/docs/COMPARISON.md
@@ -204,6 +204,12 @@ list
 flat-backed matrix. `matmul`, `softmax`, `sum`, `mean`, `norm`, `gather` and
 the rest accept either, and hand back a buffer when every operand was one.
 
+One place EigenScript is louder than NumPy: an out-of-range index in `gather`
+**raises** rather than answering a stand-in, on both containers — NumPy's
+`np.take` raises too, while a fancy-indexed read with an out-of-range entry is
+an `IndexError` there as well, so this matches. It is `gather`'s own history
+that changed: the list form used to answer `0.0` (#973/#1093).
+
 ## Dictionaries / objects
 
 JavaScript:
diff --git a/docs/SPEC.md b/docs/SPEC.md
index dcb7546c..766599cb 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -1978,9 +1978,46 @@ when unshaped. Indexing stays flat (`buf[r*cols + c]`).
 
 The tensor builtins operate directly on the flat data — no per-call conversion.
 `matmul of [a, b]` multiplies two shaped buffers (a 1-D buffer is a row vector,
-so `matmul of [vec, mat]` returns a 1-D result); `add` and `relu` are
-elementwise. The result is identical to the nested-list tensor form, so storing
-weights as shaped buffers is purely a performance choice.
+so `matmul of [vec, mat]` returns a 1-D result); `matmul_at` / `matmul_bt`
+multiply with the first / second operand transposed (`aᵀ·b`, `a·bᵀ`) without
+materialising the transpose; `add`, `subtract`, `multiply`, `divide` are
+elementwise, with a `[cols]` buffer broadcast over the rows of a
+`[rows × cols]` buffer and a number broadcast over every element; `relu`,
+`leaky_relu`, `softmax`, `log_softmax`, `sum`, `mean`, `norm`, `gather`
+compute on the shape, and `scatter_add` is `gather`'s in-place dual. The
+result is identical to the nested-list tensor form, so storing weights as
+shaped buffers is purely a performance choice — and it is the substrate the
+reverse-mode autograd tape in `lib/autograd.eigs` runs on.
+
+### `gather` and an out-of-range index
+
+`gather of [matrix, indices]` selects `matrix[i][indices[i]]` for each row.
+An index outside the row **raises** `index_range` — in every form, on a list
+tensor and on a shaped buffer alike. There is no element at that index, so an
+answer of `0.0` would be a stand-in the caller cannot tell from a real `0`
+(a Q-value, a log-probability); `scatter_add`, which is `gather`'s gradient and
+takes the same index, raises on it too.
+
+```eigenscript
+q is [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
+print of (gather of [q, [2, 0]])
+try:
+    print of (gather of [q, [2, 3]])
+catch e:
+    print of e["kind"]
+    print of e["message"]
+```
+```output
+[3, 4]
+index_range
+gather: column index 3 out of range for row 1 (cols 3)
+```
+
+Changed in this release (#973/#1093): the list form used to answer `0.0` for
+an out-of-range index and the buffer form was added folding the same way. A
+tensor that is not a matrix in the per-row form still answers `0.0` for that
+row — that is the shape reading, not the index one — and a wrong-typed
+argument still answers `0.0` unless `EIGS_STRICT=1` is set.
 
 Every tensor builtin that accepts a flat numeric list accepts a buffer in the
 same position, and returns a buffer when **every** tensor operand was a buffer:
diff --git a/docs/STDLIB.md b/docs/STDLIB.md
index 7dde43b4..44982492 100644
--- a/docs/STDLIB.md
+++ b/docs/STDLIB.md
@@ -60,6 +60,7 @@ mode is re-inventing what already ships (see "Before you hand-roll" below).
 | runtime invariant descent/preservation | `invariant.make_invariant`, `run_descent` | `lib/invariant.eigs` |
 | write tests with pass/fail tally | `test.assert_eq`, `test_summary`; `harness.start`/`check`/`finish` | `lib/test.eigs`, `lib/harness.eigs` |
 | neural-net helpers (init, loss, accuracy) | `tensor.xavier_init`, `linear`, `mse_loss`, `cross_entropy_loss` | `lib/tensor.eigs` |
+| gradients / backprop (reverse-mode autograd on a tape) | `autograd.ag_tape`, `ag_leaf`, `ag_matmul`, `ag_softmax_ce`, `ag_backward`, `ag_grad` | `lib/autograd.eigs` |
 | fixed-size integer vectors (buffer-backed) | `int_vector.int_vector_new`, `int_vector_from_list` | `lib/int_vector.eigs` |
 | a GUI (windows, widgets, charts) | `ui.panel`, `ui.button`, `ui.app_loop` + `ui_w_*` families | `lib/ui*.eigs` |
 | synthesize / play audio | `audio.play_note`, `note_freq`, `play_chord` | `lib/audio.eigs` |
@@ -299,6 +300,116 @@ Requires: `env_get`, `random_hex`, `http_request_headers` builtins.
 | `l2_norm` | `l2_norm of tensor` | Euclidean norm |
 | `scale` | `scale of [tensor, scalar]` | Scalar multiplication |
 
+### lib/autograd.eigs — Reverse-Mode Autograd (tape)
+
+Reverse-mode automatic differentiation over the f64 tensor builtins on
+shaped buffers (#973). A **tape** (Wengert list) records every op as a
+node; `ag_backward` seeds the loss with 1 and sweeps the tape in reverse
+applying each op's vector-Jacobian product, so a training step is one
+forward plus one backward — not `numerical_grad`'s one forward per
+parameter. It replaces the two hand-rolled backprops it was promoted from
+(Tidepool's DQN in `train.eigs`, iLambdaAi's transformer rules in
+`model_train.c`); `numerical_grad` stays as the gradient-check **oracle**
+(`tests/test_autograd.eigs` pins every rule below against it to 1e-4
+relative). Leaf values are the caller's own buffers — `ag_sgd_step` updates
+them in place. Build a fresh tape per step. Names carry the `ag_` prefix so
+`load_file` never shadows the builtins they wrap.
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `ag_tape` | `ag_tape of []` | New empty tape |
+| `ag_leaf` | `ag_leaf of [t, buf]` | Parameter node — gradient tracked |
+| `ag_const` | `ag_const of [t, buf]` | Data node — no gradient (inputs, targets) |
+| `ag_value` / `ag_grad` | `ag_value of node`, `ag_grad of node` | The node's value; its gradient (`null` until `ag_backward` reaches it) |
+| `ag_matmul` | `ag_matmul of [t, a, b]` | `matmul`; vjp `dA = dY·Bᵀ` (`matmul_bt`), `dB = Aᵀ·dY` (`matmul_at`) |
+| `ag_add` / `ag_sub` | `ag_add of [t, a, b]` | Same shape, or a broadcast operand (see below); a broadcast operand's gradient sums over the broadcast axis |
+| `ag_mul` | `ag_mul of [t, a, b]` | Elementwise product, same broadcast rule as `ag_add` |
+| `ag_scale` | `ag_scale of [t, a, k]` | Multiply by a number; a tensor `k` throws (use `ag_mul` with a node) |
+| `ag_relu` / `ag_leaky_relu` | `ag_relu of [t, a]` | Mask by pre-activation sign (0.01 on the negative side for leaky) |
+| `ag_softmax` / `ag_log_softmax` | `ag_softmax of [t, a]` | Row-wise; vjp `p·(dY − Σ dY·p)` / `dY − p·Σ dY` |
+| `ag_gather` | `ag_gather of [t, a, idx]` | `out[i] = a[i][idx[i]]` (1-D); vjp `scatter_add` |
+| `ag_norm` / `ag_sum` / `ag_mean` | `ag_norm of [t, a]` | Reductions to a scalar node (value is a num) |
+| `ag_softmax_ce` | `ag_softmax_ce of [t, logits, targets]` | Mean cross-entropy from logits and class indices; vjp `(p − onehot) / rows` |
+| `ag_backward` | `ag_backward of [t, node]` | Seed `node` with 1 (a ones-buffer for a tensor node) and sweep the tape |
+| `ag_sgd_step` | `ag_sgd_step of [node, lr]` | `value -= lr · grad`, in place on the caller's buffer; throws if the gradient's element count is not the parameter's |
+| `ag_sgd_step_clipped` | `ag_sgd_step_clipped of [node, lr, clip]` | As above with each gradient element clipped to ±clip (the DQN rule) |
+
+**Broadcasting.** `ag_add`, `ag_sub` and `ag_mul` inherit the elementwise
+builtins' broadcast rules: `[rows × cols]` against `[cols]` with either
+operand in either position, and a tensor against a scalar node (one whose
+value came from `ag_sum` / `ag_mean` / `ag_norm` / `ag_softmax_ce`). A
+broadcast operand contributed to every row of the result, so its gradient is
+the **sum of the result's gradient over the broadcast axis** — every rule
+does that reduction, so `ag_grad` always has its parameter's shape and
+`ag_sgd_step` always steps the parameter it was handed. A shape combination
+that is not one of the builtins' broadcast forms refuses: the forward pass
+raises from the builtin, and both step functions throw rather than stepping a
+parameter with a differently-shaped gradient.
+
+```eigenscript
+import autograd
+x is buffer of [2, 3]
+for i in range of 6:
+    x[i] is i + 1
+s is buffer of 3
+s[0] is 2
+s[1] is 3
+s[2] is 4
+t is autograd.ag_tape of []
+sn is autograd.ag_leaf of [t, s]
+y is autograd.ag_mul of [t, (autograd.ag_const of [t, x]), sn]
+autograd.ag_backward of [t, (autograd.ag_sum of [t, y])]
+g is autograd.ag_grad of sn
+print of (len of g)
+print of g[0]
+print of g[1]
+print of g[2]
+```
+```output
+3
+5
+7
+9
+```
+
+`x` is `[[1, 2, 3], [4, 5, 6]]` and `s` scales each column, so the gradient
+of `sum(x * s)` with respect to `s` is the column sum of `x` — `[5, 7, 9]`,
+three numbers for a three-element parameter, not the six of the unreduced
+product.
+
+```eigenscript
+import autograd
+x is buffer of [2, 2]
+x[0] is 1
+x[1] is 2
+x[2] is 3
+x[3] is 4
+w is buffer of [2, 1]
+w[0] is 1
+w[1] is 0.5
+t is autograd.ag_tape of []
+wn is autograd.ag_leaf of [t, w]
+y is autograd.ag_matmul of [t, (autograd.ag_const of [t, x]), wn]
+loss is autograd.ag_sum of [t, (autograd.ag_relu of [t, y])]
+autograd.ag_backward of [t, loss]
+g is autograd.ag_grad of wn
+print of (autograd.ag_value of loss)
+print of g[0]
+print of g[1]
+autograd.ag_sgd_step of [wn, 0.1]
+print of w[0]
+```
+```output
+7
+4
+6
+0.6
+```
+
+The gradient of `sum(relu(x·w))` with respect to `w` is the column sum of
+`x` (both rows are active): `[4, 6]`; the step then moves `w[0]` from 1 to
+`1 − 0.1·4 = 0.6` in the caller's buffer.
+
 ### lib/bcd.eigs — Packed BCD Codec
 
 `from_bcd of 0x26` → 26, `to_bcd of 59` → 0x59 — any width, each hex
diff --git a/docs/llms.txt b/docs/llms.txt
index c40ea25e..b1258508 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -193,8 +193,10 @@ The runtime has ~255 builtins and `lib/` covers a lot. `ord`/`chr`/`str_lower`/
 (there is no bare `lower` — it's `str_lower`; `sort_by of [items, key_fn]` is
 the record-shaped sort and needs no import). `lib/` has `string.pad_left`,
 `format.fmt_*`, `checksum.crc32`, civil-date math in `datetime`, and
-`list.filter`/`list.reduce`. **`lib/` functions are NOT ambient** — reach them
-one of two ways:
+`list.filter`/`list.reduce`, and reverse-mode autograd on shaped buffers in
+`autograd` (`ag_tape`/`ag_leaf`/`ag_matmul`…/`ag_backward`/`ag_grad` — never
+hand-roll backprop or train with `numerical_grad`). **`lib/` functions are NOT
+ambient** — reach them one of two ways:
 
 ```eigenscript
 import list                              # namespaced: list.filter of [xs, fn]
diff --git a/lib/autograd.eigs b/lib/autograd.eigs
new file mode 100644
index 00000000..c9e57645
--- /dev/null
+++ b/lib/autograd.eigs
@@ -0,0 +1,468 @@
+# ============================================================
+# Autograd Library — reverse-mode automatic differentiation on a tape
+# ============================================================
+#
+# A Wengert list (tape) over the f64 tensor builtins on shaped buffers.
+# Every op records a node {value, parents, op, saved}; `ag_backward` seeds
+# the loss node with 1 and sweeps the tape in reverse, applying each op's
+# vector-Jacobian product (vjp) rule and accumulating into `node.grad`.
+# One forward + one backward per step — no finite differences.
+# `numerical_grad` remains the gradient-check ORACLE (tests/test_autograd.eigs
+# pins every rule here against it); it is not a training path.
+#
+# How to use:
+#   import autograd
+#   t is autograd.ag_tape of []
+#   w is autograd.ag_leaf of [t, w_buf]         # parameter: gradient tracked
+#   b is autograd.ag_leaf of [t, b_buf]
+#   x is autograd.ag_const of [t, x_buf]        # data: no gradient
+#   h is autograd.ag_relu of [t, (autograd.ag_add of [t, (autograd.ag_matmul of [t, x, w]), b])]
+#   loss is autograd.ag_mean of [t, h]          # scalar node (value is a num)
+#   autograd.ag_backward of [t, loss]
+#   gw is autograd.ag_grad of w                 # buffer shaped like w_buf
+#   autograd.ag_sgd_step of [w, 0.01]           # w_buf -= lr * gw, in place
+#
+# Node handles are dicts; the tape holds them in creation order. Leaf values
+# are the caller's own buffers (shared, not copied), so `ag_sgd_step` updates
+# the caller's parameters in place. Build a fresh tape per training step.
+#
+# BROADCASTING. The elementwise ops (ag_add / ag_sub / ag_mul) inherit the
+# builtins' broadcast rules: [rows x cols] against [cols] (either operand),
+# and a tensor against a scalar node. A broadcast operand contributed to
+# every row of the result, so its gradient is the SUM of the result's
+# gradient over the broadcast axis — `_ag_reduce_to` does that reduction for
+# every elementwise rule, so `ag_grad` always has its parameter's shape and
+# `ag_sgd_step` always steps the parameter it was handed. A shape combination
+# that is not one of the builtins' broadcast forms THROWS from the backward
+# pass rather than producing a differently-shaped gradient.
+#
+# Ops (each returns a node; shapes as for the underlying builtin):
+#   ag_matmul of [t, a, b]        a (m x k) . b (k x n)           vjp: dA = dY·Bᵀ, dB = Aᵀ·dY (matmul_bt / matmul_at)
+#   ag_add of [t, a, b]           same shape, or a broadcast operand          vjp: pass-through, reduced over the broadcast axis
+#   ag_sub of [t, a, b]           a - b (same broadcast rule as ag_add)
+#   ag_mul of [t, a, b]           elementwise, same broadcast rule  vjp: dA = reduce(dY*B), dB = reduce(dY*A)
+#   ag_scale of [t, a, k]         a * k for a NUMBER k (a tensor k throws — use ag_mul)
+#   ag_relu of [t, a]                                              vjp: mask by pre-activation sign
+#   ag_leaky_relu of [t, a]                                        vjp: 1 where a > 0, 0.01 elsewhere
+#   ag_softmax of [t, a]          row-wise                         vjp: p * (dY - rowsum(dY * p))
+#   ag_log_softmax of [t, a]      row-wise                         vjp: dY - p * rowsum(dY)
+#   ag_gather of [t, a, idx]      out[i] = a[i][idx[i]] (1-D)      vjp: scatter_add
+#   ag_norm of [t, a]             L2 norm -> scalar node           vjp: dY * a / |a|
+#   ag_sum of [t, a]              -> scalar node
+#   ag_mean of [t, a]             -> scalar node
+#   ag_softmax_ce of [t, logits, targets]  mean cross-entropy from logits -> scalar node   vjp: (p - onehot) / rows
+#
+# Read-out:
+#   ag_value of node, ag_grad of node (null until backward reached it),
+#   ag_backward of [t, node], ag_sgd_step of [node, lr],
+#   ag_sgd_step_clipped of [node, lr, clip]  (elementwise clip of the gradient to ±clip first)
+#
+# Both step functions THROW if the gradient's element count does not match the
+# parameter's: stepping a parameter with a differently-shaped gradient is a
+# silent wrong number, and this module exists to remove that class.
+
+# ---- internal: shape helpers ----
+
+# _ag_dims of buf -> [rows, cols] (a 1-D buffer is one row)
+define _ag_dims(b) as:
+    local s is shape of b
+    if (len of s) == 2:
+        return [s[0], s[1]]
+    return [1, s[0]]
+
+# _ag_alloc_like of buf -> zero buffer with the same shape
+define _ag_alloc_like(b) as:
+    local s is shape of b
+    if (len of s) == 2:
+        return buffer of [s[0], s[1]]
+    return buffer of s[0]
+
+# _ag_clone of buf -> copy with the same shape
+define _ag_clone(b) as:
+    local out is _ag_alloc_like of b
+    local n is len of b
+    if n > 0:
+        buf_copy of [b, 0, out, 0, n]
+    return out
+
+# _ag_fill_like of [buf, v] -> buffer shaped like buf, every element v
+define _ag_fill_like(b, v) as:
+    local out is _ag_alloc_like of b
+    local n is len of out
+    if n > 0:
+        buf_fill of [out, 0, n, v]
+    return out
+
+# _ag_col_sum of [buf2d] -> 1-D buffer of column sums (the bias reduction)
+define _ag_col_sum(b) as:
+    local d is _ag_dims of b
+    local rows is d[0]
+    local cols is d[1]
+    local out is buffer of cols
+    for i in range of rows:
+        local ib is i * cols
+        for j in range of cols:
+            out[j] is out[j] + b[ib + j]
+    return out
+
+# _ag_reduce_to of [who, pv, g] -> `g` reduced to operand `pv`'s shape.
+#
+# The four elementwise builtins broadcast (buffer op number, and
+# [rows x cols] op [cols] either way), so an operand can be SMALLER than the
+# result. Its gradient is then the sum of `g` over the broadcast axis — the
+# operand contributed to every row, so every row's gradient flows back to it.
+# Cases, mirroring buffer_elementwise's shape rules exactly:
+#   pv a number                    -> sum of g          (scalar broadcast)
+#   same element count             -> g, reshaped to pv if the ranks differ
+#                                     (elementwise is flat, so the values are
+#                                      already right — only the shape moves)
+#   pv one row, cols matching      -> column sums        (the bias reduction)
+#   anything else                  -> THROW. A gradient whose shape does not
+#                                     match its parameter is a wrong number
+#                                     that `ag_sgd_step` would train on.
+define _ag_reduce_to(who, pv, g) as:
+    if (type of pv) == "num":
+        if (type of g) == "num":
+            return g
+        return sum of g
+    if (type of g) == "num":
+        return _ag_fill_like of [pv, g]
+    local np is len of pv
+    local ng is len of g
+    local dp is _ag_dims of pv
+    local dg is _ag_dims of g
+    if np == ng:
+        if dp[0] == dg[0] and dp[1] == dg[1] and (len of (shape of pv)) == (len of (shape of g)):
+            return g
+        local same is _ag_alloc_like of pv
+        if np > 0:
+            buf_copy of [g, 0, same, 0, np]
+        return same
+    if dp[0] == 1 and dp[1] == dg[1]:
+        local red is _ag_col_sum of g
+        local out2 is _ag_alloc_like of pv
+        buf_copy of [red, 0, out2, 0, dp[1]]
+        return out2
+    throw of (who + ": cannot reduce a " + (str of dg[0]) + "x" + (str of dg[1]) + " gradient to the operand's " + (str of dp[0]) + "x" + (str of dp[1]) + " shape (unsupported broadcast)")
+
+# _ag_reducible of [pv, g] -> 1 when `_ag_reduce_to` can carry a gradient of
+# `g`'s shape back to an operand of `pv`'s shape, 0 when it would throw. The
+# same four cases, asked BEFORE the node is pushed.
+define _ag_reducible(pv, g) as:
+    if (type of pv) == "num":
+        return 1
+    if (type of g) == "num":
+        return 1
+    if (len of pv) == (len of g):
+        return 1
+    local dp is _ag_dims of pv
+    local dg is _ag_dims of g
+    if dp[0] == 1:
+        if dp[1] == dg[1]:
+            return 1
+    return 0
+
+# _ag_check_bin of [who, av, bv, v]: the forward guard for the elementwise
+# rules. The four arithmetic BUILTINS share the list path's shape algebra, so
+# operands that do not broadcast TRUNCATE to the shorter one rather than
+# raising (#1093/#973, settled at integration: the builtin's answer must not
+# depend on whether its operands are buffers or lists). That truncation is a
+# differently-shaped value, and the tape must not build a node on it: its
+# gradient could not be reduced back to either operand and `ag_sgd_step` would
+# train on a wrong number. So the refusal that used to come from the C layer
+# lives here, one level up, where it is a statement about the TAPE.
+define _ag_check_bin(who, av, bv, v) as:
+    local oka is _ag_reducible of [av, v]
+    local okb is _ag_reducible of [bv, v]
+    if oka == 0 or okb == 0:
+        local sa is str of (shape of av)
+        local sb is str of (shape of bv)
+        local sv is str of (shape of v)
+        throw of (who + ": operands " + sa + " and " + sb + " do not broadcast (the builtin answered " + sv + ", whose gradient fits neither operand)")
+    return null
+
+# ---- internal: node bookkeeping ----
+
+define _ag_push(t, value, op, parents, saved, track) as:
+    local node is {"id": (len of t.nodes), "value": value, "grad": null, "op": op, "parents": parents, "saved": saved, "track": track}
+    append of [t.nodes, node]
+    return node
+
+define _ag_tracked(a, b) as:
+    if a.track or b.track:
+        return 1
+    return 0
+
+# Accumulate `delta` into node `id`'s gradient. Copies on first arrival so a
+# gradient passed through unchanged (ag_add's vjp) is never shared between two
+# parents and then mutated by one of them.
+define _ag_accum(t, id, delta) as:
+    local node is t.nodes[id]
+    if not node.track:
+        return null
+    if (type of node.grad) == "none":
+        if (type of delta) == "num":
+            node.grad is delta
+        else:
+            node.grad is _ag_clone of delta
+    else:
+        node.grad is add of [node.grad, delta]
+    return null
+
+# ---- public: tape + leaves ----
+
+# ag_tape of [] -> a new empty tape
+define ag_tape() as:
+    return {"nodes": []}
+
+# ag_leaf of [t, buf] -> node whose gradient is tracked (a parameter)
+define ag_leaf(t, value) as:
+    return _ag_push of [t, value, "leaf", [], null, 1]
+
+# ag_const of [t, buf] -> node with no gradient (data, targets, constants)
+define ag_const(t, value) as:
+    return _ag_push of [t, value, "const", [], null, 0]
+
+define ag_value(node) as:
+    return node.value
+
+define ag_grad(node) as:
+    return node.grad
+
+# ---- public: ops ----
+
+define ag_matmul(t, a, b) as:
+    local v is matmul of [a.value, b.value]
+    return _ag_push of [t, v, "matmul", [a.id, b.id], null, _ag_tracked of [a, b]]
+
+define ag_add(t, a, b) as:
+    local v is add of [a.value, b.value]
+    _ag_check_bin of ["ag_add", a.value, b.value, v]
+    return _ag_push of [t, v, "add", [a.id, b.id], null, _ag_tracked of [a, b]]
+
+define ag_sub(t, a, b) as:
+    local v is subtract of [a.value, b.value]
+    _ag_check_bin of ["ag_sub", a.value, b.value, v]
+    return _ag_push of [t, v, "sub", [a.id, b.id], null, _ag_tracked of [a, b]]
+
+define ag_mul(t, a, b) as:
+    local v is multiply of [a.value, b.value]
+    _ag_check_bin of ["ag_mul", a.value, b.value, v]
+    return _ag_push of [t, v, "mul", [a.id, b.id], null, _ag_tracked of [a, b]]
+
+# ag_scale of [t, a, k]: k is a NUMBER. A buffer k would broadcast in the
+# forward pass and could make the result a different shape from `a`, and the
+# vjp (dy * k) would then be the result's shape, not the parameter's — the
+# same wrong-shape class the elementwise rules reduce away. Use ag_mul with a
+# node for an elementwise or broadcast factor.
+define ag_scale(t, a, k) as:
+    if (type of k) != "num":
+        throw of ("ag_scale: k must be a number, got " + (type of k) + " — use ag_mul with a node for a tensor factor")
+    local v is multiply of [a.value, k]
+    return _ag_push of [t, v, "scale", [a.id], k, a.track]
+
+define ag_relu(t, a) as:
+    local v is relu of a.value
+    return _ag_push of [t, v, "relu", [a.id], null, a.track]
+
+define ag_leaky_relu(t, a) as:
+    local v is leaky_relu of a.value
+    return _ag_push of [t, v, "leaky_relu", [a.id], null, a.track]
+
+define ag_softmax(t, a) as:
+    local v is softmax of a.value
+    return _ag_push of [t, v, "softmax", [a.id], null, a.track]
+
+define ag_log_softmax(t, a) as:
+    local v is log_softmax of a.value
+    local p is softmax of a.value
+    return _ag_push of [t, v, "log_softmax", [a.id], p, a.track]
+
+# ag_gather of [t, a, idx]: a is [rows x cols], idx a list/buffer of one
+# column per row -> 1-D node of `rows` picks.
+define ag_gather(t, a, idx) as:
+    local v is gather of [a.value, idx]
+    return _ag_push of [t, v, "gather", [a.id], idx, a.track]
+
+define ag_norm(t, a) as:
+    local v is norm of a.value
+    return _ag_push of [t, v, "norm", [a.id], null, a.track]
+
+define ag_sum(t, a) as:
+    local v is sum of a.value
+    return _ag_push of [t, v, "sum", [a.id], null, a.track]
+
+define ag_mean(t, a) as:
+    local v is mean of a.value
+    return _ag_push of [t, v, "mean", [a.id], null, a.track]
+
+# ag_softmax_ce of [t, logits, targets]: logits [rows x cols], targets a
+# list/buffer of class indices (one per row). Value is the MEAN over rows of
+# -log softmax(logits)[i][targets[i]] (the same 1e-10 floor as log_softmax).
+define ag_softmax_ce(t, logits, targets) as:
+    local p is softmax of logits.value
+    local d is _ag_dims of logits.value
+    local rows is d[0]
+    local cols is d[1]
+    local total is 0.0
+    for i in range of rows:
+        local pt is p[i * cols + (floor of targets[i])]
+        if pt < 0.0000000001:
+            pt is 0.0000000001
+        total is total - (log of pt)
+    return _ag_push of [t, total / rows, "softmax_ce", [logits.id], [p, targets], logits.track]
+
+# ---- public: backward ----
+
+# One node's vjp: `dy` is its incoming gradient (a buffer, or a num for a
+# scalar node); each parent receives its contribution via _ag_accum.
+define _ag_vjp(t, node, dy) as:
+    local op is node.op
+    local ps is node.parents
+    if op == "matmul":
+        local av is t.nodes[ps[0]].value
+        local bv is t.nodes[ps[1]].value
+        _ag_accum of [t, ps[0], matmul_bt of [dy, bv]]
+        _ag_accum of [t, ps[1], matmul_at of [av, dy]]
+    elif op == "add" or op == "sub":
+        local pa is t.nodes[ps[0]].value
+        local pb is t.nodes[ps[1]].value
+        _ag_accum of [t, ps[0], _ag_reduce_to of ["ag_" + op, pa, dy]]
+        local db is _ag_reduce_to of ["ag_" + op, pb, dy]
+        if op == "sub":
+            db is multiply of [db, -1.0]
+        _ag_accum of [t, ps[1], db]
+    elif op == "mul":
+        local av is t.nodes[ps[0]].value
+        local bv is t.nodes[ps[1]].value
+        _ag_accum of [t, ps[0], _ag_reduce_to of ["ag_mul", av, (multiply of [dy, bv])]]
+        _ag_accum of [t, ps[1], _ag_reduce_to of ["ag_mul", bv, (multiply of [dy, av])]]
+    elif op == "scale":
+        _ag_accum of [t, ps[0], multiply of [dy, node.saved]]
+    elif op == "relu":
+        local x is t.nodes[ps[0]].value
+        local dx is _ag_alloc_like of x
+        for i in range of (len of x):
+            if x[i] > 0.0:
+                dx[i] is dy[i]
+        _ag_accum of [t, ps[0], dx]
+    elif op == "leaky_relu":
+        local x is t.nodes[ps[0]].value
+        local dx is _ag_alloc_like of x
+        for i in range of (len of x):
+            if x[i] > 0.0:
+                dx[i] is dy[i]
+            else:
+                dx[i] is dy[i] * 0.01
+        _ag_accum of [t, ps[0], dx]
+    elif op == "softmax":
+        local p is node.value
+        local d is _ag_dims of p
+        local rows is d[0]
+        local cols is d[1]
+        local dx is _ag_alloc_like of p
+        for i in range of rows:
+            local ib is i * cols
+            local s is 0.0
+            for j in range of cols:
+                s is s + dy[ib + j] * p[ib + j]
+            for j in range of cols:
+                dx[ib + j] is p[ib + j] * (dy[ib + j] - s)
+        _ag_accum of [t, ps[0], dx]
+    elif op == "log_softmax":
+        local p is node.saved
+        local d is _ag_dims of p
+        local rows is d[0]
+        local cols is d[1]
+        local dx is _ag_alloc_like of p
+        for i in range of rows:
+            local ib is i * cols
+            local s is 0.0
+            for j in range of cols:
+                s is s + dy[ib + j]
+            for j in range of cols:
+                dx[ib + j] is dy[ib + j] - p[ib + j] * s
+        _ag_accum of [t, ps[0], dx]
+    elif op == "gather":
+        local x is t.nodes[ps[0]].value
+        local dx is _ag_alloc_like of x
+        scatter_add of [dx, node.saved, dy]
+        _ag_accum of [t, ps[0], dx]
+    elif op == "norm":
+        local x is t.nodes[ps[0]].value
+        local y is node.value
+        if y > 0.0:
+            _ag_accum of [t, ps[0], multiply of [x, dy / y]]
+        else:
+            _ag_accum of [t, ps[0], _ag_alloc_like of x]
+    elif op == "sum":
+        local x is t.nodes[ps[0]].value
+        _ag_accum of [t, ps[0], _ag_fill_like of [x, dy]]
+    elif op == "mean":
+        local x is t.nodes[ps[0]].value
+        local n is len of x
+        if n > 0:
+            _ag_accum of [t, ps[0], _ag_fill_like of [x, dy / n]]
+    elif op == "softmax_ce":
+        local p is node.saved[0]
+        local targets is node.saved[1]
+        local d is _ag_dims of p
+        local rows is d[0]
+        local cols is d[1]
+        local dx is multiply of [p, dy / rows]
+        for i in range of rows:
+            local at is i * cols + (floor of targets[i])
+            dx[at] is dx[at] - dy / rows
+        _ag_accum of [t, ps[0], dx]
+    return null
+
+# ag_backward of [t, node]: seed `node` with 1 (a num for a scalar node, a
+# ones-buffer otherwise) and sweep the tape in reverse creation order.
+# Gradients land in each tracked node's `.grad`; read with ag_grad.
+define ag_backward(t, node) as:
+    if (type of node.value) == "num":
+        node.grad is 1.0
+    else:
+        node.grad is _ag_fill_like of [node.value, 1.0]
+    local i is node.id
+    loop while i >= 0:
+        local n is t.nodes[i]
+        if n.track and (type of n.grad) != "none" and (len of n.parents) > 0:
+            _ag_vjp of [t, n, n.grad]
+        i is i - 1
+    return null
+
+# ag_sgd_step of [node, lr]: node.value -= lr * node.grad, in place on the
+# caller's buffer. A leaf backward never reached (grad null) is left alone.
+define ag_sgd_step(node, lr) as:
+    if (type of node.grad) == "none":
+        return null
+    local v is node.value
+    local g is node.grad
+    if (type of v) != "buffer":
+        throw of ("ag_sgd_step: leaf value is a " + (type of v) + ", not a buffer — a scalar leaf cannot be updated in place")
+    if (len of g) != (len of v):
+        throw of ("ag_sgd_step: gradient has " + (str of (len of g)) + " elements but the parameter has " + (str of (len of v)) + " — the vjp did not reduce it to the parameter's shape")
+    for i in range of (len of v):
+        v[i] is v[i] - lr * g[i]
+    return null
+
+# ag_sgd_step_clipped of [node, lr, clip]: as ag_sgd_step, with each
+# gradient element clipped to [-clip, clip] first (the DQN's update rule).
+define ag_sgd_step_clipped(node, lr, clip) as:
+    if (type of node.grad) == "none":
+        return null
+    local v is node.value
+    local g is node.grad
+    if (type of v) != "buffer":
+        throw of ("ag_sgd_step_clipped: leaf value is a " + (type of v) + ", not a buffer — a scalar leaf cannot be updated in place")
+    if (len of g) != (len of v):
+        throw of ("ag_sgd_step_clipped: gradient has " + (str of (len of g)) + " elements but the parameter has " + (str of (len of v)) + " — the vjp did not reduce it to the parameter's shape")
+    for i in range of (len of v):
+        local gi is g[i]
+        if gi > clip:
+            gi is clip
+        elif gi < 0.0 - clip:
+            gi is 0.0 - clip
+        v[i] is v[i] - lr * gi
+    return null
diff --git a/src/builtins.c b/src/builtins.c
index b5173ca9..994ced93 100644
--- a/src/builtins.c
+++ b/src/builtins.c
@@ -3413,6 +3413,7 @@ static const char *SANDBOX_ALLOW[] = {
     "exp", "floor", "log", "max", "mean", "min", "multiply", "negative",
     "norm", "num", "pi", "pow", "round", "sign_extend", "sin", "sqrt",
     "subtract", "sum", "tan", "gather", "matmul", "reshape", "shape", "zeros",
+    "matmul_at", "matmul_bt", "scatter_add",
     "zeros_like", "fill", "leaky_relu", "relu", "softmax", "log_softmax",
     "sgd_update", "sgd_update_cols", "sgd_update_rows", "numerical_grad",
     "numerical_grad_cols", "numerical_grad_rows",
@@ -6956,6 +6957,9 @@ void register_builtins(Env *env) {
     /* ---- Tensor / math stdlib (always available) ---- */
     env_set_local_owned(env, "dot", make_builtin(builtin_dot));
     env_set_local_owned(env, "matmul", make_builtin(builtin_tensor_matmul));
+    env_set_local_owned(env, "matmul_at", make_builtin(builtin_tensor_matmul_at));
+    env_set_local_owned(env, "matmul_bt", make_builtin(builtin_tensor_matmul_bt));
+    env_set_local_owned(env, "scatter_add", make_builtin(builtin_tensor_scatter_add));
     env_set_local_owned(env, "add", make_builtin(builtin_tensor_add));
     env_set_local_owned(env, "subtract", make_builtin(builtin_tensor_subtract));
     env_set_local_owned(env, "multiply", make_builtin(builtin_tensor_multiply));
diff --git a/src/builtins_internal.h b/src/builtins_internal.h
index e323b56f..71d2e661 100644
--- a/src/builtins_internal.h
+++ b/src/builtins_internal.h
@@ -22,6 +22,9 @@ Value* builtin_tensor_negative(Value *arg);
 Value* builtin_tensor_matmul(Value *arg);
 Value* builtin_tensor_softmax(Value *arg);
 Value* builtin_tensor_log_softmax(Value *arg);
+Value* builtin_tensor_matmul_at(Value *arg);
+Value* builtin_tensor_matmul_bt(Value *arg);
+Value* builtin_tensor_scatter_add(Value *arg);
 Value* builtin_tensor_relu(Value *arg);
 Value* builtin_tensor_leaky_relu(Value *arg);
 Value* builtin_tensor_mean(Value *arg);
diff --git a/src/builtins_tensor.c b/src/builtins_tensor.c
index 230448b8..f691b07b 100644
--- a/src/builtins_tensor.c
+++ b/src/builtins_tensor.c
@@ -75,6 +75,66 @@ void ne_matmul_buf(
     }
 }
 
+/* Transposed-operand kernels for the autograd vjp rules (#973): the two
+ * matmul gradients are dA = dY.B^T and dB = A^T.dY, and materialising the
+ * transpose costs a copy per backward step. Same i-k-j tiling as
+ * ne_matmul_buf, so out[i][j] accumulates over kk in the same ascending
+ * order — byte-identical to `matmul` of the explicitly transposed operand
+ * (pinned by tests/test_autograd.eigs). model_train.c carries the f32
+ * twins of these for the transformer; these are the f64 buffer path. */
+
+/* out(k x n) = a^T . b  where a is (m x k), b is (m x n) */
+void ne_matmul_at_buf(
+    double *a, int64_t m, int64_t k,
+    double *b, int64_t n,
+    double *out
+) {
+    memset(out, 0, k * n * sizeof(double));
+    for (int64_t i0 = 0; i0 < k; i0 += NE_TENSOR_TILE_SIZE) {
+        for (int64_t j0 = 0; j0 < n; j0 += NE_TENSOR_TILE_SIZE) {
+            for (int64_t k0 = 0; k0 < m; k0 += NE_TENSOR_TILE_SIZE) {
+                int64_t i_end = i0 + NE_TENSOR_TILE_SIZE < k ? i0 + NE_TENSOR_TILE_SIZE : k;
+                int64_t j_end = j0 + NE_TENSOR_TILE_SIZE < n ? j0 + NE_TENSOR_TILE_SIZE : n;
+                int64_t k_end = k0 + NE_TENSOR_TILE_SIZE < m ? k0 + NE_TENSOR_TILE_SIZE : m;
+                for (int64_t i = i0; i < i_end; i++) {
+                    for (int64_t kk = k0; kk < k_end; kk++) {
+                        double a_ki = a[kk * k + i];
+                        for (int64_t j = j0; j < j_end; j++) {
+                            out[i * n + j] += a_ki * b[kk * n + j];
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+/* out(m x n) = a . b^T  where a is (m x k), b is (n x k) */
+void ne_matmul_bt_buf(
+    double *a, int64_t m, int64_t k,
+    double *b, int64_t n,
+    double *out
+) {
+    memset(out, 0, m * n * sizeof(double));
+    for (int64_t i0 = 0; i0 < m; i0 += NE_TENSOR_TILE_SIZE) {
+        for (int64_t j0 = 0; j0 < n; j0 += NE_TENSOR_TILE_SIZE) {
+            for (int64_t k0 = 0; k0 < k; k0 += NE_TENSOR_TILE_SIZE) {
+                int64_t i_end = i0 + NE_TENSOR_TILE_SIZE < m ? i0 + NE_TENSOR_TILE_SIZE : m;
+                int64_t j_end = j0 + NE_TENSOR_TILE_SIZE < n ? j0 + NE_TENSOR_TILE_SIZE : n;
+                int64_t k_end = k0 + NE_TENSOR_TILE_SIZE < k ? k0 + NE_TENSOR_TILE_SIZE : k;
+                for (int64_t i = i0; i < i_end; i++) {
+                    for (int64_t kk = k0; kk < k_end; kk++) {
+                        double a_ik = a[i * k + kk];
+                        for (int64_t j = j0; j < j_end; j++) {
+                            out[i * n + j] += a_ik * b[j * k + kk];
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
 /* ---- flat-buffer tensors -------------------------------------------------
  * A VAL_BUFFER carries an optional 2-D shape (rows/cols; rows==0 => 1-D, length
  * = count). The tensor builtins gain a fast path that computes directly on the
@@ -450,7 +510,11 @@ static Value* tensor_elementwise(Value *a, Value *b, BinOpFn fn) {
 Value* builtin_tensor_add(Value *arg) {
     if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2) return make_null();
     /* #1093: the buffer fast path moved into tensor_elementwise, so all five
-     * elementwise builtins share one implementation. */
+     * elementwise builtins share one implementation. #973 arrived with a
+     * second one (`buffer_elementwise`, called ahead of this); reconciled at
+     * integration by keeping THIS one — a builtin must not have two buffer
+     * paths, and this is the one whose shape rules are the list path's,
+     * container for container. */
     return tensor_elementwise(arg->data.list.items[0], arg->data.list.items[1], op_add);
 }
 
@@ -611,10 +675,237 @@ Value* builtin_tensor_matmul(Value *arg) {
     return result;
 }
 
+/* ---- transposed-operand matmuls (#973) -------------------------------------
+ * Shared argument discipline with `matmul` (#512): raise on non-matrix
+ * operands (type), incompatible shapes (value), oversized results (limit).
+ * Buffers compute on the flat data; nested lists go through the same flat
+ * kernels, so both forms agree byte-for-byte with `matmul` of the
+ * explicitly transposed operand. */
+
+/* matmul_at of [a, b] → aᵀ·b: a is (m x k), b is (m x n), result (k x n).
+ * The weight gradient dW = Xᵀ·dY of a linear layer, without materialising Xᵀ. */
+Value* builtin_tensor_matmul_at(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2) {
+        rt_error(EK_TYPE, 0, "matmul_at requires [A, B]");
+        return make_null();
+    }
+    Value *a = arg->data.list.items[0];
+    Value *b = arg->data.list.items[1];
+    if (a->type == VAL_BUFFER && b->type == VAL_BUFFER) {
+        int ar, ac, br, bc;
+        buf_dims(a, &ar, &ac); buf_dims(b, &br, &bc);
+        if (ar != br) {
+            rt_error(EK_VALUE, 0, "matmul_at: incompatible shapes "
+                     "(%dx%d transposed · %dx%d)", ar, ac, br, bc);
+            return make_null();
+        }
+        if ((int64_t)ac * bc > 10000000) {
+            rt_error(EK_LIMIT, 0, "matmul_at: result too large (%dx%d)", ac, bc);
+            return make_null();
+        }
+        /* The result is aᵀ·b = (k x n): always 2-D, since k is the column
+         * count of `a` (its length when 1-D) — the shape of a weight matrix. */
+        Value *res = make_shaped_buffer(ac, bc);
+        if (!res) return make_null();
+        ne_matmul_at_buf(a->data.buffer.data, ar, ac, b->data.buffer.data, bc, res->data.buffer.data);
+        return res;
+    }
+    int ar, ac, br, bc;
+    double *af = tensor_to_flat(a, &ar, &ac);
+    double *bf = tensor_to_flat(b, &br, &bc);
+    if (!af || !bf) {
+        free(af); free(bf);
+        rt_error(EK_TYPE, 0, "matmul_at: expected matrices (got %s, %s)",
+                 val_type_name(a->type), val_type_name(b->type));
+        return make_null();
+    }
+    if (ar != br) {
+        free(af); free(bf);
+        rt_error(EK_VALUE, 0, "matmul_at: incompatible shapes "
+                 "(%dx%d transposed · %dx%d)", ar, ac, br, bc);
+        return make_null();
+    }
+    if ((int64_t)ac * bc > 10000000) {
+        free(af); free(bf);
+        rt_error(EK_LIMIT, 0, "matmul_at: result too large (%dx%d)", ac, bc);
+        return make_null();
+    }
+    double *out = xcalloc((size_t)ac * bc, sizeof(double));
+    ne_matmul_at_buf(af, ar, ac, bf, bc, out);
+    Value *result = flat_to_tensor_2d(out, ac, bc);
+    free(af); free(bf); free(out);
+    return result;
+}
+
+/* matmul_bt of [a, b] → a·bᵀ: a is (m x k), b is (n x k), result (m x n).
+ * The input gradient dX = dY·Wᵀ of a linear layer, without materialising Wᵀ.
+ * Like `matmul`, a 1-D left operand is a row vector and yields a 1-D result. */
+Value* builtin_tensor_matmul_bt(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2) {
+        rt_error(EK_TYPE, 0, "matmul_bt requires [A, B]");
+        return make_null();
+    }
+    Value *a = arg->data.list.items[0];
+    Value *b = arg->data.list.items[1];
+    if (a->type == VAL_BUFFER && b->type == VAL_BUFFER) {
+        int ar, ac, br, bc;
+        buf_dims(a, &ar, &ac); buf_dims(b, &br, &bc);
+        if (ac != bc) {
+            rt_error(EK_VALUE, 0, "matmul_bt: incompatible shapes "
+                     "(%dx%d · %dx%d transposed)", ar, ac, br, bc);
+            return make_null();
+        }
+        if ((int64_t)ar * br > 10000000) {
+            rt_error(EK_LIMIT, 0, "matmul_bt: result too large (%dx%d)", ar, br);
+            return make_null();
+        }
+        Value *res = (a->data.buffer.rows == 0) ? make_shaped_buffer(0, br)
+                                                : make_shaped_buffer(ar, br);
+        if (!res) return make_null();
+        ne_matmul_bt_buf(a->data.buffer.data, ar, ac, b->data.buffer.data, br, res->data.buffer.data);
+        return res;
+    }
+    int ar, ac, br, bc;
+    double *af = tensor_to_flat(a, &ar, &ac);
+    double *bf = tensor_to_flat(b, &br, &bc);
+    if (!af || !bf) {
+        free(af); free(bf);
+        rt_error(EK_TYPE, 0, "matmul_bt: expected matrices (got %s, %s)",
+                 val_type_name(a->type), val_type_name(b->type));
+        return make_null();
+    }
+    if (ac != bc) {
+        free(af); free(bf);
+        rt_error(EK_VALUE, 0, "matmul_bt: incompatible shapes "
+                 "(%dx%d · %dx%d transposed)", ar, ac, br, bc);
+        return make_null();
+    }
+    if ((int64_t)ar * br > 10000000) {
+        free(af); free(bf);
+        rt_error(EK_LIMIT, 0, "matmul_bt: result too large (%dx%d)", ar, br);
+        return make_null();
+    }
+    double *out = xcalloc((size_t)ar * br, sizeof(double));
+    ne_matmul_bt_buf(af, ar, ac, bf, br, out);
+    Value *result = (ar == 1) ? flat_to_tensor_1d(out, br) : flat_to_tensor_2d(out, ar, br);
+    free(af); free(bf); free(out);
+    return result;
+}
+
+/* scatter_add of [dst, indices, values] → dst, accumulated IN PLACE (#973).
+ * The gradient of `gather`. Two forms, keyed on dst's shape:
+ *   dst [rows x cols] (shaped): dst[i][indices[i]] += values[i]  (per row)
+ *   dst 1-D (unshaped):        dst[indices[j]]    += values[j]  (flat)
+ * `indices` is a list or buffer of integers; `values` a buffer, a list of
+ * numbers, or one number broadcast to every index. Repeated indices
+ * accumulate. An out-of-range index RAISES (index_range) — a dropped
+ * gradient is a silent wrong number — and so does a length mismatch
+ * (value): indices/values counts must be equal, and the per-row form needs
+ * one index per row. Wrong types raise (type). */
+Value* builtin_tensor_scatter_add(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) {
+        rt_error(EK_TYPE, 0, "scatter_add requires [dst, indices, values]");
+        return make_null();
+    }
+    Value *dst = arg->data.list.items[0];
+    Value *indices = arg->data.list.items[1];
+    Value *values = arg->data.list.items[2];
+    if (dst->type != VAL_BUFFER) {
+        rt_error(EK_TYPE, 0, "scatter_add: dst must be a buffer, got %s", val_type_name(dst->type));
+        return make_null();
+    }
+    if (indices->type != VAL_LIST && indices->type != VAL_BUFFER) {
+        rt_error(EK_TYPE, 0, "scatter_add: indices must be a list or buffer, got %s", val_type_name(indices->type));
+        return make_null();
+    }
+    if (values->type != VAL_LIST && values->type != VAL_BUFFER && values->type != VAL_NUM) {
+        rt_error(EK_TYPE, 0, "scatter_add: values must be a buffer, a list of numbers, or a number, got %s", val_type_name(values->type));
+        return make_null();
+    }
+    int ni = (indices->type == VAL_LIST) ? indices->data.list.count : indices->data.buffer.count;
+    int nv = (values->type == VAL_LIST) ? values->data.list.count
+           : (values->type == VAL_BUFFER) ? values->data.buffer.count : ni;
+    /* Lengths must line up exactly. Truncating to the shorter side would drop
+     * gradient entries with no diagnostic — the same silent-wrong-number that
+     * makes an out-of-range index raise below (#973). A scalar `values` is the
+     * one broadcast form, and it is explicit. */
+    if (nv != ni) {
+        rt_error(EK_VALUE, 0, "scatter_add: %d indices but %d values", ni, nv);
+        return make_null();
+    }
+    int n = ni;
+    int per_row = dst->data.buffer.rows > 0;
+    int rows = per_row ? dst->data.buffer.rows : 0;
+    int cols = per_row ? dst->data.buffer.cols : 0;
+    if (per_row && rows != n) {
+        rt_error(EK_VALUE, 0, "scatter_add: dst has %d rows but %d indices", rows, n);
+        return make_null();
+    }
+    double *d = dst->data.buffer.data;
+    /* Two passes: validate every index and value first, then accumulate —
+     * so a raise leaves dst untouched instead of half-updated. */
+    for (int pass = 0; pass < 2; pass++) {
+        for (int i = 0; i < n; i++) {
+            double di, v;
+            if (indices->type == VAL_LIST) {
+                Value *iv = indices->data.list.items[i];
+                if (iv->type != VAL_NUM) {
+                    rt_error(EK_TYPE, 0, "scatter_add: index %d is %s (expected a number)", i, val_type_name(iv->type));
+                    return make_null();
+                }
+                di = iv->data.num;
+            } else {
+                di = indices->data.buffer.data[i];
+            }
+            if (values->type == VAL_LIST) {
+                Value *vv = values->data.list.items[i];
+                if (vv->type != VAL_NUM) {
+                    rt_error(EK_TYPE, 0, "scatter_add: value %d is %s (expected a number)", i, val_type_name(vv->type));
+                    return make_null();
+                }
+                v = vv->data.num;
+            } else if (values->type == VAL_BUFFER) {
+                v = values->data.buffer.data[i];
+            } else {
+                v = values->data.num;
+            }
+            int idx = (int)di;
+            if (per_row) {
+                if (idx < 0 || idx >= cols) {
+                    rt_error(EK_INDEX, 0, "scatter_add: column index %d out of range for row %d (cols %d)", idx, i, cols);
+                    return make_null();
+                }
+                if (pass) {
+                    int64_t at = (int64_t)i * cols + idx;
+                    d[at] = num_guard(d[at] + v);
+                }
+            } else {
+                if (idx < 0 || idx >= dst->data.buffer.count) {
+                    rt_error(EK_INDEX, 0, "scatter_add: index %d out of range (length %d)", idx, dst->data.buffer.count);
+                    return make_null();
+                }
+                if (pass) d[idx] = num_guard(d[idx] + v);
+            }
+        }
+    }
+    return dst;   /* borrowed, like copy_into — the VM's borrow scan compensates */
+}
+
 /* ==== BUILTIN: softmax ==== */
 Value* builtin_tensor_softmax(Value *arg) {
     /* #632: softmax of a single element normalizes to 1.0. */
     if (arg && arg->type == VAL_NUM) return make_num(1.0);
+    /* flat-buffer fast path (#973): row-wise on the shape, 1-D is one row;
+     * same ne_softmax_buf kernel as the list path, so byte-identical. */
+    if (arg && arg->type == VAL_BUFFER) {
+        Value *res = make_buffer_like(arg);
+        if (!res) return make_null();
+        int br, bc;
+        buf_dims(arg, &br, &bc);
+        memcpy(res->data.buffer.data, arg->data.buffer.data, (size_t)arg->data.buffer.count * sizeof(double));
+        ne_softmax_buf(res->data.buffer.data, br, bc);
+        return res;
+    }
     int rows, cols;
     double *flat = tensor_to_flat(arg, &rows, &cols);
     if (!flat) return make_null();
@@ -626,17 +917,38 @@ Value* builtin_tensor_softmax(Value *arg) {
 
 /* ==== BUILTIN: log_softmax ==== */
 Value* builtin_tensor_log_softmax(Value *arg) {
-    /* Accept: log_softmax of tensor  OR  log_softmax of [tensor, dim] */
+    /* Accept: log_softmax of tensor  OR  log_softmax of [tensor, dim].
+     * #973: the [tensor, dim] form is recognised only as exactly [list, num].
+     * The old test ("first element is a list") was satisfied by EVERY 2-D
+     * tensor, so `log_softmax of [[1, 2], [3, 4]]` silently answered for row
+     * 0 alone (a 1-D result of 2) — caught by the buffer/list differential
+     * in tests/test_tensor_buffer_ops.eigs. A 2-D tensor's second element is
+     * a row (a list), never a number, so the two forms no longer collide. */
     Value *tensor = arg;
-    if (arg && arg->type == VAL_LIST && arg->data.list.count >= 1) {
-        Value *first = arg->data.list.items[0];
-        if (first->type == VAL_LIST) tensor = first; /* [tensor, dim] form */
-    }
+    if (arg && arg->type == VAL_LIST && arg->data.list.count == 2 &&
+        arg->data.list.items[0]->type == VAL_LIST &&
+        arg->data.list.items[1]->type == VAL_NUM)
+        tensor = arg->data.list.items[0];   /* [tensor, dim] form */
     /* #632: log(softmax(scalar)) = log(1) = 0. */
     /* fs:ANSWER softmax of a single element is 1 and log(1) is 0, so 0.0 is
      * the arithmetic result for a scalar argument — a NUMBER is a valid
      * argument here, which is what makes this not a type guard (#632). */
     if (tensor && tensor->type == VAL_NUM) return make_num(0.0);
+    /* flat-buffer fast path (#973): same kernel + the same #865 clamp. */
+    if (tensor && tensor->type == VAL_BUFFER) {
+        Value *res = make_buffer_like(tensor);
+        if (!res) return make_null();
+        int br, bc;
+        buf_dims(tensor, &br, &bc);
+        double *d = res->data.buffer.data;
+        memcpy(d, tensor->data.buffer.data, (size_t)tensor->data.buffer.count * sizeof(double));
+        ne_softmax_buf(d, br, bc);
+        for (int i = 0; i < tensor->data.buffer.count; i++) {
+            if (!(d[i] > 0.0)) g_math_flags |= EIGS_MATH_INVALID;
+            d[i] = log(d[i] > 0.0 ? d[i] : 1e-10);
+        }
+        return res;
+    }
     int rows, cols;
     double *flat = tensor_to_flat(tensor, &rows, &cols);
     if (!flat) return make_null();
@@ -678,6 +990,16 @@ Value* builtin_tensor_leaky_relu(Value *arg) {
         double x = arg->data.num;
         return make_num(x < 0.0 ? 0.01 * x : x);
     }
+    /* flat-buffer fast path (#973), the twin of relu's. */
+    if (arg && arg->type == VAL_BUFFER) {
+        Value *res = make_buffer_like(arg);
+        if (!res) return make_null();
+        for (int i = 0; i < arg->data.buffer.count; i++) {
+            double x = arg->data.buffer.data[i];
+            res->data.buffer.data[i] = (x < 0.0) ? 0.01 * x : x;
+        }
+        return res;
+    }
     int rows, cols;
     double *flat = tensor_to_flat(arg, &rows, &cols);
     if (!flat) return make_null();
@@ -690,6 +1012,19 @@ Value* builtin_tensor_leaky_relu(Value *arg) {
 
 /* ==== BUILTIN: mean ==== */
 Value* builtin_tensor_mean(Value *arg) {
+    /* flat-buffer path (#973): the twin of sum's. An empty buffer averages
+     * to 0.0 like an empty list (no 0/0). */
+    if (arg && arg->type == VAL_BUFFER) {
+        double *d = arg->data.buffer.data;
+        int n = arg->data.buffer.count;
+        /* fs:EMPTY the mean over zero elements, as for `mean of []` below;
+         * the division would be 0/0. A buffer is a valid argument, so this
+         * is not a type guard and strict must not raise. */
+        if (n == 0) return make_num(0.0);
+        double s = 0.0;
+        for (int i = 0; i < n; i++) s = num_guard(s + d[i]);
+        return make_num(s / n);
+    }
     /* Split from the empty case below. `tensor_total` answers 0 for an empty
      * list AND for any non-tensor — a string, a dict, a function — so one
      * `total == 0` line was carrying two opposite verdicts: `mean of []`
@@ -877,23 +1212,58 @@ static int flat_index_at(Value *v, int i) {
              ? (int)v->data.list.items[i]->data.num : -1;
     return (int)v->data.buffer.data[i];
 }
+/* #973: a non-numeric element of an index LIST has no index, and reporting it
+ * as "index -1 out of range" would name the wrong fault. Buffers hold doubles,
+ * so every element is a number by construction. */
+static int flat_index_is_num(Value *v, int i) {
+    return v->type != VAL_LIST || v->data.list.items[i]->type == VAL_NUM;
+}
 
 /* ==== BUILTIN: gather ==== */
-/* gather of [tensor, indices, dim] → select elements at indices along last dim */
+/* gather of [tensor, indices, dim] -> select one element per row by index.
+ *
+ * An out-of-range index RAISES `index_range`, in EVERY form: list or buffer,
+ * per-row vector of indices or a scalar index into a 1-D tensor.
+ *
+ * Reconciled at integration (#973 vs #1093). #1093 folded an out-of-range
+ * index on the new buffer path to 0.0 because the list path did; #973 raised
+ * on it, because "a 0 in a Q-value or a log-prob is indistinguishable from a
+ * real 0". Both cannot be true of one builtin, and the answer must not depend
+ * on the container — #1093's whole contract is that a buffer is accepted
+ * WHEREVER a flat numeric list is, so one logical input has one answer.
+ * Settled on the raise, and the list path moves with it:
+ *   - there is no element at an out-of-range index, so 0.0 is a stand-in for
+ *     a rejected input, which is the fail-soft class #971/#975 are removing;
+ *   - `gather`'s own dual `scatter_add` (#973) raises on exactly this index,
+ *     so folding here would make the forward pass quiet and the backward pass
+ *     loud for the same bad index;
+ *   - the `[]` operator and `matmul`'s #512 discipline already raise.
+ * A per-row raise is unconditional, not strict-gated, for the same reason
+ * matmul's shape refusal is: it reports an argument that has no answer, not
+ * a documented soft answer.
+ *
+ * What did NOT move, so the two containers still agree: a tensor that is not
+ * a matrix in the per-row form (a 1-D buffer, or a list row that is not a
+ * list) still answers 0.0 for that row, as it always has — that is the
+ * wrong-SHAPE reading, a separate class from the index, and converting it is
+ * its own change (recorded as a residual on the integration commit). A short
+ * index vector still truncates to the row count. */
 Value* builtin_tensor_gather(Value *arg) {
     if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2) return make_null();
     Value *tensor = arg->data.list.items[0];
     Value *indices = arg->data.list.items[1];
-    /* #1093: a buffer tensor. A shaped (2-D) buffer with one index per row
-     * selects one element per row and yields a buffer; an unshaped (1-D)
-     * buffer with a scalar index yields that element. Out-of-range and
-     * wrong-shape readings mirror the list branches below: 0.0 per row for a
-     * bad index, and the trailing 0.0 for a scalar index off the end. */
+    /* #1093 + #973: a buffer tensor. A shaped (2-D) buffer with one index per
+     * row selects one element per row and yields a buffer; an unshaped (1-D)
+     * buffer with a scalar index yields that element. */
     if (tensor->type == VAL_BUFFER) {
         if (indices->type == VAL_NUM && tensor->data.buffer.rows == 0) {
             int idx = (int)indices->data.num;
-            if (idx >= 0 && idx < tensor->data.buffer.count)
-                return make_num(tensor->data.buffer.data[idx]);
+            if (idx < 0 || idx >= tensor->data.buffer.count) {
+                rt_error(EK_INDEX, 0, "gather: index %d out of range (length %d)",
+                         idx, tensor->data.buffer.count);
+                return make_null();
+            }
+            return make_num(tensor->data.buffer.data[idx]);
         } else if (flat_is_vector(indices)) {
             int shaped = tensor->data.buffer.rows > 0;
             int rows = shaped ? tensor->data.buffer.rows : tensor->data.buffer.count;
@@ -903,10 +1273,22 @@ Value* builtin_tensor_gather(Value *arg) {
             Value *out = make_shaped_buffer(0, n);
             if (!out) return make_null();
             for (int i = 0; i < n; i++) {
+                if (!shaped) { out->data.buffer.data[i] = 0.0; continue; }
+                if (!flat_index_is_num(indices, i)) {
+                    val_decref(out);
+                    rt_error(EK_TYPE, 0, "gather: index %d is %s (expected a number)",
+                             i, val_type_name(indices->data.list.items[i]->type));
+                    return make_null();
+                }
                 int idx = flat_index_at(indices, i);
-                out->data.buffer.data[i] =
-                    (shaped && idx >= 0 && idx < cols)
-                    ? tensor->data.buffer.data[(int64_t)i * cols + idx] : 0.0;
+                if (idx < 0 || idx >= cols) {
+                    val_decref(out);
+                    rt_error(EK_INDEX, 0,
+                             "gather: column index %d out of range for row %d (cols %d)",
+                             idx, i, cols);
+                    return make_null();
+                }
+                out->data.buffer.data[i] = tensor->data.buffer.data[(int64_t)i * cols + idx];
             }
             return out;
         }
@@ -918,33 +1300,47 @@ Value* builtin_tensor_gather(Value *arg) {
         Value *out = make_list(n);
         for (int i = 0; i < n; i++) {
             Value *row = tensor->data.list.items[i];
-            int idx = 0;
-            if (indices->data.list.items[i]->type == VAL_NUM)
-                idx = (int)indices->data.list.items[i]->data.num;
-            if (row->type == VAL_LIST && idx >= 0 && idx < row->data.list.count)
-                list_append_owned(out, make_num(row->data.list.items[idx]->type == VAL_NUM
-                    ? row->data.list.items[idx]->data.num : 0.0));
-            else
+            if (row->type != VAL_LIST) {   /* not a matrix row — shape, not index */
                 list_append_owned(out, make_num(0.0));
+                continue;
+            }
+            if (indices->data.list.items[i]->type != VAL_NUM) {
+                val_decref(out);
+                rt_error(EK_TYPE, 0, "gather: index %d is %s (expected a number)",
+                         i, val_type_name(indices->data.list.items[i]->type));
+                return make_null();
+            }
+            int idx = (int)indices->data.list.items[i]->data.num;
+            if (idx < 0 || idx >= row->data.list.count) {
+                val_decref(out);
+                rt_error(EK_INDEX, 0,
+                         "gather: column index %d out of range for row %d (cols %d)",
+                         idx, i, row->data.list.count);
+                return make_null();
+            }
+            list_append_owned(out, make_num(row->data.list.items[idx]->type == VAL_NUM
+                ? row->data.list.items[idx]->data.num : 0.0));
         }
         return out;
     }
     /* 1D tensor, scalar index */
     if (tensor->type == VAL_LIST && indices->type == VAL_NUM) {
         int idx = (int)indices->data.num;
-        if (idx >= 0 && idx < tensor->data.list.count)
-            return make_num(tensor->data.list.items[idx]->type == VAL_NUM
-                ? tensor->data.list.items[idx]->data.num : 0.0);
-    }
-    /* fs:TODO #971 two readings share this one line and cannot be separated
-     * without splitting it. (a) GUARD: `tensor` is not a list, or `indices` is
-     * neither a list nor a number — the wrong-type case, which should raise.
-     * (b) ANSWER: the 1D branch just above fell through because `idx` was out
-     * of range, and out-of-range → 0.0 is this builtin's established behaviour
-     * (the 2D branch above appends make_num(0.0) for the same condition), so
-     * strict must NOT raise on it. Converting as written would turn (b) into a
-     * type error; deferred rather than guessed. */
-    return make_num(0.0);
+        if (idx < 0 || idx >= tensor->data.list.count) {
+            rt_error(EK_INDEX, 0, "gather: index %d out of range (length %d)",
+                     idx, tensor->data.list.count);
+            return make_null();
+        }
+        return make_num(tensor->data.list.items[idx]->type == VAL_NUM
+            ? tensor->data.list.items[idx]->data.num : 0.0);
+    }
+    /* The fs:TODO #971 left here is resolved by the raise above: the two
+     * readings that shared this line are separated. Out-of-range no longer
+     * falls through (it raises at its branch), so what is left is only the
+     * GUARD reading — `tensor` is not a list or buffer, or `indices` is
+     * neither a vector nor a number — and it converts to ARG_GUARD like every
+     * other wrong-type case: 0.0 by default, a raise under EIGS_STRICT. */
+    ARG_GUARD(1, "gather", "a tensor and an index or index vector", make_num(0.0));
 }
 
 /* ==== Helper: call a user-defined EigenScript function from C ====
diff --git a/src/lsp_builtin_index.h b/src/lsp_builtin_index.h
index bbbf0dfb..b4a83255 100644
--- a/src/lsp_builtin_index.h
+++ b/src/lsp_builtin_index.h
@@ -176,6 +176,8 @@ static const char *builtin_docs[][2] = {
     {"ls", "ls of \"path\" → list of filenames in directory, or [] on failure."},
     {"math_flags", "math_flags — builtin; see docs/BUILTINS.md"},
     {"matmul", "matmul — builtin; see docs/BUILTINS.md"},
+    {"matmul_at", "matmul_at of [a, b] → aᵀ·b: a is (m x k), b is (m x n), result (k x n)."},
+    {"matmul_bt", "matmul_bt of [a, b] → a·bᵀ: a is (m x k), b is (n x k), result (m x n)."},
     {"max", "max — builtin; see docs/BUILTINS.md"},
     {"md5", "md5 — builtin; see docs/BUILTINS.md"},
     {"md5_file", "md5_file — builtin; see docs/BUILTINS.md"},
@@ -249,6 +251,7 @@ static const char *builtin_docs[][2] = {
     {"scan_int_tokens", "scan_int_tokens of text"},
     {"scan_ints", "scan_ints of text"},
     {"scan_tokens", "scan_tokens of text"},
+    {"scatter_add", "scatter_add of [dst, indices, values] → dst, accumulated IN PLACE (#973)."},
     {"screen_clear", "screen_clear of null — clear terminal and hide cursor"},
     {"screen_end", "screen_end of null — show cursor and reset"},
     {"screen_put", "screen_put of [row, col, char, color_code] — write a character at terminal position"},
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index a9fd5120..bda6f975 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -5187,6 +5187,17 @@ check_eigs_suite "flat-buffer tensors" test_flat_buffer_tensor.eigs "PASS: flat-
 # #932: a 65x65 by 65x67 matmul so the i and j tile bounds run multi-tile with
 # a partial remainder in every dimension, not only their single-tile path.
 check_eigs_suite "tiled tensor kernels (#745, #932)" test_tensor_kernel_tiling.eigs "TENSOR_KERNEL_TILING_OK" 1
+# #973: the flat-buffer surface the autograd tape runs on — matmul_at/matmul_bt
+# byte-identical to matmul of the transposed list operand, scatter_add vs the
+# list loop (and gather's dual), the buffer elementwise/softmax/leaky_relu/mean
+# paths vs the list path, numerical_grad on a buffer parameter; loud raises.
+check_eigs_suite "flat-buffer tensor ops for autograd: matmul_at/bt, scatter_add, buffer paths (#973)" \
+    test_tensor_buffer_ops.eigs "All tests passed." 78
+# #973: lib/autograd.eigs — every vjp rule vs the numerical_grad oracle (1e-4
+# relative + 1e-6 absolute), a 2-layer softmax-CE MLP trained by the tape, and
+# the Tidepool DQN shape (433->64->32->6, batch 32) through one backward.
+check_eigs_suite "lib/autograd: vjp rules vs numerical_grad, MLP trains, DQN shape backward (#973)" \
+    test_autograd.eigs "All tests passed." 101
 # #597: vectorized buffer kernels (buf_mix/buf_scale_range/buf_fill/buf_peak/
 # buf_dot + buf_copy loud bounds) — correctness, raise-on-bad-window, and the
 # differential leg (builtin exactly equals the interpreted per-sample loop on
diff --git a/tests/test_autograd.eigs b/tests/test_autograd.eigs
new file mode 100644
index 00000000..cb48e844
--- /dev/null
+++ b/tests/test_autograd.eigs
@@ -0,0 +1,680 @@
+# lib/autograd.eigs — reverse-mode autograd on a tape (#973).
+#
+# Three parts:
+#   1. Every vjp rule against the finite-difference ORACLE `numerical_grad`
+#      on small seeded-random shaped buffers (a batch axis everywhere a rule
+#      reduces over one).
+#   2. End-to-end: a 2-layer MLP (matmul → bias → relu → matmul → bias →
+#      softmax-CE) trained by the tape on a toy 3-class problem; and the
+#      Tidepool DQN shape (433 → 64 → 32 → 6, batch 32) through one backward.
+#   3. Bookkeeping: constants get no gradient, a node used twice accumulates,
+#      a leaf the loss never reached stays null.
+#
+# TOLERANCE: |tape − numerical| <= 1e-4·|numerical| + 1e-6, per element.
+# Why: central differences with eps = 1e-5 in f64 carry a truncation error of
+# O(eps²·f''') ≈ 1e-10 and a roundoff error of ≈ ulp(|f|)/eps ≈ 1e-11 for
+# the O(1..10) losses here — both orders of magnitude under the 1e-6 absolute
+# floor, which exists so that entries whose true gradient is exactly 0 (a
+# masked relu unit) are judged absolutely rather than relatively. Any wrong
+# rule is a gross miss: a sign error is 200% off, a dropped factor >= 100%
+# (the planted-fault run flips one sign and this file goes red).
+#
+# Marker: "All tests passed." (lib/test.eigs); `Tests: N` drives the tally.
+
+load_file of "lib/test.eigs"
+import autograd
+
+EPS is 0.00001
+REL is 0.0001
+ABS is 0.000001
+
+seed_random of 973
+
+# ---- helpers ----
+
+define rnd_buf(rows, cols, lo, hi) as:
+    local b is buffer of [rows, cols]
+    for i in range of (rows * cols):
+        b[i] is lo + (random of null) * (hi - lo)
+    return b
+
+define rnd_vec(n, lo, hi) as:
+    local b is buffer of n
+    for i in range of n:
+        b[i] is lo + (random of null) * (hi - lo)
+    return b
+
+# check_grad of [tag, param, loss_fn, tape_grad]: every element of the tape
+# gradient within tolerance of the central-difference oracle. Prints the
+# worst relative miss so the margin is visible in the log.
+define check_grad(tag, param, loss_fn, tape_grad) as:
+    local ng is numerical_grad of [loss_fn, param, EPS]
+    assert_true of [(type of tape_grad) == "buffer", tag + ": tape gradient is a buffer"]
+    if (type of tape_grad) != "buffer":
+        return null
+    assert_eq of [len of tape_grad, len of param, tag + ": gradient has the parameter's element count"]
+    local ps is shape of param
+    local gs is shape of tape_grad
+    assert_eq of [len of gs, len of ps, tag + ": gradient has the parameter's rank"]
+    local worst is 0.0
+    local bad is 0
+    for i in range of (len of param):
+        local d is tape_grad[i] - ng[i]
+        if d < 0.0:
+            d is 0.0 - d
+        local mag is ng[i]
+        if mag < 0.0:
+            mag is 0.0 - mag
+        local tol is REL * mag + ABS
+        if d > tol:
+            bad is bad + 1
+            print of f"  {tag}[{i}]: tape={tape_grad[i]} numerical={ng[i]} |diff|={d} > tol {tol}"
+        local rel is d / (mag + ABS)
+        if rel > worst:
+            worst is rel
+    assert_eq of [bad, 0, tag + ": every element within 1e-4 relative + 1e-6 absolute of numerical_grad"]
+    print of f"  {tag}: {len of param} elements, worst |diff|/(|g|+1e-6) = {worst}"
+    return null
+
+# ============================================================
+# 1. vjp rules vs numerical_grad
+# ============================================================
+print of "=== vjp rules vs numerical_grad ==="
+
+# --- matmul (both operands) + mul with the SAME node twice (accumulation) ---
+mmA is rnd_buf of [4, 3, -1.0, 1.0]
+mmB is rnd_buf of [3, 2, -1.0, 1.0]
+define loss_matmul() as:
+    local t is autograd.ag_tape of []
+    local y is autograd.ag_matmul of [t, (autograd.ag_leaf of [t, mmA]), (autograd.ag_leaf of [t, mmB])]
+    return autograd.ag_value of (autograd.ag_sum of [t, (autograd.ag_mul of [t, y, y])])
+t1 is autograd.ag_tape of []
+n_a is autograd.ag_leaf of [t1, mmA]
+n_b is autograd.ag_leaf of [t1, mmB]
+n_y is autograd.ag_matmul of [t1, n_a, n_b]
+n_l is autograd.ag_sum of [t1, (autograd.ag_mul of [t1, n_y, n_y])]
+autograd.ag_backward of [t1, n_l]
+assert_near of [autograd.ag_value of n_l, loss_matmul of [], 0.000000000001, "matmul: forward value is the plain-builtin forward"]
+check_grad of ["matmul dA", mmA, loss_matmul, autograd.ag_grad of n_a]
+check_grad of ["matmul dB", mmB, loss_matmul, autograd.ag_grad of n_b]
+
+# --- matmul with a 1-D (row-vector) left operand: the DQN's single-obs forward ---
+mvX is rnd_vec of [3, -1.0, 1.0]
+define loss_matmul_vec() as:
+    local t is autograd.ag_tape of []
+    local y is autograd.ag_matmul of [t, (autograd.ag_leaf of [t, mvX]), (autograd.ag_leaf of [t, mmB])]
+    return autograd.ag_value of (autograd.ag_sum of [t, (autograd.ag_mul of [t, y, y])])
+t1v is autograd.ag_tape of []
+nv_x is autograd.ag_leaf of [t1v, mvX]
+nv_b is autograd.ag_leaf of [t1v, mmB]
+nv_y is autograd.ag_matmul of [t1v, nv_x, nv_b]
+autograd.ag_backward of [t1v, (autograd.ag_sum of [t1v, (autograd.ag_mul of [t1v, nv_y, nv_y])])]
+check_grad of ["matmul(1-D x) dx", mvX, loss_matmul_vec, autograd.ag_grad of nv_x]
+check_grad of ["matmul(1-D x) dW", mmB, loss_matmul_vec, autograd.ag_grad of nv_b]
+
+# --- add with a bias broadcast over the batch axis, then relu ---
+# X [5 x 3] batch, W [3 x 4], b [4]: loss = sum(relu(X.W + b)^2)
+bX is rnd_buf of [5, 3, -1.0, 1.0]
+bW is rnd_buf of [3, 4, -1.0, 1.0]
+bb is rnd_vec of [4, -0.5, 0.5]
+define loss_bias_relu() as:
+    local t is autograd.ag_tape of []
+    local z is autograd.ag_add of [t, (autograd.ag_matmul of [t, (autograd.ag_const of [t, bX]), (autograd.ag_leaf of [t, bW])]), (autograd.ag_leaf of [t, bb])]
+    local h is autograd.ag_relu of [t, z]
+    return autograd.ag_value of (autograd.ag_sum of [t, (autograd.ag_mul of [t, h, h])])
+t2 is autograd.ag_tape of []
+n2_x is autograd.ag_const of [t2, bX]
+n2_w is autograd.ag_leaf of [t2, bW]
+n2_b is autograd.ag_leaf of [t2, bb]
+n2_z is autograd.ag_add of [t2, (autograd.ag_matmul of [t2, n2_x, n2_w]), n2_b]
+n2_h is autograd.ag_relu of [t2, n2_z]
+autograd.ag_backward of [t2, (autograd.ag_sum of [t2, (autograd.ag_mul of [t2, n2_h, n2_h])])]
+# The relu kink: finite differences straddle it when |z| < eps. Assert the
+# seeded inputs keep every pre-activation clear of it, so a miss below would
+# be the rule, not the oracle.
+kink_clear is 1
+n2_zv is autograd.ag_value of n2_z
+for i in range of (len of n2_zv):
+    zi is n2_zv[i]
+    if zi < 0.0:
+        zi is 0.0 - zi
+    if zi < 0.001:
+        kink_clear is 0
+assert_true of [kink_clear, "relu: no pre-activation within 1e-3 of the kink (seeded)"]
+assert_true of [(len of (shape of (autograd.ag_grad of n2_b))) == 1 and (len of (autograd.ag_grad of n2_b)) == 4, "bias gradient is 1-D [4] (reduced over the batch axis of 5)"]
+check_grad of ["bias(add) db", bb, loss_bias_relu, autograd.ag_grad of n2_b]
+check_grad of ["relu∘add dW", bW, loss_bias_relu, autograd.ag_grad of n2_w]
+assert_true of [(type of (autograd.ag_grad of n2_x)) == "none", "const input gets no gradient"]
+
+# --- same-shape add, and sub (mean-squared error), both operands ---
+sA is rnd_buf of [3, 4, -1.0, 1.0]
+sB is rnd_buf of [3, 4, -1.0, 1.0]
+sC is rnd_buf of [3, 4, -1.0, 1.0]
+define loss_add_sub() as:
+    local t is autograd.ag_tape of []
+    local d is autograd.ag_sub of [t, (autograd.ag_add of [t, (autograd.ag_leaf of [t, sA]), (autograd.ag_const of [t, sC])]), (autograd.ag_leaf of [t, sB])]
+    return autograd.ag_value of (autograd.ag_mean of [t, (autograd.ag_mul of [t, d, d])])
+t3 is autograd.ag_tape of []
+n3_a is autograd.ag_leaf of [t3, sA]
+n3_b is autograd.ag_leaf of [t3, sB]
+n3_d is autograd.ag_sub of [t3, (autograd.ag_add of [t3, n3_a, (autograd.ag_const of [t3, sC])]), n3_b]
+autograd.ag_backward of [t3, (autograd.ag_mean of [t3, (autograd.ag_mul of [t3, n3_d, n3_d])])]
+check_grad of ["add/sub/mean dA", sA, loss_add_sub, autograd.ag_grad of n3_a]
+check_grad of ["add/sub/mean dB (negated)", sB, loss_add_sub, autograd.ag_grad of n3_b]
+
+# --- sub with a bias broadcast: [4 x 3] - [3] ---
+subM is rnd_buf of [4, 3, -1.0, 1.0]
+subv is rnd_vec of [3, -1.0, 1.0]
+define loss_sub_bias() as:
+    local t is autograd.ag_tape of []
+    local d is autograd.ag_sub of [t, (autograd.ag_const of [t, subM]), (autograd.ag_leaf of [t, subv])]
+    return autograd.ag_value of (autograd.ag_sum of [t, (autograd.ag_mul of [t, d, d])])
+t3b is autograd.ag_tape of []
+n3b_v is autograd.ag_leaf of [t3b, subv]
+n3b_d is autograd.ag_sub of [t3b, (autograd.ag_const of [t3b, subM]), n3b_v]
+autograd.ag_backward of [t3b, (autograd.ag_sum of [t3b, (autograd.ag_mul of [t3b, n3b_d, n3b_d])])]
+check_grad of ["sub(bias broadcast) dv", subv, loss_sub_bias, autograd.ag_grad of n3b_v]
+
+# --- mul (distinct operands) + scale ---
+muA is rnd_buf of [2, 5, -1.0, 1.0]
+muB is rnd_buf of [2, 5, -1.0, 1.0]
+define loss_mul_scale() as:
+    local t is autograd.ag_tape of []
+    local p is autograd.ag_mul of [t, (autograd.ag_leaf of [t, muA]), (autograd.ag_leaf of [t, muB])]
+    local q is autograd.ag_scale of [t, p, 2.5]
+    return autograd.ag_value of (autograd.ag_sum of [t, (autograd.ag_mul of [t, q, q])])
+t4 is autograd.ag_tape of []
+n4_a is autograd.ag_leaf of [t4, muA]
+n4_b is autograd.ag_leaf of [t4, muB]
+n4_q is autograd.ag_scale of [t4, (autograd.ag_mul of [t4, n4_a, n4_b]), 2.5]
+autograd.ag_backward of [t4, (autograd.ag_sum of [t4, (autograd.ag_mul of [t4, n4_q, n4_q])])]
+check_grad of ["mul/scale dA", muA, loss_mul_scale, autograd.ag_grad of n4_a]
+check_grad of ["mul/scale dB", muB, loss_mul_scale, autograd.ag_grad of n4_b]
+
+# --- leaky_relu ---
+lrA is rnd_buf of [3, 4, -1.0, 1.0]
+lrC is rnd_buf of [3, 4, -1.0, 1.0]
+define loss_leaky() as:
+    local t is autograd.ag_tape of []
+    local h is autograd.ag_leaky_relu of [t, (autograd.ag_leaf of [t, lrA])]
+    return autograd.ag_value of (autograd.ag_sum of [t, (autograd.ag_mul of [t, h, (autograd.ag_const of [t, lrC])])])
+t5 is autograd.ag_tape of []
+n5_a is autograd.ag_leaf of [t5, lrA]
+n5_h is autograd.ag_leaky_relu of [t5, n5_a]
+autograd.ag_backward of [t5, (autograd.ag_sum of [t5, (autograd.ag_mul of [t5, n5_h, (autograd.ag_const of [t5, lrC])])])]
+neg_seen is 0
+for i in range of (len of lrA):
+    if lrA[i] < 0.0:
+        neg_seen is 1
+assert_true of [neg_seen, "leaky_relu: the seeded input has negative entries (the 0.01 branch is exercised)"]
+check_grad of ["leaky_relu dA", lrA, loss_leaky, autograd.ag_grad of n5_a]
+
+# --- softmax (row-wise, 3 rows of 4) ---
+smA is rnd_buf of [3, 4, -2.0, 2.0]
+smC is rnd_buf of [3, 4, -1.0, 1.0]
+define loss_softmax() as:
+    local t is autograd.ag_tape of []
+    local p is autograd.ag_softmax of [t, (autograd.ag_leaf of [t, smA])]
+    return autograd.ag_value of (autograd.ag_sum of [t, (autograd.ag_mul of [t, p, (autograd.ag_const of [t, smC])])])
+t6 is autograd.ag_tape of []
+n6_a is autograd.ag_leaf of [t6, smA]
+n6_p is autograd.ag_softmax of [t6, n6_a]
+autograd.ag_backward of [t6, (autograd.ag_sum of [t6, (autograd.ag_mul of [t6, n6_p, (autograd.ag_const of [t6, smC])])])]
+check_grad of ["softmax dA", smA, loss_softmax, autograd.ag_grad of n6_a]
+
+# --- log_softmax ---
+define loss_log_softmax() as:
+    local t is autograd.ag_tape of []
+    local p is autograd.ag_log_softmax of [t, (autograd.ag_leaf of [t, smA])]
+    return autograd.ag_value of (autograd.ag_sum of [t, (autograd.ag_mul of [t, p, (autograd.ag_const of [t, smC])])])
+t7 is autograd.ag_tape of []
+n7_a is autograd.ag_leaf of [t7, smA]
+n7_p is autograd.ag_log_softmax of [t7, n7_a]
+autograd.ag_backward of [t7, (autograd.ag_sum of [t7, (autograd.ag_mul of [t7, n7_p, (autograd.ag_const of [t7, smC])])])]
+check_grad of ["log_softmax dA", smA, loss_log_softmax, autograd.ag_grad of n7_a]
+
+# --- softmax + cross-entropy (p − onehot), through a linear layer with bias ---
+ceX is rnd_buf of [6, 3, -1.0, 1.0]
+ceW is rnd_buf of [3, 4, -1.0, 1.0]
+ceb is rnd_vec of [4, -0.5, 0.5]
+ceT is [2, 0, 3, 1, 2, 0]
+define loss_ce() as:
+    local t is autograd.ag_tape of []
+    local z is autograd.ag_add of [t, (autograd.ag_matmul of [t, (autograd.ag_const of [t, ceX]), (autograd.ag_leaf of [t, ceW])]), (autograd.ag_leaf of [t, ceb])]
+    return autograd.ag_value of (autograd.ag_softmax_ce of [t, z, ceT])
+t8 is autograd.ag_tape of []
+n8_w is autograd.ag_leaf of [t8, ceW]
+n8_b is autograd.ag_leaf of [t8, ceb]
+n8_z is autograd.ag_add of [t8, (autograd.ag_matmul of [t8, (autograd.ag_const of [t8, ceX]), n8_w]), n8_b]
+n8_l is autograd.ag_softmax_ce of [t8, n8_z, ceT]
+autograd.ag_backward of [t8, n8_l]
+# The value itself: mean of -log softmax(z)[i][t_i], recomputed with the builtins.
+ce_ref is 0.0
+ce_lsm is log_softmax of (autograd.ag_value of n8_z)
+for i in range of 6:
+    ce_ref is ce_ref - ce_lsm[i * 4 + ceT[i]]
+assert_near of [autograd.ag_value of n8_l, ce_ref / 6, 0.000000000001, "softmax_ce value = mean(-log_softmax[target])"]
+check_grad of ["softmax_ce dW", ceW, loss_ce, autograd.ag_grad of n8_w]
+check_grad of ["softmax_ce db", ceb, loss_ce, autograd.ag_grad of n8_b]
+
+# --- gather (scatter-add vjp): Q [5 x 3], one action per row, MSE to a target ---
+gX is rnd_buf of [5, 2, -1.0, 1.0]
+gW is rnd_buf of [2, 3, -1.0, 1.0]
+gIdx is [2, 0, 1, 2, 2]
+gTarget is rnd_vec of [5, -1.0, 1.0]
+define loss_gather() as:
+    local t is autograd.ag_tape of []
+    local q is autograd.ag_matmul of [t, (autograd.ag_const of [t, gX]), (autograd.ag_leaf of [t, gW])]
+    local picked is autograd.ag_gather of [t, q, gIdx]
+    local d is autograd.ag_sub of [t, picked, (autograd.ag_const of [t, gTarget])]
+    return autograd.ag_value of (autograd.ag_mean of [t, (autograd.ag_mul of [t, d, d])])
+t9 is autograd.ag_tape of []
+n9_w is autograd.ag_leaf of [t9, gW]
+n9_q is autograd.ag_matmul of [t9, (autograd.ag_const of [t9, gX]), n9_w]
+n9_p is autograd.ag_gather of [t9, n9_q, gIdx]
+n9_d is autograd.ag_sub of [t9, n9_p, (autograd.ag_const of [t9, gTarget])]
+autograd.ag_backward of [t9, (autograd.ag_mean of [t9, (autograd.ag_mul of [t9, n9_d, n9_d])])]
+assert_eq of [len of (autograd.ag_value of n9_p), 5, "gather: one pick per row"]
+# Unpicked Q entries must get exactly zero (scatter_add only touches indexed slots).
+gq is autograd.ag_grad of n9_q
+zero_unpicked is 1
+for i in range of 5:
+    for j in range of 3:
+        if j != gIdx[i] and gq[i * 3 + j] != 0.0:
+            zero_unpicked is 0
+assert_true of [zero_unpicked, "gather vjp: unpicked entries receive exactly 0"]
+check_grad of ["gather∘matmul dW", gW, loss_gather, autograd.ag_grad of n9_w]
+
+# --- norm (scalar node) ---
+nmX is rnd_buf of [3, 3, -1.0, 1.0]
+nmW is rnd_buf of [3, 2, -1.0, 1.0]
+define loss_norm() as:
+    local t is autograd.ag_tape of []
+    local y is autograd.ag_matmul of [t, (autograd.ag_const of [t, nmX]), (autograd.ag_leaf of [t, nmW])]
+    return autograd.ag_value of (autograd.ag_norm of [t, y])
+t10 is autograd.ag_tape of []
+n10_w is autograd.ag_leaf of [t10, nmW]
+n10_n is autograd.ag_norm of [t10, (autograd.ag_matmul of [t10, (autograd.ag_const of [t10, nmX]), n10_w])]
+autograd.ag_backward of [t10, n10_n]
+assert_near of [autograd.ag_value of n10_n, norm of (matmul of [nmX, nmW]), 0.000000000001, "norm value is the builtin norm"]
+check_grad of ["norm dW", nmW, loss_norm, autograd.ag_grad of n10_w]
+
+# --- sum over a 1-D leaf (the seed is a num, the gradient a ones-buffer) ---
+suV is rnd_vec of [6, -1.0, 1.0]
+define loss_sum() as:
+    local t is autograd.ag_tape of []
+    return autograd.ag_value of (autograd.ag_sum of [t, (autograd.ag_leaf of [t, suV])])
+t11 is autograd.ag_tape of []
+n11_v is autograd.ag_leaf of [t11, suV]
+autograd.ag_backward of [t11, (autograd.ag_sum of [t11, n11_v])]
+check_grad of ["sum dv", suV, loss_sum, autograd.ag_grad of n11_v]
+
+# --- backward on a non-scalar node seeds a ones-buffer; a leaf off the path stays null ---
+t12 is autograd.ag_tape of []
+n12_a is autograd.ag_leaf of [t12, sA]
+n12_off is autograd.ag_leaf of [t12, sB]
+n12_h is autograd.ag_relu of [t12, n12_a]
+autograd.ag_backward of [t12, n12_h]
+g12 is autograd.ag_grad of n12_a
+ones_where_pos is 1
+for i in range of (len of sA):
+    want is 0.0
+    if sA[i] > 0.0:
+        want is 1.0
+    if g12[i] != want:
+        ones_where_pos is 0
+assert_true of [ones_where_pos, "backward on a tensor node seeds ones; relu vjp masks them"]
+assert_true of [(type of (autograd.ag_grad of n12_off)) == "none", "a leaf the loss never reached keeps grad = null"]
+
+# ============================================================
+# 2. End-to-end: 2-layer MLP trained by the tape on a toy 3-class problem
+# ============================================================
+print of "=== 2-layer MLP, softmax-CE, trained by the tape ==="
+
+# 30 points in the plane, class = nearest of three centres.
+N_PTS is 30
+centres is [[2.0, 0.0], [-1.0, 1.7], [-1.0, -1.7]]
+mlp_x is buffer of [N_PTS, 2]
+mlp_t is []
+for i in range of N_PTS:
+    c is i % 3
+    mlp_x[i * 2] is centres[c][0] + ((random of null) - 0.5) * 1.2
+    mlp_x[i * 2 + 1] is centres[c][1] + ((random of null) - 0.5) * 1.2
+    append of [mlp_t, c]
+H is 8
+w1 is rnd_buf of [2, H, -0.5, 0.5]
+b1 is buffer of H
+w2 is rnd_buf of [H, 3, -0.5, 0.5]
+b2 is buffer of 3
+
+define mlp_step(lr) as:
+    local t is autograd.ag_tape of []
+    local x is autograd.ag_const of [t, mlp_x]
+    local nw1 is autograd.ag_leaf of [t, w1]
+    local nb1 is autograd.ag_leaf of [t, b1]
+    local nw2 is autograd.ag_leaf of [t, w2]
+    local nb2 is autograd.ag_leaf of [t, b2]
+    local h is autograd.ag_relu of [t, (autograd.ag_add of [t, (autograd.ag_matmul of [t, x, nw1]), nb1])]
+    local z is autograd.ag_add of [t, (autograd.ag_matmul of [t, h, nw2]), nb2]
+    local loss is autograd.ag_softmax_ce of [t, z, mlp_t]
+    autograd.ag_backward of [t, loss]
+    autograd.ag_sgd_step of [nw1, lr]
+    autograd.ag_sgd_step of [nb1, lr]
+    autograd.ag_sgd_step of [nw2, lr]
+    autograd.ag_sgd_step of [nb2, lr]
+    return autograd.ag_value of loss
+
+STEPS is 150
+losses is []
+for s in range of STEPS:
+    append of [losses, mlp_step of 0.3]
+initial_loss is losses[0]
+final_loss is losses[STEPS - 1]
+# "monotonically-ish": compare 10-step window means; count the windows that
+# decrease versus their predecessor.
+windows is []
+for k in range of (STEPS / 10):
+    acc is 0.0
+    for j in range of 10:
+        acc is acc + losses[k * 10 + j]
+    append of [windows, acc / 10]
+down is 0
+for k in range of ((len of windows) - 1):
+    if windows[k + 1] < windows[k]:
+        down is down + 1
+print of f"  loss: initial {initial_loss} -> final {final_loss} ({down}/{(len of windows) - 1} windows decreasing)"
+assert_true of [initial_loss > 0.9, "MLP: initial loss near ln(3) = 1.0986 for 3 classes (sanity of the CE value)"]
+assert_true of [final_loss < initial_loss * 0.25, "MLP: final loss < 25% of initial after 150 tape steps"]
+assert_true of [down >= ((len of windows) - 1) - 1, "MLP: at most one 10-step window fails to decrease"]
+# Accuracy on the training points after training.
+define mlp_accuracy() as:
+    local h is relu of (add of [(matmul of [mlp_x, w1]), b1])
+    local z is add of [(matmul of [h, w2]), b2]
+    local correct is 0
+    for i in range of N_PTS:
+        local best is 0
+        for c in range of 3:
+            if z[i * 3 + c] > z[i * 3 + best]:
+                best is c
+        if best == mlp_t[i]:
+            correct is correct + 1
+    return correct / N_PTS
+acc_final is mlp_accuracy of []
+print of f"  training accuracy after {STEPS} steps: {acc_final}"
+assert_true of [acc_final >= 0.9, "MLP: >= 90% training accuracy on the toy problem"]
+
+# ============================================================
+# 2b. The Tidepool DQN shape: 433 -> 64 -> 32 -> 6, batch 32, one backward
+# ============================================================
+print of "=== Tidepool DQN shape (433 -> 64 -> 32 -> 6, batch 32) ==="
+DQ_IN is 433
+DQ_H1 is 64
+DQ_H2 is 32
+DQ_ACT is 6
+DQ_BS is 32
+dq_x is rnd_buf of [DQ_BS, DQ_IN, -1.0, 1.0]
+dq_w1 is rnd_buf of [DQ_IN, DQ_H1, -0.07, 0.07]
+dq_b1 is buffer of DQ_H1
+dq_w2 is rnd_buf of [DQ_H1, DQ_H2, -0.2, 0.2]
+dq_b2 is buffer of DQ_H2
+dq_w3 is rnd_buf of [DQ_H2, DQ_ACT, -0.3, 0.3]
+dq_b3 is buffer of DQ_ACT
+dq_actions is []
+dq_target is buffer of DQ_BS
+for i in range of DQ_BS:
+    append of [dq_actions, i % DQ_ACT]
+    dq_target[i] is (random of null) * 2.0 - 1.0
+td is autograd.ag_tape of []
+dn_x is autograd.ag_const of [td, dq_x]
+dn_w1 is autograd.ag_leaf of [td, dq_w1]
+dn_b1 is autograd.ag_leaf of [td, dq_b1]
+dn_w2 is autograd.ag_leaf of [td, dq_w2]
+dn_b2 is autograd.ag_leaf of [td, dq_b2]
+dn_w3 is autograd.ag_leaf of [td, dq_w3]
+dn_b3 is autograd.ag_leaf of [td, dq_b3]
+dn_h1 is autograd.ag_relu of [td, (autograd.ag_add of [td, (autograd.ag_matmul of [td, dn_x, dn_w1]), dn_b1])]
+dn_h2 is autograd.ag_relu of [td, (autograd.ag_add of [td, (autograd.ag_matmul of [td, dn_h1, dn_w2]), dn_b2])]
+dn_q is autograd.ag_add of [td, (autograd.ag_matmul of [td, dn_h2, dn_w3]), dn_b3]
+dn_pick is autograd.ag_gather of [td, dn_q, dq_actions]
+dn_err is autograd.ag_sub of [td, dn_pick, (autograd.ag_const of [td, dq_target])]
+dn_loss is autograd.ag_mean of [td, (autograd.ag_mul of [td, dn_err, dn_err])]
+autograd.ag_backward of [td, dn_loss]
+assert_eq of [shape of (autograd.ag_value of dn_q), [DQ_BS, DQ_ACT], "DQN: Q is [32 x 6]"]
+assert_eq of [shape of (autograd.ag_grad of dn_w1), [DQ_IN, DQ_H1], "DQN: dW1 is [433 x 64]"]
+assert_eq of [shape of (autograd.ag_grad of dn_b1), [DQ_H1], "DQN: db1 is [64]"]
+assert_eq of [shape of (autograd.ag_grad of dn_w2), [DQ_H1, DQ_H2], "DQN: dW2 is [64 x 32]"]
+assert_eq of [shape of (autograd.ag_grad of dn_b2), [DQ_H2], "DQN: db2 is [32]"]
+assert_eq of [shape of (autograd.ag_grad of dn_w3), [DQ_H2, DQ_ACT], "DQN: dW3 is [32 x 6]"]
+assert_eq of [shape of (autograd.ag_grad of dn_b3), [DQ_ACT], "DQN: db3 is [6]"]
+# db3 is the column-sum of the gathered TD error: only the taken actions' columns.
+db3 is autograd.ag_grad of dn_b3
+db3_ref is buffer of DQ_ACT
+dn_errv is autograd.ag_value of dn_err
+for i in range of DQ_BS:
+    db3_ref[dq_actions[i]] is db3_ref[dq_actions[i]] + 2.0 * dn_errv[i] / DQ_BS
+db3_ok is 1
+for a in range of DQ_ACT:
+    dd is db3[a] - db3_ref[a]
+    if dd < 0.0:
+        dd is 0.0 - dd
+    if dd > 0.000000000001:
+        db3_ok is 0
+assert_true of [db3_ok, "DQN: db3 equals the hand-rolled per-action TD-error reduction (train.eigs:299-303 shape)"]
+# One clipped SGD step moves the parameters in place (the caller's buffers).
+w1_before is dq_w1[0]
+autograd.ag_sgd_step_clipped of [dn_w1, 0.01, 1.0]
+assert_true of [dq_w1[0] != w1_before or (autograd.ag_grad of dn_w1)[0] == 0.0, "DQN: ag_sgd_step_clipped updates the caller's w1 buffer in place"]
+dn2_h1 is relu of (add of [(matmul of [dq_x, dq_w1]), dq_b1])
+dn2_h2 is relu of (add of [(matmul of [dn2_h1, dq_w2]), dq_b2])
+dn2_q is add of [(matmul of [dn2_h2, dq_w3]), dq_b3]
+dn2_pick is gather of [dn2_q, dq_actions]
+dn2_err is subtract of [dn2_pick, dq_target]
+dq_loss_after is mean of (multiply of [dn2_err, dn2_err])
+assert_true of [dq_loss_after < (autograd.ag_value of dn_loss), "DQN: one clipped step on w1 alone lowers the TD loss"]
+
+# ============================================================
+# 4. Broadcast operands (#973 round 2)
+# ============================================================
+# The elementwise builtins broadcast ([rows x cols] against [cols] either way,
+# and a tensor against a scalar), so an operand can be SMALLER than the result
+# and its gradient must be summed over the broadcast axis. ag_add/ag_sub did
+# that; ag_mul did not — it returned an unreduced [rows x cols] gradient for a
+# [cols] parameter, and ag_sgd_step then stepped the parameter with the first
+# `cols` entries of it. Every elementwise rule is now checked in BOTH
+# orientations with BOTH operands against numerical_grad; the matched-shape
+# halves of the same rules are section 1 above (add/sub/mul dA and dB).
+# It runs last so that sections 1-3 draw the same seeded random stream they
+# did before this section existed.
+print of "=== broadcast operands vs numerical_grad ==="
+
+BC_MODE is 0
+BC_NAMES is ["add [M,v]", "add [v,M]", "sub [M,v]", "sub [v,M]", "mul [M,v]", "mul [v,M]"]
+bcM is rnd_buf of [5, 4, -1.0, 1.0]
+bcV is rnd_vec of [4, -1.0, 1.0]
+bcC is rnd_buf of [5, 4, -1.0, 1.0]
+
+# bc_forward of t -> [M-node, v-node, loss-node]; BC_MODE picks the rule and
+# the operand order. The loss is sum((M op v) * C) with C constant, so the
+# gradient of the broadcast operand is a genuine column sum over the 5-row
+# batch axis (not a value an unreduced gradient could accidentally match).
+define bc_forward(t) as:
+    local mn is autograd.ag_leaf of [t, bcM]
+    local vn is autograd.ag_leaf of [t, bcV]
+    local y is null
+    if BC_MODE == 0:
+        y is autograd.ag_add of [t, mn, vn]
+    elif BC_MODE == 1:
+        y is autograd.ag_add of [t, vn, mn]
+    elif BC_MODE == 2:
+        y is autograd.ag_sub of [t, mn, vn]
+    elif BC_MODE == 3:
+        y is autograd.ag_sub of [t, vn, mn]
+    elif BC_MODE == 4:
+        y is autograd.ag_mul of [t, mn, vn]
+    else:
+        y is autograd.ag_mul of [t, vn, mn]
+    local l is autograd.ag_sum of [t, (autograd.ag_mul of [t, y, (autograd.ag_const of [t, bcC])])]
+    return [mn, vn, l]
+
+define bc_loss() as:
+    local t is autograd.ag_tape of []
+    local r is bc_forward of t
+    return autograd.ag_value of r[2]
+
+for bc_m in range of 6:
+    BC_MODE is bc_m
+    bc_t is autograd.ag_tape of []
+    bc_r is bc_forward of bc_t
+    autograd.ag_backward of [bc_t, bc_r[2]]
+    check_grad of [BC_NAMES[bc_m] + " dM (full shape)", bcM, bc_loss, autograd.ag_grad of bc_r[0]]
+    check_grad of [BC_NAMES[bc_m] + " dv (broadcast operand)", bcV, bc_loss, autograd.ag_grad of bc_r[1]]
+
+# --- scalar-node operand: a learned scalar scaling a matrix ---
+# `multiply of [buffer, number]` is the builtins' other broadcast form, and a
+# node's value is a number whenever it came from ag_sum/ag_mean/ag_norm/
+# ag_softmax_ce. The scalar's gradient is the sum of the whole result's.
+scM is rnd_buf of [3, 4, -1.0, 1.0]
+scK is rnd_vec of [2, 0.5, 1.5]
+define loss_scalar_mul() as:
+    local t is autograd.ag_tape of []
+    local kn is autograd.ag_mean of [t, (autograd.ag_leaf of [t, scK])]
+    local y is autograd.ag_mul of [t, (autograd.ag_const of [t, scM]), kn]
+    return autograd.ag_value of (autograd.ag_sum of [t, (autograd.ag_mul of [t, y, y])])
+t1b is autograd.ag_tape of []
+n1b_k is autograd.ag_leaf of [t1b, scK]
+n1b_y is autograd.ag_mul of [t1b, (autograd.ag_const of [t1b, scM]), (autograd.ag_mean of [t1b, n1b_k])]
+autograd.ag_backward of [t1b, (autograd.ag_sum of [t1b, (autograd.ag_mul of [t1b, n1b_y, n1b_y])])]
+check_grad of ["mul [M, scalar node] dk", scK, loss_scalar_mul, autograd.ag_grad of n1b_k]
+
+define loss_scalar_add() as:
+    local t is autograd.ag_tape of []
+    local kn is autograd.ag_mean of [t, (autograd.ag_leaf of [t, scK])]
+    local y is autograd.ag_add of [t, (autograd.ag_const of [t, scM]), kn]
+    return autograd.ag_value of (autograd.ag_sum of [t, (autograd.ag_mul of [t, y, y])])
+t1c is autograd.ag_tape of []
+n1c_k is autograd.ag_leaf of [t1c, scK]
+n1c_y is autograd.ag_add of [t1c, (autograd.ag_const of [t1c, scM]), (autograd.ag_mean of [t1c, n1c_k])]
+autograd.ag_backward of [t1c, (autograd.ag_sum of [t1c, (autograd.ag_mul of [t1c, n1c_y, n1c_y])])]
+check_grad of ["add [M, scalar node] dk", scK, loss_scalar_add, autograd.ag_grad of n1c_k]
+
+# --- SGD on a broadcast parameter lowers the loss ---
+# The half the shape bug reached: ag_sgd_step steps the buffer it was handed,
+# so an unreduced gradient trains the parameter on the wrong numbers.
+sgD is rnd_buf of [6, 4, -1.0, 1.0]
+sgT is rnd_buf of [6, 4, -1.0, 1.0]
+sgV is rnd_vec of [4, -1.0, 1.0]
+define sg_loss() as:
+    local t is autograd.ag_tape of []
+    local y is autograd.ag_add of [t, (autograd.ag_const of [t, sgD]), (autograd.ag_leaf of [t, sgV])]
+    local e is autograd.ag_sub of [t, y, (autograd.ag_const of [t, sgT])]
+    return autograd.ag_value of (autograd.ag_mean of [t, (autograd.ag_mul of [t, e, e])])
+sg_first is sg_loss of null
+sg_prev is sg_first
+sg_monotone is 1
+for sg_step in range of 20:
+    sg_t is autograd.ag_tape of []
+    sg_vn is autograd.ag_leaf of [sg_t, sgV]
+    sg_y is autograd.ag_add of [sg_t, (autograd.ag_const of [sg_t, sgD]), sg_vn]
+    sg_e is autograd.ag_sub of [sg_t, sg_y, (autograd.ag_const of [sg_t, sgT])]
+    autograd.ag_backward of [sg_t, (autograd.ag_mean of [sg_t, (autograd.ag_mul of [sg_t, sg_e, sg_e])])]
+    assert_eq of [len of (autograd.ag_grad of sg_vn), 4, "sgd(broadcast): gradient stays the parameter's 4 elements"]
+    autograd.ag_sgd_step of [sg_vn, 0.5]
+    sg_now is sg_loss of null
+    if sg_now >= sg_prev:
+        sg_monotone is 0
+    sg_prev is sg_now
+# The reachable optimum: with D and T fixed, L(v) is minimised at
+# v[j] = mean_i (T - D)[i][j], and the residual is the column variance. A
+# gradient that is not column-summed cannot find it.
+sgOpt is 0.0
+for sg_j in range of 4:
+    sg_mu is 0.0
+    for sg_i in range of 6:
+        sg_mu is sg_mu + (sgT[sg_i * 4 + sg_j] - sgD[sg_i * 4 + sg_j])
+    sg_mu is sg_mu / 6
+    for sg_i2 in range of 6:
+        sg_r is (sgD[sg_i2 * 4 + sg_j] + sg_mu) - sgT[sg_i2 * 4 + sg_j]
+        sgOpt is sgOpt + sg_r * sg_r
+sgOpt is sgOpt / 24
+assert_true of [sg_monotone, "sgd(broadcast): 20 steps on the [4] bias each lower the loss"]
+assert_true of [sg_prev >= sgOpt, "sgd(broadcast): the trained loss does not beat the analytic optimum"]
+assert_true of [sg_prev <= sgOpt * 1.001 + 0.000000001, "sgd(broadcast): 20 steps reach the analytic optimum (within 0.1%)"]
+print of f"  sgd(broadcast): loss {sg_first} -> {sg_prev} (optimum {sgOpt})"
+
+# --- rules that cannot take a broadcast operand REFUSE, they do not guess ---
+mmRefused is 0
+mmWhy is ""
+try:
+    mmWhy is "no raise, answered shape " + (str of (shape of (matmul of [bcM, bcV])))
+catch mm_e:
+    mmRefused is 1
+    mmWhy is mm_e.message
+assert_true of [mmRefused, "matmul of a [5x4] and a [4] refuses (no bias-shaped broadcast) instead of guessing: " + mmWhy]
+
+# The elementwise BUILTIN does not refuse a non-broadcastable pair: `add`,
+# `subtract`, `multiply`, `divide` share ONE implementation with the list path
+# (#1093/#973, settled at integration), and that algebra truncates to the
+# shorter operand — for buffers exactly as it always has for lists. Pinned in
+# both containers here so the parity is what this asserts, not an accident:
+# Both answers are pinned because they DIVERGE, and a pinned divergence is
+# visible where an unpinned one drifts: the buffer path truncates flat to the
+# shorter operand ([3]) while the list path recurses per row and broadcasts the
+# scalar ([3, 4]). Neither is a meaningful answer — the operands do not
+# broadcast — and unifying them means deciding whether this whole class should
+# raise, which is a change to the five arithmetic builtins' LIST algebra and
+# its own differential. Recorded as a residual, gated here.
+ewShapeBuf is str of (shape of (add of [bcM, (buffer of 3)]))
+ewLst is [[1.0, 2.0, 3.0, 4.0], [1.0, 2.0, 3.0, 4.0], [1.0, 2.0, 3.0, 4.0], [1.0, 2.0, 3.0, 4.0], [1.0, 2.0, 3.0, 4.0]]
+ewShapeList is str of (shape of (add of [ewLst, [1.0, 1.0, 1.0]]))
+assert_eq of [ewShapeBuf, "[3]", "add of a [5x4] buffer and a [3] buffer truncates flat to [3]"]
+assert_eq of [ewShapeList, "[3, 4]", "add of the same shapes as LISTS answers [3, 4] — the one container divergence left in the elementwise algebra"]
+
+# The TAPE refuses it, one level up: a truncated value's gradient fits neither
+# operand, so `ag_add` throws instead of pushing a node `ag_sgd_step` would
+# train on. (This refusal used to live in the C layer as a buffer-only raise.)
+ewRefused is 0
+ewWhy is ""
+et is autograd.ag_tape of []
+eA is autograd.ag_leaf of [et, bcM]
+eB is autograd.ag_leaf of [et, (buffer of 3)]
+try:
+    ewWhy is "no raise, answered shape " + (str of (shape of (autograd.ag_add of [et, eA, eB]).value))
+catch ew_e:
+    ewRefused is 1
+    ewWhy is str of ew_e
+assert_true of [ewRefused, "ag_add of a [5x4] and a [3] refuses, so no tape node is ever built: " + ewWhy]
+
+# ag_sgd_step is the last line of defence: a gradient whose element count does
+# not match its parameter's throws instead of stepping the first `n` entries.
+gt is autograd.ag_tape of []
+gn is autograd.ag_leaf of [gt, (buffer of 4)]
+gn.grad is buffer of [5, 4]
+sgdRefused is 0
+sgdWhy is "no raise"
+try:
+    autograd.ag_sgd_step of [gn, 0.1]
+catch sgd_e:
+    sgdRefused is 1
+    sgdWhy is str of sgd_e
+assert_true of [sgdRefused, "ag_sgd_step throws on a gradient whose element count is not the parameter's: " + sgdWhy]
+scaleRefused is 0
+scaleWhy is ""
+try:
+    scaleWhy is "no raise, answered shape " + (str of (shape of (autograd.ag_value of (autograd.ag_scale of [gt, (autograd.ag_leaf of [gt, bcV]), bcM]))))
+catch scale_e:
+    scaleRefused is 1
+    scaleWhy is str of scale_e
+assert_true of [scaleRefused, "ag_scale refuses a tensor k (it would broadcast and reshape the result): " + scaleWhy]
+
+gn2 is autograd.ag_leaf of [gt, (buffer of 4)]
+gn2.grad is buffer of [5, 4]
+sgdcRefused is 0
+sgdcWhy is "no raise"
+try:
+    autograd.ag_sgd_step_clipped of [gn2, 0.1, 1.0]
+catch sgdc_e:
+    sgdcRefused is 1
+    sgdcWhy is str of sgdc_e
+assert_true of [sgdcRefused, "ag_sgd_step_clipped throws on a mis-shaped gradient too: " + sgdcWhy]
+
+test_summary of null
diff --git a/tests/test_misc_builtins.eigs b/tests/test_misc_builtins.eigs
index 80589b1a..208ef76b 100644
--- a/tests/test_misc_builtins.eigs
+++ b/tests/test_misc_builtins.eigs
@@ -21,10 +21,24 @@ neg is negative of [1, 2, 3]
 assert_eq of [neg[0], -1, "negative[0]"]
 assert_eq of [neg[2], -3, "negative[2]"]
 
-# gather — gather rows by index
+# gather — ONE ELEMENT PER ROW, indexed by column (not "gather rows by index",
+# which is what the comment here used to say). The call was
+# `gather of [matrix, [0, 2], 0]` against 2-column rows, so column 2 did not
+# exist and row 1 answered a stand-in 0; only `len` was asserted, so the wrong
+# number was invisible. Found when an out-of-range index started raising
+# (#973/#1093). Now the values are asserted, and the raise has its own check.
 matrix is [[10, 20], [30, 40], [50, 60]]
-gathered is gather of [matrix, [0, 2], 0]
-assert_eq of [len of gathered, 2, "gather row count"]
+gathered is gather of [matrix, [0, 1, 0]]
+assert_eq of [len of gathered, 3, "gather row count"]
+assert_eq of [gathered[0], 10, "gather row 0 column 0"]
+assert_eq of [gathered[1], 40, "gather row 1 column 1"]
+assert_eq of [gathered[2], 50, "gather row 2 column 0"]
+gather_raised is 0
+try:
+    gather of [matrix, [0, 2]]
+catch gather_e:
+    gather_raised is 1
+assert_eq of [gather_raised, 1, "gather: an out-of-range column raises, it does not fold to 0"]
 
 # num_copy — independent copy of numeric value
 x is 42
diff --git a/tests/test_sandbox_allow.eigs b/tests/test_sandbox_allow.eigs
index 5cecf42a..eb18a774 100644
--- a/tests/test_sandbox_allow.eigs
+++ b/tests/test_sandbox_allow.eigs
@@ -37,6 +37,19 @@ rbb_blk    is (sandbox_run of [[ABI, [GET_NAME,0,0, CONST,1,0, CALL,1,0, RETURN]
 r_len is sandbox_run of [[ABI, [GET_NAME,0,0, CONST,1,0, CALL,1,0, RETURN], ["len", "hello"]], 1000]
 allow_ok is (r_len["ok"] == 1) and (r_len["result"] == 5)
 
+# (c2) #973: the autograd tape's pure-compute kernels are allowlisted —
+# matmul_at/matmul_bt/scatter_add compute on the arguments handed in (a
+# deep-copied constant here) and touch no host state.
+r_at is sandbox_run of [[ABI, [GET_NAME,0,0, CONST,1,0, CALL,1,0, RETURN], ["matmul_at", [[[1.0, 2.0]], [[3.0, 4.0]]]]], 1000]
+at_ok is (r_at["ok"] == 1) and (r_at["result"] == [[3.0, 4.0], [6.0, 8.0]])
+r_bt is sandbox_run of [[ABI, [GET_NAME,0,0, CONST,1,0, CALL,1,0, RETURN], ["matmul_bt", [[[1.0, 2.0]], [[3.0, 4.0]]]]], 1000]
+bt_ok is (r_bt["ok"] == 1) and (r_bt["result"] == [11.0])
+r_sc is sandbox_run of [[ABI, [GET_NAME,0,0, CONST,1,0, CALL,1,0, RETURN], ["scatter_add", [[0.0, 0.0], [1], 5.0]]], 1000]
+# dst is a list here, not a buffer: the call is REACHABLE (a type error from the
+# builtin itself, not the sandbox's blocked-stub denial).
+sc_ok is (r_sc["ok"] == 0) and (r_sc["error"]["kind"] == "type_mismatch")
+allow_973 is at_ok and bt_ok and sc_ok
+
 # ---- Containment of the SANDBOX ENV ITSELF, not just the name policy ----
 # The allowlist is a filter over NAMES. These three cover the ways a sandboxed
 # chunk reached past it while every "blocked builtin" check above still passed.
@@ -88,7 +101,7 @@ r_fn is sandbox_run of [[ABI, [GET_NAME,0,0, RETURN], ["len"]], 1000]
 fn_msg is r_fn["error"]["message"]
 fn_named is (r_fn["ok"] == 0) and ((index_of of [fn_msg, "contains a callable"]) >= 0)
 
-if escape_blocked and screen_blk and exit_blk and seed_blk and close_blk and rbb_blk and allow_ok and no_writethrough and no_fn_escape and no_import and big_unscannable and fn_named:
+if escape_blocked and screen_blk and exit_blk and seed_blk and close_blk and rbb_blk and allow_ok and allow_973 and no_writethrough and no_fn_escape and no_import and big_unscannable and fn_named:
     print of "SANDBOX_ALLOW_OK"
 else:
     print of "SANDBOX_ALLOW_FAIL"
@@ -102,6 +115,8 @@ else:
     print of rbb_blk
     print of "allow_ok="
     print of allow_ok
+    print of "allow_973 (matmul_at/matmul_bt/scatter_add reachable)="
+    print of allow_973
     print of "no_writethrough/no_fn_escape/no_import="
     print of no_writethrough
     print of no_fn_escape
diff --git a/tests/test_tensor_buffer_inputs.eigs b/tests/test_tensor_buffer_inputs.eigs
index 9a617680..d3cba94d 100644
--- a/tests/test_tensor_buffer_inputs.eigs
+++ b/tests/test_tensor_buffer_inputs.eigs
@@ -117,6 +117,29 @@ pair of ["gather 2-D buffer indices", (gather of [l2, [2, 0]]),
          (gather of [b2, (buf_from_list of [2, 0])]), 1]
 # 1-D tensor + scalar index -> the element
 assert_eq of [(gather of [ba, 2]), (gather of [la, 2]), "gather 1-D scalar index"]
+# Out-of-range: this fixture's original claim was that the buffer path FOLDS to
+# 0.0 "to mirror the list branches". It was never asserted, and #973 arrived
+# raising `index_range` on the same input. Settled at integration on the raise,
+# for BOTH containers — the container must not change the answer (this file's
+# whole thesis), and there is no element at that index, so a 0 there is a
+# stand-in for a rejected input. Asserted now, as a pair, in both directions.
+define gather_kind(fn) as:
+    local got is "no-raise"
+    try:
+        fn of null
+    catch e:
+        got is e["kind"]
+    return got
+assert_eq of [(gather_kind of ((n) => gather of [l2, [2, 9]])),
+              (gather_kind of ((n) => gather of [b2, [2, 9]])),
+              "gather out-of-range: list and buffer agree"]
+assert_eq of [(gather_kind of ((n) => gather of [b2, [2, 9]])), "index_range",
+              "gather out-of-range raises index_range (it does not fold to 0.0)"]
+assert_eq of [(gather_kind of ((n) => gather of [la, 99])),
+              (gather_kind of ((n) => gather of [ba, 99])),
+              "gather 1-D scalar out-of-range: list and buffer agree"]
+assert_eq of [(gather_kind of ((n) => gather of [ba, 99])), "index_range",
+              "gather 1-D scalar out-of-range raises index_range"]
 
 # ============ reshape (buffer-native) ============
 rs is reshape of [ba, 2, 2]
diff --git a/tests/test_tensor_buffer_ops.eigs b/tests/test_tensor_buffer_ops.eigs
new file mode 100644
index 00000000..5b6109ea
--- /dev/null
+++ b/tests/test_tensor_buffer_ops.eigs
@@ -0,0 +1,241 @@
+# Flat-buffer tensor surface added for the autograd tape (#973):
+#   matmul_at / matmul_bt   — transposed-operand matmuls, BYTE-IDENTICAL to
+#                             `matmul` of the explicitly transposed list operand
+#   scatter_add             — gather's dual, vs the hand-written list loop
+#   gather on buffers       — vs the list path
+#   subtract/multiply/divide on buffers, scalar + bias broadcast — vs the list
+#                             path (same num_guard elementwise kernels)
+#   softmax/log_softmax/leaky_relu/mean on buffers — vs the list path
+#   numerical_grad on a buffer parameter — vs the list parameter
+# plus the loud failure modes (shape/type/index errors raise, never fold to 0).
+# Marker: "All tests passed." (lib/test.eigs).
+
+load_file of "lib/test.eigs"
+load_file of "lib/linalg.eigs"
+
+seed_random of 4242
+
+define rnd_list(r, c) as:
+    local m is []
+    for i in range of r:
+        local row is []
+        for j in range of c:
+            append of [row, (random of null) * 2.0 - 1.0]
+        append of [m, row]
+    return m
+
+define to_buf(m) as:
+    local r is len of m
+    local c is len of m[0]
+    local b is buffer of [r, c]
+    for i in range of r:
+        for j in range of c:
+            b[i * c + j] is m[i][j]
+    return b
+
+define vec_buf(v) as:
+    local b is buffer of (len of v)
+    for i in range of (len of v):
+        b[i] is v[i]
+    return b
+
+# same_2d of [tag, list2d, buf]: every element `==` (exact), plus shape.
+define same_2d(tag, m, b) as:
+    local r is len of m
+    local c is len of m[0]
+    assert_eq of [shape of b, [r, c], tag + ": shape"]
+    local mism is 0
+    for i in range of r:
+        for j in range of c:
+            if m[i][j] != b[i * c + j]:
+                mism is mism + 1
+    assert_eq of [mism, 0, tag + ": byte-identical to the list formulation"]
+    return null
+
+define same_1d(tag, v, b) as:
+    assert_eq of [len of b, len of v, tag + ": length"]
+    local mism is 0
+    for i in range of (len of v):
+        if v[i] != b[i]:
+            mism is mism + 1
+    assert_eq of [mism, 0, tag + ": byte-identical to the list formulation"]
+    return null
+
+define raises(tag, fn, kind) as:
+    local got is "no-raise"
+    try:
+        fn of null
+    catch e:
+        got is e["kind"]
+    assert_eq of [got, kind, tag + ": raises " + kind]
+    return null
+
+print of "=== matmul_at / matmul_bt vs matmul of the transposed operand ==="
+# Sizes cross the 32-wide kernel tile so the tiled accumulation order is
+# exercised in every dimension (m=35 rows shared, k=33, n=34).
+A is rnd_list of [35, 33]
+B is rnd_list of [35, 34]
+C is rnd_list of [34, 33]
+at_ref is matmul of [(mat_transpose of A), B]
+same_2d of ["matmul_at buffers (35x33)ᵀ·(35x34)", at_ref, matmul_at of [(to_buf of A), (to_buf of B)]]
+at_list is matmul_at of [A, B]
+assert_eq of [at_list, at_ref, "matmul_at on nested lists equals matmul of the transpose"]
+bt_ref is matmul of [A, (mat_transpose of C)]
+same_2d of ["matmul_bt buffers (35x33)·(34x33)ᵀ", bt_ref, matmul_bt of [(to_buf of A), (to_buf of C)]]
+bt_list is matmul_bt of [A, C]
+assert_eq of [bt_list, bt_ref, "matmul_bt on nested lists equals matmul of the transpose"]
+# A 1-D left operand is a row vector (as for matmul): result is 1-D.
+x is rnd_list of [1, 33]
+xb is vec_buf of x[0]
+bt_vec is matmul_bt of [xb, (to_buf of C)]
+assert_eq of [shape of bt_vec, [34], "matmul_bt of a 1-D left operand is 1-D"]
+same_1d of ["matmul_bt 1-D left operand", (matmul of [x[0], (mat_transpose of C)]), bt_vec]
+# matmul_at of two 1-D operands is the outer product (k x n), the dW of a
+# single-observation linear layer.
+y is rnd_list of [1, 5]
+at_outer is matmul_at of [xb, (vec_buf of y[0])]
+assert_eq of [shape of at_outer, [33, 5], "matmul_at of two 1-D operands is the (k x n) outer product"]
+same_2d of ["matmul_at outer product", (matmul of [(mat_transpose of x), y]), at_outer]
+# Loud failures, the #512 discipline shared with matmul.
+raises of ["matmul_at shape mismatch", (nul) => matmul_at of [(buffer of [3, 2]), (buffer of [4, 2])], "value"]
+raises of ["matmul_bt shape mismatch", (nul) => matmul_bt of [(buffer of [3, 2]), (buffer of [4, 3])], "value"]
+raises of ["matmul_at non-matrix", (nul) => matmul_at of ["a", (buffer of [4, 3])], "type_mismatch"]
+raises of ["matmul_bt non-matrix", (nul) => matmul_bt of [(buffer of [4, 3]), 7], "type_mismatch"]
+
+print of "=== scatter_add vs the list loop; gather on buffers ==="
+Q is rnd_list of [7, 4]
+idx is [3, 0, 2, 2, 1, 3, 0]
+vals is rnd_list of [1, 7]
+# per-row form: dst[i][idx[i]] += vals[i]
+ref is []
+for i in range of 7:
+    row is [0.0, 0.0, 0.0, 0.0]
+    row[idx[i]] is row[idx[i]] + vals[0][i]
+    append of [ref, row]
+dst is buffer of [7, 4]
+ret is scatter_add of [dst, idx, (vec_buf of vals[0])]
+same_2d of ["scatter_add per-row", ref, dst]
+assert_true of [ret == dst, "scatter_add returns dst (in place)"]
+# repeated indices accumulate; values may be a list or a broadcast number
+dst2 is buffer of [2, 3]
+scatter_add of [dst2, [1, 1], [2.0, 3.0]]
+scatter_add of [dst2, [1, 1], 0.5]
+assert_eq of [dst2[1], 2.5, "scatter_add accumulates (2.0 + 0.5) at row 0"]
+assert_eq of [dst2[4], 3.5, "scatter_add accumulates (3.0 + 0.5) at row 1"]
+# flat form on a 1-D dst: dst[idx[j]] += vals[j], repeats accumulate
+flat is buffer of 5
+scatter_add of [flat, [4, 0, 4, 2], [1.0, 2.0, 3.0, 4.0]]
+same_1d of ["scatter_add flat", [2.0, 0.0, 4.0, 0.0, 4.0], flat]
+# gather on a buffer equals gather on the list, and is scatter_add's dual
+g_list is gather of [Q, idx]
+g_buf is gather of [(to_buf of Q), idx]
+same_1d of ["gather buffer vs list", g_list, g_buf]
+g_bufidx is gather of [(to_buf of Q), (vec_buf of idx)]
+same_1d of ["gather with buffer indices", g_list, g_bufidx]
+# duality: scatter_add(zeros, idx, gather(Q, idx)) puts each pick back in place
+back is buffer of [7, 4]
+scatter_add of [back, idx, g_buf]
+dual_ok is 1
+for i in range of 7:
+    for j in range of 4:
+        want is 0.0
+        if j == idx[i]:
+            want is Q[i][j]
+        if back[i * 4 + j] != want:
+            dual_ok is 0
+assert_true of [dual_ok, "scatter_add(zeros, idx, gather(Q, idx)) restores exactly the picked entries"]
+# loud failures — and a raise leaves dst UNTOUCHED (validated before written)
+guard is buffer of [3, 4]
+raises of ["scatter_add column out of range", (nul) => scatter_add of [guard, [1, 4, 1], [1.0, 2.0, 3.0]], "index_range"]
+assert_eq of [sum of guard, 0.0, "scatter_add: a raise leaves dst untouched (no partial row 0 write)"]
+raises of ["scatter_add flat out of range", (nul) => scatter_add of [(buffer of 3), [3], 1.0], "index_range"]
+raises of ["scatter_add non-buffer dst", (nul) => scatter_add of [[0.0, 0.0], [0], 1.0], "type_mismatch"]
+# length mismatches are LOUD, not truncated — a dropped gradient entry is a
+# silent wrong number, the same reason an out-of-range index raises
+raises of ["scatter_add values shorter than indices", (nul) => scatter_add of [(buffer of 8), [0, 1, 2], [5.0]], "value"]
+raises of ["scatter_add per-row index count != rows", (nul) => scatter_add of [(buffer of [3, 4]), [0, 1, 2, 0], [1.0, 2.0, 3.0, 4.0]], "value"]
+raises of ["scatter_add string index", (nul) => scatter_add of [(buffer of 3), ["x"], 1.0], "type_mismatch"]
+# gather's out-of-range raise is the SETTLED semantics of the builtin, not of
+# its buffer path: #1093 folded to 0.0 here to mirror the list path, #973
+# raised; the answer must not depend on the container, so the list path moved
+# to the raise too (there is no element at that index, and `scatter_add` — the
+# same index, the backward direction — already raised). Pinned as a pair.
+raises of ["gather buffer column out of range", (nul) => gather of [(buffer of [2, 3]), [0, 3]], "index_range"]
+raises of ["gather LIST column out of range (same rule, other container)", (nul) => gather of [[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]], [0, 3]], "index_range"]
+raises of ["gather buffer 1-D scalar index out of range", (nul) => gather of [(buffer of 3), 7], "index_range"]
+raises of ["gather LIST 1-D scalar index out of range", (nul) => gather of [[1.0, 2.0, 3.0], 7], "index_range"]
+raises of ["gather negative index", (nul) => gather of [[[1.0, 2.0]], [-1]], "index_range"]
+raises of ["gather non-numeric index", (nul) => gather of [[[1.0, 2.0]], ["x"]], "type_mismatch"]
+# in-range gather is untouched, in both containers
+assert_eq of [gather of [[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]], [2, 0]], [3.0, 4.0], "gather list in range unchanged"]
+
+print of "=== elementwise buffer paths vs the list path ==="
+M is rnd_list of [6, 5]
+N is rnd_list of [6, 5]
+v is rnd_list of [1, 5]
+Mb is to_buf of M
+Nb is to_buf of N
+vb is vec_buf of v[0]
+same_2d of ["subtract buf-buf", (subtract of [M, N]), subtract of [Mb, Nb]]
+same_2d of ["multiply buf-buf", (multiply of [M, N]), multiply of [Mb, Nb]]
+same_2d of ["divide buf-buf", (divide of [M, N]), divide of [Mb, Nb]]
+same_2d of ["add bias broadcast [6x5]+[5]", (add of [M, v[0]]), add of [Mb, vb]]
+same_2d of ["subtract bias broadcast [6x5]-[5]", (subtract of [M, v[0]]), subtract of [Mb, vb]]
+same_2d of ["subtract bias broadcast [5]-[6x5]", (subtract of [v[0], M]), subtract of [vb, Mb]]
+same_2d of ["multiply bias broadcast", (multiply of [M, v[0]]), multiply of [Mb, vb]]
+same_2d of ["multiply buf-scalar", (multiply of [M, 2.5]), multiply of [Mb, 2.5]]
+same_2d of ["add scalar-buf", (add of [0.25, M]), add of [0.25, Mb]]
+same_2d of ["divide scalar-buf", (divide of [1.0, M]), divide of [1.0, Mb]]
+# divide by a zero element folds to 0 on both paths (the documented rule)
+z is buffer of 2
+z[0] is 3.0
+same_1d of ["divide by zero element folds to 0", (divide of [[1.0, 1.0], [3.0, 0.0]]), divide of [(vec_buf of [1.0, 1.0]), z]]
+# Settled at integration (#973 vs #1093): the four arithmetic builtins have
+# ONE buffer path, and it is the shared `tensor_elementwise` algebra — so the
+# answers below are the LIST answers, container for container, rather than the
+# buffer-only raises #973 proposed. Both modes are pinned: default is the
+# release answer, EIGS_STRICT=1 is where the wrong-type case goes loud.
+assert_eq of [shape of (add of [(buffer of [2, 3]), (buffer of 4)]), [4],
+              "non-broadcastable buffer pair truncates to the shorter (the list rule), it does not raise"]
+assert_eq of [shape of (add of [[1.0, 2.0, 3.0], [1.0, 2.0]]), [2],
+              "the list pair it mirrors truncates the same way"]
+assert_eq of [multiply of [(buffer of 3), "x"], 0.0,
+              "buffer op string answers 0 by default, exactly as list op string does"]
+assert_eq of [multiply of [[1.0, 2.0, 3.0], "x"], 0.0,
+              "list op string answers 0 by default (the answer the buffer path now shares)"]
+
+print of "=== softmax / log_softmax / leaky_relu / mean on buffers ==="
+S is rnd_list of [3, 40]
+Sb is to_buf of S
+same_2d of ["softmax buffer (40-wide rows)", (softmax of S), softmax of Sb]
+same_2d of ["log_softmax buffer", (log_softmax of S), log_softmax of Sb]
+same_2d of ["leaky_relu buffer", (leaky_relu of S), leaky_relu of Sb]
+assert_eq of [mean of Sb, mean of S, "mean of a buffer equals mean of the list"]
+assert_eq of [mean of (buffer of 0), 0.0, "mean of an empty buffer is 0 (no 0/0)"]
+# #973 found while writing this differential: `log_softmax` of a 2-D LIST used
+# to answer for row 0 only (a 1-D result), because its `[tensor, dim]` form was
+# detected by "first element is a list" — true of every 2-D tensor. Pinned:
+# the 2-D list keeps its rank and matches softmax row-for-row; the explicit
+# [tensor, dim] form still works.
+ls2 is log_softmax of [[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]]
+assert_eq of [shape of ls2, [3, 2], "log_softmax of a 2-D list is 2-D (was row 0 only)"]
+assert_eq of [ls2[2][1], (log_softmax of [5.0, 6.0])[1], "log_softmax of a 2-D list: row 2 is its own row's log-softmax"]
+assert_eq of [shape of (log_softmax of [[[1.0, 2.0], [3.0, 4.0]], 1]), [2, 2], "log_softmax [tensor, dim] form still accepted"]
+s1 is vec_buf of [1.0, 2.0, 3.0]
+same_1d of ["softmax of a 1-D buffer is one row", (softmax of [1.0, 2.0, 3.0]), softmax of s1]
+assert_eq of [shape of (softmax of s1), [3], "softmax of a 1-D buffer stays 1-D"]
+
+print of "=== numerical_grad on a buffer parameter ==="
+wl is [[1.0, -2.0], [0.5, 3.0]]
+wb is to_buf of wl
+define loss_list() as:
+    return sum of (multiply of [wl, wl])
+define loss_buf() as:
+    return sum of (multiply of [wb, wb])
+gl is numerical_grad of [loss_list, wl, 0.00001]
+gb is numerical_grad of [loss_buf, wb, 0.00001]
+assert_eq of [shape of gb, [2, 2], "numerical_grad of a shaped buffer keeps the shape"]
+same_2d of ["numerical_grad buffer vs list parameter", gl, gb]
+assert_eq of [wb[1], -2.0, "numerical_grad restores the perturbed buffer element"]
+
+test_summary of null

From 51e74b1f22787f3b45d591d8939cfeabfbac3ef8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 19:36:46 +0000
Subject: [PATCH 20/39] =?UTF-8?q?strict:=20finish=20the=20fail-soft->loud?=
 =?UTF-8?q?=20ladder=20=E2=80=94=20JSON=20parse=20failure,=20the=20NaN=20s?=
 =?UTF-8?q?ources,=20the=20-1/falsy=20families;=20record=20the=20deferrals?=
 =?UTF-8?q?=20(#971)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Under EIGS_STRICT=1 three more classes of stand-in now raise a catchable
error; with the flag off every one is byte-identical to v0.43.0, proven
by tools/strict_differential.sh against a build of the parent commit:

  identical-when-off: 98   differing: 0   waived: 0
  raises-under-strict: 98  silent: 0      misattributed: 0
  answer-pins held: 30     valid-input rows unchanged in BOTH modes: 122/122

Phase C — json_path (the 13 JSON-parser sites). A document that failed to
parse was walked leniently and answered the same "" an absent key does,
so malformed JSON was indistinguishable from a missing field:

  $ EIGS_STRICT=1 eigenscript -e 'print of (json_path of ["{\"a\": 1e", "a"])'
  before: 0                      (rc 0 — the partial parse's placeholder)
  after:  Error line 1: json_path: invalid JSON at position 8   (rc 1, kind value)

Strict applies json_decode's own acceptance test (structural error, a
repaired \u scalar, trailing garbage); JSON false/null/absent keys are
answers and stay quiet in both modes. The three parse_number fs:CHANNEL
sites and the `false` fs:LITERAL are untouched; the `!root` fs:TODO is
now fs:STRICT. ext_http's shared store / header parsing and the store's
catalog read the flag channel directly and never pass through json_path,
so they are unaffected in either mode (grep'd).

NaN collapse — enumerated on the tree rather than assumed. The operators
cannot reach NaN from finite operands (0/0 and x%0 raise first; no operand
can hold an inf; sum/mean/norm/dot/buf_* accumulate through num_guard per
step), so the reachable sources are builtins: pow(negative, fractional),
num of "nan", f64_from_bytes of a NaN pattern, matmul reaching inf-inf,
tensor_load of NaN bytes, and the elementwise divide by zero (pre-collapsed
to 0 where `/` raises). Each collapses to 0 + math_flags.invalid exactly as
before and raises under strict naming the builtin (num_guard_named); the
NaN branch of num_guard itself is the backstop ("arithmetic: ...") for any
source the list misses. The JIT bails to the interpreter on a non-finite
result, so both tiers raise from the same guard (probes run with
EIGS_JIT_OFF=1 as well; tools/jit_diff.sh green).

NO default-path change, and that is the second draft. matmul's BUFFER
path stores the kernel's raw inf-inf NaN, and a raw NaN in a buffer is a
NaN-boxed slot tag, so `r[0]` reads back as `null` (0xFFF8... is
SLOT_NULL_BITS) with math_flags.invalid still 0:

  $ eigenscript mm.eigs          # 1e200*1e200 + 1e200*(-1e200), buffers
  v0.43.0:  null / {"invalid": 0}
  draft 1:  0    / {"invalid": 1}      <- collapsed like the list path
  now:      null / {"invalid": 0}      <- byte-identical again

Collapsing it looked free and cost the one claim this reform makes. It
made the probe diverge from the baseline, which had to be carried as
EXPECTED_DIVERGE_FIXED="matmul" in tools/strict_differential.sh — a
waiver inside the instrument that proves "with the flag off, nothing
changed", for a fix nobody asked #971 for. The strict half now raises
through STRICT_DOMAIN, which is a no-op when the flag is off, so the soft
path cannot drift; the waiver is deleted and both waiver lists are empty.
The `null` read is a real defect and is recorded in ROADMAP.md as its own
change (it must decide the buffer contract for inf and NaN together and
mirror it in ouroboros aot_rt.h, whose round-187 fixture pins the raw inf
read), with SM49a/SM49b pinning today's two answers so neither moves by
accident.

Phase D — the -1 and falsy families (#1008) were already loud on the
parent (index_of/ord/list_index_of, file_exists/is_dir/read_text/...);
this pins their documented sentinels for a valid-but-absent input in
both modes (index_of miss -1, file_exists of a missing path 0, ...) and
converts the wrong-type launderers `--sweep` still listed: split, the
three scan_* builtins, tokenize_ids/tokenize_with_names, token_name,
channel_closed, f64_to_bytes, buffer, json_build, sort, random_int,
random_hex (the taped ones via ARG_GUARD_TAPED). Sweep QUIET rows 89 -> 75;
the remainder are argument-ignoring builtins, dict-valid ones, and the
`return make_null()` population the classifier header keeps out of scope.

[99s] under load. The section ran the differential, threw the failing
run's output away and re-ran the tool for a diagnostic, so a
non-deterministic red printed someone else's green report: a full-suite
log from 2026-09-06 has "FAIL: a guard went silent..." followed by a
clean report ending in "OK". It now captures ONE run and prints that
run's own output. The tool grew the two things that can make a loaded box
produce a finding about code that is fine: a probe whose process died on
a signal or could not be exec'd is its own DID NOT RUN bucket naming the
exit status (it was scored "raised by the wrong guard"), and the EXIT
trap prints ABORTED when the script exits before its verdict line
instead of exiting nonzero in silence. Nothing is retried and a crash
stays red. 180 standalone runs (idle, alongside a full suite, and under
added fork pressure) did not reproduce the red, so the cause is not
named here — the next occurrence names itself.

Regression tests: tests/test_strict_math.sh SM36-SM84 (85 rows; SM49 is
now SM49a/SM49b — strict on: raises
naming the builtin and the position; strict off: byte-identical; the
answers pinned in both modes; catchability as kind `value`; the JIT-off
arm), plus a probe/pin/valid row per site in tools/strict_differential.sh,
whose cross-check derives guarded names from STRICT_REQUIRE,
STRICT_DOMAIN and num_guard_named as well as ARG_GUARD (a new site of any
spelling without a probe goes red in [99s]). Planted faults: dropping the
matmul STRICT_DOMAIN turns SM55 red and [99s] SILENT; restoring the
draft-1 collapse turns SM49b red and the two-binary differential
"differing: 1"; dropping the json_path strict block, op_pow's
num_guard_named or split's STRICT_REQUIRE turns SM38/SM50/SM69 red. The
gate hardening is proven the same way: a killed run prints ABORTED, and a
probe binary that exits 139 reports "abs — killed by signal 11 — a crash,
not a guard" instead of "misattributed".

Docs: SPEC.md strict section lists the three classes and the matmul
buffer asymmetry; BUILTINS.md rows for every touched builtin;
LANGUAGE_CONTRACT.md numbers; llms.txt; the write-eigenscript skill.
ROADMAP.md records three deferrals as decisions: value-level invalidity
taint (positional attribution executed and refuted; the bit must travel
with the value and on the tape), the raw non-finite in a matmul buffer
result, and flipping strict to default (94 consumer entry points: 0
change status under strict; the runtime's own suite pins the soft
answers; the AOT mirror must flip first).

Residuals: ouroboros aot_rt.h carries its own inlined num_guard
(aot_num_guard_inl) and aot_tensor_matmul (raw kernel, deliberately
byte-identical to ne_matmul_buf) — the strict NaN raise needs mirroring
there; every other flipped arm is a runtime builtin the AOT links. No
waiver is in force in tools/strict_differential.sh.

Closes #971

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
(cherry picked from commit 95779d9ee1fdbd50816286101ae2d669950bc00c)
---
 .claude/skills/write-eigenscript/SKILL.md |   2 +-
 ROADMAP.md                                |  90 ++++++++
 docs/BUILTINS.md                          |  36 ++--
 docs/LANGUAGE_CONTRACT.md                 |  17 +-
 docs/SPEC.md                              |  34 ++-
 docs/llms.txt                             |   4 +-
 src/builtins.c                            |  97 +++++++--
 src/builtins_host.c                       |   3 +
 src/builtins_tensor.c                     |  55 ++++-
 src/eigenscript.c                         |  12 ++
 src/eigenscript.h                         |  41 +++-
 tests/run_all_tests.sh                    |  17 +-
 tests/test_strict_math.sh                 | 142 ++++++++++++-
 tools/strict_differential.sh              | 239 +++++++++++++++++++---
 14 files changed, 705 insertions(+), 84 deletions(-)

diff --git a/.claude/skills/write-eigenscript/SKILL.md b/.claude/skills/write-eigenscript/SKILL.md
index cc1691ae..fde5c852 100644
--- a/.claude/skills/write-eigenscript/SKILL.md
+++ b/.claude/skills/write-eigenscript/SKILL.md
@@ -45,7 +45,7 @@ The error-prone parts of the language. Most are not surfaced when working in a c
 
 ## Values
 - `+` concatenates **strings only** — list concat is `append of [xs, v]` (in place) or a comprehension; `xs + ys` is a runtime error.
-- Numbers are finite by construction: NaN collapses to `0`, overflow saturates at ±1e308 (`sqrt of -1` is `0`, not an error).
+- Numbers are finite by construction: NaN collapses to `0`, overflow saturates at ±1e308 (`sqrt of -1` is `0`, not an error). Under `EIGS_STRICT=1` the domain clamps, a NaN result, wrong-typed builtin arguments and a malformed `json_path` document raise catchable errors instead — run graders/tests with it on.
 - **Hex integer literals** (`0xFF`, `0X10`; digits only, ends at the first non-hex char) are a real lexed form since #378 (post-v0.24.0); hex-FLOAT forms (`0x1p4`, `0xA.8`) are loud parse errors. **On a v0.24.0-or-earlier pin hex is a strtod accident**: it works HOSTED (including hex floats) but the freestanding profile lexes `0xFF` as `0` + identifier `xFF` — don't use hex in code that must run freestanding on an old pin. No modulo keyword — the operator is `%` (`mod` is a parse error).
 
 ## Strings
diff --git a/ROADMAP.md b/ROADMAP.md
index 796409ec..31b5b20e 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -150,6 +150,96 @@ observer/deterministic-replay niche instead of diluting it.**
       "num IS f64" so a future wider kind stays possible
       ([#417](https://github.com/InauguralSystems/EigenScript/issues/417))
 
+- [ ] **Value-level invalidity taint for the observer** — **DEFERRED, by
+      evidence, not omission.** #971 item 1 proposed threading
+      `math_flags & INVALID` into the `ObserverSlot` so a binding produced by
+      an invalid op refuses the rest bands the way saturation does. It was
+      built (a consumed per-state `math_invalid_pending` edge, a
+      `v_invalid` slot bit OR'd into the five band functions) and
+      **reverted**: attribution is positional — "the next binding observed
+      after an invalid op" — and holds only when the invalid op is lexically
+      the last thing evaluated before the observed assignment. Executed:
+      `a is sqrt of (0 - 1.0)` reads `diverging`, but `local t is sqrt of
+      (0 - 1.0)` / `a is t` and a `safe_sqrt` wrapper both certify
+      **`converged`** on the fabricated 0 (false negatives), and the mirror
+      false positive — a discarded invalid op tainting an honestly converged
+      neighbour — is equally reachable. Saturation needs no state because it
+      is derivable from `last_value` alone; a clamped NaN lands mid-band and
+      is not. So the bit must **travel with the value**: a taint on `Value`
+      propagated through copies, returns and the NaN-boxed `EigsSlot`
+      immediates, **and carried on the tape** — `tape_read.c`/`step.c`/
+      `eigsdap.c` rebuild slots from recorded values, so the live runtime
+      reported `diverging` where `--step` reported `[converged]` on the same
+      program (a missing key in an old dump must not read as "valid"). That
+      is a design pass of its own, not a sub-bullet. What shipped instead:
+      under `EIGS_STRICT=1` every reachable NaN source raises (item 3 of the
+      strict ladder), so a grader that needs invalidity loud has it without
+      the taint.
+      ([#971](https://github.com/InauguralSystems/EigenScript/issues/971))
+- [ ] **A `matmul` BUFFER result is stored raw — `inf` reads back above
+      `1e308`, and a `NaN` reads back as `null`.** The boxed roads go
+      through `make_num`, whose `num_guard` saturates an
+      infinity and collapses a `NaN` to `0` + `math_flags.invalid`. The
+      buffer fast path writes the kernel's accumulator straight into the
+      result buffer instead, so both survive: `r[0] > 1e308` is `1`, and a
+      `NaN` element is not a number the program can even see — its bit
+      pattern IS the boxed-slot tag for null (0xFFF8… == `SLOT_NULL_BITS`),
+      so `r[0]` reads `null` out of a buffer of numbers, and
+      `math_flags.invalid` stays `0`.
+      **#971 built the NaN half of the fix and then reverted it, on
+      purpose.** Collapsing NaN there is two lines and passed every test,
+      but it changes the DEFAULT path (`null` -> `0`, `invalid` 0 -> 1), and
+      the one claim the strict reform makes is that with the flag off
+      nothing changed — proven by `tools/strict_differential.sh` against the
+      previous release binary. Shipping it meant carrying a waived
+      divergence in that tool, i.e. the proof with a hole in it, for an
+      incidental fix that was never what #971 was about. So strict raises on
+      both paths (`STRICT_DOMAIN`, which cannot touch the soft path) and the
+      default answer is byte-identical to v0.43.0; `tests/test_strict_math.sh`
+      SM49a/SM49b pin both halves so neither moves by accident.
+      **The writer is not the place to fix it.** `matmul` is not the only
+      road to a `NaN` buffer element: `ext_store` round-trips one on
+      purpose (`store_nonfinite_sentinel` encodes `"nan"`/`"inf"`/`"-inf"`
+      because JSON has no literal for them), and the embed API's
+      `eigs_value_buffer_set` takes a raw `double` from the host. Whatever
+      is decided has to be decided at the READ, where every road meets.
+      Doing it properly is its own change: decide the buffer contract for
+      BOTH non-finites together (saturate the `inf` too, or keep both raw and
+      make the buffer read report a NaN as a number rather than as `null`),
+      mirror it in the AOT — ouroboros `aot_rt.h`'s `aot_tensor_matmul`
+      reads the same raw buffer and its round-187 fixture PINS the `inf`
+      read — and run the differential over both.
+      ([#971](https://github.com/InauguralSystems/EigenScript/issues/971))
+- [ ] **Flip `EIGS_STRICT` to the default?** — **DEFERRED; the evidence
+      says it is now cheap, the decision is still open.** Measured
+      2026-09-06 on the v0.43.0 tree with the #971 Phase C/D + NaN work
+      applied: **94 consumer entry points** (DMG `test_cpu`/`test_memory` +
+      the 500K-cycle canary, EigenMiniSat DPLL/CDCL solves, EigenRegex S1–S12
+      + smoke, EigenGauntlet's 11 labs at size 1, Tidepool, dynamics,
+      liferaft, tidelog, phugoid, polymethod, DeslanStudio's 24 headless
+      tests, iLambdaAi, eddy) run twice on the same binary, flag off and
+      `EIGS_STRICT=1`: **0 of 94 change exit status under strict**; the six
+      that fail do so identically in both modes for load-path reasons
+      unrelated to the flag. (Re-spot-checked 2026-09-07 on the final
+      binary — DMG `test_cpu`, EigenMiniSat `test_solver`, EigenGauntlet
+      `tensor`/`io`, Tidepool `test_game`, dynamics `solve`, liferaft
+      `test_prng`, EigenRegex `test_smoke`: 8 of 8 unchanged.) The runtime's own suite is a different story —
+      it PINS the soft answers (`sqrt of -1` is `0`, `cos of "hello"` is
+      `0`, the `fs:ANSWER` pins) in dozens of sections, so flipping the
+      default means rewriting those pins as `EIGS_STRICT=0` rows and
+      re-deciding which stand-ins survive as documented answers (the
+      classification ledger in `tools/failsoft_classify_check.sh` is the
+      input). Two things must land first: the AOT mirror (ouroboros
+      `aot_rt.h` carries its own inlined `num_guard`, `op_div`-shaped
+      `aot_ddiv` and a raw-`inf` matmul read pinned by its round-187
+      fixture — a default flip without the mirror flipping recreates the
+      #975 div0 fossil), and a decision on the **raw non-finite in a
+      `matmul` buffer result** (the entry below). Until then:
+      strict stays opt-in, graders and CI lanes turn it on, and the
+      differential (`tools/strict_differential.sh <parent-build>`) keeps
+      the default path byte-identical.
+      ([#971](https://github.com/InauguralSystems/EigenScript/issues/971))
+
 ### AOT (ouroboros — the native-perf path; not the JIT)
 
 - [x] Close the F-OURO-23 envelope via `lib/checksum.eigs` (CRC-32) as
diff --git a/docs/BUILTINS.md b/docs/BUILTINS.md
index 63dcbeee..c8e66a6d 100644
--- a/docs/BUILTINS.md
+++ b/docs/BUILTINS.md
@@ -49,7 +49,7 @@ audio (`audio_open`, `audio_close`, `audio_pause`, `audio_play`,
 | `print` | `print of value` | Output value to stdout with newline |
 | `len` | `len of value` | Length of string or list count |
 | `str` | `str of value` | Convert to string representation |
-| `num` | `num of value` | Convert to number (parse string or coerce) |
+| `num` | `num of value` | Convert to number (parse string or coerce). `num of "nan"` is `0` (sets `math_flags.invalid`) and `num of "inf"` saturates to `1e308`; under `EIGS_STRICT=1` the `NaN` case raises a `value` error naming `num` (#971). |
 | `type` | `type of value` | Return type name: "num", "str", "list", "dict", "buffer", "text_builder", "fn", "builtin", "none" (the null value — SPEC.md is normative and its gated example prints `none`; the string `"null"` is never produced) |
 | `math_flags` | `math_flags of null` | Sticky numeric status: `{overflow, invalid}` — 1 when a clamp has fired since the last `clear_math_flags` (#865) |
 | `clear_math_flags` | `clear_math_flags of null` | Reset both status bits |
@@ -77,7 +77,7 @@ numeric fast paths used by reassignment and `unobserved` blocks.
 | `list_slice` | `list_slice of [list, start, end]` | New list with the elements of [start, end) — dual of `copy_into`. Negative indices count from the end, like `[]`; bounds then clamp to [0, len]. `start >= end` gives `[]`. Never raises on bounds |
 | `num_copy` | `num_copy of value` | Create independent copy of numeric value |
 | `hex` | `hex of n` or `hex of [n, nibbles]` | Uppercase hex string of a non-negative integer, zero-padded to `nibbles` (never truncated). Raises on negatives, fractions, non-numbers |
-| `sort` | `sort of list` | Sort an all-number or all-string list in-place (numeric / lexicographic). Mixed or non-scalar elements raise — use `sort_by` for records. Returns the list |
+| `sort` | `sort of list` | Sort an all-number or all-string list in-place (numeric / lexicographic). Mixed or non-scalar elements raise — use `sort_by` for records. Returns the list. A non-list argument is handed back unchanged; under `EIGS_STRICT=1` it raises (#971). |
 | `list_truncate` | `list_truncate of [list, new_len]` | Shrink list in-place to new_len items. No-op if new_len >= length. Returns the list |
 | `list_remove_at` | `list_remove_at of [list, index]` | Remove element at index, shift tail down (mutates). No-op if out of bounds. Returns the list |
 | `list_insert_at` | `list_insert_at of [list, index, value]` | Insert value at index, shift tail up (mutates) — dual of `list_remove_at`. `index == len` appends; any other out-of-bounds index is a no-op. Returns the list |
@@ -98,8 +98,8 @@ numeric fast paths used by reassignment and `unobserved` blocks.
 | `ends_with` | `ends_with of [s, suffix]` | 1 if s ends with suffix, else 0 |
 | `index_of` | `index_of of [haystack, needle]` | First index of needle in haystack, or -1 (non-string operands are -1) |
 | `substr` | `substr of [s, start, length]` | Extract substring |
-| `split` | `split of [s, delim]` | Split string by delimiter into list |
-| `scan_ints` | `scan_ints of s` or `scan_ints of [s, comment_marker]` | C-backed scan of whitespace-delimited signed integer tokens, optionally skipping comment lines |
+| `split` | `split of [s, delim]` | Split string by delimiter into list. A non-string `s` splits as `""` (so answers `[""]`) and a non-string `delim` falls back to `" "`; under `EIGS_STRICT=1` both raise (#971). |
+| `scan_ints` | `scan_ints of s` or `scan_ints of [s, comment_marker]` | C-backed scan of whitespace-delimited signed integer tokens, optionally skipping comment lines. No string in the argument answers `[]`; under `EIGS_STRICT=1` it raises (#971, same for `scan_tokens`/`scan_int_tokens`). |
 | `scan_tokens` | `scan_tokens of s` or `scan_tokens of [s, comment_marker]` | C-backed scan of whitespace-delimited token rows `[text, line, col, start, end]` |
 | `scan_int_tokens` | `scan_int_tokens of s` or `scan_int_tokens of [s, comment_marker]` | Token rows `[text, line, col, start, end, is_int, value]` |
 | `trim` | `trim of s` | Strip leading/trailing whitespace |
@@ -156,7 +156,7 @@ Compact typed arrays of doubles with O(1) indexed access. Iterable with
 
 | Name | Signature | Description |
 |------|-----------|-------------|
-| `buffer` | `buffer of count` | Create zero-filled buffer of given size |
+| `buffer` | `buffer of count` | Create zero-filled buffer of given size (or `buffer of [rows, cols]` for a shaped one). A non-numeric size makes an empty buffer; under `EIGS_STRICT=1` it raises (#971). |
 | `buf_get` | `buf_get of [buf, index]` | Read element; out-of-range raises `index_range` (#502 — folding to 0 was indistinguishable from a real stored 0), matching the `buf[i]` operator |
 | `buf_set` | `buf_set of [buf, index, value]` | Write element |
 | `buf_len` | `buf_len of buf` | Return buffer element count |
@@ -192,8 +192,8 @@ For serialization: reconstruct strings/floats from raw bytes (the inverse of an
 | Name | Signature | Description |
 |------|-----------|-------------|
 | `str_from_bytes` | `str_from_bytes of <list\|buffer>` | Build a string from raw byte values (0–255) — the list form of `chr` (`chr of n` == `str_from_bytes of [n]` for 1–255), inverting an `ord`-over-bytes loop. Strings are NUL-terminated: a `0` byte ends the string — keep NUL-bearing binary in a buffer. |
-| `f64_to_bytes` | `f64_to_bytes of x` | List of 8 ints: the big-endian IEEE-754 encoding of double `x` (network byte order, portable across host endianness). |
-| `f64_from_bytes` | `f64_from_bytes of <list\|buffer>` | Decode a double from the first 8 big-endian IEEE-754 bytes. Inverse of `f64_to_bytes`. |
+| `f64_to_bytes` | `f64_to_bytes of x` | List of 8 ints: the big-endian IEEE-754 encoding of double `x` (network byte order, portable across host endianness). A non-number encodes as `0.0`; under `EIGS_STRICT=1` it raises (#971). |
+| `f64_from_bytes` | `f64_from_bytes of <list\|buffer>` | Decode a double from the first 8 big-endian IEEE-754 bytes. Inverse of `f64_to_bytes`. A `NaN` bit pattern collapses to `0` (sets `math_flags.invalid`); under `EIGS_STRICT=1` it raises a `value` error (#971). |
 
 Buffers also support direct indexing (`buf[i]`, `buf[i] is val`) and
 compound assignment (`buf[i] += val`).
@@ -226,9 +226,9 @@ sandbox allowlist can name them) but every call raises `value`:
 |------|-----------|-------------|
 | `json_encode` | `json_encode of value` | Serialize value to JSON string. Raises on a value nested deeper than 200 levels — which includes any **cyclic** value (`dict_set of [d, "self", d]`, `append of [a, a]`), since a cycle has no depth. Catchable. |
 | `json_decode` | `json_decode of s` | Parse JSON string to value. Raises past the same 200-level limit, so a document that decodes always re-encodes. `\uXXXX` surrogate pairs are combined into one code point; unpaired surrogates, an escaped NUL, and malformed `\u` escapes raise (strict decode — lenient callers such as `json_path` receive the complete document with U+FFFD in place of the bad scalar). |
-| `json_build` | `json_build of [k1, v1, k2, v2, ...]` | Build JSON object from key-value pairs |
+| `json_build` | `json_build of [k1, v1, k2, v2, ...]` | Build JSON object from key-value pairs. `json_build of null` is `{}`; any other non-list answers `{}` too and raises under `EIGS_STRICT=1` (#971). |
 | `json_raw` | `json_raw of s` | Wrap raw JSON string (skip encoding) |
-| `json_path` | `json_path of [json_str, "dot.path"]` | Extract nested value by dot-notation path |
+| `json_path` | `json_path of [json_str, "dot.path"]` | Extract nested value by dot-notation path; `""` when there is no value at that path (absent key, index out of range, JSON `null`). The document is parsed leniently: a malformed document is walked as far as it parsed, so a parse failure also answers `""` or a partial value. Under `EIGS_STRICT=1` a document that `json_decode` would reject (structural error, a repaired `\u` scalar, trailing garbage) raises a catchable `value` error `json_path: invalid JSON at position N` instead (#971 Phase C); JSON `false`/`null`/absent keys stay answers in both modes. |
 
 ## Dictionaries
 
@@ -342,7 +342,7 @@ Boolean keywords that check the most recently observed value:
 | `proc_close` | `proc_close of fd` | Idempotent `close(2)`. Returns 1 on success, 0 if already closed / invalid. |
 | `proc_wait` | `proc_wait of pid` | Block on `waitpid(pid, ...)` and return the exit code (or `128 + signum` if killed by a signal). Answers `-1` when the pid is not a positive number or `waitpid` reports no such child — there is no exit status to give. |
 | `env_get` | `env_get of "VAR_NAME"` | Get environment variable (empty string if unset) |
-| `random_hex` | `random_hex of n` | Generate n random hex characters from /dev/urandom |
+| `random_hex` | `random_hex of n` | Generate n random hex characters from /dev/urandom (`""` for `n <= 0` or `n > 256`). A non-number `n` answers `""`; under `EIGS_STRICT=1` it raises (#971). |
 | `try_parse` | `try_parse of code_string` | 1 if string is valid EigenScript syntax, 0 otherwise |
 | `mkdir` | `mkdir of "path"` | Create directory (and parents). 1 on success, 0 on failure. Trace-recorded: replay serves the recorded bit and does not re-create the directory (#585) |
 | `ls` | `ls of "path"` | List directory contents as list of strings. Trace-recorded, so replay is deterministic (#585) |
@@ -392,7 +392,7 @@ stdlib roots. See [Modules](SPEC.md#modules) for import collision handling.
 | Name | Signature | Description |
 |------|-----------|-------------|
 | `random` | `random of null` | Random float in [0, 1) |
-| `random_int` | `random_int of [lo, hi]` | Random integer in [lo, hi] inclusive; raises on non-finite or out-of-int64 bounds and on a span over 2^31 |
+| `random_int` | `random_int of [lo, hi]` | Random integer in [lo, hi] inclusive; raises on non-finite or out-of-int64 bounds and on a span over 2^31. A malformed argument (not `[lo, hi]`, or non-numeric bounds) answers `0`; under `EIGS_STRICT=1` it raises (#971). |
 | `seed_random` | `seed_random of n` | Seed the RNG for deterministic sequences |
 
 ## Time
@@ -479,8 +479,8 @@ heterogeneous or nested data.
 | `add` | `add of [a, b]` | Element-wise addition |
 | `subtract` | `subtract of [a, b]` | Element-wise subtraction |
 | `multiply` | `multiply of [a, b]` | Element-wise multiplication |
-| `divide` | `divide of [a, b]` | Element-wise division; zero denominator returns 0, overflow saturates |
-| `pow` | `pow of [base, exp]` | Element-wise exponentiation; overflow saturates |
+| `divide` | `divide of [a, b]` | Element-wise division; zero denominator returns 0 (where the `/` operator raises), overflow saturates. Under `EIGS_STRICT=1` a zero denominator raises `divide: division by zero` (#971). |
+| `pow` | `pow of [base, exp]` | Element-wise exponentiation; overflow saturates. A negative base with a fractional exponent is `NaN` and collapses to `0` (sets `math_flags.invalid`); under `EIGS_STRICT=1` it raises a `value` error naming `pow` (#971). |
 | `negative` | `negative of t` | Element-wise negation |
 
 All five arithmetic builtins take shaped **buffers** wherever they take a flat
@@ -516,7 +516,7 @@ either way, so the numbers are byte-identical.
 
 | Name | Signature | Description |
 |------|-----------|-------------|
-| `matmul` | `matmul of [a, b]` | Matrix multiplication. Two shaped buffers multiply on the flat data and give a buffer; a 1-D left operand gives a 1-D result. Mixed list/buffer operands give a list |
+| `matmul` | `matmul of [a, b]` | Matrix multiplication. Two shaped buffers multiply on the flat data and give a buffer; a 1-D left operand gives a 1-D result. Mixed list/buffer operands give a list. An accumulation that reaches `inf - inf` is `NaN`; under `EIGS_STRICT=1` that raises a catchable `value` error naming `matmul` (#971). With the flag off the two result kinds differ, and the difference is pre-existing: a **list/tensor** result boxes through `make_num`, so the `NaN` collapses to `0` and sets `math_flags.invalid`, while a **buffer** result is whatever the kernel wrote — the raw `NaN` stays in the buffer and reads back as `null` (a `NaN` bit pattern is a boxed slot tag), with `math_flags` untouched. An overflowed element in a buffer result is likewise stored raw (reads back above `1e308`). Both buffer holes are recorded in ROADMAP.md; #971 left them exactly as v0.43.0 had them rather than change the default path under a strict-mode flag. |
 | `matmul_at` | `matmul_at of [a, b]` | `aᵀ·b` without materialising the transpose: `a` is `(m × k)`, `b` is `(m × n)`, result `(k × n)` — the weight gradient `dW = Xᵀ·dY` of a linear layer. Buffers and nested lists; byte-identical to `matmul` of the explicitly transposed operand (same tiled kernel order). Two 1-D operands give their `(k × n)` outer product. Shape/type/size errors raise like `matmul` (#973) |
 | `matmul_bt` | `matmul_bt of [a, b]` | `a·bᵀ`: `a` is `(m × k)`, `b` is `(n × k)`, result `(m × n)` — the input gradient `dX = dY·Wᵀ`. A 1-D left operand is a row vector and yields a 1-D result, as for `matmul` (#973) |
 | `gather` | `gather of [matrix, indices, dim]` | Gather one element per row: `out[i] = matrix[i][indices[i]]`. `matrix` may be a shaped buffer and `indices` a list or a buffer; a shaped-buffer `matrix` gives a buffer. `gather of [vec, i]` on a 1-D tensor returns element `i`. An **out-of-range index raises `index_range`** — in every form, list or buffer (#973/#1093, settled at integration: there is no element there, and `scatter_add` raises on the same index). A row that is not a row (a 1-D tensor in the per-row form) still answers `0.0` for that row |
@@ -544,7 +544,7 @@ either way, so the numbers are byte-identical.
 | Name | Signature | Description |
 |------|-----------|-------------|
 | `tensor_save` | `tensor_save of [tensor, "path"]` | Save a list or buffer tensor to a binary file (preserves observer state) |
-| `tensor_load` | `tensor_load of "path"` | Load tensor from binary file (restores observer state) |
+| `tensor_load` | `tensor_load of "path"` | Load tensor from binary file (restores observer state). `NaN` bytes in the file collapse to `0` (sets `math_flags.invalid`); under `EIGS_STRICT=1` they raise a `value` error naming `tensor_load` (#971). |
 
 ### Gradients & SGD
 
@@ -571,9 +571,9 @@ either way, so the numbers are byte-identical.
 
 | Name | Signature | Description |
 |------|-----------|-------------|
-| `tokenize_ids` | `tokenize_ids of code_string` | Return list of token type IDs |
+| `tokenize_ids` | `tokenize_ids of code_string` | Return list of token type IDs. A non-string answers `[]`; under `EIGS_STRICT=1` it raises (#971, same for `tokenize_with_names`). |
 | `tokenize_with_names` | `tokenize_with_names of code_string` | Return list of `[id, name]` pairs |
-| `token_name` | `token_name of id` | Return token type name by ID |
+| `token_name` | `token_name of id` | Return token type name by ID (`"?"` for an unknown id). A non-number answers `"?"` too; under `EIGS_STRICT=1` it raises (#971). |
 
 ## Corpus Preparation
 
@@ -847,7 +847,7 @@ Requires full build. Transformer model inference and training.
 | `try_recv` | `try_recv of channel` | Non-blocking receive. Returns the value if available, `null` if the channel is empty. |
 | `recv_timeout` | `recv_timeout of [channel, ms]` | Bounded-wait receive. Returns the value if one arrives before `ms` milliseconds elapse, else `null`. A close while waiting also returns `null`. Fractional `ms` is honored (ns precision on Linux); negative `ms` degenerates to a `try_recv`. |
 | `close_channel` | `close_channel of channel` | Close the channel. Wakes all blocked senders/receivers. |
-| `channel_closed` | `channel_closed of channel` | Returns 1 if closed, 0 otherwise. |
+| `channel_closed` | `channel_closed of channel` | Returns 1 if closed, 0 otherwise. An unknown or reclaimed channel is closed (1). A value that is not a channel handle also answers 1; under `EIGS_STRICT=1` it raises (#971). |
 | `task_spawn` | `task_spawn of fn` or `task_spawn of [fn, arg1, ...]` | Create a cooperative task (#408) running `fn` on the single OS thread — deterministic by construction, unlike `spawn`'s OS thread. Args are deep-COPIED (share-nothing, like channel sends), not shared by reference. Returns a numeric task id. (Increment 1a: the task is recorded and reported by `task_alive`; the copying-stack scheduler that runs and interleaves tasks — `task_yield`/`task_join` — lands in a later increment.) |
 | `task_alive` | `task_alive of id` | Returns 1 while the task is runnable or suspended, 0 once it has finished (or for an unknown id). |
 | `task_self` | `task_self of null` | The **running task's own id** (a number, in the same integer space `task_spawn` returns; the main task is 0, including before any task has been spawned). Lets a worker hand out its own id as a reply address — the message-link pattern a mailbox otherwise cannot express (#526). Deterministic — reads scheduler state, records no nondeterminism. |
diff --git a/docs/LANGUAGE_CONTRACT.md b/docs/LANGUAGE_CONTRACT.md
index b5224741..b6fb2f59 100644
--- a/docs/LANGUAGE_CONTRACT.md
+++ b/docs/LANGUAGE_CONTRACT.md
@@ -148,13 +148,20 @@ examples (executed by the suite).
   returns `log(1e-10)`, i.e. `-23.025850929940457`), `sqrt of x` for
   negative `x` (returns 0, otherwise indistinguishable from
   `sqrt of 0`), and `asin`/`acos` outside [-1, 1] (argument clamped).
-  `invalid` is also set when a NaN is collapsed, which arithmetic
-  cannot produce (there is no way to obtain an Inf to combine) but
-  string conversion can: `num of "nan"` is `0` and `num of "inf"` is
+  `invalid` is also set when a NaN is collapsed, which the arithmetic
+  operators cannot produce (there is no way to obtain an Inf to combine)
+  but a few builtins can: `num of "nan"` is `0` and `num of "inf"` is
   `1e308`, so a data column containing either used to parse to a
-  plausible number with nothing to check. Both bits are sticky until
+  plausible number with nothing to check; `pow` of a negative base with
+  a fractional exponent, `f64_from_bytes` of a NaN bit pattern,
+  `matmul` reaching `inf - inf` (on its list result — a `matmul` whose
+  result is a *buffer* keeps the raw NaN instead, and reads back as
+  `null`; ROADMAP.md), and `tensor_load` of a file carrying
+  NaN bytes collapse the same way. Both bits are sticky until
   `clear_math_flags`, so bracket a computation the way you would on an
-  FPU.
+  FPU. Under `EIGS_STRICT=1` every one of those NaN sources raises a
+  catchable `value` error naming the builtin instead of collapsing
+  (SPEC.md, *Strict mode*).
 - **Saturation is not associative, and that is not detectable from the
   value alone.** `(1e300 * 1e300) / 1e300` is `1e8`; `1e300 * (1e300 /
   1e300)` is `1e300`. The first overflowed and came back down, and
diff --git a/docs/SPEC.md b/docs/SPEC.md
index 766599cb..e7601568 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -257,8 +257,38 @@ consequences are contracts you can rely on:
   documented answer. Every site in the surface therefore carries a written
   classification, mechanically enforced by
   `tools/failsoft_classify_check.sh`.
-  Overflow saturation and the `NaN`→`0` collapse are unchanged by the flag for
-  now. (Division and modulo by zero raise in *both* modes — no defined value.)
+  Three further classes are loud under the same flag and unchanged without it:
+  - **The `NaN`→`0` collapse.** With the flag off a `NaN` still collapses to
+    `0` and sets `math_flags.invalid`. Under strict every reachable `NaN`
+    source raises a catchable `value` error naming the builtin: `pow` of a
+    negative base with a fractional exponent, `num of "nan"`,
+    `f64_from_bytes` of a `NaN` bit pattern, `matmul` when its accumulation
+    reaches `inf - inf`, `tensor_load` of a file carrying `NaN` bytes — and
+    the elementwise `divide` by zero, which answers `0` by default where the
+    `/` operator raises. The arithmetic operators themselves cannot reach a
+    `NaN` from finite operands (`0 / 0` and `x % 0` raise first, and no
+    operand can hold an infinity), so any other source hits a backstop that
+    raises as `arithmetic`. The JIT bails to the interpreter on a non-finite
+    result, so both tiers raise from the same guard. One default-path
+    asymmetry is older than strict mode and is left alone by it: a `matmul`
+    whose result is a **buffer** keeps the raw `NaN` the kernel wrote (it
+    reads back as `null`, and `math_flags` is not set), where a list result
+    collapses to `0` — strict raises on both.
+  - **JSON parse failure in `json_path`.** With the flag off a malformed
+    document is walked leniently and a parse failure answers the same `""`
+    an absent key does. Under strict `json_path` applies `json_decode`'s
+    acceptance test and raises a catchable `value` error naming the position;
+    JSON `false`, `null` and an absent key are answers and stay quiet.
+  - **The sentinel and falsy families.** `index_of`/`list_index_of`/`ord`
+    (`-1`), `file_exists`/`is_dir`/`is_file`/`read_text`/`read_bytes`/`ls`/
+    `mkdir`/`env_get` (`0`/`""`), and the wrong-type launderers the sweep
+    found (`split`, `scan_ints`, `buffer`, `channel_closed`, `f64_to_bytes`,
+    `json_build`, `sort`, `random_int`, `random_hex`, `token_name`,
+    `tokenize_ids`...) raise on a wrong-typed argument; the documented
+    sentinel for a valid-but-absent input — `index_of` miss `-1`,
+    `file_exists` of a missing path `0` — is unchanged in both modes.
+  Overflow saturation is unchanged by the flag. (Division and modulo by zero
+  raise in *both* modes — no defined value.)
 - **Integer bitwise ops act on int64, exact past 2^32.** `&` `|` `^` `~` `<<`
   `>>` and their `bit_*` builtin forms interpret operands as 64-bit integers, so
   `1 << 40` is exact where an f64 mantissa alone would not help. This is the
diff --git a/docs/llms.txt b/docs/llms.txt
index b1258508..7c9eb303 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -131,7 +131,9 @@ print of ("sqrt(2) = " + (str of (newton_sqrt of 2)))   # sqrt(2) = 1.4142135623
   (in place) or a comprehension — `xs + ys` is a runtime error.
 - Numbers are f64 and finite by construction: `NaN` collapses to `0`, overflow
   saturates at ±1e308, `sqrt of -1` is `0`. Integer bit ops are `bit_and`/`&`
-  etc. on int64; exactness ends at 2^53.
+  etc. on int64; exactness ends at 2^53. `EIGS_STRICT=1` makes the stand-ins
+  loud: out-of-domain math, a NaN result, a wrong-typed builtin argument and a
+  malformed `json_path` document raise catchable errors instead.
 - Hex integer literals: `0xFF`, `0X10` (digits only). Hex-float forms
   (`0x1p4`) are parse errors. No `mod` keyword — the operator is `%`.
 - f-strings interpolate: `f"step {i}: {report of x}"`. Escapes: `\n \t \r \\ \" \{ \}`.
diff --git a/src/builtins.c b/src/builtins.c
index 994ced93..706cd66c 100644
--- a/src/builtins.c
+++ b/src/builtins.c
@@ -554,7 +554,9 @@ Value* builtin_num(Value *arg) {
             }
             return make_num(neg ? -v : v);
         }
-        return make_num(strtod(arg->data.str, NULL));
+        /* #971: strtod reads "nan"/"inf" — the in-language route to a NaN.
+         * Default collapses to 0 (+ EIGS_MATH_INVALID); strict raises, named. */
+        return make_num(num_guard_named(strtod(arg->data.str, NULL), "num"));
     }
     if (arg->type == VAL_NULL) return make_num(0);   /* fs:ANSWER coercion contract */
     return make_num(0);                              /* fs:ANSWER coercion contract */
@@ -1579,7 +1581,11 @@ void eigs_json_escape_string(strbuf *out, const char *s) {
 
 Value* builtin_json_build(Value *arg) {
     /* json_build of [key1, val1, key2, val2, ...] — properly escaped JSON object */
-    if (!arg || arg->type != VAL_LIST) return make_str("{}");
+    /* #971 Phase D: a non-list (a dict, a string) built an empty object.
+     * `json_build of null` stays the empty-object idiom in both modes. */
+    ARG_GUARD(arg && arg->type != VAL_NULL && arg->type != VAL_LIST,
+              "json_build", "a list of alternating keys and values", make_str("{}"));
+    if (!arg || arg->type == VAL_NULL) return make_str("{}");   /* fs:ANSWER no pairs — the empty object */
     int count = arg->data.list.count;
     strbuf out;
     strbuf_init(&out);
@@ -1655,6 +1661,17 @@ Value* builtin_starts_with(Value *arg) {
 
 Value* builtin_split(Value *arg) {
     const char *str = "", *delim = " ";
+    /* #971 Phase D: a non-string subject coerced to "" (so `split of 42` was
+     * [""], a plausible one-part answer) and a non-string delimiter fell
+     * back to " " silently. Coercion shape — no single stand-in to name —
+     * so STRICT_REQUIRE: raise under strict, byte-identical otherwise. */
+    STRICT_REQUIRE(!arg || !(arg->type == VAL_STR ||
+                             (arg->type == VAL_LIST && arg->data.list.count >= 1 &&
+                              arg->data.list.items[0]->type == VAL_STR)),
+                   "split", "a string or [string, delimiter]");
+    STRICT_REQUIRE(arg->type == VAL_LIST && arg->data.list.count >= 2 &&
+                   arg->data.list.items[1]->type != VAL_STR,
+                   "split", "a string delimiter");
     if (arg && arg->type == VAL_STR) {
         str = arg->data.str;
     } else if (arg && arg->type == VAL_LIST && arg->data.list.count >= 1) {
@@ -1723,6 +1740,9 @@ Value* builtin_scan_ints(Value *arg) {
     }
 
     Value *out = make_list(128);
+    /* #971 Phase D: no string in the argument — a wrong type read as
+     * "no tokens". Coercion shape: raise under strict, unchanged otherwise. */
+    STRICT_REQUIRE(!str, "scan_ints", "a string or [string, comment_marker]");
     if (!str) return out;
 
     const char *p = str;
@@ -1821,6 +1841,9 @@ Value* builtin_scan_tokens(Value *arg) {
     }
 
     Value *out = make_list(128);
+    /* #971 Phase D: no string in the argument — a wrong type read as
+     * "no tokens". Coercion shape: raise under strict, unchanged otherwise. */
+    STRICT_REQUIRE(!str, "scan_tokens", "a string or [string, comment_marker]");
     if (!str) return out;
 
     const char *base = str;
@@ -1903,6 +1926,9 @@ Value* builtin_scan_int_tokens(Value *arg) {
     }
 
     Value *out = make_list(128);
+    /* #971 Phase D: no string in the argument — a wrong type read as
+     * "no tokens". Coercion shape: raise under strict, unchanged otherwise. */
+    STRICT_REQUIRE(!str, "scan_int_tokens", "a string or [string, comment_marker]");
     if (!str) return out;
 
     const char *base = str;
@@ -2283,12 +2309,14 @@ Value* builtin_random(Value *arg) {
 
 /* random_int of [lo, hi] → integer in [lo, hi] inclusive */
 Value* builtin_random_int(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2)
-        TRACE_NONDET_RET("random_int", make_num(0));
+    /* #971 Phase D: a malformed range answered 0 — a number in nobody's
+     * range. Taped shape: the soft half still records/replays as before. */
+    ARG_GUARD_TAPED(!arg || arg->type != VAL_LIST || arg->data.list.count < 2,
+                    "random_int", "[lo, hi]", make_num(0));
     Value *lo = arg->data.list.items[0];
     Value *hi = arg->data.list.items[1];
-    if (!lo || lo->type != VAL_NUM || !hi || hi->type != VAL_NUM)
-        TRACE_NONDET_RET("random_int", make_num(0));
+    ARG_GUARD_TAPED(!lo || lo->type != VAL_NUM || !hi || hi->type != VAL_NUM,
+                    "random_int", "numeric bounds", make_num(0));
     eigs_ensure_random_seeded();
     /* Range-check as doubles before any integer cast — a double outside the
      * int64_t range (or non-finite) makes the cast itself UB (#698 fixed the
@@ -2486,13 +2514,30 @@ Value* builtin_json_path(Value *arg) {
 
     int pos = 0;
     Value *root = eigs_json_parse_root(json_str, &pos);   /* #777: fresh parse */
-    /* fs:TODO #971 PHASE C. This is NOT "no value at that path" — the
-     * DOCUMENT failed to parse, and that input error is laundered into the
-     * same "" that a legitimately-absent key returns, so a caller cannot
-     * tell malformed JSON from a missing field. Converting it means deciding
-     * whether JSON parse failure raises at all, which is a contract change
-     * with its own consumers (the flag channel below, ext_http, tidelog).
-     * Deliberately left soft here and recorded as the Phase C decision. */
+    /* #971 Phase C. A DOCUMENT that failed to parse is not "no value at that
+     * path", yet the lenient walk below answers the same "" an absent key
+     * returns, so a caller cannot tell malformed JSON from a missing field.
+     * Decided: under EIGS_STRICT the parse failure raises — a catchable
+     * `value` error naming the position, on exactly the acceptance test
+     * json_decode applies (structural error, a repaired scalar, or trailing
+     * garbage after the value). With the flag off nothing changes: the
+     * partial document is walked as before, which the flag channel's other
+     * consumers (ext_http's shared store and header parsing, the store's
+     * catalog) rely on and which this raise does not touch — they never
+     * pass through json_path. JSON `false`/`null`/literals are answers and
+     * stay quiet in both modes. */
+    if (g_strict) {
+        int end = pos;
+        eigs_json_skip_ws(json_str, &end);
+        if (!root || g_json_parse_err || g_json_parse_recoverable ||
+            json_str[end] != '\0') {
+            if (root) val_decref(root);
+            rt_error(EK_VALUE, 0, "json_path: invalid JSON at position %d", end);
+            return make_null();
+        }
+    }
+    /* fs:STRICT the g_strict block above raised on a parse failure; the soft
+     * "" is the flag-off path (unchanged since before #971 Phase C). */
     if (!root) return make_str("");
     Value *current = root;   /* walks borrowed children of root */
 
@@ -2690,7 +2735,7 @@ void free_tokenlist(TokenList *tl) {
  * Exposes the runtime's own tokenizer to .eigs code.
  * The learner sees its world the way the runtime does. */
 Value* builtin_tokenize_ids(Value *arg) {
-    if (!arg || arg->type != VAL_STR) return make_list(0);
+    ARG_GUARD(!arg || arg->type != VAL_STR, "tokenize_ids", "a source string", make_list(0));  /* #971 Phase D */
     const char *src = arg->data.str;
     if (!src || !src[0]) return make_list(0);
 
@@ -2710,7 +2755,7 @@ Value* builtin_tokenize_ids(Value *arg) {
  * token types get an empty string. Used by corpus builders that need
  * per-identifier information for vocabulary enrichment. */
 Value* builtin_tokenize_with_names(Value *arg) {
-    if (!arg || arg->type != VAL_STR) return make_list(0);
+    ARG_GUARD(!arg || arg->type != VAL_STR, "tokenize_with_names", "a source string", make_list(0));  /* #971 Phase D */
     const char *src = arg->data.str;
     if (!src || !src[0]) return make_list(0);
 
@@ -2744,7 +2789,9 @@ Value* builtin_tokenize_with_names(Value *arg) {
 /* ==== BUILTIN: token_name ==== */
 /* token_name of id → string name of token type (for display) */
 Value* builtin_token_name(Value *arg) {
-    if (!arg || arg->type != VAL_NUM) return make_str("?");
+    /* #971 Phase D: "?" is the documented answer for an UNKNOWN id (below);
+     * for a non-number it was laundering a type mistake into that answer. */
+    ARG_GUARD(!arg || arg->type != VAL_NUM, "token_name", "a token id", make_str("?"));
     int id = (int)arg->data.num;
     static const char *names[] = {
         "NUM", "STR", "IDENT",
@@ -4797,8 +4844,13 @@ Value* builtin_close_channel(Value *arg) {
 }
 
 Value* builtin_channel_closed(Value *arg) {
+    /* #971 Phase D: get_channel folds "not a channel handle" into "no such
+     * channel". The second is the documented answer (a reclaimed channel is
+     * closed); the first is a type mistake reading as closed. Split. */
+    int not_a_handle = !arg || arg->type != VAL_DICT || !dict_get(arg, "_channel_id");
+    ARG_GUARD(not_a_handle, "channel_closed", "a channel", make_num(1));
     Channel *ch = get_channel(arg);
-    if (!ch) return make_num(1);
+    if (!ch) return make_num(1);   /* fs:ANSWER an unknown/reclaimed channel is closed */
     /* Read ch->closed under the mutex: close_channel writes it while holding
      * the lock, so a bare read here is a data race (caught by the #401 TSan
      * gate — it fired in CI where two workers polled channel_closed against a
@@ -5600,6 +5652,9 @@ Value* builtin_buffer(Value *arg) {
         return v;
     }
     int count = 0;
+    /* #971 Phase D: a non-number size (or a malformed [rows, cols]) made an
+     * EMPTY buffer — a plausible object with nothing in it. */
+    STRICT_REQUIRE(!arg || arg->type != VAL_NUM, "buffer", "a size or [rows, cols]");
     if (arg && arg->type == VAL_NUM) count = (int)arg->data.num;
     if (count < 0) count = 0;
     if (count > 10000000) count = 10000000;
@@ -5772,6 +5827,8 @@ Value* builtin_str_from_bytes(Value *arg) {
  * the host bit pattern is captured via memcpy, then bytes are extracted with
  * explicit shifts, yielding the standard IEEE-754 layout on any platform. */
 Value* builtin_f64_to_bytes(Value *arg) {
+    /* #971 Phase D: a non-number encoded as 0.0's eight bytes. */
+    STRICT_REQUIRE(!arg || arg->type != VAL_NUM, "f64_to_bytes", "a number");
     double d = (arg && arg->type == VAL_NUM) ? arg->data.num : 0.0;
     uint64_t bits;
     memcpy(&bits, &d, sizeof(bits));
@@ -5804,7 +5861,9 @@ Value* builtin_f64_from_bytes(Value *arg) {
         bits = (bits << 8) | (uint64_t)((int)bytes_in[i] & 0xFF);
     double d;
     memcpy(&d, &bits, sizeof(d));
-    return make_num(d);
+    /* #971: eight arbitrary bytes can spell a NaN; collapse (default) or
+     * raise (strict) under this builtin's own name. */
+    return make_num(num_guard_named(d, "f64_from_bytes"));
 }
 
 /* ---- DEFLATE codecs (inflate/deflate, #684) ----
@@ -6702,6 +6761,8 @@ static int sort_cmp_str(const void *a, const void *b) {
 }
 
 Value* builtin_sort(Value *arg) {
+    /* #971 Phase D: a non-list was handed back unchanged, as if sorted. */
+    STRICT_REQUIRE(arg && arg->type != VAL_LIST, "sort", "a list");
     if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2)
         return arg ? arg : make_null();
     ValType t = arg->data.list.items[0] ? arg->data.list.items[0]->type
diff --git a/src/builtins_host.c b/src/builtins_host.c
index 33e77072..f0ebcf89 100644
--- a/src/builtins_host.c
+++ b/src/builtins_host.c
@@ -1962,6 +1962,9 @@ Value* builtin_proc_wait(Value *arg) {
 /* random_hex of n → string of n random hex characters from /dev/urandom.
  * Capability builtin: provides randomness so .eigs libraries can generate tokens. */
 Value* builtin_random_hex(Value *arg) {
+    /* #971 Phase D: a non-number length answered "" (as does a length of 0,
+     * which stays the answer). Taped: the soft half records as before. */
+    ARG_GUARD_TAPED(!arg || arg->type != VAL_NUM, "random_hex", "a number of hex digits", make_str(""));
     int n = (arg && arg->type == VAL_NUM) ? (int)arg->data.num : 0;
     if (n <= 0 || n > 256) TRACE_NONDET_RET("random_hex", make_str(""));
     int bytes_needed = (n + 1) / 2;
diff --git a/src/builtins_tensor.c b/src/builtins_tensor.c
index f691b07b..cc804d2c 100644
--- a/src/builtins_tensor.c
+++ b/src/builtins_tensor.c
@@ -319,8 +319,17 @@ typedef double (*BinOpFn)(double, double);
 static double op_add(double a, double b) { return num_guard(a + b); }
 static double op_sub(double a, double b) { return num_guard(a - b); }
 static double op_mul(double a, double b) { return num_guard(a * b); }
-static double op_div(double a, double b) { return (b == 0.0) ? 0.0 : num_guard(a / b); }
-static double op_pow(double a, double b) { return num_guard(pow(a, b)); }
+/* #971: the elementwise zero-denominator stand-in. The `/` operator raises
+ * on a zero divisor in both modes; this helper answered 0 instead (the
+ * IEEE result would be inf or NaN, so the 0 is a pre-collapse). Default
+ * unchanged; under strict it is the same undefined operation and raises. */
+static double op_div(double a, double b) {
+    if (b == 0.0) { STRICT_DOMAIN(1, "divide", "division by zero"); return 0.0; }
+    return num_guard(a / b);
+}
+/* #971: pow(negative, non-integer) is NaN — the one arithmetic builtin whose
+ * finite inputs reach a NaN. Named so the strict raise says `pow`. */
+static double op_pow(double a, double b) { return num_guard_named(pow(a, b), "pow"); }
 
 /* #1093: materialise a buffer as the nested-list tensor of the same shape, so
  * a MIXED buffer/list pair falls back to the list path (and yields a list). */
@@ -642,6 +651,38 @@ Value* builtin_tensor_matmul(Value *arg) {
                                                 : make_shaped_buffer(ar, bc);
         if (!res) return make_null();
         ne_matmul_buf(a->data.buffer.data, ar, ac, b->data.buffer.data, bc, res->data.buffer.data);
+        /* #971: the kernel accumulates raw, so inf - inf leaves a NaN in the
+         * result buffer. The boxed roads collapse a NaN in make_num's
+         * num_guard; this path stores it verbatim, and a raw
+         * NaN in a buffer is not a number the program can see — its bit
+         * pattern is a NaN-boxed slot tag, so `r[i]` reads back as `null`
+         * (0xFFF8... is SLOT_NULL_BITS).
+         *
+         * Under strict that undefined result RAISES, named, like every
+         * other enumerated NaN source. With the flag OFF the buffer is
+         * left exactly as the kernel wrote it, INCLUDING that NaN: this
+         * reform's whole safety claim is that the default path is
+         * byte-identical to the previous release, and collapsing here
+         * would change `r[0]` from `null` to 0 and set EIGS_MATH_INVALID
+         * where the release set nothing (measured against the v0.43.0
+         * binary). The `null` read is a real defect — it is a buffer
+         * element that is neither a number nor a program-made null — but
+         * it is a PRE-EXISTING one, it is not unique to this writer
+         * (ext_store round-trips a NaN buffer element deliberately —
+         * store_nonfinite_sentinel), and fixing it means fixing the READ
+         * for every road at once. That is its own change with its own
+         * differential; it is recorded in ROADMAP.md, not smuggled in
+         * under a strict-mode flag. STRICT_DOMAIN is the shape for that:
+         * it raises under strict and does nothing otherwise, so the soft
+         * path cannot drift. */
+        if (g_strict) {
+            for (int i = 0; i < res->data.buffer.count; i++)
+                if (res->data.buffer.data[i] != res->data.buffer.data[i]) {
+                    STRICT_DOMAIN(1, "matmul",
+                                  "result is not a number (NaN has no defined value)");
+                    break;
+                }
+        }
         return res;
     }
     int ar, ac, br, bc;
@@ -666,6 +707,10 @@ Value* builtin_tensor_matmul(Value *arg) {
     }
     double *out = xcalloc((size_t)ar * bc, sizeof(double));
     ne_matmul_buf(af, ar, ac, bf, bc, out);
+    /* #971: same NaN collapse as the buffer path, so the strict raise names
+     * matmul instead of the bare num_guard backstop inside make_num. */
+    for (int64_t i = 0; i < (int64_t)ar * bc; i++)
+        if (out[i] != out[i]) out[i] = num_guard_named(out[i], "matmul");
     Value *result;
     if (ar == 1)
         result = flat_to_tensor_1d(out, bc);
@@ -2067,6 +2112,12 @@ Value* builtin_tensor_load(Value *arg) {
     double *data = xmalloc_array((size_t)total, sizeof(double));
     if (!data) { fclose(f); return make_null(); }
     if ((int)fread(data, sizeof(double), total, f) != total) { free(data); fclose(f); return make_null(); }
+    /* #971: the file is untrusted bytes, so a NaN pattern is reachable
+     * here. flat_to_tensor_* would collapse it through make_num anyway
+     * (same 0 + EIGS_MATH_INVALID); guarding first lets the strict raise
+     * name tensor_load. */
+    for (int i = 0; i < total; i++)
+        if (data[i] != data[i]) data[i] = num_guard_named(data[i], "tensor_load");
 
     /* Read observer state if present */
     double *obs_data = NULL;
diff --git a/src/eigenscript.c b/src/eigenscript.c
index 9cb59b75..1d461b1e 100644
--- a/src/eigenscript.c
+++ b/src/eigenscript.c
@@ -175,6 +175,18 @@ void rt_error(ErrKind kind, int line, const char *fmt, ...) {
     }
 }
 
+/* #971: the strict half of the NaN collapse. Off, num_guard folds a NaN to
+ * 0 and sets EIGS_MATH_INVALID — a plausible number nothing downstream can
+ * tell from a real zero. On, the operation has no honest value, so it joins
+ * div0/mod0 and the domain raises: a catchable EK_VALUE. `who` is NULL when
+ * the backstop in num_guard fired for a source the enumerated callers of
+ * num_guard_named do not cover; the message then names the arithmetic
+ * rather than a builtin, which is still louder than a silent 0. */
+void eigs_strict_nan_raise(const char *who) {
+    rt_error(EK_VALUE, 0, "%s: result is not a number (NaN has no defined value)",
+             who ? who : "arithmetic");
+}
+
 const char* tok_type_name(TokType t) {
     switch (t) {
         case TOK_NUM: return "number";
diff --git a/src/eigenscript.h b/src/eigenscript.h
index c7c39eb0..52f9d91e 100644
--- a/src/eigenscript.h
+++ b/src/eigenscript.h
@@ -1404,15 +1404,54 @@ void free_value(Value *v);
                                  * there. Detection has to sit where the operands
                                  * are still live — the arithmetic dispatch. */
 
+/* #971: under EIGS_STRICT a NaN does not collapse — it RAISES a catchable
+ * `value` error. `who` names the builtin whose result was undefined (the
+ * enumerated sources call num_guard_named); NULL is the backstop from
+ * num_guard itself for a source nobody enumerated. Out of line so the NaN
+ * branch stays one call on a path a finite program never takes. */
+void eigs_strict_nan_raise(const char *who);
+
 static inline double num_guard(double x) {
     /* Fast path unchanged: the flag writes live only on the clamp branches,
      * which a program that does not overflow never takes. */
-    if (x != x) { g_math_flags |= EIGS_MATH_INVALID; return 0.0; }        /* NaN */
+    if (x != x) {                                                            /* NaN */
+        g_math_flags |= EIGS_MATH_INVALID;
+        if (g_strict) eigs_strict_nan_raise(NULL);
+        return 0.0;
+    }
     if (x > EIGS_NUM_MAX)  { g_math_flags |= EIGS_MATH_OVERFLOW; return EIGS_NUM_MAX; }
     if (x < -EIGS_NUM_MAX) { g_math_flags |= EIGS_MATH_OVERFLOW; return -EIGS_NUM_MAX; }
     return x;
 }
 
+/* #971: num_guard for a builtin whose result CAN be NaN on the current tree
+ * (`pow` of a negative base with a fractional exponent, `num of "nan"`,
+ * `f64_from_bytes` of a NaN bit pattern, `matmul`'s inf-inf accumulation,
+ * `tensor_load` of a file carrying NaN bytes). Default path identical to
+ * num_guard — collapse to 0, set EIGS_MATH_INVALID — but under strict the
+ * raise NAMES the builtin, which the bare backstop cannot. The string is the
+ * cross-check key tools/strict_differential.sh derives its probe set from,
+ * so a new caller here without a probe row goes red there. */
+static inline double num_guard_named(double x, const char *who) {
+    if (x != x) {
+        g_math_flags |= EIGS_MATH_INVALID;
+        if (g_strict) eigs_strict_nan_raise(who);
+        return 0.0;
+    }
+    return num_guard(x);
+}
+
+/* #971: a value-domain raise inside a double-returning helper, where
+ * ARG_GUARD's `return make_null()` does not fit. Raises under strict and
+ * does nothing otherwise, so the soft path is byte-identical by
+ * construction (the caller keeps returning its stand-in). `who` is the
+ * cross-check key, like ARG_GUARD's. */
+#define STRICT_DOMAIN(cond, who, what)                                       \
+    do {                                                                      \
+        if (g_strict && (cond))                                               \
+            rt_error(EK_VALUE, 0, "%s: %s", (who), (what));                   \
+    } while (0)
+
 /* The g_vm_multithreaded flag (state->multithreaded, bridge macro above)
  * is set to 1 by builtin_spawn before pthread_create, then stays 1.
  * Single-threaded scripts (the common case — DMG, MiniSat, Tidepool,
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index bda6f975..21b60739 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -6020,16 +6020,27 @@ echo ""
 # existed — one probe named a builtin that does not exist and passed on
 # "undefined variable"), every documented ANSWER must stay quiet, and every
 # guard must have a probe.
+# RUN ONCE, REPORT THAT RUN. The first version threw the failing run's output
+# away (`>/dev/null`) and re-ran the tool to produce a diagnostic — so the
+# evidence printed under a FAIL banner came from a DIFFERENT run, and if the
+# failure was not deterministic the diagnostic was green. That is not a
+# hypothetical: a full-suite log from 2026-09-06 shows this section printing
+# "FAIL: a guard went silent..." followed by a completely clean report ending
+# in "OK", which is unreadable and untriageable — the one run that knew what
+# happened was discarded. Capture once; print what THAT run said.
 echo "[99s] Strict argument-guard differential (#971, no-baseline half)"
 TOTAL=$((TOTAL + 1))
-if bash "$TESTS_DIR/../tools/strict_differential.sh" --no-baseline >/dev/null 2>&1; then
+STRICT_DIFF_OUT="$(bash "$TESTS_DIR/../tools/strict_differential.sh" --no-baseline 2>&1)"
+STRICT_DIFF_RC=$?
+if [ "$STRICT_DIFF_RC" = 0 ]; then
     PASS=$((PASS + 1))
     echo "  PASS: every guard raises from its own guard; every answer stays quiet"
 else
     FAIL=$((FAIL + 1))
     echo "  FAIL: a guard went silent, raised from the wrong place, a pin broke,"
-    echo "        or a guard has no probe"
-    bash "$TESTS_DIR/../tools/strict_differential.sh" --no-baseline 2>&1 | sed -n '1,14p'
+    echo "        a guard has no probe, or a probe did not run (exit $STRICT_DIFF_RC)"
+    echo "  --- output of the run that failed (not a re-run) ---"
+    printf '%s\n' "$STRICT_DIFF_OUT" | sed -n '1,24p'
 fi
 echo ""
 
diff --git a/tests/test_strict_math.sh b/tests/test_strict_math.sh
index af070b3a..059a9fa2 100755
--- a/tests/test_strict_math.sh
+++ b/tests/test_strict_math.sh
@@ -40,7 +40,21 @@ run() {
     local exit_ok=0
     if [ "$xexit" = "0" ] && [ "$rc" = "0" ]; then exit_ok=1; fi
     if [ "$xexit" = "1" ] && [ "$rc" != "0" ]; then exit_ok=1; fi
-    if [ "$exit_ok" = "1" ] && echo "$out" | grep -qF "$substr"; then
+    if [ "$exit_ok" = "1" ] && echo "$out" | grep -qF -- "$substr"; then
+        ok "$name"
+    else
+        fail "$name" "rc=$rc out='$out'"
+    fi
+}
+
+# run_jitoff <name> <expect-substr> <program>: EIGS_STRICT=1 with the JIT off,
+# expecting a raise — the interpreter half of the JIT/interpreter agreement.
+run_jitoff() {
+    local name="$1" substr="$2" prog="$3"
+    printf '%s\n' "$prog" > "$TMP"
+    local out rc
+    out=$(EIGS_STRICT=1 EIGS_JIT_OFF=1 "$EIGS" "$TMP" 2>&1); rc=$?
+    if [ "$rc" != "0" ] && echo "$out" | grep -qF -- "$substr"; then
         ok "$name"
     else
         fail "$name" "rc=$rc out='$out'"
@@ -141,5 +155,131 @@ run "SM34 strict: list_contains finding nothing is 0"  1 0 "0" 'print of (list_c
 run "SM35 strict: JSON false still decodes to 0"       1 0 "0" \
     'print of (json_path of ["{\"a\": false}", "a"])'
 
+# --- #971 Phase C: JSON parse failure in json_path ----------------------------
+# json_path walked a PARTIAL document and answered the same "" an absent key
+# returns, so malformed JSON was indistinguishable from a missing field. Under
+# strict the parse failure raises (json_decode's acceptance test: structural
+# error, repaired scalar, trailing garbage) as a catchable `value` error naming
+# the position. Off: byte-identical (SM36/SM37 pin the lenient walk). JSON
+# `false`/`null`/absent-key are ANSWERS and stay quiet in both modes.
+run "SM36 default json_path(bad number) still walks partial" unset 0 "[0]" \
+    'print of f"[{json_path of ["{\"a\": 1e", "a"]}]"'
+run "SM37 default json_path(truncated array) still partial" unset 0 "[[1,2]]" \
+    'print of f"[{json_path of ["{\"a\": [1, 2", "a"]}]"'
+run "SM38 strict json_path(bad number) raises with position" 1 1 "json_path: invalid JSON at position 8" \
+    'print of (json_path of ["{\"a\": 1e", "a"])'
+run "SM39 strict json_path(truncated) raises" 1 1 "json_path: invalid JSON at position" \
+    'print of (json_path of ["{\"a\": [1, 2", "a"])'
+run "SM40 strict json_path(trailing garbage) raises" 1 1 "json_path: invalid JSON at position 9" \
+    'print of (json_path of ["{\"a\": 1} x", "a"])'
+run "SM41 strict json_path(empty document) raises" 1 1 "json_path: invalid JSON at position 0" \
+    'print of (json_path of ["", "a"])'
+run "SM42 strict json_path raise is catchable as value" 1 0 "caught value" \
+'try:
+    x is json_path of ["{bad", "a"]
+catch e:
+    print of f"caught {e.kind}"'
+run "SM43 strict: JSON false is still 0"                1 0 "0"  'print of (json_path of ["{\"a\": false}", "a"])'
+run "SM44 strict: absent key is still empty"            1 0 "[]" 'print of f"[{json_path of ["{\"a\": 1}", "b"]}]"'
+run "SM45 strict: JSON null still renders empty"        1 0 "[]" 'print of f"[{json_path of ["{\"a\": null}", "a"]}]"'
+run "SM46 strict: valid nested path still resolves"     1 0 "x"  'print of (json_path of ["{\"a\": [1, {\"b\": \"x\"}]}", "a.1.b"])'
+
+# --- #971 NaN-collapse: the reachable NaN sources raise under strict ------------
+# Enumerated on the tree (the VM's own + - * / % cannot reach NaN from finite
+# operands — 0/0 and x%0 raise first, and no operand can hold an inf): `pow`
+# of a negative base with a fractional exponent, `num of "nan"` (strtod),
+# `f64_from_bytes` of a NaN bit pattern, `matmul`'s inf-inf accumulation (list
+# and buffer paths), `tensor_load` of a file carrying NaN bytes, and the
+# elementwise `divide` by zero (pre-collapsed to 0 where `/` raises). Default
+# collapses to 0 + math_flags.invalid exactly as before (SM47-SM49 pin it).
+run "SM47 default pow(-8, 0.5) still 0"            unset 0 "0"  'print of (pow of [0 - 8, 0.5])'
+run "SM48 default num(\"nan\") still 0 + invalid"  unset 0 "0 1" \
+'local v is num of "nan"
+print of f"{v} {(math_flags of null).invalid}"'
+run "SM49a default matmul(inf-inf) LIST path still collapses to 0 + invalid" unset 0 "[0] 1" \
+'local r is matmul of [[[1e200, 1e200]], [[1e200], [0 - 1e200]]]
+print of f"{r} {(math_flags of null).invalid}"'
+# The BUFFER path is deliberately NOT collapsed with the flag off. The kernel
+# writes into the result buffer raw, so the NaN stays there, and a raw NaN in
+# a buffer reads back as `null` (its bit pattern is a NaN-boxed slot tag,
+# 0xFFF8... == SLOT_NULL_BITS) with math_flags.invalid still 0. That is what
+# v0.43.0 does, and this change's contract is that the flag-off path is
+# byte-identical to it: an earlier draft collapsed it to 0 here and had to
+# carry a waiver in tools/strict_differential.sh to say so. The `null` read
+# is a real defect and is recorded in ROADMAP.md as its own change; SM49b
+# pins the CURRENT answer so that change cannot happen by accident.
+run "SM49b default matmul(inf-inf) BUFFER path is byte-identical to v0.43.0" unset 0 "null 0" \
+'local m1 is buffer of [1, 2]
+m1[0] is 1e200
+m1[1] is 1e200
+local m2 is buffer of [2, 1]
+m2[0] is 1e200
+m2[1] is 0 - 1e200
+local r is matmul of [m1, m2]
+print of f"{r[0]} {(math_flags of null).invalid}"'
+run "SM50 strict pow(-8, 0.5) raises, named"       1 1 "pow: result is not a number"     'print of (pow of [0 - 8, 0.5])'
+run "SM51 strict elementwise pow raises"           1 1 "pow: result is not a number"     'print of (pow of [[0 - 8, 4], 0.5])'
+run "SM52 strict num(\"nan\") raises, named"       1 1 "num: result is not a number"     'print of (num of "nan")'
+run "SM53 strict f64_from_bytes(NaN bits) raises"  1 1 "f64_from_bytes: result is not a number" \
+    'print of (f64_from_bytes of ([127, 248, 0, 0, 0, 0, 0, 0]))'
+run "SM54 strict matmul list inf-inf raises"       1 1 "matmul: result is not a number" \
+    'print of (matmul of [[[1e200, 1e200]], [[1e200], [0 - 1e200]]])'
+run "SM55 strict matmul buffer inf-inf raises"     1 1 "matmul: result is not a number" \
+'local m1 is buffer of [1, 2]
+m1[0] is 1e200
+m1[1] is 1e200
+local m2 is buffer of [2, 1]
+m2[0] is 1e200
+m2[1] is 0 - 1e200
+local r is matmul of [m1, m2]
+print of (r[0])'
+run "SM56 strict divide-by-zero (elementwise) raises" 1 1 "divide: division by zero" 'print of (divide of [[1], [0]])'
+run "SM57 strict NaN raise is catchable as value"  1 0 "caught value" \
+'try:
+    x is pow of [0 - 8, 0.5]
+catch e:
+    print of f"caught {e.kind}"'
+run "SM58 strict: num(\"inf\") still saturates (overflow, not NaN)" 1 0 "1e+308" 'print of (num of "inf")'
+run "SM59 strict: pow with an integer exponent is defined"      1 0 "-8"     'print of (pow of [0 - 2, 3])'
+run "SM60 strict: tensor_load of NaN bytes raises, named" 1 1 "tensor_load: result is not a number" \
+'write_bytes of ["/tmp/eigs_strict_nan_$$.tensor", [1, 0, 0, 0, 1, 0, 0, 0, 2, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 248, 127, 0, 0, 0, 0, 0, 0, 4, 64]]
+print of (tensor_load of "/tmp/eigs_strict_nan_$$.tensor")'
+rm -f "/tmp/eigs_strict_nan_$$.tensor"
+# The interpreter and the JIT must agree: the JIT bails to the interpreter on
+# any non-finite result, so the raise comes from the same num_guard either way.
+run_jitoff "SM61 strict pow raises with the JIT off too" "pow: result is not a number" \
+'print of (pow of [0 - 8, 0.5])'
+
+# --- #971 Phase D: the -1 / falsy sentinel families (#1008) and the --sweep list
+# The documented sentinel for a valid-but-absent input is pinned in BOTH modes;
+# only a wrong-typed argument raises.
+run "SM62 strict: index_of miss is still -1"            1 0 "-1" 'print of (index_of of ["abc", "z"])'
+run "SM63 strict: file_exists of an absent path is 0"   1 0 "0"  'print of (file_exists of "/nonexistent/eigs_971_probe")'
+run "SM64 strict: is_dir of an absent path is 0"        1 0 "0"  'print of (is_dir of "/nonexistent/eigs_971_probe")'
+run "SM65 strict: read_text of an absent path is empty" 1 0 "[]" 'print of f"[{read_text of "/nonexistent/eigs_971_probe"}]"'
+run "SM66 strict index_of(num, str) raises"             1 1 "index_of: expected"    'print of (index_of of [42, "x"])'
+run "SM67 strict file_exists(num) raises"               1 1 "file_exists: expected" 'print of (file_exists of 42)'
+# --sweep candidates converted in this pass (each was a wrong type reading as
+# a plausible answer: `split of 42` -> [""], `buffer of "x"` -> an empty
+# buffer, `channel_closed of 42` -> 1 "closed", `f64_to_bytes of "x"` -> the
+# bytes of 0.0, `random_int of "x"` -> 0, `json_build of {..}` -> "{}").
+run "SM68 default split(num) still [\"\"]"              unset 0 '[""]' 'print of (split of 42)'
+run "SM69 strict split(num) raises"                     1 1 "split: expected"       'print of (split of 42)'
+run "SM70 strict split with a non-string delimiter raises" 1 1 "split: expected a string delimiter" 'print of (split of ["a b", 42])'
+run "SM71 strict scan_ints(dict) raises"                1 1 "scan_ints: expected"   'print of (scan_ints of ({"k": 1}))'
+run "SM72 strict buffer(str) raises"                    1 1 "buffer: expected"      'print of (buffer of "x")'
+run "SM73 strict channel_closed(num) raises"            1 1 "channel_closed: expected" 'print of (channel_closed of 42)'
+run "SM74 strict: unknown channel is still closed (1)"  1 0 "1"  'print of (channel_closed of ({"_channel_id": 99999}))'
+run "SM75 strict f64_to_bytes(str) raises"              1 1 "f64_to_bytes: expected" 'print of (f64_to_bytes of "x")'
+run "SM76 strict random_int(bad bounds) raises"         1 1 "random_int: expected" 'print of (random_int of ["a", 3])'
+run "SM77 strict json_build(dict) raises"               1 1 "json_build: expected" 'print of (json_build of ({"a": 1}))'
+run "SM78 strict: json_build of null is still {}"       1 0 "{}" 'print of (json_build of null)'
+run "SM79 strict sort(dict) raises"                     1 1 "sort: expected a list" 'print of (sort of ({"a": 1}))'
+run "SM80 strict token_name(str) raises"                1 1 "token_name: expected" 'print of (token_name of "x")'
+run "SM81 strict: token_name of an unknown id is still ?" 1 0 "?" 'print of (token_name of 9999)'
+run "SM82 strict tokenize_ids(num) raises"              1 1 "tokenize_ids: expected" 'print of (tokenize_ids of 42)'
+run "SM83 strict random_hex(str) raises"                1 1 "random_hex: expected" 'print of (random_hex of "x")'
+run "SM84 strict: random_hex of 0 is still empty"       1 0 "[]" 'print of f"[{random_hex of 0}]"'
+
 echo "STRICT: $PASS passed, $FAIL failed"
 [ "$FAIL" -eq 0 ]
diff --git a/tools/strict_differential.sh b/tools/strict_differential.sh
index 2964b419..7d08137c 100755
--- a/tools/strict_differential.sh
+++ b/tools/strict_differential.sh
@@ -40,15 +40,43 @@
 #   - --sweep is discovery, not a gate: it has no allowlist, so nothing
 #     fails when a new laundering builtin appears. Making it a gate needs a
 #     pinned expected-quiet list, which nobody has written.
+# UNDER LOAD. Every measurement here is one short child process, and the tool
+# makes no timing assumption: nothing is backgrounded, nothing polls, no probe
+# depends on scheduling order, and a probe that hangs hangs (it is not raced
+# against a timer, so a slow box cannot turn a pass into a fail). What a loaded
+# box CAN do is stop a child from running at all — a fork that fails, a kill, a
+# binary relinked underneath the run — and until 2026-09-07 that arrived as a
+# finding ABOUT THE CODE: a probe killed by a signal exits nonzero, so it was
+# scored "raised, but not by its own guard", and a harness that died mid-run
+# printed no verdict at all while still exiting nonzero. Both now say what they
+# are: `probes that did not run` is its own bucket, naming the exit status, and
+# the EXIT trap prints ABORTED when the script exits before its verdict line.
+# A red from either is still a red — nothing is retried, and a crash (signal)
+# is reported as a crash — but it names the environment instead of the table.
+#
+#   - The probe row's THIRD field (#971 Phase C/D + NaN) is the substring
+#     the strict raise must carry; it defaults to "<who>: expected", the
+#     shape ARG_GUARD/STRICT_REQUIRE emit. A NaN source (num_guard_named)
+#     raises "<who>: result is not a number"; a STRICT_DOMAIN site raises
+#     "<who>: <what>"; json_path raises "json_path: invalid JSON". The
+#     cross-check derives its name set from ALL of those spellings, so a
+#     guard of any kind without a probe row still goes red — but a row
+#     whose expect field is too loose (a bare builtin name) is the same
+#     vacuity the "<name>: expected" rule closed, and nothing here
+#     catches it beyond review.
 
 set -uo pipefail
 cd "$(cd "$(dirname "$0")/.." && pwd)"
 
 # EIGS_DIFF_NEW lets the harness be pointed at another build, which is how
-# it is validated: run it with NEW := the BASELINE binary and both
-# detectors must fire (the baseline lacks these guards, so probes go
-# silent under strict; and the waived divergence vanishes, so the
-# stale-waiver check speaks). A harness that has never failed has not been
+# it is validated: run it with NEW := the previous release's binary and the
+# loudness detector must fire, because that binary lacks the guards this
+# tree added. Measured 2026-09-07 against the v0.43.0 build:
+# `raises-under-strict: 77 silent: 21` and FAIL, where this tree scores
+# 98/0 and OK. (The stale-waiver check is not exercised that way while both
+# waiver lists are empty, which they are — see the waiver block below. It is
+# exercised by ADDING a waiver for a probe that does not diverge, which is
+# what it exists to catch.) A harness that has never failed has not been
 # shown to work.
 NEW="${EIGS_DIFF_NEW:-./src/eigenscript}"
 BASE="${1:-}"
@@ -66,13 +94,46 @@ if [ "$BASE" = "--no-baseline" ]; then NO_BASELINE=1; BASE=""; fi
 [ -x "$NEW" ] || { echo "FAIL: no built binary at $NEW"; exit 1; }
 
 TMP="$(mktemp -d)"
-trap 'rm -rf "$TMP"' EXIT
+# ONE trap (a second EXIT trap would silently replace this one). It cleans up
+# and then answers the question a bare nonzero exit cannot: did this script
+# reach its verdict? A run killed mid-way, or aborted by `set -u` on an unbound
+# name, exits nonzero having printed no finding — which reads downstream as
+# "the gate found something" and sends the next person hunting a guard that is
+# fine. Seen once in a full-suite run (2026-09-06): [99s] printed FAIL and its
+# diagnostic re-run printed a completely clean report, because the failing run
+# was discarded rather than shown. If that happens again this line says so.
+verdict_printed=0
+_sd_main_pid=$BASHPID
+_sd_exit() {
+    local es=$?
+    # ONLY the top-level shell. bash runs an EXIT trap in a subshell that is
+    # killed by a signal too, and this trap both deletes $TMP and speaks: a
+    # signalled command substitution would otherwise remove the temp dir out
+    # from under the still-running parent and print ABORTED before the parent
+    # reaches its verdict. $BASHPID is per-subshell where $$ is not.
+    [ "$BASHPID" = "${_sd_main_pid:-}" ] || return 0
+    rm -rf "${TMP:-}"
+    if [ "${verdict_printed:-0}" != "1" ]; then
+        if [ "$es" = "0" ]; then
+            echo "  ABORTED: this differential was terminated before printing a verdict."
+        else
+            echo "  ABORTED: this differential exited (rc=$es) before printing a verdict."
+        fi
+        echo "           Nothing above is a finding about the code under test —"
+        echo "           the harness itself did not finish (killed, or an unbound"
+        echo "           name under 'set -u'). Re-run it; if it aborts again, the"
+        echo "           abort is the bug."
+    fi
+}
+trap _sd_exit EXIT
 
 # ---------------------------------------------------------------- probes
-# name|program
+# name|program[|expect]
 # Each program calls the builtin with a WRONG-TYPED argument at the right
 # arity, so the guard under test is the one that fires. `who` is the name
-# ARG_GUARD reports, which is what the cross-check below matches on.
+# ARG_GUARD reports, which is what the cross-check below matches on. The
+# optional third field is the message substring the raise must carry when
+# it is not ARG_GUARD's "<who>: expected" (the NaN and domain rows).
 PROBES=$(cat <<'EOF'
 abs|print of (abs of "x")
 acos|print of (acos of "x")
@@ -89,6 +150,7 @@ dot|print of (dot of [1, 2])
 ends_with|print of (ends_with of [42, "x"])
 f64_from_bytes|print of (f64_from_bytes of "x")
 floor|print of (floor of "x")
+gather|print of (gather of ["hello", [0]])
 has_key|print of (has_key of [42, "k"])
 join|print of (join of [42, ","])
 json_path|print of (json_path of 42)
@@ -163,6 +225,27 @@ audio_sweep|print of (len of (audio_sweep of ["100", 200, 0.01, 0.5, 0]))
 audio_noise|print of (len of (audio_noise of [0.001, "0.5"]))
 audio_envelope|print of (len of (audio_envelope of [([0.1, 0.2]), "0.01", 0.01, 0.5, 0.01]))
 audio_gain|print of (len of (audio_gain of [([1.0]), "2.0"]))
+json_path|print of (json_path of ["{\"a\": 1e", "a"])|json_path: invalid JSON at position
+pow|print of (pow of [0 - 8, 0.5])|pow: result is not a number
+num|print of (num of "nan")|num: result is not a number
+f64_from_bytes|print of (f64_from_bytes of ([127, 248, 0, 0, 0, 0, 0, 0]))|f64_from_bytes: result is not a number
+matmul|local m1 is buffer of [1, 2]\nm1[0] is 1e200\nm1[1] is 1e200\nlocal m2 is buffer of [2, 1]\nm2[0] is 1e200\nm2[1] is 0 - 1e200\nlocal r is matmul of [m1, m2]\nprint of (r[0])|matmul: result is not a number
+tensor_load|write_bytes of ["@TMP@/nan.tensor", [1, 0, 0, 0, 1, 0, 0, 0, 2, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 248, 127, 0, 0, 0, 0, 0, 0, 4, 64]]\nprint of (tensor_load of "@TMP@/nan.tensor")|tensor_load: result is not a number
+divide|print of (divide of [[1], [0]])|divide: division by zero
+split|print of (split of 42)
+scan_ints|print of (scan_ints of ({"k": 1}))
+scan_tokens|print of (scan_tokens of ({"k": 1}))
+scan_int_tokens|print of (scan_int_tokens of ({"k": 1}))
+tokenize_ids|print of (tokenize_ids of 42)
+tokenize_with_names|print of (tokenize_with_names of 42)
+token_name|print of (token_name of "x")
+channel_closed|print of (channel_closed of 42)
+f64_to_bytes|print of (f64_to_bytes of "x")
+buffer|print of (buffer of "x")
+json_build|print of (json_build of ({"a": 1}))
+sort|print of (sort of ({"a": 1}))
+random_int|print of (random_int of ["a", 3])
+random_hex|print of (random_hex of "x")
 EOF
 )
 # A probe that needs a real resource must build it under this run's own $TMP,
@@ -190,6 +273,7 @@ try_parse of invalid syntax is 0|print of (try_parse of "!!!")
 max of an empty list is 0|print of (max of ([]))
 sum of an empty list is 0 (the identity, not a type mistake)|print of (sum of ([]))
 mean of an empty list is 0|print of (mean of ([]))
+gather of a 1-D tensor in the per-row form is 0 per row (shape, not index)|print of (gather of [[1, 2], [0, 0]])
 norm of a real vector still computes|print of (norm of [3, 4])
 index_of that finds nothing is -1, not an error|print of (index_of of ["abc", "z"])
 list_index_of that finds nothing is -1|print of (list_index_of of [([1, 2]), 9])
@@ -197,6 +281,18 @@ ord of the empty string is -1 (no first byte)|print of (ord of "")
 sum of a bare number is that number|print of (sum of 7)
 join with a real separator still joins|print of (join of [["a", "b"], "-"])
 json false decodes to 0|print of (json_path of ["{\"a\": false}", "a"])
+json_path of an absent key is "" (no value at that path)|print of f"[{json_path of ["{\"a\": 1}", "b"]}]"
+json_path of a JSON null renders as ""|print of f"[{json_path of ["{\"a\": null}", "a"]}]"
+file_exists of a real absent path is 0 (#1008 Phase D)|print of (file_exists of "/nonexistent/eigs_971_probe")
+is_dir of a real absent path is 0|print of (is_dir of "/nonexistent/eigs_971_probe")
+read_text of a real absent path is ""|print of f"[{read_text of "/nonexistent/eigs_971_probe"}]"
+index_of miss is -1 even with the flag on|print of (index_of of ["abc", "z"])
+num of "inf" saturates (overflow, not NaN)|print of (num of "inf")
+pow of a negative base with an INTEGER exponent is defined|print of (pow of [0 - 2, 3])
+token_name of an unknown id is "?"|print of (token_name of 9999)
+channel_closed of a reclaimed/unknown channel is 1|print of (channel_closed of ({"_channel_id": 99999}))
+json_build of null is the empty object|print of (json_build of null)
+random_hex of 0 is ""|print of f"[{random_hex of 0}]"
 EOF
 )
 
@@ -233,6 +329,7 @@ print of (has_key of [{"k": 1}, "k"])
 print of (path_join of ["a", "b"])
 print of (atan2 of [1, 1])
 print of (list_contains of [[1, 2, 3], 2])
+print of (gather of [[[1, 2], [3, 4]], [0, 1]])
 print of (str_replace of ["banana", "an", "X"])
 print of (add of [[1, 2], [3, 4]])
 print of (sqrt of [4, 9])
@@ -246,6 +343,29 @@ print of (task_alive of 1)
 print of (str_upper of "abc")
 print of (cos of 0)
 print of (len of [1, 2, 3])
+print of (json_path of ["{\"a\": [1, {\"b\": \"x\"}]}", "a.1.b"])
+print of (pow of [2, 10])
+print of (pow of [[1, 2, 3], 2])
+print of (num of "3.5e2")
+print of (f64_from_bytes of (f64_to_bytes of 42.5))
+print of (matmul of [[[1, 2]], [[3], [4]]])
+local m1 is buffer of [1, 2]\nm1[0] is 1e200\nm1[1] is 1e200\nlocal m2 is buffer of [2, 1]\nm2[0] is 1e200\nm2[1] is 1e200\nlocal r is matmul of [m1, m2]\nprint of (r[0] > 1e308)
+print of (divide of [[6, 8], [2, 4]])
+print of (split of ["a,b,c", ","])
+print of (split of "x y")
+print of (scan_ints of "1 2 -3")
+print of (len of (scan_tokens of "a b"))
+print of (len of (scan_int_tokens of "1 x"))
+print of (len of (tokenize_ids of "x is 1"))
+print of (token_name of 0)
+print of (channel_closed of (channel of null))
+print of (f64_to_bytes of 1)
+print of (len of (buffer of 4))
+print of (len of (buffer of [2, 3]))
+print of (json_build of ["k", 1])
+print of (sort of [3, 1, 2])
+seed_random of 7\nprint of (random_int of [1, 1])
+print of (len of (random_hex of 4))
 EOF
 )
 
@@ -283,6 +403,18 @@ EOF
 #     stable across runs" (proof: two baseline runs must DIFFER)
 #   EXPECTED_DIVERGE_FIXED    — "the old answer was stable and wrong"
 #     (proof: two baseline runs must AGREE, and the new answer must be 0)
+# #971 (NaN enumeration) ALMOST added one, and the second look is the reason
+# both lists are empty. matmul's BUFFER path stores the kernel's raw inf-inf
+# NaN, and a raw NaN in a buffer is not a number the program can see — its bit
+# pattern is a NaN-boxed slot tag, so `r[0]` reads back as `null` (0xFFF8...
+# is SLOT_NULL_BITS). Collapsing it to 0 the way the list path does looked
+# like a free fix, and it was written, waived here as EXPECTED_DIVERGE_FIXED,
+# and proven. But a proven waiver is still a hole in the ONE claim this whole
+# tool exists to make — "with the flag off, nothing changed" — and that claim
+# is worth more than the incidental fix. The strict half now raises through
+# STRICT_DOMAIN, which cannot touch the soft path, `r[0]` still reads `null`
+# with the flag off, and the pre-existing `null` read is recorded in
+# ROADMAP.md as its own change with its own differential. Nothing is waived.
 EXPECTED_DIVERGE_UNSTABLE=""
 EXPECTED_DIVERGE_FIXED=""
 EXPECTED_DIVERGE="$EXPECTED_DIVERGE_UNSTABLE
@@ -314,6 +446,19 @@ run_capture() {   # <binary> <env-strict|-> <file>  -> prints "rc\nstdout+stderr
     printf '%s\n%s' "$rc" "$out"
 }
 
+# Did this run MEASURE anything? A guard raise exits 1. Exit 126/127 means the
+# process could not be executed, and >= 128 means it was killed by a signal —
+# neither is a statement about a guard, and scoring them as one is how a loaded
+# box produces a finding about code that is fine. Returns the reason, or "" when
+# the run is a legitimate measurement.
+run_did_not_measure() {   # <rc>
+    case "$1" in
+        126|127) printf 'the process could not be executed (exit %s)' "$1" ;;
+        1[3-9][0-9]|12[89]) printf 'killed by signal %s — a crash, not a guard' "$(( $1 - 128 ))" ;;
+        *) printf '' ;;
+    esac
+}
+
 # rc is initialised ONCE, here, before any check can run. It used to be
 # assigned rc=0 down in the summary block — AFTER the cross-check section had
 # already set rc=1 — so a STALE UNPROBEABLE WAIVER finding printed and the
@@ -324,6 +469,7 @@ rc=0
 n_probe=0 n_ident=0 n_differ=0 n_raise=0 n_silent=0 n_waived=0
 waived_seen=""
 n_pin=0 n_pin_ok=0 n_pin_broke=0 n_misattr=0
+n_unrun=0 unrun_list=""
 differ_list="" silent_list="" pin_list="" misattr_list=""
 n_skipped=0 skipped_list=""
 
@@ -348,20 +494,30 @@ n_skipped=0 skipped_list=""
 # — `eigen_eval_loss` reported as "raised by the wrong guard: undefined
 # variable" in a default build. A sibling list of file names drifts from the
 # Makefile exactly the way §1 of mechanical-gates describes.
+# The guarded-name extractor, shared by the variant-only scan and the
+# cross-check so the two cannot disagree about what a guard looks like.
+# Every strict spelling counts: ARG_GUARD and its taped forms, the coercion
+# shape STRICT_REQUIRE (#971 Phase B — sites the classifier cannot see), the
+# domain shape STRICT_DOMAIN and the NaN sources num_guard_named (#971
+# NaN enumeration). The first quoted string in the call is the name.
+extract_guard_names() {
+    awk '
+    /(ARG_GUARD(_TAPED|_PRETAKE)?|STRICT_REQUIRE|STRICT_DOMAIN|num_guard_named)\(/ { acc = ""; collecting = 1 }
+    collecting { acc = acc $0; if (acc ~ /\);[ \t]*$/ || $0 ~ /\);/) {
+        collecting = 0
+        n = split(acc, parts, "\"")
+        if (n >= 2) print parts[2]
+    } }
+    ' "$@"
+}
+
 release_srcs="$(make print-SRC_V_release 2>/dev/null | tr ' ' '\n' | sed '/^$/d' | sort -u)"
 variant_only=""
 if [ -n "$release_srcs" ]; then
     for f in src/*.c; do
         printf '%s\n' "$release_srcs" | grep -qxF "$f" && continue
         variant_only="$variant_only
-$(awk '
-    /ARG_GUARD(_TAPED|_PRETAKE)?\(/ { acc = ""; collecting = 1 }
-    collecting { acc = acc $0; if (acc ~ /\);[ \t]*$/ || $0 ~ /\);/) {
-        collecting = 0
-        n = split(acc, parts, "\"")
-        if (n >= 2) print parts[2]
-    } }
-' "$f")"
+$(extract_guard_names "$f")"
     done
     variant_only="$(printf '%s\n' "$variant_only" | sed '/^$/d' | sort -u)"
 else
@@ -392,8 +548,9 @@ probe_builtin_present() {
     return 0
 }
 
-while IFS='|' read -r who prog; do
+while IFS='|' read -r who prog expect; do
     [ -z "${who:-}" ] && continue
+    expect="${expect:-$who: expected}"
     # A probe for a builtin this build does not contain would "not raise" for
     # the uninteresting reason that the name is undefined, which reads as a
     # guard that went silent. Skip it, and COUNT the skip — a probe that
@@ -430,7 +587,12 @@ while IFS='|' read -r who prog; do
 
     s="$(run_capture "$NEW" 1 "$f")"
     s_rc="${s%%$'\n'*}"
-    if [ "$s_rc" != "0" ]; then
+    why="$(run_did_not_measure "$s_rc")"
+    if [ -n "$why" ]; then
+        n_unrun=$((n_unrun + 1))
+        unrun_list="$unrun_list
+    $who — $why: $(printf '%s' "$s" | tr '\n' ' ' | cut -c1-70)"
+    elif [ "$s_rc" != "0" ]; then
         # A nonzero exit is NOT enough. A probe that raises somewhere else
         # entirely — an arity error before the type guard, an unconditional
         # rt_error higher up — scores as coverage while testing nothing. So
@@ -447,13 +609,21 @@ while IFS='|' read -r who prog; do
         # The FULL who, not its first component: the shared tensor helpers
         # are registered as "sqrt/exp/log/negative" and emit that verbatim,
         # so trimming at the slash made the matcher miss its own message.
-        if printf '%s' "$s" | grep -qF "$who: expected"; then
-            n_raise=$((n_raise + 1))
-        else
+        # A shell substring match, NOT `printf ... | grep -q`: under
+        # `set -o pipefail` that pipe is a race — grep -q exits on its first
+        # match and closes the pipe, and if the multi-line error text (message
+        # + source excerpt + caret) is still being written the writer takes
+        # SIGPIPE, the pipeline reports failure, and a correctly attributed
+        # raise is scored MISATTRIBUTED. Fired once in 6 runs under load
+        # (text_builder_to_string, 2026-09-06) and made [99s] flake red.
+        case "$s" in
+            *"$expect"*) n_raise=$((n_raise + 1)) ;;
+            *)
             n_misattr=$((n_misattr + 1))
             misattr_list="$misattr_list
     $who — raised, but not by its own guard: $(printf '%s' "$s" | tr '\n' ' ' | cut -c1-70)"
-        fi
+            ;;
+        esac
     else
         n_silent=$((n_silent + 1))
         silent_list="$silent_list
@@ -466,7 +636,12 @@ while IFS='|' read -r label prog; do
     n_pin=$((n_pin + 1))
     f="$TMP/pin.eigs"; printf '%s\n' "$prog" > "$f"
     s="$(run_capture "$NEW" 1 "$f")"
-    if [ "${s%%$'\n'*}" = "0" ]; then
+    why="$(run_did_not_measure "${s%%$'\n'*}")"
+    if [ -n "$why" ]; then
+        n_unrun=$((n_unrun + 1))
+        unrun_list="$unrun_list
+    pin: $label — $why"
+    elif [ "${s%%$'\n'*}" = "0" ]; then
         n_pin_ok=$((n_pin_ok + 1))
     else
         n_pin_broke=$((n_pin_broke + 1))
@@ -519,6 +694,7 @@ if [ "${1:-}" = "--sweep" ] || [ "${2:-}" = "--sweep" ]; then
     done
     echo "  quiet=$quiet loud=$loud skipped=$skipped (skipped = side-effecting/blocking, see SKIP above)"
     echo "  A QUIET row is a CANDIDATE, not a defect: read the function before acting."
+    verdict_printed=1   # the sweep's verdict IS its listing; it is not a gate
     exit 0
 fi
 
@@ -554,14 +730,7 @@ fi
 # "guarded but unprobed" hole this cross-check exists to detect, living inside
 # the cross-check. Caught when three freshly added guards reported as STALE
 # PROBES rather than as newly covered ones.
-guarded="$(awk '
-    /ARG_GUARD(_TAPED|_PRETAKE)?\(/ { acc = ""; collecting = 1 }
-    collecting { acc = acc $0; if (acc ~ /\);[ \t]*$/ || $0 ~ /\);/) {
-        collecting = 0
-        n = split(acc, parts, "\"")
-        if (n >= 2) print parts[2]
-    } }
-' src/*.c | sed '/^$/d' | sort -u)"
+guarded="$(extract_guard_names src/*.c | sed '/^$/d' | sort -u)"
 probed="$(printf '%s\n' "$PROBES" | cut -d'|' -f1 | sed '/^$/d' | sort -u)"
 
 # Names absent from THIS build (computed above by execution) are excused for
@@ -589,6 +758,7 @@ else
     echo "  identical-when-off: SKIPPED (no baseline binary given)"
 fi
 echo "  raises-under-strict: $n_raise   silent: $n_silent   misattributed: $n_misattr"
+[ "$n_unrun" -gt 0 ] && echo "  probes that did not run: $n_unrun"
 echo "  answer-pins held: $n_pin_ok   broken: $n_pin_broke"
 if [ -n "$BASE" ]; then
     echo "  valid-input rows unchanged in BOTH modes: $((n_valid * 2 - $(printf '%s' "$valid_list" | grep -c '\[strict=' || true))) / $((n_valid * 2))"
@@ -599,6 +769,10 @@ fi
 [ -n "$differ_list" ] && { echo "  DIFFERING (the default path was NOT preserved):$differ_list"; rc=1; }
 [ -n "$silent_list" ] && { echo "  SILENT UNDER STRICT:$silent_list"; rc=1; }
 [ -n "$misattr_list" ] && { echo "  RAISED BY THE WRONG GUARD (probe does not reach its target):$misattr_list"; rc=1; }
+# NOT a finding about a guard, and said in those words so the reader goes to the
+# machine and not to the probe table. Still red: an unmeasured probe leaves the
+# invariant unproven, and this tool does not go green on unmeasured population.
+[ -n "$unrun_list" ]  && { echo "  DID NOT RUN (the environment, not a guard — nothing is retried):$unrun_list"; rc=1; }
 [ -n "$valid_list" ]  && { echo "  VALID INPUT CHANGED (a guard is too broad, or a split reordered a real branch):$valid_list"; rc=1; }
 [ -n "$pin_list" ]    && { echo "  PIN BROKEN (the reform overshot into a documented answer):$pin_list"; rc=1; }
 [ -n "$missing" ]     && { echo "  GUARDED BUT UNPROBED:"; printf '    %s\n' $missing; rc=1; }
@@ -621,7 +795,7 @@ fi
 # other, and neither is the instability check.
 if [ -n "$BASE" ]; then
     for w in $EXPECTED_DIVERGE_FIXED; do
-        wprog="$(printf '%s\n' "$PROBES" | grep -F "$w|" | head -1 | cut -d'|' -f2-)"
+        wprog="$(printf '%s\n' "$PROBES" | grep -F "$w|" | head -1 | cut -d'|' -f2)"
         [ -z "$wprog" ] && continue
         printf '%b\n' "$wprog" > "$TMP/w.eigs"
         probe_builtin_present "$w" || { echo "  waiver not exercised: $w is not in this build"; continue; }
@@ -646,7 +820,7 @@ fi
 
 if [ -n "$BASE" ]; then
     for w in $EXPECTED_DIVERGE_UNSTABLE; do
-        wprog="$(printf '%s\n' "$PROBES" | grep -F "$w|" | head -1 | cut -d'|' -f2-)"
+        wprog="$(printf '%s\n' "$PROBES" | grep -F "$w|" | head -1 | cut -d'|' -f2)"
         if [ -n "$wprog" ]; then
             printf '%b\n' "$wprog" > "$TMP/w.eigs"
             r1="$(run_capture "$BASE" - "$TMP/w.eigs")"
@@ -713,5 +887,6 @@ if [ "$NO_BASELINE" = 1 ]; then
     echo "        of the parent commit — that half is the safety claim."
 fi
 
+verdict_printed=1
 [ "$rc" = 0 ] && echo "OK" || echo "FAIL"
 exit $rc

From 25c85dd2c94d3dcb9e1f9879b249f795b31b0676 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 20:17:13 +0000
Subject: [PATCH 21/39] lint: W024 flags an observer read on a binding rebound
 from a container element; document what carries a trajectory; make every lint
 message UTF-8-safe (#1048)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Observer trajectory is keyed to an environment slot (`env_obs_slot`), never
to a Value, so a dict field or list element carries no history and the
obvious per-entity read

    loop while i < n:
        local q is fleet[i][2]        # ONE binding, rebound n times
        if diverging of q: ...

manufactures verdicts: the slot's window is the round-robin interleave of
every entity it visits. Repro on v0.43.0 (two entities, one decaying by
x0.9 per step, one sign-flipping, 40 steps):

    shared binding entity 0: oscillating      # the DECAYING entity
    named bindings a: improving   b: oscillating
    for-body local entity 0/1: equilibrium
    closure entity 0: improving   1: oscillating
    $ eigenscript --lint p1.eigs -> no issues found

After, on the same file:

    p1.eigs:8: warning[W024]: 'q' is rebound from 'fleet[..][..]' each
    iteration: 'report_value of q' judges the round-robin of every element
    it visits, not one entity (#1048) — use one named binding or one
    closure per entity

The rule (src/lint.c, `check_container_rebind`), per loop with innermost-
owner attribution: a name (re)bound from a PROJECTION of an element that
walks the loop — `fleet[i][2]`, `chans[i].a`, `for ent in fleet: ent.v`, a
destructure `[n, k, v] is fleet[i]`, or a field of a base rebound from such
an element (`ch is chans[i]` then `ch.a`), transitively — plus an observer
read of it (`<predicate> of q`, `report`/`report_value`/`observe`/
`trajectory of q`) anywhere in that loop (nested function bodies excluded).
The projection may sit under arithmetic whose other operands are inert (a
literal, a name the loop never assigns, another projection), because that is
the spelling the reporting consumer ships: phugoid rung 4 writes `local qobs
is fleet[i][2] + 0.0`. An accumulator (`total is total + fleet[i].v`) is not
that shape and stays silent, and neither is a base rebound from a call
(`s is step of s`, then `s[0] + 0.0` — one entity over time). A flat `xs[i]`
deliberately does NOT fire: subscripting a scalar list by the counter is how
lib/experiment.eigs and lib/simulation.eigs replay a recorded series through
one binding, and that IS one trajectory (a per-entity scalar list read the
same way is the named residual).

The asymmetry from the issue's last comment, measured with `when is q`
rather than taken from the report: a module-level `for`-body `local` is
fresh each iteration on every tier (closure in body, interrogated binder,
nested in if/try/match, loaded module: when=1) so every read answers
`equilibrium`; inside ANY function it is a frame slot that persists
(when=30) and interleaves like a `loop while` binding; a plain `for`-body
assignment creates in the enclosing scope and persists. W024 names each case
with its own text and both runtime facts are pinned by the test.

The first cut of W024 introduced a defect of its own. `LintWarning.message`
is 256 bytes and W024 is the first rule to interpolate an unbounded
identifier twice, so a ~37-character name (`_cumulative_mean_normalized_
difference` = 38; `diagnostic_header_unterminated_text_concat` = 42) pushed
the message over and `vsnprintf` cut it INSIDE the em dash of the remedy
clause:

    $ eigenscript --lint --json long37.eigs | python3 -c "import sys,json; json.loads(sys.stdin.buffer.read())"
    UnicodeDecodeError: 'utf-8' codec can't decode byte 0xe2 in position 332

`jq` hides exactly this (it substitutes U+FFFD), and `eigenlsp` publishes the
same strings over JSON-RPC. Separately `w024_render`'s `char[32]` buffer cut
the container spelling and dropped its `[..][..]`, so a 41-character list
name read `rebound from 'diagnostic_header_unterminated_'` — a name that
appears nowhere in the program, describing the whole list rather than a
projection of one element.

The message is not what gets cut; the IDENTIFIERS are. `w024_emit` renders
with an identifier budget that shrinks (128 -> 8) until the whole message
fits, and each identifier is clipped with a MIDDLE ellipsis on UTF-8
boundaries. The direction is deliberate: a clipped identifier is recoverable
(the diagnostic cites the line and the name is in the source), a clipped
remedy is not, and a middle ellipsis is what keeps `fleet[..][..]` from
degrading to `fleet`. `w024_render` now measures the suffix chain first and
gives the base name what is left, so the projection marker survives any base
length.

Underneath that, two chokepoints make the guarantee hold for rules that do
not exist yet: `lint_vdiag` renders into a scratch and copies through
`lint_copy_utf8`, which truncates on a character boundary and marks the cut
with `...`; `lint_json_escape` clips whole characters only. So a message can
be shortened but never halved mid-character, whatever it interpolates.

**This was never W024-only.** Sweeping identifier length 1..250 against
v0.43.0 — the release before this change — three shipped rules already emit
invalid UTF-8 on BOTH channels: W015 at a 74-character name, W023 at 161-162,
W018 at 198-199 (W024 at 56). Each band is one or two lengths wide out of
250, which is why "no pre-existing rule is long enough" was the wrong
argument and why the gate sweeps instead of sampling.

Gate: `tools/lint_message_utf8_check.sh` (suite section `[81u]`, ~20s) drives
every documented code with a 200-character identifier from
`tests/lint_utf8/`, decodes `--lint --json` strictly with python3 (never jq),
requires each fixture to actually PRODUCE its code, checks the registry in
three directions (documented -> fixture-or-pinned-exemption, fixture -> doc
row, and code emitted by the lint TUs -> doc row, which is what makes a
future rule enrol), re-verifies each of the 8 pinned exemptions (the empty-
block codes are unreachable because the parser demands a statement — the
probe re-checks that), sweeps the four longest messages over 250 identifier
lengths on both channels, and asserts the two chokepoints are still the only
writers. `--selftest` plants six faults and requires each to be caught.

Regression tests (tests/test_lint.sh, section [81], 232 checks): the issue's
shape, the four other spellings, the three arithmetic spellings, the runtime
proof (shared -> `oscillating`, named -> `improving` for the same entity),
the named-binding and closure forms silent, the accumulator and call-rebound
negatives silent, six correct negatives silent with exit 0, the module/
function `for` variants, `when is` = 1 vs 30, `# lint: allow W024`, the 38-
and 200-character cases decoded strictly on both channels with the remedy
clause and the `[..][..]` suffix asserted present, the lexer's rejection of a
non-ASCII identifier (which is why every fixture is ASCII), and the
PREDICATES.md closure recipe EXTRACTED from the doc — not copied — with a
vacuity guard, executed (prints `improving oscillating`), linted clean, and
its printed-output comment pinned. Planted faults: reverting both chokepoints
and the shrink-to-fit reddens 5 test checks and 5 gate checks including the
sweep at len=56 on both channels; restoring the pre-fix `w024_render` reddens
exactly one check and reproduces `rebound from 'diagnostic_header_
unterminated_'`; unregistering the check reddens 13+3 positives with every
negative still green; dropping only the arithmetic descent reddens exactly
the 3 arithmetic checks.

Sweeps with `--lint`: 507 in-tree `.eigs` (lib/ tests/ examples/, excluding
the deliberate fixtures in tests/lint_utf8/) — output byte-identical to the
v0.43.0 baseline binary, 0 W024; 721 `.eigs` across the 15 consumer repos on
this box — 2 hits, both the originating code (phugoid `swarm.eigs:98,130`,
`tests/swarm_profile.eigs:65`).

Docs: DIAGNOSTICS.md W024 row and the `--json` contract paragraph (every
message is valid UTF-8; a clip lands on a character boundary and is marked
`...`; rules that interpolate unbounded text budget it themselves);
PREDICATES.md "What carries a trajectory" (the table, the closure-per-entity
recipe); OBSERVER.md pointer table; llms.txt one line; ROADMAP.md
"Container-keyed observer trajectory" with the mechanism, the ask, the layers
it touches (compiler operand forms, VM observer updates and the #915 reader
scan, JIT inline caches, tape/step/DAP/SIGUSR1, the AOT mirror) and the open
design questions. Container-keyed trajectory itself is not built in this
round.

Closes #1048

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
(cherry picked from commit ad79dcb73cf1e1c1dc130e19a06ab8896ea39582)
---
 ROADMAP.md                       |  30 ++
 docs/DIAGNOSTICS.md              |  14 +
 docs/OBSERVER.md                 |  16 +
 docs/PREDICATES.md               |  70 +++
 docs/llms.txt                    |   8 +-
 src/lint.c                       | 753 ++++++++++++++++++++++++++++++-
 src/lint_host.c                  |   9 +
 src/lint_internal.h              |   7 +
 tests/lint_utf8/E002.eigs        |   2 +
 tests/lint_utf8/E003.eigs        |   1 +
 tests/lint_utf8/E004.eigs        |   1 +
 tests/lint_utf8/E005.eigs        |   3 +
 tests/lint_utf8/W001.eigs        |   1 +
 tests/lint_utf8/W002.eigs        |   3 +
 tests/lint_utf8/W003.eigs        |   4 +
 tests/lint_utf8/W010.eigs        |   2 +
 tests/lint_utf8/W012.eigs        |   2 +
 tests/lint_utf8/W013.eigs        |   3 +
 tests/lint_utf8/W014.eigs        |   6 +
 tests/lint_utf8/W015.eigs        |   6 +
 tests/lint_utf8/W016.eigs        |   4 +
 tests/lint_utf8/W017.eigs        |   4 +
 tests/lint_utf8/W018.eigs        |   5 +
 tests/lint_utf8/W019.eigs        |   2 +
 tests/lint_utf8/W020.eigs        |   4 +
 tests/lint_utf8/W021.eigs        |   3 +
 tests/lint_utf8/W022.eigs        |   4 +
 tests/lint_utf8/W023.eigs        |   8 +
 tests/lint_utf8/W024.eigs        |   6 +
 tests/run_all_tests.sh           |  21 +
 tests/test_lint.sh               | 438 ++++++++++++++++++
 tools/lint_message_sweep.py      |  93 ++++
 tools/lint_message_utf8_check.sh | 303 +++++++++++++
 33 files changed, 1834 insertions(+), 2 deletions(-)
 create mode 100644 tests/lint_utf8/E002.eigs
 create mode 100644 tests/lint_utf8/E003.eigs
 create mode 100644 tests/lint_utf8/E004.eigs
 create mode 100644 tests/lint_utf8/E005.eigs
 create mode 100644 tests/lint_utf8/W001.eigs
 create mode 100644 tests/lint_utf8/W002.eigs
 create mode 100644 tests/lint_utf8/W003.eigs
 create mode 100644 tests/lint_utf8/W010.eigs
 create mode 100644 tests/lint_utf8/W012.eigs
 create mode 100644 tests/lint_utf8/W013.eigs
 create mode 100644 tests/lint_utf8/W014.eigs
 create mode 100644 tests/lint_utf8/W015.eigs
 create mode 100644 tests/lint_utf8/W016.eigs
 create mode 100644 tests/lint_utf8/W017.eigs
 create mode 100644 tests/lint_utf8/W018.eigs
 create mode 100644 tests/lint_utf8/W019.eigs
 create mode 100644 tests/lint_utf8/W020.eigs
 create mode 100644 tests/lint_utf8/W021.eigs
 create mode 100644 tests/lint_utf8/W022.eigs
 create mode 100644 tests/lint_utf8/W023.eigs
 create mode 100644 tests/lint_utf8/W024.eigs
 create mode 100644 tools/lint_message_sweep.py
 create mode 100755 tools/lint_message_utf8_check.sh

diff --git a/ROADMAP.md b/ROADMAP.md
index 31b5b20e..95b062f8 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -134,6 +134,36 @@ observer/deterministic-replay niche instead of diluting it.**
 - [x] `ext_net` raw TCP/UDP sockets as tape-recorded nondet inputs —
       record/replay networking no incumbent stdlib has
       ([#414](https://github.com/InauguralSystems/EigenScript/issues/414))
+- [ ] **Container-keyed observer trajectory** — dict fields and list
+      elements carrying their own observer slot, keyed by (container
+      identity, key) ([#1048](https://github.com/InauguralSystems/EigenScript/issues/1048)).
+      *Mechanism today:* trajectory lives on an environment slot
+      (`env_obs_slot(Env *e, int idx)` → `e->obs[idx]`; the Value carries no
+      observer state), so per-entity observation needs one persistent
+      binding per entity — a named local or a closure per entity (the
+      recommended form; docs/PREDICATES.md "What carries a trajectory").
+      *The ask:* let `fleet[i][2] is v` / `ch.a is v` update a slot owned by
+      the container entry, so `diverging of fleet[i][2]` answers about that
+      entity — the form a consumer reaches for first (phugoid rung 4), whose
+      current failure is silent: one binding rebound per entity carries the
+      round-robin interleave and manufactures verdicts (lint `W024` now
+      names it; the module-level `for`-body `local` answers `equilibrium`
+      instead, the same rule from the other side). *Layers it touches:* the
+      compiler (new predicate/`report`/`trajectory` operand forms over
+      index/field expressions, today `E005` for the report words), the VM
+      (`OP_INDEX_SET`/`OP_DOT_SET` observer update + reader opcodes and the
+      observer gate's reader scan, #915), the JIT inline caches on dict
+      fields and indexed stores, `trajectory of` snapshots, the tape /
+      `--step` / DAP / SIGUSR1 dump (a slot per entry to record and
+      replay), and the AOT mirror in ouroboros. *Open design questions:*
+      list insert/remove shifts identities (is the slot keyed by position
+      or by the element's identity, and what does `sort` do to a history?);
+      lazy slot allocation keyed by statically-named fields only (`ch.a`)
+      versus every dynamic key (memory: a slot per entry of every observed
+      container, or an opt-in `observed` container); whether the container
+      or the entry owns the slot when the entry is itself a container; and
+      the tape format for per-entry observer records. Deliberately not
+      built in the same round as `W024` — needs its own design pass.
 
 ### Design decisions (cheap to decide, expensive to defer)
 
diff --git a/docs/DIAGNOSTICS.md b/docs/DIAGNOSTICS.md
index ba32f4ef..8027699e 100644
--- a/docs/DIAGNOSTICS.md
+++ b/docs/DIAGNOSTICS.md
@@ -273,6 +273,7 @@ a code's meaning never changes, and retired codes are not reused.
 | `W021` | hint | Function definition shadows a **public stdlib function** from a module the file never imported (`define 'median' shadows lib/stats.eigs 'median' (import stats to use it)`) — a discoverability nudge toward `lib/*.eigs` (#591), sibling of `W013` (which covers compiled-in builtins; a name that is both stays `W013`-only). The name table is scraped from the public top-level defines of the same `lib/` directories the import resolver searches; the hint stays silent when the module is imported, and when the linted file *is* the module that ships the name. Name-only matching has false positives (a deliberately-different local `mean`), so this is hint-severity: advisory, **never fails `--lint`** under either `--lint-level`, and suppressible like any other code. |
 | `W022` | warning | A bare literal argument list with **more elements than the callee's parameters** — with `define two(a, b)`, `two of [1, 2, 99]` passes 3 arguments to a 2-parameter callee (#733). Since #974 the runtime raises a catchable `value`-kind error at that call site (`call passes 3 arguments but the callee takes 2`); this warning catches the same mistake earlier, statically, without running the program. Conservative by construction, and **same-file only**: it fires only when the callee name provably has one meaning in the file — exactly one `define` of it anywhere and no other binding (assignment, param, lambda param, loop/comprehension var, catch name, list-pattern name, import, or any identifier inside a `match` pattern poisons the name), so a call into an imported module's callee is never checked here — cross-module over-arity reaches the runtime raise instead. One-parameter callees are exempt by the #405 semantics themselves: a 2+-element bare list binds WHOLE to a single parameter — nothing is dropped, and that shape is the deliberate variadic idiom (`reverse of [1, 2, 3]`). Parenthesized lists (`f of ([...])`) are a single argument and never fire. |
 | `W023` | warning | A direct bare assignment in one `if`/`elif`/`else` sibling branch has a `local` assignment in another branch and may mutate an outer module binding (#870). It fires only when the compiler-shaped model proves a module name and finds no parameter, captured/interrogated/env-bound name, dominating same-environment binder, or enclosing binder; unknown shapes stay silent (including the documented enclosing-`catch` false negative). |
+| `W024` | warning | An observer read (`<predicate> of q`, `report` / `report_value` / `observe` / `trajectory of q`) on a binding that the same loop rebinds from a **projection of an element that walks the loop** — `local q is fleet[i][2]`, `q is chans[i].a`, `for ent in fleet: q is ent.v`, `[n, k, v] is fleet[i]`, or a field of a base rebound from such an element (`ch is chans[i]` then `ch.a`) — with the read anywhere in that loop (#1048). The projection may sit under arithmetic with inert operands (`fleet[i][2] + 0.0`, `-fleet[i][2]`, `fleet[i][2] * scale` where the loop never assigns `scale`), which is the spelling the reporting consumer ships; an accumulator (`total is total + fleet[i].v`) is not that shape and stays silent. Observer trajectory lives on an environment slot, never on a Value, so a dict field or list element carries no history and the one binding's window becomes the **round-robin interleave** of every entity it visits: a monotonically decaying entity reads `oscillating`, with no diagnostic (phugoid rung 4 shipped this in every arm). The message names the two working forms — one named binding per entity, or one closure per entity — see [PREDICATES, What carries a trajectory](PREDICATES.md#what-carries-a-trajectory). A **module-level `for`-body `local`** is the opposite failure and gets its own text: the loop env is cleared each iteration, so the slot holds one observation and every read answers `equilibrium` (predicates: false) — that variant fires for any RHS when the `local` is the name's only assignment in the loop; inside a function a `for`-body `local` is a persisting frame slot and is treated like a `loop while` binding (both measured with `when is q`). Conservative by construction, and the residuals are named: a fixed field or element (`game.energy`, `xs[0]`) never fires — that is the documented way to give a field a trajectory; a base rebound from a call (`state is step of state`) never fires; a subscript that is not counter arithmetic (`xs[len of xs - 1]`) never fires; a **flat `xs[i]`** never fires, because subscripting a scalar list by the counter is also how a recorded series is replayed through one binding to classify it (`lib/experiment.eigs`, `lib/simulation.eigs`) — so a per-entity *scalar* list read the same way (`energies[i]`) is the one interleave this rule cannot see; reads outside the loop, interrogatives (`why is q`) and reads of the `for` binder itself are not covered. |
 
 The human linter output carries the code inline:
 
@@ -305,6 +306,19 @@ so `--lint --json 2>/dev/null` is pure JSON). Each element is:
 - Exit code follows `--lint-level` (see below); the default fails on any
   surviving warning.
 
+- **Every `message` is valid UTF-8, whatever it interpolates.** Messages are
+  assembled in a fixed 256-byte buffer, so a rule that interpolates a long
+  identifier can have its message clipped — but the clip always lands on a
+  character boundary and is marked with a trailing `...`, never inside a
+  multi-byte sequence. This is a consumer-visible contract: a byte-level cut
+  produced a payload strict decoders reject while `jq` silently substituted
+  U+FFFD (#1048), and `eigenlsp` publishes the same strings over JSON-RPC.
+  Rules that interpolate unbounded text are expected to budget it themselves
+  so the actionable half of the message survives — `W024` shrinks the
+  identifiers it quotes (middle ellipsis) rather than let the remedy be cut.
+  `tools/lint_message_utf8_check.sh` drives every code above with a
+  200-character identifier and decodes the result strictly.
+
 The `--json` flag may appear before or after the path. Runtime errors are
 not part of `--lint` — it compiles the program but never runs it.
 
diff --git a/docs/OBSERVER.md b/docs/OBSERVER.md
index 2c8e53c8..2a611d43 100644
--- a/docs/OBSERVER.md
+++ b/docs/OBSERVER.md
@@ -85,6 +85,22 @@ Two of these are the load-bearing pair:
 Everything the observer "experiences" is one continuous quantity (`why`)
 and its sign. It has no words. The words come from the oracle.
 
+### What carries a trajectory
+
+Everything above is keyed to an **environment slot** (`env_obs_slot`) — the
+Value carries no observer state. A binding has a history; a container
+element does not (#1048):
+
+| carries a trajectory | does not |
+|---|---|
+| a named local; a closure-captured local (one factory call per entity); an `eval`-generated name | a dict field `ch.a`; a list element `xs[0]`; a function parameter; a `for` binder; a `for`-body `local` at module level (cleared each iteration) |
+
+And one binding rebound from a *different* element each iteration
+(`loop while i < n: local q is fleet[i][2]`) carries the interleave of all of
+them — a verdict about nothing. Lint `W024` flags that shape; the full table,
+the module-level-`for` asymmetry and the closure-per-entity recipe are in
+[PREDICATES, What carries a trajectory](PREDICATES.md#what-carries-a-trajectory).
+
 ## The oracle: where names come from
 
 The observer's experience is a smooth, continuous signal. Turning that
diff --git a/docs/PREDICATES.md b/docs/PREDICATES.md
index 43819fea..dfdb182e 100644
--- a/docs/PREDICATES.md
+++ b/docs/PREDICATES.md
@@ -845,6 +845,76 @@ loop while not (converged of x):
   deadband (`dh_zero`, default 0.1% relative). For a tighter answer,
   lower it first: `set_observer_thresholds of [1e-6, 1e-5, 0.1]`.
 
+## What carries a trajectory
+
+Observer trajectory is keyed to an **environment slot** — `env_obs_slot(Env *e,
+int idx)` returns `e->obs[idx]`, and the Value itself carries no observer
+state. So every predicate, `report`, `report_value`, `observe` and
+`trajectory of x` answer about a *binding*, and only a binding that persists
+across the observations has a history to classify (#1048). Every case
+follows from that one rule:
+
+| form | persistent env slot? | trajectory |
+|---|---|---|
+| a named local (`q is v`, `local q is v`) | yes | **carries** |
+| a closure-captured local (one factory call per entity) | yes — each call is its own `Env` | **carries**, N chosen at runtime |
+| an `eval`-generated name | yes | carries, N chosen at runtime (loses lint and the AOT — prefer the closure) |
+| a dict field `ch.a` | no — a Value in a container | none: `equilibrium`, no history |
+| a list element `xs[0]` | no — a Value in a container | none |
+| a function parameter | the frame dies each call | none: one observation per call |
+| a `for` binder `for x in xs:` | fresh each iteration (#1062) | none |
+| a `for`-body `local` **at module level** | the loop env is cleared each iteration | none: one observation, every read answers `equilibrium` |
+| a `for`-body `local` **inside a function** | a frame slot that persists for the loop | carries — and **interleaves** if fed several entities |
+| a `for`-body plain `q is …` | creates in the enclosing scope, persists | carries — and interleaves |
+| a `loop while`-body binding (plain or `local`) | one env, persists | carries — and interleaves |
+
+The last three rows are the sharp edge. The obvious per-entity read
+
+```eigenscript
+loop while i < n:
+    local q is fleet[i][2]        # ONE binding, rebound n times
+    if diverging of q: ...
+```
+
+does not lose resolution — it **manufactures verdicts**: the slot's window is
+the round-robin interleave of every entity it visits, so a monotonically
+decaying entity reads `oscillating`. Lint `W024` names this shape — including
+the common `local q is fleet[i][2] + 0.0` spelling, where the projection sits
+under arithmetic — and the module-level `for` variant, whose reads always
+answer `equilibrium`. The
+mirror form is fine: a *fixed* field or element copied into a binding each
+tick (`local e is game.energy`) is exactly how a container field is given a
+trajectory.
+
+**The recommended per-entity form is a closure per entity** — one `Env`, and
+so one slot, per factory call, in ordinary static source that lints and
+compiles like anything else:
+
+```eigenscript
+define make_ch as:
+    local q is 0.0
+    define step(v) as:
+        q is v
+        return report_value of q
+    return step
+
+fleet is [["a", 0, 100.0], ["b", 0, 1.0]]
+chans is [make_ch of [], make_ch of []]
+t is 0
+loop while t < 40:
+    fleet[0][2] is fleet[0][2] * 0.9      # decaying
+    fleet[1][2] is 0.0 - fleet[1][2]      # sign-flipping
+    a is (chans[0]) of fleet[0][2]
+    b is (chans[1]) of fleet[1][2]
+    t is t + 1
+print of (a + " " + b)                    # improving oscillating
+```
+
+A named binding per entity (`qa is fleet[0][2]`, `qb is fleet[1][2]`) is the
+same thing when N is fixed at authoring time. Container-keyed trajectory
+(dict fields and list elements carrying their own slot) is a ROADMAP item,
+not a current capability.
+
 ## Cost
 
 The `dh_window` costs one `xcalloc(N * sizeof(double))` (80 bytes at the
diff --git a/docs/llms.txt b/docs/llms.txt
index 7c9eb303..e43d765b 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -118,7 +118,13 @@ print of ("sqrt(2) = " + (str of (newton_sqrt of 2)))   # sqrt(2) = 1.4142135623
   zero reads `improving` until inside the scale. A mode slower than N samples
   of your cadence cannot fold in the window — `set_observer_window of ["x", n]`
   (4..64; default 10, `set_observer_window of n`) so N >= period/step.
-  Don't guess the predicate — see docs/PREDICATES.md.
+- Trajectory is keyed to a binding's env slot, never to a value: a dict field,
+  list element, parameter or `for` binder has none, and ONE binding rebound
+  from `fleet[i][2]` in a loop carries the interleave of every entity (lint
+  `W024`) — give each entity its own named binding or a closure per entity.
+- `converged` needs LOW absolute entropy on top of a settled window: a value
+  pinned at `5.0` reports `stable`, never `converged`; pinned at `0.0`/`1.0` it
+  converges. Don't guess the predicate — see docs/PREDICATES.md.
 - Temporal reads: `prev of x` (value before the last assignment),
   `what is x at 12` / `state_at of 12` (past-line state). Bare `x at 12` is a
   parse error. Wrap hot loops in `unobserved:` to skip the observer's entropy
diff --git a/src/lint.c b/src/lint.c
index 502f6fac..273eef3a 100644
--- a/src/lint.c
+++ b/src/lint.c
@@ -8,6 +8,45 @@
 
 /* ---- Lint warning storage ---- */
 
+/* Length of the longest prefix of `s` that is at most `max` bytes AND ends on
+ * a UTF-8 character boundary. A cut inside a multi-byte sequence leaves a
+ * lone lead/continuation byte, which is not valid UTF-8: `--lint --json` then
+ * emits a payload a strict decoder rejects (Python raises; jq silently
+ * substitutes U+FFFD, which is how it hides) and the LSP publishes that byte
+ * inside a JSON-RPC message. #1048. Invalid input is handled the same way —
+ * an incomplete or stray sequence at the cut is dropped, never halved. */
+size_t lint_utf8_prefix(const char *s, size_t max) {
+    if (!s) return 0;
+    size_t n = strlen(s);
+    if (n > max) n = max;
+    /* Back up to the last byte that STARTS a character; a lone lead byte at
+     * the cut counts (a bare 0xE2 is exactly the #1048 payload). */
+    size_t i = n;
+    while (i > 0 && ((unsigned char)s[i - 1] & 0xC0) == 0x80) i--;
+    if (i == 0) return 0;                      /* only continuation bytes */
+    unsigned char lead = (unsigned char)s[i - 1];
+    size_t need = lead < 0xC0 ? 1 : lead < 0xE0 ? 2 : lead < 0xF0 ? 3 : 4;
+    return (i - 1 + need == n) ? n : i - 1;    /* complete: keep. cut: drop it */
+}
+
+/* Copy `src` into `dst` (`cap` bytes), truncating on a UTF-8 boundary and
+ * marking the cut with "..." so a clipped message says so. Every diagnostic
+ * in the tree funnels through lint_vdiag, so this is the whole-class
+ * guarantee: no lint rule, present or future, can emit malformed UTF-8 no
+ * matter what it interpolates. Individual rules must still keep their
+ * ACTIONABLE half inside the budget — a truncation here is valid output but
+ * a worse message (see w024_emit's shrink-to-fit). */
+static void lint_copy_utf8(char *dst, size_t cap, const char *src) {
+    if (!dst || cap == 0) return;
+    if (!src) { dst[0] = '\0'; return; }
+    size_t keep = lint_utf8_prefix(src, cap - 1);
+    if (keep == strlen(src)) { memcpy(dst, src, keep); dst[keep] = '\0'; return; }
+    if (cap < 5) { dst[0] = '\0'; return; }
+    keep = lint_utf8_prefix(src, cap - 4);
+    memcpy(dst, src, keep);
+    memcpy(dst + keep, "...", 4);
+}
+
 static void lint_vdiag(LintContext *ctx, int line, int col, int len,
                        const char *level,
                        const char *code, const char *fmt, va_list ap) {
@@ -18,7 +57,12 @@ static void lint_vdiag(LintContext *ctx, int line, int col, int len,
     w->len  = len;
     snprintf(w->level, sizeof(w->level), "%s", level);
     snprintf(w->code, sizeof(w->code), "%s", code);
-    vsnprintf(w->message, sizeof(w->message), fmt, ap);
+    /* Render first, then copy on a character boundary: vsnprintf straight
+     * into w->message would cut mid-sequence (#1048). The scratch can itself
+     * clip a pathological message; lint_copy_utf8 repairs either cut. */
+    char rendered[1024];
+    vsnprintf(rendered, sizeof(rendered), fmt, ap);
+    lint_copy_utf8(w->message, sizeof(w->message), rendered);
 }
 
 static void lint_warn(LintContext *ctx, int line, const char *code,
@@ -2789,11 +2833,718 @@ static void check_error_kind_typo(ASTNode *ast, LintContext *ctx) {
     w018_scan(ast, ctx, &sc);
 }
 
+/* ---- W024: observer read on a binding rebound from a container element ---- */
+
+/* Observer trajectory lives on an ENVIRONMENT SLOT (`env_obs_slot`), never on
+ * a Value: a dict field or list element carries no history, so the obvious
+ * per-entity read
+ *
+ *     loop while i < n:
+ *         local q is fleet[i][2]     # ONE binding, rebound n times
+ *         if diverging of q: ...
+ *
+ * does not lose resolution — it MANUFACTURES verdicts. The single slot's
+ * window is the round-robin interleave of every entity it visits, so a
+ * monotonically decaying entity reads `oscillating` (#1048, phugoid rung 4).
+ * The two working forms need one persistent slot per entity: a named
+ * binding per entity, or a closure per entity (`define make_ch as: local q
+ * is 0.0 / define step(v) as: q is v / return report of q`).
+ *
+ * The rule, per loop (each assignment belongs to its innermost loop):
+ *   - a name is (re)bound from a VARYING container read — an index whose
+ *     subscript is a counter (a name assigned somewhere in the loop, or the
+ *     `for` binder), or a field/index of a base that is itself such a read
+ *     (`ch is chans[i]` then `ch.a`), transitively, optionally under
+ *     arithmetic with inert operands (`fleet[i][2] + 0.0`, the spelling the
+ *     reporting consumer ships);
+ *   - and an observer read of that name (`<predicate> of q`, `report`,
+ *     `report_value`, `observe`, `trajectory of q`) sits in the same loop
+ *     (nested `if`/loops included; nested function bodies excluded — a
+ *     different env).
+ * A binding that persists across iterations then interleaves (message A):
+ * every `loop while` binding, a plain `for`-body assignment (it creates in
+ * the enclosing scope), and a `for`-body `local` INSIDE A FUNCTION (a frame
+ * slot). A MODULE-LEVEL `for`-body `local` is the opposite failure: the loop
+ * env is cleared each iteration, so the slot holds one observation and every
+ * read answers `equilibrium` / false (message B) — the asymmetry the issue's
+ * last comment reports. Both were measured with `when is q` (1 vs 30) on
+ * every module-level tier (closure in body, interrogated binder, nested in
+ * if/try/match, loaded module) and every function-level one. Message B
+ * fires for any RHS when the local is the binding's ONLY assignment in the
+ * loop; a local assigned again inside the iteration has a real
+ * intra-iteration trajectory and stays silent.
+ *
+ * Conservative by construction, and the residuals are named: a fixed
+ * container read (`game.energy`, `xs[0]`) never fires — that is the
+ * documented way to give a field a trajectory; a base rebound from a call
+ * (`state is step of state`) never fires; an index that is anything but
+ * counter arithmetic (`xs[len of xs - 1]`) never fires; reads outside the
+ * loop, interrogatives (`why is q`) and reads of the `for` binder itself are
+ * not covered. The one shape it cannot tell apart is a single time series
+ * replayed through one binding (`loop while t < n: s is samples[t]`), which
+ * IS one trajectory — that site carries `# lint: allow W024`. */
+
+#define W024_MAX_NAMES 64
+
+typedef struct {
+    const char *name;
+    ASTNode    *assign;        /* first assignment owned by THIS loop, or NULL */
+    ASTNode    *rhs;           /* its RHS */
+    int         assign_count;  /* assignments to the name in the loop subtree */
+    int         local_only;    /* that first assignment is `local` */
+    int         walks;         /* RHS is an element that walks the loop (any depth) */
+    ASTNode    *proj;          /* the PROJECTION of a walking element it reads — fires */
+    int         destructure;   /* the assignment is a list-pattern destructure */
+    ASTNode    *read;          /* first observer read in the loop subtree */
+    const char *read_form;     /* "diverging of", "report_value of", ... */
+} W024Name;
+
+typedef struct {
+    W024Name    names[W024_MAX_NAMES];
+    int         count;
+    int         overflow;      /* > W024_MAX_NAMES names: fail safe to silence */
+    const char *for_var;       /* the `for` binder, NULL for `loop while` */
+} W024Loop;
+
+static W024Name *w024_entry(W024Loop *lp, const char *name) {
+    if (!name) return NULL;
+    for (int i = 0; i < lp->count; i++)
+        if (strcmp(lp->names[i].name, name) == 0) return &lp->names[i];
+    if (lp->count >= W024_MAX_NAMES) { lp->overflow = 1; return NULL; }
+    W024Name *e = &lp->names[lp->count++];
+    memset(e, 0, sizeof(*e));
+    e->name = name;
+    return e;
+}
+
+/* `<pred> of q` / `report|report_value|observe|trajectory of q` over an
+ * ident: the compiler-resolved slot reads (the same four query names W019
+ * anchors on). Returns the subject name and the form, or NULL. */
+static const char *w024_observer_read(ASTNode *n, const char **subject) {
+    if (!n || n->type != AST_RELATION) return NULL;
+    ASTNode *l = n->data.relation.left, *r = n->data.relation.right;
+    if (!l || !r || r->type != AST_IDENT) return NULL;
+    if (l->type == AST_PREDICATE) {
+        int k = l->data.predicate.kind;
+        static const char *forms[] = {
+            "converged of", "stable of", "improving of",
+            "diverging of", "oscillating of", "equilibrium of" };
+        const char *nm = (k >= 0) ? eigs_predicate_name((unsigned)k) : NULL;
+        if (!nm) return NULL;
+        for (size_t i = 0; i < sizeof(forms) / sizeof(forms[0]); i++)
+            if (strncmp(forms[i], nm, strlen(nm)) == 0 && forms[i][strlen(nm)] == ' ') {
+                *subject = r->data.ident.name;
+                return forms[i];
+            }
+        return NULL;
+    }
+    if (l->type == AST_IDENT) {
+        static const char *names[] = {"report", "report_value", "observe", "trajectory"};
+        static const char *forms[] = {"report of", "report_value of", "observe of", "trajectory of"};
+        for (size_t i = 0; i < sizeof(names) / sizeof(names[0]); i++)
+            if (strcmp(l->data.ident.name, names[i]) == 0) {
+                *subject = r->data.ident.name;
+                return forms[i];
+            }
+    }
+    return NULL;
+}
+
+/* Pass 1: every assignment, every observer read, in the loop subtree.
+ * `nested` is 1 inside a nested loop: its assignments still count (they are
+ * counters and re-assignments for this loop's purposes) but belong to that
+ * loop for reporting. Function and lambda bodies are a different env and are
+ * not entered. */
+static void w024_collect(ASTNode *n, W024Loop *lp, int nested) {
+    if (!n || lp->overflow) return;
+    const char *subject = NULL;
+    const char *form = w024_observer_read(n, &subject);
+    if (form) {
+        W024Name *e = w024_entry(lp, subject);
+        if (e && !e->read) { e->read = n; e->read_form = form; }
+        return;
+    }
+    switch (n->type) {
+        case AST_ASSIGN: {
+            W024Name *e = w024_entry(lp, n->data.assign.name);
+            if (e) {
+                e->assign_count++;
+                if (!nested && !e->assign) {
+                    e->assign = n;
+                    e->rhs = n->data.assign.expr;
+                    e->local_only = n->data.assign.local_only;
+                }
+            }
+            w024_collect(n->data.assign.expr, lp, nested);
+            break;
+        }
+        case AST_LIST_PATTERN_ASSIGN:
+            /* `[name, kind, v] is fleet[i]` destructures the entity: each
+             * name is rebound from the element in turn. */
+            for (int i = 0; i < n->data.list_pattern_assign.name_count; i++) {
+                W024Name *e = w024_entry(lp, n->data.list_pattern_assign.names[i]);
+                if (e) {
+                    e->assign_count++;
+                    if (!nested && !e->assign) {
+                        e->assign = n;
+                        e->rhs = n->data.list_pattern_assign.expr;
+                        e->local_only = 0;
+                        e->destructure = 1;
+                    }
+                }
+            }
+            w024_collect(n->data.list_pattern_assign.expr, lp, nested);
+            break;
+        case AST_LOOP:
+            w024_collect(n->data.loop.cond, lp, nested);
+            for (int i = 0; i < n->data.loop.body_count; i++)
+                w024_collect(n->data.loop.body[i], lp, 1);
+            break;
+        case AST_FOR: {
+            W024Name *e = w024_entry(lp, n->data.forloop.var);
+            if (e) e->assign_count++;
+            w024_collect(n->data.forloop.iter, lp, nested);
+            for (int i = 0; i < n->data.forloop.body_count; i++)
+                w024_collect(n->data.forloop.body[i], lp, 1);
+            break;
+        }
+        case AST_FUNC:
+        case AST_LAMBDA:
+            break;
+        case AST_IF:
+            w024_collect(n->data.cond.cond, lp, nested);
+            for (int i = 0; i < n->data.cond.if_count; i++)
+                w024_collect(n->data.cond.if_body[i], lp, nested);
+            for (int i = 0; i < n->data.cond.else_count; i++)
+                w024_collect(n->data.cond.else_body[i], lp, nested);
+            break;
+        case AST_BLOCK:
+        case AST_UNOBSERVED:
+            for (int i = 0; i < n->data.block.count; i++)
+                w024_collect(n->data.block.stmts[i], lp, nested);
+            break;
+        case AST_TRY: {
+            W024Name *e = w024_entry(lp, n->data.trycatch.err_name);
+            if (e) e->assign_count++;
+            for (int i = 0; i < n->data.trycatch.try_count; i++)
+                w024_collect(n->data.trycatch.try_body[i], lp, nested);
+            for (int i = 0; i < n->data.trycatch.catch_count; i++)
+                w024_collect(n->data.trycatch.catch_body[i], lp, nested);
+            break;
+        }
+        case AST_MATCH:
+            w024_collect(n->data.match.expr, lp, nested);
+            for (int c = 0; c < n->data.match.case_count; c++)
+                for (int i = 0; i < n->data.match.body_counts[c]; i++)
+                    w024_collect(n->data.match.bodies[c][i], lp, nested);
+            break;
+        case AST_BINOP:
+            w024_collect(n->data.binop.left, lp, nested);
+            w024_collect(n->data.binop.right, lp, nested);
+            break;
+        case AST_UNARY:
+            w024_collect(n->data.unary.operand, lp, nested);
+            break;
+        case AST_RELATION:
+            w024_collect(n->data.relation.left, lp, nested);
+            w024_collect(n->data.relation.right, lp, nested);
+            break;
+        case AST_RETURN:
+            w024_collect(n->data.ret.expr, lp, nested);
+            break;
+        case AST_LIST:
+            for (int i = 0; i < n->data.list.count; i++)
+                w024_collect(n->data.list.elems[i], lp, nested);
+            break;
+        case AST_DICT:
+            for (int i = 0; i < n->data.dict.count; i++) {
+                w024_collect(n->data.dict.keys[i], lp, nested);
+                w024_collect(n->data.dict.vals[i], lp, nested);
+            }
+            break;
+        case AST_INDEX:
+            w024_collect(n->data.index.target, lp, nested);
+            w024_collect(n->data.index.index, lp, nested);
+            break;
+        case AST_SLICE:
+            w024_collect(n->data.slice.target, lp, nested);
+            w024_collect(n->data.slice.start, lp, nested);
+            w024_collect(n->data.slice.end, lp, nested);
+            break;
+        case AST_DOT:
+            w024_collect(n->data.dot.target, lp, nested);
+            break;
+        case AST_DOT_ASSIGN:
+            w024_collect(n->data.dot_assign.target, lp, nested);
+            w024_collect(n->data.dot_assign.expr, lp, nested);
+            break;
+        case AST_INDEX_ASSIGN:
+            w024_collect(n->data.index_assign.target, lp, nested);
+            w024_collect(n->data.index_assign.index, lp, nested);
+            w024_collect(n->data.index_assign.expr, lp, nested);
+            break;
+        case AST_LISTCOMP:
+            w024_collect(n->data.listcomp.expr, lp, nested);
+            w024_collect(n->data.listcomp.iter, lp, nested);
+            w024_collect(n->data.listcomp.filter, lp, nested);
+            break;
+        case AST_INTERROGATE:
+            w024_collect(n->data.interrogate.expr, lp, nested);
+            w024_collect(n->data.interrogate.at_expr, lp, nested);
+            w024_collect(n->data.interrogate.when_expr, lp, nested);
+            break;
+        case AST_PROGRAM:
+            for (int i = 0; i < n->data.program.count; i++)
+                w024_collect(n->data.program.stmts[i], lp, nested);
+            break;
+        case AST_NUM: case AST_STR: case AST_IDENT: case AST_NULL:
+        case AST_PREDICATE: case AST_BREAK: case AST_CONTINUE: case AST_IMPORT:
+            break;
+    }
+}
+
+/* Does this subscript walk the loop? Counter arithmetic only — an ident
+ * assigned in the loop (or the `for` binder), numbers, and arithmetic / unary
+ * over those. Anything else (`len of xs - 1`, a nested index) is not a
+ * counter and reads as fixed. */
+static int w024_index_varies(ASTNode *ix, W024Loop *lp) {
+    if (!ix) return 0;
+    switch (ix->type) {
+        case AST_IDENT: {
+            if (lp->for_var && strcmp(ix->data.ident.name, lp->for_var) == 0) return 1;
+            W024Name *e = NULL;
+            for (int i = 0; i < lp->count; i++)
+                if (strcmp(lp->names[i].name, ix->data.ident.name) == 0) { e = &lp->names[i]; break; }
+            return e && e->assign_count > 0;
+        }
+        case AST_BINOP:
+            return w024_index_varies(ix->data.binop.left, lp) ||
+                   w024_index_varies(ix->data.binop.right, lp);
+        case AST_UNARY:
+            return w024_index_varies(ix->data.unary.operand, lp);
+        case AST_NUM: case AST_STR: case AST_NULL: case AST_ASSIGN: case AST_RELATION:
+        case AST_IF: case AST_LOOP: case AST_FUNC: case AST_RETURN: case AST_BLOCK:
+        case AST_LIST: case AST_INDEX: case AST_LISTCOMP: case AST_FOR: case AST_PROGRAM:
+        case AST_INTERROGATE: case AST_PREDICATE: case AST_TRY: case AST_DICT: case AST_DOT:
+        case AST_BREAK: case AST_CONTINUE: case AST_DOT_ASSIGN: case AST_IMPORT:
+        case AST_MATCH: case AST_LAMBDA: case AST_UNOBSERVED: case AST_INDEX_ASSIGN:
+        case AST_LIST_PATTERN_ASSIGN: case AST_SLICE:
+            return 0;
+    }
+    return 0;
+}
+
+/* Is this expression an ELEMENT that walks the loop — the `for` binder, a
+ * name rebound in the loop from such an element (`ch is chans[i]`), a
+ * container read subscripted by a counter (`chans[i]`), or a field/index of
+ * any of those? */
+static int w024_elem_walks(ASTNode *n, W024Loop *lp) {
+    if (!n) return 0;
+    switch (n->type) {
+        case AST_IDENT:
+            if (lp->for_var && strcmp(n->data.ident.name, lp->for_var) == 0) return 1;
+            for (int i = 0; i < lp->count; i++)
+                if (strcmp(lp->names[i].name, n->data.ident.name) == 0)
+                    return lp->names[i].walks;
+            return 0;
+        case AST_INDEX:
+            return w024_index_varies(n->data.index.index, lp) ||
+                   w024_elem_walks(n->data.index.target, lp);
+        case AST_DOT:
+            return w024_elem_walks(n->data.dot.target, lp);
+        case AST_NUM: case AST_STR: case AST_NULL: case AST_ASSIGN: case AST_RELATION:
+        case AST_IF: case AST_LOOP: case AST_FUNC: case AST_RETURN: case AST_BLOCK:
+        case AST_LIST: case AST_LISTCOMP: case AST_FOR: case AST_PROGRAM: case AST_BINOP:
+        case AST_UNARY: case AST_INTERROGATE: case AST_PREDICATE: case AST_TRY:
+        case AST_DICT: case AST_BREAK: case AST_CONTINUE: case AST_DOT_ASSIGN:
+        case AST_IMPORT: case AST_MATCH: case AST_LAMBDA: case AST_UNOBSERVED:
+        case AST_INDEX_ASSIGN: case AST_LIST_PATTERN_ASSIGN: case AST_SLICE:
+            return 0;
+    }
+    return 0;
+}
+
+/* The fire condition: the RHS reads a PROJECTION of a walking element — a
+ * field or sub-element of it (`fleet[i][2]`, `chans[i].a`, `ent.v`, or a
+ * destructure `[n, k, v] is fleet[i]`), i.e. one quantity read out of each
+ * entity record in turn. A FLAT `xs[i]` is deliberately not one: subscripting
+ * a scalar list by the counter is also how a recorded series is replayed
+ * through one binding to classify it (`lib/experiment.eigs`,
+ * `lib/simulation.eigs`), and that IS one trajectory; the per-entity scalar
+ * list (`energies[i]`) is the same text and stays silent — see the residual
+ * in the header comment.
+ *
+ * The projection may sit under arithmetic, because the shipped spelling of
+ * this bug does exactly that: phugoid rung 4 — the consumer that reported
+ * #1048 — writes `local qobs is fleet[i][2] + 0.0` (the `+ 0.0` forces the
+ * assignment the observer walks). `-fleet[i][2]`, `fleet[i][2] * scale` and
+ * `fleet[i][2] - fleet[i][3]` are the same read. The other operand must be
+ * INERT — a literal, a name the loop never assigns, or another projection —
+ * so an accumulator (`total is total + fleet[i].v`, where `total` carries
+ * across iterations and has a real trajectory of its own) stays silent. */
+static ASTNode *w024_proj_node(ASTNode *n, W024Loop *lp);
+
+/* May this operand accompany a projection without making the RHS something
+ * other than one entity's quantity? */
+static int w024_operand_inert(ASTNode *n, W024Loop *lp) {
+    if (!n) return 0;
+    if (n->type == AST_NUM || n->type == AST_STR || n->type == AST_NULL) return 1;
+    if (n->type == AST_IDENT) {
+        if (lp->for_var && strcmp(n->data.ident.name, lp->for_var) == 0) return 0;
+        for (int i = 0; i < lp->count; i++)
+            if (strcmp(lp->names[i].name, n->data.ident.name) == 0)
+                return lp->names[i].assign_count == 0;   /* loop-invariant name */
+        return 1;
+    }
+    return w024_proj_node(n, lp) != NULL;
+}
+
+/* The projecting subexpression of `n`, or NULL. Also what the message
+ * renders, so `fleet[i][2] + 0.0` reports `fleet[..][..]`. */
+static ASTNode *w024_proj_node(ASTNode *n, W024Loop *lp) {
+    if (!n) return NULL;
+    if (n->type == AST_INDEX)
+        return w024_elem_walks(n->data.index.target, lp) ? n : NULL;
+    if (n->type == AST_DOT)
+        return w024_elem_walks(n->data.dot.target, lp) ? n : NULL;
+    if (n->type == AST_UNARY)
+        return w024_proj_node(n->data.unary.operand, lp);
+    if (n->type == AST_BINOP) {
+        ASTNode *p = w024_proj_node(n->data.binop.left, lp);
+        if (p && w024_operand_inert(n->data.binop.right, lp)) return p;
+        p = w024_proj_node(n->data.binop.right, lp);
+        if (p && w024_operand_inert(n->data.binop.left, lp)) return p;
+        return NULL;
+    }
+    return NULL;
+}
+
+/* The projection this RHS reads, or NULL. A destructure names the element
+ * itself (`[a, b] is fleet[i]`), so the element IS the reported form. */
+static ASTNode *w024_projects_walking_elem(ASTNode *rhs, W024Loop *lp, int destructure) {
+    if (!rhs) return NULL;
+    if (destructure) return w024_elem_walks(rhs, lp) ? rhs : NULL;
+    return w024_proj_node(rhs, lp);
+}
+
+/* ---- W024 message assembly: bounded, and bounded in the right place ----
+ *
+ * `LintWarning.message` is 256 bytes. W024 is the first rule to interpolate
+ * an unbounded IDENTIFIER more than once, so it is the first that a long but
+ * ordinary name can push over the edge: at ~37 characters (real names in this
+ * ecosystem reach 42) the old code cut the message inside the em dash of
+ * "... - use one named binding or one closure per entity", which both emitted
+ * an invalid UTF-8 byte and dropped the only actionable half (#1048).
+ *
+ * The message is therefore never the thing that gets cut: the IDENTIFIERS are
+ * budgeted, and the budget shrinks until the whole message fits. That
+ * direction is deliberate — a clipped identifier is recoverable (the
+ * diagnostic cites the line, and the name is in the source), a clipped remedy
+ * is not. Clipping is a middle ellipsis so a spelling keeps its tail:
+ * `fleet[..][..]` must not degrade to `fleet`, which reads as if the whole
+ * list were bound. */
+
+#define W024_SPELL_CAP  272   /* rendering scratch: base + suffix chain */
+#define W024_SFX_CAP    96    /* of which the `[..]` / `.key` chain */
+
+/* `s` into `out`, at most `budget` display bytes, cutting the MIDDLE (head +
+ * "..." + tail) on UTF-8 character boundaries so both ends survive. */
+static void w024_ellipsize(const char *s, char *out, size_t cap, size_t budget) {
+    if (!out || cap == 0) return;
+    if (!s) { out[0] = '\0'; return; }
+    if (budget > cap - 1) budget = cap - 1;
+    size_t n = strlen(s);
+    if (n <= budget) { memcpy(out, s, n + 1); return; }
+    if (budget < 8) {   /* too small for head+"..."+tail: plain boundary cut */
+        size_t k = lint_utf8_prefix(s, budget);
+        memcpy(out, s, k); out[k] = '\0'; return;
+    }
+    size_t keep = budget - 3;
+    size_t head = lint_utf8_prefix(s, keep / 2);
+    size_t tail = keep - head;
+    /* Walk the tail start forward to a character boundary. */
+    size_t ts = n - tail;
+    while (ts < n && ((unsigned char)s[ts] & 0xC0) == 0x80) ts++;
+    memcpy(out, s, head);
+    memcpy(out + head, "...", 3);
+    memcpy(out + head + 3, s + ts, n - ts);
+    out[head + 3 + (n - ts)] = '\0';
+}
+
+/* Short spelling of the RHS for the message: `fleet[..][..]`, `ch.a`.
+ * The suffix chain is measured FIRST and the base name gets what is left, so
+ * a long container name loses its own tail and never the `[..][..]` that
+ * says this is a projection of one element. */
+static void w024_render(ASTNode *n, char *buf, size_t cap) {
+    if (!buf || cap == 0) return;
+    buf[0] = '\0';
+    if (!n || cap < 8) return;
+
+    /* The chain, outermost first. */
+    ASTNode *chain[16];
+    int nch = 0, deep = 0;
+    ASTNode *base = n;
+    while (base && (base->type == AST_INDEX || base->type == AST_DOT)) {
+        if (nch < (int)(sizeof chain / sizeof chain[0])) chain[nch++] = base;
+        else deep = 1;
+        base = (base->type == AST_INDEX) ? base->data.index.target
+                                         : base->data.dot.target;
+    }
+
+    /* Suffix, in source order (= chain reversed). */
+    char sfx[W024_SFX_CAP];
+    size_t so = 0;
+    sfx[0] = '\0';
+    if (deep) { memcpy(sfx, "...", 3); so = 3; sfx[so] = '\0'; }
+    for (int i = nch - 1; i >= 0 && so + 6 < sizeof sfx; i--) {
+        if (chain[i]->type == AST_INDEX) {
+            memcpy(sfx + so, "[..]", 5);
+            so += 4;
+        } else {
+            char key[24];
+            w024_ellipsize(chain[i]->data.dot.key ? chain[i]->data.dot.key : "..",
+                           key, sizeof key, 16);
+            so += (size_t)snprintf(sfx + so, sizeof sfx - so, ".%s", key);
+            if (so >= sizeof sfx) { so = sizeof sfx - 1; sfx[so] = '\0'; break; }
+        }
+    }
+
+    char bb[W024_SPELL_CAP];
+    size_t bbudget = (so + 2 < cap) ? cap - 1 - so : 1;
+    w024_ellipsize(base && base->type == AST_IDENT ? base->data.ident.name : "...",
+                   bb, sizeof bb, bbudget);
+    snprintf(buf, cap, "%s%s", bb, sfx);
+}
+
+typedef enum {
+    W024_INTERLEAVE,   /* rebound from a container element every iteration */
+    W024_FRESH_PROJ,   /* module-level `for`-body local, element RHS */
+    W024_FRESH_PLAIN   /* module-level `for`-body local, any other RHS */
+} W024Msg;
+
+/* Emit, shrinking the identifier budget until the whole message fits
+ * LintWarning.message. The literals below are the contract this loop keeps:
+ * the smallest budget must fit them with room for both names, the read form
+ * and the spelling — asserted by the fixtures in tests/test_lint.sh (a
+ * 200-character identifier) and by tools/lint_message_utf8_check.sh, which
+ * decodes `--lint --json` strictly for every registered code. */
+static void w024_emit(LintContext *ctx, int line, W024Msg kind,
+                      const char *name, const char *rhs, const char *read_form) {
+    static const size_t budgets[] = { 128, 96, 64, 48, 32, 24, 16, 12, 8 };
+    const size_t nb = sizeof budgets / sizeof budgets[0];
+    const size_t fit = sizeof ((LintWarning *)0)->message;
+    char nbuf[W024_SPELL_CAP + 8], rbuf[W024_SPELL_CAP + 8], msg[1024];
+    for (size_t bi = 0; bi < nb; bi++) {
+        w024_ellipsize(name, nbuf, sizeof nbuf, budgets[bi]);
+        w024_ellipsize(rhs,  rbuf, sizeof rbuf, budgets[bi]);
+        switch (kind) {
+            case W024_INTERLEAVE:
+                snprintf(msg, sizeof msg,
+                    "'%s' is rebound from '%s' each iteration: '%s %s' judges the "
+                    "round-robin of every element it visits, not one entity "
+                    "(#1048) — use one named binding or one closure per entity",
+                    nbuf, rbuf, read_form, nbuf);
+                break;
+            case W024_FRESH_PROJ:
+                snprintf(msg, sizeof msg,
+                    "'%s' is a 'for'-body local, fresh each iteration: '%s %s' "
+                    "sees one observation and always answers equilibrium (#1048); "
+                    "a persisting binding would interleave every element instead "
+                    "— use one named binding or one closure per entity",
+                    nbuf, read_form, nbuf);
+                break;
+            case W024_FRESH_PLAIN:
+                snprintf(msg, sizeof msg,
+                    "'%s' is a 'for'-body local, fresh each iteration: '%s %s' "
+                    "sees one observation and always answers equilibrium (#1048) "
+                    "— bind it before the loop so its slot persists",
+                    nbuf, read_form, nbuf);
+                break;
+        }
+        if (strlen(msg) < fit) break;
+    }
+    lint_warn(ctx, line, "W024", "%s", msg);
+}
+
+static void w024_analyse_loop(ASTNode *loop, int fn_depth, LintContext *ctx) {
+    W024Loop lp;
+    memset(&lp, 0, sizeof(lp));
+    if (loop->type == AST_FOR) {
+        lp.for_var = loop->data.forloop.var;
+        w024_collect(loop->data.forloop.iter, &lp, 0);
+        for (int i = 0; i < loop->data.forloop.body_count; i++)
+            w024_collect(loop->data.forloop.body[i], &lp, 0);
+    } else {
+        w024_collect(loop->data.loop.cond, &lp, 0);
+        for (int i = 0; i < loop->data.loop.body_count; i++)
+            w024_collect(loop->data.loop.body[i], &lp, 0);
+    }
+    if (lp.overflow) return;
+    /* Walking is transitive through rebound bases (`ch is chans[i]`, then
+     * `ch.a`), and a name's projection can only be recognised once its base
+     * is known to walk: iterate to a fixed point; each pass can only add. */
+    for (int changed = 1, guard = 0; changed && guard <= lp.count + 1; guard++) {
+        changed = 0;
+        for (int i = 0; i < lp.count; i++) {
+            W024Name *e = &lp.names[i];
+            if (!e->assign) continue;
+            if (!e->walks && w024_elem_walks(e->rhs, &lp)) { e->walks = 1; changed = 1; }
+            if (!e->proj) {
+                ASTNode *p = w024_projects_walking_elem(e->rhs, &lp, e->destructure);
+                if (p) { e->proj = p; changed = 1; }
+            }
+        }
+    }
+    for (int i = 0; i < lp.count; i++) {
+        W024Name *e = &lp.names[i];
+        if (!e->assign || !e->read) continue;
+        int fresh_local = loop->type == AST_FOR && e->local_only && fn_depth == 0;
+        char rendered[W024_SPELL_CAP], rhs[W024_SPELL_CAP + 8];
+        if (fresh_local) {
+            if (e->assign_count != 1) continue;   /* intra-iteration trajectory */
+            w024_emit(ctx, e->assign->line,
+                      e->proj ? W024_FRESH_PROJ : W024_FRESH_PLAIN,
+                      e->name, NULL, e->read_form);
+            continue;
+        }
+        if (!e->proj) continue;
+        w024_render(e->proj, rendered, sizeof(rendered));
+        /* `[a, b] is fleet[i]` — say what was destructured */
+        snprintf(rhs, sizeof(rhs), "%s%s", e->destructure ? "[..] is " : "", rendered);
+        w024_emit(ctx, e->assign->line, W024_INTERLEAVE,
+                  e->name, rhs, e->read_form);
+    }
+}
+
+/* Driver: every loop, innermost-owner attribution; fn_depth > 0 inside any
+ * define/lambda (where a `for`-body `local` is a persisting frame slot). */
+static void w024_walk(ASTNode *n, int fn_depth, LintContext *ctx) {
+    if (!n) return;
+    switch (n->type) {
+        case AST_LOOP:
+            w024_analyse_loop(n, fn_depth, ctx);
+            w024_walk(n->data.loop.cond, fn_depth, ctx);
+            for (int i = 0; i < n->data.loop.body_count; i++)
+                w024_walk(n->data.loop.body[i], fn_depth, ctx);
+            break;
+        case AST_FOR:
+            w024_analyse_loop(n, fn_depth, ctx);
+            w024_walk(n->data.forloop.iter, fn_depth, ctx);
+            for (int i = 0; i < n->data.forloop.body_count; i++)
+                w024_walk(n->data.forloop.body[i], fn_depth, ctx);
+            break;
+        case AST_FUNC:
+            for (int i = 0; i < n->data.func.param_count; i++)
+                w024_walk(n->data.func.param_defaults ? n->data.func.param_defaults[i] : NULL, fn_depth + 1, ctx);
+            for (int i = 0; i < n->data.func.body_count; i++)
+                w024_walk(n->data.func.body[i], fn_depth + 1, ctx);
+            break;
+        case AST_LAMBDA:
+            w024_walk(n->data.lambda.body, fn_depth + 1, ctx);
+            break;
+        case AST_IF:
+            w024_walk(n->data.cond.cond, fn_depth, ctx);
+            for (int i = 0; i < n->data.cond.if_count; i++)
+                w024_walk(n->data.cond.if_body[i], fn_depth, ctx);
+            for (int i = 0; i < n->data.cond.else_count; i++)
+                w024_walk(n->data.cond.else_body[i], fn_depth, ctx);
+            break;
+        case AST_BLOCK:
+        case AST_UNOBSERVED:
+            for (int i = 0; i < n->data.block.count; i++)
+                w024_walk(n->data.block.stmts[i], fn_depth, ctx);
+            break;
+        case AST_PROGRAM:
+            for (int i = 0; i < n->data.program.count; i++)
+                w024_walk(n->data.program.stmts[i], fn_depth, ctx);
+            break;
+        case AST_TRY:
+            for (int i = 0; i < n->data.trycatch.try_count; i++)
+                w024_walk(n->data.trycatch.try_body[i], fn_depth, ctx);
+            for (int i = 0; i < n->data.trycatch.catch_count; i++)
+                w024_walk(n->data.trycatch.catch_body[i], fn_depth, ctx);
+            break;
+        case AST_MATCH:
+            w024_walk(n->data.match.expr, fn_depth, ctx);
+            for (int c = 0; c < n->data.match.case_count; c++)
+                for (int i = 0; i < n->data.match.body_counts[c]; i++)
+                    w024_walk(n->data.match.bodies[c][i], fn_depth, ctx);
+            break;
+        case AST_ASSIGN:
+            w024_walk(n->data.assign.expr, fn_depth, ctx);
+            break;
+        case AST_LIST_PATTERN_ASSIGN:
+            w024_walk(n->data.list_pattern_assign.expr, fn_depth, ctx);
+            break;
+        case AST_DOT_ASSIGN:
+            w024_walk(n->data.dot_assign.target, fn_depth, ctx);
+            w024_walk(n->data.dot_assign.expr, fn_depth, ctx);
+            break;
+        case AST_INDEX_ASSIGN:
+            w024_walk(n->data.index_assign.target, fn_depth, ctx);
+            w024_walk(n->data.index_assign.index, fn_depth, ctx);
+            w024_walk(n->data.index_assign.expr, fn_depth, ctx);
+            break;
+        case AST_RETURN:
+            w024_walk(n->data.ret.expr, fn_depth, ctx);
+            break;
+        case AST_BINOP:
+            w024_walk(n->data.binop.left, fn_depth, ctx);
+            w024_walk(n->data.binop.right, fn_depth, ctx);
+            break;
+        case AST_UNARY:
+            w024_walk(n->data.unary.operand, fn_depth, ctx);
+            break;
+        case AST_RELATION:
+            w024_walk(n->data.relation.left, fn_depth, ctx);
+            w024_walk(n->data.relation.right, fn_depth, ctx);
+            break;
+        case AST_LIST:
+            for (int i = 0; i < n->data.list.count; i++)
+                w024_walk(n->data.list.elems[i], fn_depth, ctx);
+            break;
+        case AST_DICT:
+            for (int i = 0; i < n->data.dict.count; i++) {
+                w024_walk(n->data.dict.keys[i], fn_depth, ctx);
+                w024_walk(n->data.dict.vals[i], fn_depth, ctx);
+            }
+            break;
+        case AST_INDEX:
+            w024_walk(n->data.index.target, fn_depth, ctx);
+            w024_walk(n->data.index.index, fn_depth, ctx);
+            break;
+        case AST_SLICE:
+            w024_walk(n->data.slice.target, fn_depth, ctx);
+            w024_walk(n->data.slice.start, fn_depth, ctx);
+            w024_walk(n->data.slice.end, fn_depth, ctx);
+            break;
+        case AST_DOT:
+            w024_walk(n->data.dot.target, fn_depth, ctx);
+            break;
+        case AST_LISTCOMP:
+            w024_walk(n->data.listcomp.expr, fn_depth, ctx);
+            w024_walk(n->data.listcomp.iter, fn_depth, ctx);
+            w024_walk(n->data.listcomp.filter, fn_depth, ctx);
+            break;
+        case AST_INTERROGATE:
+            w024_walk(n->data.interrogate.expr, fn_depth, ctx);
+            break;
+        case AST_NUM: case AST_STR: case AST_IDENT: case AST_NULL:
+        case AST_PREDICATE: case AST_BREAK: case AST_CONTINUE: case AST_IMPORT:
+            break;
+    }
+}
+
+static void check_container_rebind(ASTNode *ast, LintContext *ctx) {
+    w024_walk(ast, 0, ctx);
+}
+
 void lint_run_checks(ASTNode *ast, const char *path,
                      const char *source, LintContext *ctx) {
     check_outer_mutation(ast, ctx);
     check_sibling_outer_mutation(ast, ctx);
     check_bare_predicate_alias(ast, ctx);
+    check_container_rebind(ast, ctx);
     check_one_element_arg_list(ast, ctx);
     check_over_arity(ast, ctx);
     check_dead_unobserved(ast, ctx);
diff --git a/src/lint_host.c b/src/lint_host.c
index 485f7074..2a0597c2 100644
--- a/src/lint_host.c
+++ b/src/lint_host.c
@@ -21,6 +21,12 @@
 /* Escape a string for embedding in a JSON string literal (into a caller
  * buffer). This helper is host-only now that every JSON-producing lint path
  * lives in this TU; keeping it static prevents a generic host symbol leak. */
+/* JSON string escaping. The output buffer is the SECOND place a diagnostic
+ * can be cut (the first is lint_vdiag's message buffer), so it clips whole
+ * UTF-8 characters only: emitting half a sequence produces a payload a
+ * strict decoder rejects, and `jq` hides that by substituting U+FFFD
+ * (#1048). Bytes >= 0x80 are passed through raw — the input is UTF-8 and
+ * JSON accepts it as-is. */
 static void lint_json_escape(const char *s, char *out, size_t outsz) {
     size_t o = 0;
     for (size_t i = 0; s[i] && o + 2 < outsz; i++) {
@@ -32,6 +38,9 @@ static void lint_json_escape(const char *s, char *out, size_t outsz) {
         /* other control chars are dropped */
     }
     out[o] = '\0';
+    /* The loop can stop inside a multi-byte character (the capacity test is
+     * per byte); drop the partial tail rather than emit it. */
+    out[lint_utf8_prefix(out, o)] = '\0';
 }
 
 /* Known builtin names — the registry itself, never a hand list (#459: the
diff --git a/src/lint_internal.h b/src/lint_internal.h
index 216535a2..69be547c 100644
--- a/src/lint_internal.h
+++ b/src/lint_internal.h
@@ -33,6 +33,13 @@ typedef struct {
     int builtin_count;
 } LintContext;
 
+/* Length of the longest prefix of `s` at most `max` bytes that ends on a
+ * UTF-8 character boundary (src/lint.c). Every place a diagnostic string is
+ * truncated must go through it: a cut inside a multi-byte sequence makes
+ * `--lint --json` undecodable and puts a malformed byte in the LSP's
+ * JSON-RPC stream (#1048). */
+size_t lint_utf8_prefix(const char *s, size_t max);
+
 /* Diagnostic helpers shared by lint.c and the host-only walkers. */
 void lint_hint(LintContext *ctx, int line, const char *code,
                const char *fmt, ...);
diff --git a/tests/lint_utf8/E002.eigs b/tests/lint_utf8/E002.eigs
new file mode 100644
index 00000000..2c8a66be
--- /dev/null
+++ b/tests/lint_utf8/E002.eigs
@@ -0,0 +1,2 @@
+x is 1
+qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz ryyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
diff --git a/tests/lint_utf8/E003.eigs b/tests/lint_utf8/E003.eigs
new file mode 100644
index 00000000..4bac3c6f
--- /dev/null
+++ b/tests/lint_utf8/E003.eigs
@@ -0,0 +1 @@
+print of qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
diff --git a/tests/lint_utf8/E004.eigs b/tests/lint_utf8/E004.eigs
new file mode 100644
index 00000000..bf3fdcd6
--- /dev/null
+++ b/tests/lint_utf8/E004.eigs
@@ -0,0 +1 @@
+break
diff --git a/tests/lint_utf8/E005.eigs b/tests/lint_utf8/E005.eigs
new file mode 100644
index 00000000..e8cc4198
--- /dev/null
+++ b/tests/lint_utf8/E005.eigs
@@ -0,0 +1,3 @@
+report is 5
+qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is 1
+print of qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
diff --git a/tests/lint_utf8/W001.eigs b/tests/lint_utf8/W001.eigs
new file mode 100644
index 00000000..151dd6bc
--- /dev/null
+++ b/tests/lint_utf8/W001.eigs
@@ -0,0 +1 @@
+qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is 1
diff --git a/tests/lint_utf8/W002.eigs b/tests/lint_utf8/W002.eigs
new file mode 100644
index 00000000..e41b99c8
--- /dev/null
+++ b/tests/lint_utf8/W002.eigs
@@ -0,0 +1,3 @@
+define f(qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz) as:
+    return 1
+print of (f of [2])
diff --git a/tests/lint_utf8/W003.eigs b/tests/lint_utf8/W003.eigs
new file mode 100644
index 00000000..2eae453e
--- /dev/null
+++ b/tests/lint_utf8/W003.eigs
@@ -0,0 +1,4 @@
+define f() as:
+    return 1
+    qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is 2
+print of (f of [])
diff --git a/tests/lint_utf8/W010.eigs b/tests/lint_utf8/W010.eigs
new file mode 100644
index 00000000..54b645b0
--- /dev/null
+++ b/tests/lint_utf8/W010.eigs
@@ -0,0 +1,2 @@
+d is {"qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz": 1, "qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz": 2}
+print of d
diff --git a/tests/lint_utf8/W012.eigs b/tests/lint_utf8/W012.eigs
new file mode 100644
index 00000000..4cdfda3c
--- /dev/null
+++ b/tests/lint_utf8/W012.eigs
@@ -0,0 +1,2 @@
+print is 1
+x is print
diff --git a/tests/lint_utf8/W013.eigs b/tests/lint_utf8/W013.eigs
new file mode 100644
index 00000000..56406b6f
--- /dev/null
+++ b/tests/lint_utf8/W013.eigs
@@ -0,0 +1,3 @@
+define len as:
+    return 1
+print of (len of [])
diff --git a/tests/lint_utf8/W014.eigs b/tests/lint_utf8/W014.eigs
new file mode 100644
index 00000000..dd198a39
--- /dev/null
+++ b/tests/lint_utf8/W014.eigs
@@ -0,0 +1,6 @@
+qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is 1.0
+ryyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy is 2.0
+loop while converged:
+    qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz * 0.5
+    ryyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy is ryyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy * 0.5
+print of qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
diff --git a/tests/lint_utf8/W015.eigs b/tests/lint_utf8/W015.eigs
new file mode 100644
index 00000000..48044a9f
--- /dev/null
+++ b/tests/lint_utf8/W015.eigs
@@ -0,0 +1,6 @@
+define qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz() as:
+    return 1
+define g() as:
+    qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is 5
+    return qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+print of (g of [])
diff --git a/tests/lint_utf8/W016.eigs b/tests/lint_utf8/W016.eigs
new file mode 100644
index 00000000..843fd2bc
--- /dev/null
+++ b/tests/lint_utf8/W016.eigs
@@ -0,0 +1,4 @@
+qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is 1.0
+qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz * 0.5
+if stable:
+    print of 1
diff --git a/tests/lint_utf8/W017.eigs b/tests/lint_utf8/W017.eigs
new file mode 100644
index 00000000..51183bac
--- /dev/null
+++ b/tests/lint_utf8/W017.eigs
@@ -0,0 +1,4 @@
+define f(a) as:
+    return a
+qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is 3
+print of (f of [qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz])
diff --git a/tests/lint_utf8/W018.eigs b/tests/lint_utf8/W018.eigs
new file mode 100644
index 00000000..cfe62233
--- /dev/null
+++ b/tests/lint_utf8/W018.eigs
@@ -0,0 +1,5 @@
+try:
+    print of ([] of 1)
+catch qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz:
+    if qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz.kind == "IO":
+        print of 1
diff --git a/tests/lint_utf8/W019.eigs b/tests/lint_utf8/W019.eigs
new file mode 100644
index 00000000..9fbd2109
--- /dev/null
+++ b/tests/lint_utf8/W019.eigs
@@ -0,0 +1,2 @@
+qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is 1
+why is qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
diff --git a/tests/lint_utf8/W020.eigs b/tests/lint_utf8/W020.eigs
new file mode 100644
index 00000000..d06a8d5d
--- /dev/null
+++ b/tests/lint_utf8/W020.eigs
@@ -0,0 +1,4 @@
+qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is {"a": 1}
+unobserved:
+    qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz.a is 2
+print of qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
diff --git a/tests/lint_utf8/W021.eigs b/tests/lint_utf8/W021.eigs
new file mode 100644
index 00000000..5fa53fce
--- /dev/null
+++ b/tests/lint_utf8/W021.eigs
@@ -0,0 +1,3 @@
+define median as:
+    return 1
+print of (median of [])
diff --git a/tests/lint_utf8/W022.eigs b/tests/lint_utf8/W022.eigs
new file mode 100644
index 00000000..ce33534c
--- /dev/null
+++ b/tests/lint_utf8/W022.eigs
@@ -0,0 +1,4 @@
+define two(a, b) as:
+    return a + b
+qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is 1
+print of (two of [qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz, 2, 99])
diff --git a/tests/lint_utf8/W023.eigs b/tests/lint_utf8/W023.eigs
new file mode 100644
index 00000000..e029ec33
--- /dev/null
+++ b/tests/lint_utf8/W023.eigs
@@ -0,0 +1,8 @@
+qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is 5
+define f(flag) as:
+    if flag == 1:
+        local qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is 1
+    else:
+        qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is 2
+    return qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+print of (f of 0)
diff --git a/tests/lint_utf8/W024.eigs b/tests/lint_utf8/W024.eigs
new file mode 100644
index 00000000..1d756c4f
--- /dev/null
+++ b/tests/lint_utf8/W024.eigs
@@ -0,0 +1,6 @@
+qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz is [[1, 2, 3.0], [4, 5, 6.0]]
+i is 0
+loop while i < 2:
+    local ryyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy is qzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz[i][2]
+    print of diverging of ryyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+    i is i + 1
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 21b60739..6a1eb817 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -5058,6 +5058,27 @@ else
 fi
 echo ""
 
+# [81u] Lint diagnostic UTF-8 gate (#1048). A lint message is built in a
+# 256-byte buffer and shipped through --lint --json and the LSP; W024 was the
+# first rule to interpolate an unbounded identifier twice, and a ~37-character
+# name truncated it inside an em dash, emitting a lone 0xE2 that Python's
+# decoder rejects and jq hides behind U+FFFD. The gate drives every registered
+# code with a 200-character identifier, decodes strictly, checks the registry
+# both ways, and re-verifies each pinned exemption; --selftest plants five
+# faults (including a new rule with no doc row) and requires each to be caught.
+echo "[81u] lint diagnostic UTF-8 gate (#1048)"
+TOTAL=$((TOTAL + 1))
+if bash "$TESTS_DIR/../tools/lint_message_utf8_check.sh" >/dev/null 2>&1 && \
+   bash "$TESTS_DIR/../tools/lint_message_utf8_check.sh" --selftest >/dev/null 2>&1; then
+    PASS=$((PASS + 1))
+    echo "  PASS: no lint rule can emit a message truncated mid-UTF-8 (gate self-test green)"
+else
+    FAIL=$((FAIL + 1))
+    echo "  FAIL: a lint diagnostic is malformed UTF-8, or the gate self-test broke"
+    bash "$TESTS_DIR/../tools/lint_message_utf8_check.sh" 2>&1 | grep -E "^FAIL|SELFTEST-FAIL" | head -10
+fi
+echo ""
+
 # [81b] Test runner (--test) + exe_path builtin — runs test_*.eigs files
 # in their own processes and reports pass/fail (human + --json).
 echo "[81b] Test runner (--test)"
diff --git a/tests/test_lint.sh b/tests/test_lint.sh
index 85e5ce58..abb6067d 100644
--- a/tests/test_lint.sh
+++ b/tests/test_lint.sh
@@ -1952,6 +1952,444 @@ check_status "compiling file still exits 0" "$RC" "0"
 check_contains "compiling file still reports clean" "$OUTPUT" "no issues found"
 rm -f "$TMPFILE"
 
+# --- #1048 (W024): observer read on a binding rebound from a container element ---
+# Trajectory lives on an env slot, never on a Value: one binding rebound from
+# `fleet[i][2]` each iteration carries the round-robin of every entity, and a
+# monotonically decaying entity reads `oscillating` — silent-wrong, the shape
+# phugoid rung 4 shipped. The positive is the issue's own loop; the negatives
+# are the two working forms (a named binding per entity, a closure per entity)
+# plus the stdlib's flat time-series replay, which a rule that flagged it would
+# teach people to rewrite.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+cat > "$TMPFILE" << 'EIGS'
+fleet is [["a", 0, 100.0], ["b", 0, 1.0]]
+step is 0
+loop while step < 40:
+    fleet[0][2] is fleet[0][2] * 0.9
+    fleet[1][2] is 0.0 - fleet[1][2]
+    i is 0
+    loop while i < 2:
+        local q is fleet[i][2]
+        if diverging of q:
+            print of i
+        i is i + 1
+    step is step + 1
+EIGS
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_contains "#1048 W024 fires on the issue's loop-while shape" "$OUTPUT" ":8: warning\[W024\]: 'q' is rebound from 'fleet\[..\]\[..\]'"
+check_contains "#1048 W024 names the read and the mechanism" "$OUTPUT" "'diverging of q' judges the round-robin"
+check_contains "#1048 W024 names the working forms" "$OUTPUT" "one named binding or one closure per entity"
+JSON=$($EIGS --lint --json "$TMPFILE" 2>/dev/null || true)
+check_contains "#1048 W024 json shape" "$JSON" '"code":"W024","severity":"warning","line":8'
+rm -f "$TMPFILE"
+
+# Runtime proof that the rule is about a real verdict, not style: the same
+# program answers `oscillating` for the DECAYING entity through the shared
+# binding and `improving` through a named one.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+cat > "$TMPFILE" << 'EIGS'
+fleet is [["a", 0, 100.0], ["b", 0, 1.0]]
+step is 0
+qa is 0.0
+loop while step < 40:
+    fleet[0][2] is fleet[0][2] * 0.9
+    fleet[1][2] is 0.0 - fleet[1][2]
+    i is 0
+    loop while i < 2:
+        local q is fleet[i][2]
+        if step == 39 and i == 0:
+            print of ("shared " + (report_value of q))
+        i is i + 1
+    qa is fleet[0][2]
+    step is step + 1
+print of ("named " + (report_value of qa))
+EIGS
+RUN=$($EIGS "$TMPFILE" 2>&1 || true)
+check_contains "#1048 shared binding manufactures 'oscillating' for a decaying entity" "$RUN" "^shared oscillating$"
+check_contains "#1048 named binding answers 'improving' for the same entity" "$RUN" "^named improving$"
+rm -f "$TMPFILE"
+
+# The closure-per-entity recipe is EXTRACTED from docs/PREDICATES.md, not
+# copied here: a copy gates nothing once the doc drifts (#1048 round 2).
+# PREDICATES.md is not in tests/test_doc_examples.py's file list, so this is
+# the only thing that keeps that recipe honest — it must run, print the two
+# correct verdicts for the two entities, and lint clean.
+PREDOC="$TESTS_DIR/../docs/PREDICATES.md"
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+awk '
+    /^\*\*The recommended per-entity form is a closure per entity\*\*/ { armed = 1; next }
+    armed && /^```eigenscript$/ { infence = 1; armed = 0; next }
+    infence && /^```$/ { exit }
+    infence { print }
+' "$PREDOC" > "$TMPFILE"
+# Vacuity guard: an extraction that silently yields nothing would make every
+# assertion below pass on an empty file.
+check_contains "#1048 PREDICATES.md closure recipe extracts (non-vacuous)" "$(cat "$TMPFILE")" "define make_ch as:"
+check_contains "#1048 PREDICATES.md closure recipe extracts the whole block" "$(cat "$TMPFILE")" "print of (a + \" \" + b)"
+# The doc's own printed claim is pinned too, so the block and its comment
+# cannot drift apart.
+check_contains "#1048 PREDICATES.md states the recipe's output" "$(cat "$TMPFILE")" "# improving oscillating"
+RUN=$($EIGS "$TMPFILE" 2>&1 || true)
+check_contains "#1048 PREDICATES.md closure recipe prints one verdict per entity" "$RUN" "^improving oscillating$"
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_not_contains "#1048 PREDICATES.md closure recipe lints clean" "$OUTPUT" "W024"
+rm -f "$TMPFILE"
+
+# Working form 1: one named binding per entity — silent.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+cat > "$TMPFILE" << 'EIGS'
+fleet is [["a", 0, 100.0], ["b", 0, 1.0]]
+step is 0
+qa is 0.0
+qb is 0.0
+loop while step < 40:
+    fleet[0][2] is fleet[0][2] * 0.9
+    fleet[1][2] is 0.0 - fleet[1][2]
+    qa is fleet[0][2]
+    qb is fleet[1][2]
+    if diverging of qa:
+        print of "a"
+    if diverging of qb:
+        print of "b"
+    step is step + 1
+EIGS
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_not_contains "#1048 W024 silent on one named binding per entity (fixed index)" "$OUTPUT" "W024"
+rm -f "$TMPFILE"
+
+# Working form 2: one closure per entity — silent (the loop rebinds `ch`
+# from `chans[i]` but observes nothing through it; the slot that carries the
+# trajectory is the factory's captured `q`).
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+cat > "$TMPFILE" << 'EIGS'
+define make_ch as:
+    local q is 0.0
+    define step(v) as:
+        q is v
+        return report_value of q
+    return step
+fleet is [["a", 0, 100.0], ["b", 0, 1.0]]
+chans is [make_ch of [], make_ch of []]
+t is 0
+loop while t < 40:
+    fleet[0][2] is fleet[0][2] * 0.9
+    fleet[1][2] is 0.0 - fleet[1][2]
+    i is 0
+    loop while i < 2:
+        local ch is chans[i]
+        local v is ch of fleet[i][2]
+        if t == 39:
+            print of v
+        i is i + 1
+    t is t + 1
+EIGS
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_not_contains "#1048 W024 silent on one closure per entity" "$OUTPUT" "W024"
+rm -f "$TMPFILE"
+
+# The other spellings of the same interleave: a field of the walking element,
+# a base rebound from the element, a `for` binder's field, a destructure.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+cat > "$TMPFILE" << 'EIGS'
+chans is [{"a": 1.0}, {"a": 2.0}]
+fleet is [["a", 0, 100.0], ["b", 0, 1.0]]
+i is 0
+loop while i < 2:
+    local ch is chans[i]
+    local q is ch.a
+    if stable of q:
+        print of i
+    i is i + 1
+for ent in chans:
+    e is ent.a
+    print of (report of e)
+for row in fleet:
+    [nm, kind, v] is row
+    print of (report_value of v)
+k is 0
+loop while k < 2:
+    w is chans[k].a
+    print of (trajectory of w)
+    k is k + 1
+EIGS
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_contains "#1048 W024 field of a base rebound from the element" "$OUTPUT" ":6: warning\[W024\]: 'q' is rebound from 'ch.a'"
+check_contains "#1048 W024 field of a for binder" "$OUTPUT" ":11: warning\[W024\]: 'e' is rebound from 'ent.a'"
+check_contains "#1048 W024 destructure of the walking element" "$OUTPUT" ":14: warning\[W024\]: 'v' is rebound from '\[..\] is row'"
+check_contains "#1048 W024 field of a counter-subscripted element" "$OUTPUT" ":18: warning\[W024\]: 'w' is rebound from 'chans\[..\].a'"
+rm -f "$TMPFILE"
+
+# The spelling the reporting consumer actually ships: the projection sits
+# under arithmetic (`fleet[i][2] + 0.0` — the `+ 0.0` forces the assignment
+# the observer walks). phugoid rung 4's `run_ceiling` / `run_disciplined`
+# arms are this exact text, and the first cut of the rule was silent on all
+# of them. An accumulator (`total is total + fleet[i][1]`) is NOT this shape
+# — it carries across iterations and has a trajectory of its own — and a
+# base rebound from a call (`s is halve of s`) is one entity over time.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+cat > "$TMPFILE" << 'EIGS'
+define halve(a) as:
+    return [a[0] * 0.5]
+fleet is [[0, 100.0], [0, 1.0]]
+scale is 2.0
+total is 0.0
+i is 0
+loop while i < 2:
+    local qobs is fleet[i][1] + 0.0
+    if oscillating of qobs:
+        print of "o"
+    local v is fleet[i][1] * scale
+    if stable of v:
+        print of "v"
+    local w is 0.0 - fleet[i][1]
+    if diverging of w:
+        print of "w"
+    total is total + fleet[i][1]
+    if converged of total:
+        print of "t"
+    i is i + 1
+s is [50.0]
+m is 0
+loop while m < 5:
+    s is halve of s
+    local u is s[0] + 0.0
+    if converged of u:
+        print of "u"
+    m is m + 1
+EIGS
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_contains "#1048 W024 projection under arithmetic (the shipped '+ 0.0' spelling)" "$OUTPUT" ":8: warning\[W024\]: 'qobs' is rebound from 'fleet\[..\]\[..\]'"
+check_contains "#1048 W024 projection times a loop-invariant name" "$OUTPUT" ":11: warning\[W024\]: 'v' is rebound from 'fleet\[..\]\[..\]'"
+check_contains "#1048 W024 negated projection" "$OUTPUT" ":14: warning\[W024\]: 'w' is rebound from 'fleet\[..\]\[..\]'"
+check_not_contains "#1048 W024 silent: accumulator over the elements (line 17)" "$OUTPUT" ":17: warning\[W024\]"
+check_not_contains "#1048 W024 silent: call-rebound base read with '+ 0.0' (line 25)" "$OUTPUT" ":25: warning\[W024\]"
+rm -f "$TMPFILE"
+
+# Negatives that must stay silent — each is correct, load-bearing code:
+#  - a FIXED field/element mirrored into a binding (the documented way to give
+#    a dict field a trajectory);
+#  - a base rebound from a call (functional state update);
+#  - a subscript that is not counter arithmetic;
+#  - a flat `xs[i]` replay of a recorded series (lib/experiment.eigs's shape —
+#    one trajectory; also the rule's named residual for per-entity scalars);
+#  - a binding observed in a loop that does not rebind it from an element;
+#  - the projection outside any loop.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+cat > "$TMPFILE" << 'EIGS'
+game is {"energy": 100.0, "pos": [0.0, 0.0]}
+xs is [1.0, 2.0, 3.0]
+series is [3.0, 2.0, 1.0]
+tracker is 0
+i is 0
+loop while i < 10:
+    game.energy is game.energy * 0.9
+    local e is game.energy
+    if converged of e:
+        print of "settled"
+    local first is xs[0]
+    if stable of first:
+        print of "first"
+    local px is game.pos[0]
+    if stable of px:
+        print of "px"
+    game is {"energy": game.energy, "pos": game.pos}
+    local e2 is game.energy
+    if stable of e2:
+        print of "e2"
+    local last is xs[len of xs - 1]
+    if stable of last:
+        print of "last"
+    i is i + 1
+for k in range of (len of series):
+    tracker is series[k]
+    print of (report of tracker)
+x is 100.0
+loop while not (converged of x):
+    x is x * 0.5
+q is game.pos[0]
+print of (report of q)
+EIGS
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_not_contains "#1048 W024 silent on fixed field/element, call-rebound base, non-counter subscript, flat series replay" "$OUTPUT" "W024"
+LINT_STATUS=0; $EIGS --lint "$TMPFILE" >/dev/null 2>&1 || LINT_STATUS=$?
+check_status "#1048 W024 negatives lint clean (exit 0)" "$LINT_STATUS" "0"
+rm -f "$TMPFILE"
+
+# The asymmetry row from the issue's last comment, measured with `when is q`:
+# a MODULE-LEVEL `for`-body `local` is fresh each iteration (one observation,
+# every read answers equilibrium), while inside a function it is a persisting
+# frame slot that interleaves like a `loop while` binding. Both are wrong for
+# the per-entity read; the lint names each.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+cat > "$TMPFILE" << 'EIGS'
+fleet is [["a", 0, 100.0], ["b", 0, 1.0]]
+for i in range of 2:
+    local q is fleet[i][2]
+    print of (report_value of q)
+for k in range of 5:
+    local y is k * 2.0
+    print of (report of y)
+define scan as:
+    for i in range of 2:
+        local r is fleet[i][2]
+        print of (report_value of r)
+    for k in range of 5:
+        local z is k * 2.0
+        print of (report of z)
+for k in range of 5:
+    local w is k * 2.0
+    w is w * 0.5
+    print of (report of w)
+scan of []
+EIGS
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_contains "#1048 W024 module for-body local from an element: always equilibrium" "$OUTPUT" ":3: warning\[W024\]: 'q' is a 'for'-body local, fresh each iteration"
+check_contains "#1048 W024 module for-body local (element): names the interleave alternative" "$OUTPUT" "persisting binding would interleave"
+check_contains "#1048 W024 module for-body local (any RHS): always equilibrium" "$OUTPUT" ":6: warning\[W024\]: 'y' is a 'for'-body local, fresh each iteration"
+check_contains "#1048 W024 module for-body local (any RHS): advice is bind before the loop" "$OUTPUT" "bind it before the loop so its slot persists"
+check_contains "#1048 W024 function for-body local from an element: interleave (frame slot persists)" "$OUTPUT" ":10: warning\[W024\]: 'r' is rebound from 'fleet\[..\]\[..\]'"
+check_not_contains "#1048 W024 silent: function for-body local with its own trajectory (line 13)" "$OUTPUT" ":13: warning\[W024\]"
+check_not_contains "#1048 W024 silent: module for-body local assigned twice per iteration (line 16)" "$OUTPUT" ":16: warning\[W024\]"
+rm -f "$TMPFILE"
+
+# The runtime facts the two messages rest on (so the asymmetry cannot drift
+# silently under the lint): one observation per module-level iteration,
+# thirty inside a function.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+cat > "$TMPFILE" << 'EIGS'
+xs is [100.0, 1.0]
+for k in range of 30:
+    local q is xs[k % 2]
+    if k == 29:
+        print of ("module when=" + (str of (when is q)))
+define f as:
+    for k in range of 30:
+        local r is xs[k % 2]
+        if k == 29:
+            print of ("function when=" + (str of (when is r)))
+f of []
+EIGS
+RUN=$($EIGS "$TMPFILE" 2>&1 || true)
+check_contains "#1048 module-level for-body local is fresh per iteration (when=1)" "$RUN" "^module when=1$"
+check_contains "#1048 function for-body local persists across iterations (when=30)" "$RUN" "^function when=30$"
+rm -f "$TMPFILE"
+
+# --- #1048 round 2: a long identifier may not break the message ----------
+# W024 is the first rule to interpolate an unbounded identifier twice, so it
+# was the first whose message could overflow LintWarning.message[256]. The
+# overflow cut inside the em dash of the remedy clause: `--lint --json` then
+# emitted a lone 0xE2 (invalid UTF-8 — Python's decoder rejects it, jq hides
+# it behind U+FFFD) and the human line lost the only actionable half. The fix
+# budgets the IDENTIFIERS (middle ellipsis, UTF-8 boundaries) instead of the
+# message, so these assertions are: valid UTF-8, remedy present, suffix kept.
+check_json_utf8() {   # $1 = name, $2 = file — decode BOTH outputs STRICTLY
+    TOTAL=$((TOTAL + 1))
+    local test_name="$1" f="$2" out rc
+    # The human line on stderr is the other consumer and has its own copy of
+    # the bytes; decode it too, or a fix in the JSON escaper alone would hide
+    # a message buffer that is still malformed.
+    if ! "$EIGS" --lint "$f" 2>&1 >/dev/null | python3 -c 'import sys; sys.stdin.buffer.read().decode("utf-8")' 2>/dev/null; then
+        echo "  FAIL: $test_name (human --lint output is not valid UTF-8)"; FAIL=$((FAIL + 1)); return
+    fi
+    out=$("$EIGS" --lint --json "$f" 2>/dev/null | python3 -c '
+import json, sys
+raw = sys.stdin.buffer.read()
+try:
+    d = json.loads(raw.decode("utf-8"))
+except UnicodeDecodeError as e:
+    print("NOT-UTF8 %s" % e); raise SystemExit(1)
+except Exception as e:
+    print("NOT-JSON %s" % e); raise SystemExit(1)
+for x in d:
+    n = len(x["message"].encode("utf-8"))
+    if n > 255:
+        print("OVERLONG %d" % n); raise SystemExit(1)
+print("OK")
+')
+    rc=$?
+    if [ $rc -eq 0 ] && [ "$out" = "OK" ]; then
+        echo "  PASS: $test_name"; PASS=$((PASS + 1))
+    else
+        echo "  FAIL: $test_name ($out)"; FAIL=$((FAIL + 1))
+    fi
+}
+
+# 37+ characters: the threshold the defect was found at. Real names in this
+# ecosystem reach 42 (`diagnostic_header_unterminated_text_concat`).
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+cat > "$TMPFILE" << 'EIGS'
+fleet is [["a", 0, 100.0], ["b", 0, 1.0]]
+i is 0
+loop while i < 2:
+    local _cumulative_mean_normalized_difference is fleet[i][2]
+    print of diverging of _cumulative_mean_normalized_difference
+    i is i + 1
+EIGS
+check_json_utf8 "#1048 W024 --lint --json is valid UTF-8 for a 38-char identifier" "$TMPFILE"
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_contains "#1048 W024 keeps its remedy clause at a 38-char identifier" "$OUTPUT" "use one named binding or one closure per entity"
+check_contains "#1048 W024 keeps the container spelling at a 38-char identifier" "$OUTPUT" "rebound from 'fleet\[\.\.\]\[\.\.\]'"
+rm -f "$TMPFILE"
+
+# A 200-character identifier AND a 300-character container name: the message
+# must still be valid, still end with the remedy, and still show the [..][..]
+# that says this is a projection of one element rather than the whole list.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+LONGV="v$(printf 'x%.0s' $(seq 1 199))"
+LONGC="c$(printf 'y%.0s' $(seq 1 299))"
+cat > "$TMPFILE" << EIGS
+$LONGC is [["a", 0, 100.0], ["b", 0, 1.0]]
+i is 0
+loop while i < 2:
+    local $LONGV is ${LONGC}[i][2]
+    print of diverging of $LONGV
+    i is i + 1
+EIGS
+check_json_utf8 "#1048 W024 --lint --json is valid UTF-8 for a 200-char identifier" "$TMPFILE"
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_contains "#1048 W024 keeps its remedy clause at a 200-char identifier" "$OUTPUT" "use one named binding or one closure per entity"
+check_contains "#1048 W024 keeps the [..][..] suffix at a 300-char container name" "$OUTPUT" "\.\.\.[a-z]*\[\.\.\]\[\.\.\]"
+check_contains "#1048 W024 ellipsises the identifier, not the message" "$OUTPUT" "'v[a-z]*\.\.\.[a-z]*' is rebound"
+rm -f "$TMPFILE"
+
+# The `for`-body-local messages take the same identifier budget.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+LONGV="w$(printf 'x%.0s' $(seq 1 199))"
+cat > "$TMPFILE" << EIGS
+fleet is [["a", 0, 100.0], ["b", 0, 1.0]]
+for k in range of 2:
+    local $LONGV is fleet[k][2]
+    print of (report of $LONGV)
+EIGS
+check_json_utf8 "#1048 W024 for-body message is valid UTF-8 at 200 chars" "$TMPFILE"
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_contains "#1048 W024 for-body message keeps its remedy clause at 200 chars" "$OUTPUT" "use one named binding or one closure per entity"
+rm -f "$TMPFILE"
+
+# Why the fixtures above are all ASCII: the lexer admits no other identifier.
+# tools/lint_message_utf8_check.sh states that as its reason for not driving a
+# multi-byte name, so it is pinned here rather than assumed.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+printf 'q\xc3\xa9nergie is 2\nprint of q\xc3\xa9nergie\n' > "$TMPFILE"
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_contains "#1048 the lexer rejects a non-ASCII identifier (so fixtures are ASCII)" "$OUTPUT" "parse error"
+rm -f "$TMPFILE"
+
+# Deliberate sites carry the allow comment like every other code.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+cat > "$TMPFILE" << 'EIGS'
+fleet is [["a", 0, 100.0], ["b", 0, 1.0]]
+i is 0
+loop while i < 2:
+    local q is fleet[i][2]   # lint: allow W024
+    if diverging of q:
+        print of i
+    i is i + 1
+EIGS
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_not_contains "#1048 '# lint: allow W024' suppresses it" "$OUTPUT" "W024"
+rm -f "$TMPFILE"
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed, $TOTAL total"
 exit $FAIL
diff --git a/tools/lint_message_sweep.py b/tools/lint_message_sweep.py
new file mode 100644
index 00000000..8a4521d9
--- /dev/null
+++ b/tools/lint_message_sweep.py
@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Sweep identifier length across the longest lint messages, decoding strictly.
+
+Driven by tools/lint_message_utf8_check.sh (#1048). The defect this exists for
+is LENGTH-SENSITIVE: a lint message is assembled into a 256-byte buffer, and as
+the interpolated identifier grows the truncation point walks through the
+message. Only the lengths that land it inside a multi-byte character (the em
+dashes and typographic quotes the messages themselves carry) produce malformed
+output, so a corpus of hand-picked lengths misses it. Measured against
+v0.43.0 — the release before the fix — each of these shapes has a narrow band
+of bad lengths and nothing outside it:
+
+    W024  len 56           (both channels)
+    W015  len 74           (both channels)
+    W018  len 198, 199     (both channels)
+    W023  len 161, 162     (both channels)
+
+Those four are the rules whose messages are long enough to truncate at a
+plausible identifier length; W024 is merely the one a consumer hit. Both
+channels are decoded, because the human line on stderr and the `--lint --json`
+payload on stdout carry separate copies of the bytes and were fixed at
+different chokepoints.
+
+Residual: this sweeps FOUR shapes, not every rule. The class guarantee is the
+structural one the caller checks — every diagnostic is assembled by lint_vdiag,
+which truncates through lint_utf8_prefix — and this is its empirical
+corroboration, not its proof.
+"""
+import os
+import subprocess
+import sys
+import tempfile
+
+MAX_LEN = 250
+
+
+def shape(code: str, n: int) -> str:
+    a = "q" + "z" * (n - 1)
+    if code == "W024":
+        return ("fleet is [[1, 2, 3.0], [4, 5, 6.0]]\ni is 0\nloop while i < 2:\n"
+                "    local %s is fleet[i][2]\n    print of diverging of %s\n"
+                "    i is i + 1\n" % (a, a))
+    if code == "W015":
+        return ("define %s() as:\n    return 1\ndefine g() as:\n    %s is 5\n"
+                "    return %s\nprint of (g of [])\n" % (a, a, a))
+    if code == "W018":
+        return ('try:\n    print of ([] of 1)\ncatch %s:\n'
+                '    if %s.kind == "IO":\n        print of 1\n' % (a, a))
+    if code == "W023":
+        return ("%s is 5\ndefine f(flag) as:\n    if flag == 1:\n        local %s is 1\n"
+                "    else:\n        %s is 2\n    return %s\nprint of (f of 0)\n"
+                % (a, a, a, a))
+    raise KeyError(code)
+
+
+def main() -> int:
+    eigs = sys.argv[1]
+    codes = ["W024", "W015", "W018", "W023"]
+    bad, seen, runs = [], 0, 0
+    for code in codes:
+        for n in range(1, MAX_LEN + 1):
+            with tempfile.NamedTemporaryFile("w", suffix=".eigs", delete=False) as f:
+                f.write(shape(code, n))
+                path = f.name
+            try:
+                for mode in (["--lint"], ["--lint", "--json"]):
+                    r = subprocess.run([eigs] + mode + [path], capture_output=True)
+                    out = r.stdout if "--json" in mode else r.stderr
+                    runs += 1
+                    if code.encode() in out:
+                        seen += 1
+                    try:
+                        out.decode("utf-8")
+                    except UnicodeDecodeError as e:
+                        bad.append("%s len=%d %s: %s" % (code, n, " ".join(mode), e))
+            finally:
+                os.unlink(path)
+    # Vacuity guard: every length of every shape must have produced its own
+    # code on both channels. Without it, a shape that stopped firing (a rule
+    # renamed, a fixture that no longer parses) would sweep clean and pass.
+    if seen < runs:
+        print("VACUOUS: only %d of %d outputs carried their code" % (seen, runs))
+        return 1
+    if bad:
+        print("MALFORMED: " + "; ".join(bad[:6]))
+        return 1
+    print("swept %d shapes x %d lengths x 2 channels (%d runs), all decode"
+          % (len(codes), MAX_LEN, runs))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/tools/lint_message_utf8_check.sh b/tools/lint_message_utf8_check.sh
new file mode 100755
index 00000000..1683136d
--- /dev/null
+++ b/tools/lint_message_utf8_check.sh
@@ -0,0 +1,303 @@
+#!/bin/bash
+# lint_message_utf8_check.sh — no lint diagnostic may be malformed UTF-8.
+#
+# WHY THIS EXISTS (#1048). A lint message is assembled into a fixed 256-byte
+# buffer (`LintWarning.message`) and shipped two ways: the human line on
+# stderr and `--lint --json`, which `eigenlsp` mirrors into JSON-RPC. W024 was
+# the first rule to interpolate an unbounded identifier more than once, and at
+# a ~37-character name its message truncated INSIDE an em dash, emitting a
+# lone 0xE2. Python's decoder rejects that payload; `jq` hides it by
+# substituting U+FFFD. The bug is a property of the CLASS (any rule, any long
+# name), so this gate polices the class rather than that one rule:
+#
+#   1. every registered diagnostic code is driven by a fixture built around a
+#      200-character identifier, and every fixture's `--lint --json` output is
+#      decoded STRICTLY (`bytes.decode('utf-8')` + `json.loads`) — no jq, which
+#      is lenient exactly where this bug lives;
+#   2. each fixture must actually PRODUCE its code, so the corpus cannot rot
+#      into a set of files that lint clean and pass vacuously;
+#   3. the registry is checked in BOTH directions — a code in docs/DIAGNOSTICS.md
+#      with no fixture and no pinned exemption fails, and so does a fixture for
+#      a code the docs do not list;
+#   4. each pinned exemption must still be TRUE: the codes marked unreachable
+#      are re-driven and must still come back as a parse error (E002). If a
+#      future parser accepts an empty block, this goes red and asks for the
+#      real fixture instead of quietly waiving it.
+#
+# WHAT IT DOES NOT COVER (residuals, stated so the green means something):
+#   - It exercises each code ONCE, with one pathological shape. A rule whose
+#     message interpolates something else unbounded (a string literal, a path)
+#     can still be long in a way no fixture here reaches. The structural half
+#     below is what backs that up: every diagnostic in the tree is assembled by
+#     lint_vdiag, which truncates through lint_utf8_prefix, so a message can be
+#     clipped but never halved mid-character. This script asserts that the
+#     chokepoint is still the only writer.
+#   - It says nothing about whether a truncated message is still USEFUL. That
+#     is the rule author's job (W024 shrinks its identifiers instead, so its
+#     remedy clause always survives); tests/test_lint.sh pins it for W024.
+#   - The identifier is ASCII because the lexer admits no other kind (isalpha,
+#     C locale — verified: a UTF-8 identifier is a syntax error). The multi-byte
+#     bytes in play are the ones the MESSAGES themselves carry (em dash,
+#     arrows), which is exactly where the bug was.
+#
+# Cost: ~35 binary invocations for the per-code half plus the sweep's 2000
+# (four shapes x 250 lengths x 2 channels) — about 20s on the dev box under
+# load, which is the price of a length band one or two values wide.
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+EIGS="${EIGENSCRIPT_BIN:-$ROOT/src/eigenscript}"
+FIXDIR="$ROOT/tests/lint_utf8"
+DOCS="$ROOT/docs/DIAGNOSTICS.md"
+
+# Pinned exemptions: code -> reason. Each is re-verified below.
+EXEMPT_CODES="E001 W004 W005 W006 W007 W008 W009 W011"
+exempt_reason() {
+    case "$1" in
+    E001) echo "reserved and never emitted (docs/DIAGNOSTICS.md says so); lexer failures surface as E002" ;;
+    W004|W005|W006|W007|W008|W009)
+          echo "empty block: the parser requires at least one statement, so no source reaches it (re-verified: fixture is E002)" ;;
+    W011) echo "'is' in a condition: the parser now rejects it before the linter sees it (re-verified: fixture is E002)" ;;
+    *)    echo "" ;;
+    esac
+}
+
+fail=0
+checked=0
+note() { printf '%s\n' "$*"; }
+bad()  { printf 'FAIL: %s\n' "$*"; fail=$((fail + 1)); }
+
+if [ ! -x "$EIGS" ]; then echo "FAIL: no binary at $EIGS"; exit 1; fi
+if [ ! -d "$FIXDIR" ]; then echo "FAIL: no fixture dir $FIXDIR"; exit 1; fi
+
+# --- the strict decoder (python3, never jq) --------------------------------
+decode() {   # $1 = file of raw --lint --json bytes; $2 = code that must appear
+    python3 - "$1" "$2" <<'PY'
+import json, sys
+raw = open(sys.argv[1], 'rb').read()
+want = sys.argv[2]
+try:
+    text = raw.decode('utf-8')
+except UnicodeDecodeError as e:
+    print("NOT-UTF8 %s" % e); sys.exit(2)
+try:
+    diags = json.loads(text)
+except Exception as e:
+    print("NOT-JSON %s: %s" % (type(e).__name__, e)); sys.exit(3)
+codes = [d.get('code') for d in diags]
+if want and want not in codes:
+    print("MISSING %s (got %s)" % (want, ','.join(c or '?' for c in codes) or 'none')); sys.exit(4)
+for d in diags:
+    m = d.get('message', '')
+    if not isinstance(m, str):
+        print("NON-STRING message"); sys.exit(5)
+    # A message that ends inside a word is allowed (lint_copy_utf8 marks it
+    # "..."); one that is not valid UTF-8 is what this gate forbids, and
+    # json.loads above already proved that for the whole payload.
+    if len(m.encode('utf-8')) > 255:
+        print("OVERLONG %d bytes" % len(m.encode('utf-8'))); sys.exit(6)
+print("OK %d diagnostic(s)" % len(diags))
+PY
+}
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+# --- --selftest: prove each half FAILS on a planted fault ------------------
+# A gate that only ever passes is indistinguishable from one that measures
+# nothing, and three of the four checks here are cheap to neuter by accident.
+if [ "${1:-}" = "--selftest" ]; then
+    st_fail=0
+    st() {  # $1 = what, $2 = expected-nonzero command output/rc
+        if [ "$2" = "0" ]; then echo "SELFTEST-FAIL: $1 did not fire"; st_fail=1
+        else echo "  selftest ok: $1 fires"; fi
+    }
+    # 1. a payload cut mid-UTF-8 (the #1048 byte) must be rejected
+    printf '[{"code":"W024","severity":"warning","line":1,"file":"f","message":"x \xe2"}]\n' > "$TMP/st1.json"
+    decode "$TMP/st1.json" W024 >/dev/null 2>&1; st "mid-UTF-8 payload" $?
+    # 2. a valid payload that lacks the expected code (a fixture gone vacuous)
+    printf '[{"code":"W001","severity":"warning","line":1,"file":"f","message":"ok"}]\n' > "$TMP/st2.json"
+    decode "$TMP/st2.json" W024 >/dev/null 2>&1; st "fixture that stopped firing its code" $?
+    # 3. an over-long message (a rule that outgrew the buffer)
+    python3 -c "
+import json,sys
+json.dump([{'code':'W024','severity':'warning','line':1,'file':'f','message':'x'*300}], open('$TMP/st3.json','w'))
+"
+    decode "$TMP/st3.json" W024 >/dev/null 2>&1; st "message longer than the 255-byte buffer" $?
+    # 4. the structural check: a lint.c whose chokepoint copy is gone
+    sed 's/lint_copy_utf8(w->message, sizeof(w->message), rendered);/vsnprintf(w->message, sizeof(w->message), fmt, ap);/' \
+        "$ROOT/src/lint.c" > "$TMP/lint_planted.c"
+    grep -q 'lint_copy_utf8(w->message, sizeof(w->message), rendered);' "$TMP/lint_planted.c"; st "chokepoint removed from lint_vdiag" $?
+    # 5. a NEW rule added to a lint TU with no row in docs/DIAGNOSTICS.md —
+    #    the direction that makes this gate cover rules that do not exist yet.
+    printf 'lint_warn(ctx, 1, "W099", "a new rule");\n' > "$TMP/newrule.c"
+    st_probe="$(grep -ohE '"[WE]0[0-9][0-9]"' "$TMP/newrule.c" | tr -d '"')"
+    st_docs="$(grep -oE '^\| *`[WE]0[0-9][0-9]`' "$DOCS" | grep -oE '[WE]0[0-9][0-9]' | sort -u | tr '\n' ' ')"
+    case " $st_docs " in
+        *" $st_probe "*) st "undocumented new lint code" 0 ;;
+        *) st "undocumented new lint code" 1 ;;
+    esac
+    # 6. an empty fixture dir (the whole corpus deleted) must not read as clean
+    mkdir -p "$TMP/emptyfix"
+    ls "$TMP/emptyfix"/*.eigs >/dev/null 2>&1; st "empty fixture directory" $?
+    [ "$st_fail" -eq 0 ] && { echo "OK: gate self-test — planted faults all caught"; exit 0; }
+    echo "FAILED: the gate no longer catches a planted fault"; exit 1
+fi
+
+# --- 1/2. every fixture fires its code and decodes strictly ----------------
+fixture_codes=""
+for f in "$FIXDIR"/*.eigs; do
+    [ -e "$f" ] || { bad "no fixtures in $FIXDIR"; break; }
+    code="$(basename "$f" .eigs)"
+    fixture_codes="$fixture_codes $code"
+    "$EIGS" --lint --json "$f" > "$TMP/out.json" 2>/dev/null
+    out="$(decode "$TMP/out.json" "$code")"
+    rc=$?
+    checked=$((checked + 1))
+    if [ $rc -ne 0 ]; then bad "$code: $out"; else note "  ok   $code  ($out)"; fi
+done
+
+# --- E000: the unreadable-file path, which has no fixture file -------------
+"$EIGS" --lint --json "$TMP/no-such-$(printf 'z%.0s' $(seq 1 200)).eigs" > "$TMP/e000.json" 2>/dev/null
+out="$(decode "$TMP/e000.json" E000)"; rc=$?
+checked=$((checked + 1))
+if [ $rc -ne 0 ]; then bad "E000: $out"; else note "  ok   E000 ($out)"; fi
+fixture_codes="$fixture_codes E000"
+
+# --- 3. registry, both directions ------------------------------------------
+doc_codes="$(grep -oE '^\| *`[WE]0[0-9][0-9]`' "$DOCS" | grep -oE '[WE]0[0-9][0-9]' | sort -u | tr '\n' ' ')"
+[ -n "$doc_codes" ] || bad "docs/DIAGNOSTICS.md yielded no codes (matcher broke)"
+used_exempt=""
+for c in $doc_codes; do
+    case " $fixture_codes " in *" $c "*) continue ;; esac
+    case " $EXEMPT_CODES " in
+        *" $c "*) used_exempt="$used_exempt $c"; note "  wvr  $c  ($(exempt_reason "$c"))" ;;
+        *) bad "$c is documented but has neither a fixture nor a pinned exemption" ;;
+    esac
+done
+for c in $fixture_codes; do
+    case " $doc_codes " in
+        *" $c "*) ;;
+        *) bad "fixture $c.eigs has no row in docs/DIAGNOSTICS.md" ;;
+    esac
+done
+# ...and the third direction, which is what makes this cover rules that do not
+# exist yet: a code emitted by the lint TUs must be DOCUMENTED, so a new rule
+# lands with a row here and then with a fixture. (Residual: it scans the two
+# lint TUs for code literals; codes recorded by the parser through
+# eigs_record_first_error_code_at — E001/E002/E005 — are covered by the
+# docs->fixture direction above, not by this scan.)
+src_codes="$(grep -ohE '"[WE]0[0-9][0-9]"' "$ROOT/src/lint.c" "$ROOT/src/lint_host.c" | tr -d '"' | sort -u)"
+[ -n "$src_codes" ] || bad "no diagnostic codes found in the lint TUs (matcher broke)"
+for c in $src_codes; do
+    case " $doc_codes " in
+        *" $c "*) ;;
+        *) bad "$c is emitted by src/lint*.c but has no row in docs/DIAGNOSTICS.md" ;;
+    esac
+done
+
+# --- 4. every exemption is still true --------------------------------------
+for c in $EXEMPT_CODES; do
+    case " $used_exempt " in *" $c "*) ;; *)
+        case " $fixture_codes " in
+            *" $c "*) bad "$c is exempt AND has a fixture — drop the exemption" ;;
+            *) bad "$c is exempt but not in docs/DIAGNOSTICS.md — stale waiver" ;;
+        esac ;;
+    esac
+done
+# The unreachable ones must STILL be unreachable: drive the shape and require
+# a parse error. If the parser ever accepts it, this fails and asks for a
+# real fixture rather than waiving a code that now has a source form.
+unreachable_probe() {   # $1 = code, $2 = source
+    printf '%s' "$2" > "$TMP/probe.eigs"
+    "$EIGS" --lint --json "$TMP/probe.eigs" > "$TMP/probe.json" 2>/dev/null
+    if ! grep -q '"code":"E002"' "$TMP/probe.json"; then
+        bad "$1: the shape its exemption calls unparseable now parses — write a fixture"
+    else
+        checked=$((checked + 1))
+    fi
+}
+unreachable_probe W004 'x is 1
+if x == 1:
+    # empty
+print of x
+'
+unreachable_probe W005 'x is 0
+loop while x > 0:
+    # empty
+print of x
+'
+unreachable_probe W006 'for k in range of 2:
+    # empty
+print of 1
+'
+unreachable_probe W007 'define f() as:
+    # empty
+print of 1
+'
+unreachable_probe W008 'try:
+    # empty
+catch e:
+    print of 1
+'
+unreachable_probe W009 'try:
+    print of 1
+catch e:
+    # empty
+print of 2
+'
+unreachable_probe W011 'x is 1
+if x is 1:
+    print of 1
+'
+
+# --- boundary sweep: no IDENTIFIER LENGTH may break the message ------------
+# The single-fixture checks above test one length each, and the defect is
+# length-sensitive: the cut walks through the message as the name grows, and
+# only the lengths that land it inside a multi-byte character are malformed.
+# Measured against v0.43.0, the release before the fix: W015 breaks at a
+# 74-character name, W023 at 161-162, W018 at 198-199 — and W024, the one a
+# consumer reported, at 56. Each band is one or two lengths wide out of 250, so
+# a corpus of hand-picked lengths misses them; this is also why "no
+# pre-existing rule is long enough" was wrong as an argument. Both channels are
+# decoded: the human line and the JSON payload hold separate copies of the
+# bytes and are repaired at different chokepoints.
+sweep_out="$(python3 "$ROOT/tools/lint_message_sweep.py" "$EIGS")"
+if [ $? -ne 0 ]; then bad "identifier-length sweep: $sweep_out"; else note "  ok   sweep ($sweep_out)"; checked=$((checked + 1)); fi
+
+# --- structural half: the chokepoint is still the only writer --------------
+# Every diagnostic is assembled by lint_vdiag, which renders into a scratch
+# and copies through lint_copy_utf8/lint_utf8_prefix. A rule that formats
+# straight into a message buffer would bypass the boundary check, so no other
+# writer may exist. (Matcher residual: it looks for the assembly spellings
+# below, not for aliasing through a pointer.)
+LINTC="$ROOT/src/lint.c"
+if ! grep -q 'lint_copy_utf8(w->message, sizeof(w->message), rendered);' "$LINTC"; then
+    bad "lint_vdiag no longer copies the message through lint_copy_utf8"
+else
+    checked=$((checked + 1))
+fi
+strays="$(grep -nE '(vs|s)?n?printf\([^)]*->message' "$LINTC" "$ROOT/src/lint_host.c" | grep -v 'lint_copy_utf8' || true)"
+if [ -n "$strays" ]; then
+    bad "a diagnostic message is formatted outside lint_vdiag: $strays"
+else
+    checked=$((checked + 1))
+fi
+if ! grep -q 'lint_utf8_prefix(out, o)' "$ROOT/src/lint_host.c"; then
+    bad "lint_json_escape no longer clips on a UTF-8 boundary"
+else
+    checked=$((checked + 1))
+fi
+
+# --- verdict ---------------------------------------------------------------
+# Floor, not an exact count: adding a rule (and its fixture) raises it, and
+# only REMOVING coverage needs an edit here.
+FLOOR=33
+if [ "$checked" -lt "$FLOOR" ]; then
+    bad "only $checked checks ran, floor is $FLOOR — coverage was removed"
+fi
+if [ "$fail" -eq 0 ]; then
+    echo "OK: lint message UTF-8 gate — $checked checks, $(echo $doc_codes | wc -w) documented codes, $(echo $used_exempt | wc -w) pinned exemptions"
+    exit 0
+fi
+echo "FAILED: $fail problem(s)"
+exit 1

From 644e080c2738e1c98092b7899a49983715915a57 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 18:40:10 +0000
Subject: [PATCH 22/39] modules: a namespace is a LIVE VIEW of the module env,
 not a snapshot (#1057)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`import M` bound a SHALLOW COPY of M's top-level bindings, so whether an
importer saw live state depended on the VALUE'S TYPE: a dict or list was
shared by reference and tracked, a number or string was frozen at import
time and went silently stale, and `M.x is v` reached only the copy. The
rule users had to learn — "module state must be boxed in a container or it
goes stale in your importer" — had no principle behind it, and its failure
mode was a wrong number rather than an error. Nine stdlib modules exist in
that shape.

Minimal repro (baseline v0.43.0 / a6c50fb):

    # q4.eigs: ctr is 0 / define bump() as: ctr is ctr + 1
    #                   / define peek() as: return ctr
    import q4
    q4.bump of null
    q4.bump of null
    print of f"module internal view: {q4.peek of null}"   -> 2
    print of f"dict view:            {q4.ctr}"            -> 0    <-- stale
    import q3            # v is 1 / define peek() as: return v
    q3.v is 42
    print of f"namespace read: {q3.v}"                    -> 42
    print of f"module peek:    {q3.peek of null}"         -> 1    <-- never saw it

After: 2 / 2 and 42 / 42. The container probe (`_q5`) is unchanged at 1 / 1.

Design (shape (i) of the two the issue sketched; recorded here because the
alternative was priced): the namespace stays a VAL_DICT and gains a flag,
`Value::module_ns`, plus an OWNING backref to the module `Env`.

  - The flag byte lands in struct Value's existing TAIL PADDING, so
    sizeof(Value) is unchanged at 72 bytes (measured both sides). The Env*
    itself lives in a small side table keyed by the dict pointer
    (eigs_module_ns_env) rather than in the union, which would have grown
    every Value in the system by 8 bytes for a feature a handful of dicts
    use.
  - A field READ projects the module's current binding into the dict slot
    and returns it (`dict_get_hashed`); an exclusive untracked numeric
    mirror is refreshed in place, so a hot `M.CONST` read allocates
    nothing. A field WRITE goes through to the module binding
    (`dict_set_hashed` -> `env_set_local_hashed`) and mirrors into the dict.
  - The dict's own storage is kept as that mirror, so a namespace is still
    an ordinary dict for every whole-dict reader — `keys`, `values`, `len`,
    `str`, `json_encode`, equality, truthiness, channel send — each of
    which now calls `eigs_module_ns_sync` first.
  - `_`-prefixed module bindings stay private: never projected, never
    written.
  - VAL_MODULE (shape (ii)) was rejected: it puts a new arm on every
    closed-enum switch AND on every `type != VAL_DICT` comparison, and
    -Werror=switch only enumerates the first kind.

Ownership and the collector: attach takes `env_incref`, so dict -> env is a
new OWNED edge and gets ONE row in GC_EDGE_TABLE (walked by
GC_FOR_EACH_CHILD, cleared by gc_clear_node); `free_value` is the non-cycle
mirror of that row. `docs/CLOSURE_CYCLE_GC.md` lists the edge.

Caches: the interpreter's `dict_get_cached` / `dict_set_cached` /
`dict_set_cached_immediate` bail on the flag (their slots are the mirror),
and the JIT's inline dict probe carries the same guard — one
`testb $1, module_ns(%rdi)` + `jne` right after its `type == VAL_DICT`
check, per the "inline fast paths mirror the interpreter" rule.
`module_ns_project` / `_sync` take `env_shared_lock` around the env load
exactly as `env_get_hashed_slot` does (#607).

Regression test: `tests/test_module_live_view.eigs` (30 checks, wired into
run_all_tests.sh) with companion modules `tests/modlive_{counter,box,plain,
outer}.eigs`. It pins the issue's three probes plus the controls that must
NOT move: containers still shared by reference, a value read OUT of a
namespace is a value and not an alias, functions callable as `M.f of x` and
extractable as values, `type of M` still "dict", `keys`/`len`/`has_key`,
`_`-privacy, `str`/`json_encode` current, the module cache returning the
same live state on re-import, a new key written through the namespace
binding in the module, nested imports live through the outer namespace, and
the `load_file` and `eval` roads unchanged.

Planted fault: removing the `eigs_module_ns_attach` call in OP_IMPORT
restores snapshot semantics and takes the section red 9/30 — the same nine
checks the baseline binary fails.

`lib/eigen.eigs` mirrors the rule (a name-keyed module-env registry
consulted by `dot`/`dot_assign`). It is not reachable today: that
interpreter's `import` reads its module with
`read_text of ("lib/" + name + ".eigs")`, which resolves to "" instead of
raising, so every meta-interpreted import has produced an EMPTY namespace
since long before this change (`eigen_run of "import math\nkeys of math"`
-> `[]` on the baseline too). Separate gap, noted in the file.

Validation: release suite 4279/4279 (0 FAIL); ASan+UBSan suite with
detect_leaks=1 4280/4280 (0 FAIL, no leak-tally NOTE — tally still 0,
section [87] closure-cycles leak-clean); `tools/road_diff.sh`
fixtures=21 runs=198 failures=0; `tools/jit_diff.sh` OK (231 programs x
{jit, osr}, 0 ledgered); `tools/replay_diff.sh` OK (231 programs, 0
ledgered); `make jit-smoke` green; the three probes byte-identical under
`EIGS_JIT_OFF=1` and `EIGS_JIT_OSR_THRESHOLD=1`.

Closes #1057

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
(cherry picked from commit 6278a480ca957f1af03e14faa0dd7bfd33aa74d9)
---
 docs/CLOSURE_CYCLE_GC.md         |   5 +-
 docs/COMPARISON.md               |  21 +++
 docs/JIT_STAGE5_INLINE_IC.md     |  11 ++
 docs/LANGUAGE_CONTRACT.md        |  12 +-
 docs/SPEC.md                     |  49 ++++++-
 docs/llms.txt                    |   6 +
 lib/eigen.eigs                   |  46 +++++++
 src/builtins.c                   |   7 +-
 src/eigenscript.c                | 225 ++++++++++++++++++++++++++++++-
 src/eigenscript.h                |  23 ++++
 src/jit.c                        |   5 +-
 src/vm.c                         |  16 +++
 tests/modlive_box.eigs           |  10 ++
 tests/modlive_counter.eigs       |  17 +++
 tests/modlive_outer.eigs         |  11 ++
 tests/modlive_plain.eigs         |   5 +
 tests/run_all_tests.sh           |   1 +
 tests/test_module_live_view.eigs |  99 ++++++++++++++
 18 files changed, 556 insertions(+), 13 deletions(-)
 create mode 100644 tests/modlive_box.eigs
 create mode 100644 tests/modlive_counter.eigs
 create mode 100644 tests/modlive_outer.eigs
 create mode 100644 tests/modlive_plain.eigs
 create mode 100644 tests/test_module_live_view.eigs

diff --git a/docs/CLOSURE_CYCLE_GC.md b/docs/CLOSURE_CYCLE_GC.md
index a06bdf7f..c5bacf29 100644
--- a/docs/CLOSURE_CYCLE_GC.md
+++ b/docs/CLOSURE_CYCLE_GC.md
@@ -98,7 +98,10 @@ as a force-destroy escape hatch (no current callers in main).
 - **Universe.** Everything reachable from registered envs over **owned
   edges only**: env value slots, `env->parent`, `fn->closure`,
   `fn->chunk` (the OP_CLOSURE ref), `chunk->functions[]`,
-  `chunk->env_cache`, list items, dict values. Three node kinds: values
+  `chunk->env_cache`, list items, dict values, and a module namespace's
+  backref to its module env (#1057 — `import M`'s dict is a live view of
+  M's `Env` and holds an owning ref on it; the pointer lives in a side
+  table keyed by the dict, so the `Value` does not grow). Three node kinds: values
   (LIST/DICT/FN — everything else is a leaf), envs, chunks. Chunks are
   on real cycles: `fn → chunk → env_cache → parent → E → fn` is exactly
   the shape a recycled call env creates. `g_global_env` is a stop node —
diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md
index d8505c28..55db515d 100644
--- a/docs/COMPARISON.md
+++ b/docs/COMPARISON.md
@@ -606,6 +606,27 @@ catch e:
 undefined variable 'z'
 ```
 
+An imported module's namespace is a **live view** of that module's
+bindings, the way Python's module objects are — `m.x` reads the current
+binding and `m.x is v` writes it, for a number or string exactly as for
+a dict. It is not a copy taken at import time, so no "box your module
+state in a container or importers go stale" rule exists (#1057):
+
+```eigenscript
+write_text of ["cmp_live.eigs", "seen is 0\ndefine tick() as:\n    seen is seen + 1\n"]
+import cmp_live
+cmp_live.tick of null
+print of cmp_live.seen
+rm of "cmp_live.eigs"
+```
+```output
+1
+```
+
+The namespace is still an ordinary dict, so `keys`, `values`, `len` and
+indexing work on it — closer to a Lua module table than to a Rust `mod`,
+which has no runtime value at all.
+
 <!-- Embed contract: #1038/#1028; language-level observer semantics unchanged. -->
 The C embedding API starts observer recording open. Source evals retain
 cross-unit history by default; hosts may explicitly promise isolated observer
diff --git a/docs/JIT_STAGE5_INLINE_IC.md b/docs/JIT_STAGE5_INLINE_IC.md
index 58dc262d..089c1cc6 100644
--- a/docs/JIT_STAGE5_INLINE_IC.md
+++ b/docs/JIT_STAGE5_INLINE_IC.md
@@ -187,6 +187,17 @@ examples/tests for `__loop_iterations__` before changing semantics).
 - Helper fallback blocks share the epilogue's `%r13d` advance
   machinery — the inline guard-fail jump target is the start of the
   full helper sequence for the *same* op, not the epilogue.
+- **Module namespaces bail out of the dict probe (#1057).** `import M`
+  binds a dict that is a LIVE VIEW of the module's `Env`, so its own
+  `keys`/`vals` slots are only a mirror and must never answer a field
+  read. `emit_dict_cache_probe` therefore carries one extra guard right
+  after the `type == VAL_DICT` check — `testb $1, module_ns(%rdi)`,
+  bailing to the helper when set. The helper routes through
+  `dict_get_hashed` / `dict_set_hashed`, which project the module's
+  current binding. The interpreter's `dict_get_cached` /
+  `dict_set_cached` / `dict_set_cached_immediate` carry the mirror of
+  that guard, so the inline path and the interpreter agree by
+  construction; `tools/jit_diff.sh` is the differential.
 - x86-64 only: everything here is inside `#if defined(__x86_64__)`.
 - Platform gates: the only Linux/Darwin split lives in the prologue's
   TLS load (`#if defined(__APPLE__)` calls `eigs_jit_load_eigs_current`,
diff --git a/docs/LANGUAGE_CONTRACT.md b/docs/LANGUAGE_CONTRACT.md
index b6fb2f59..0491656e 100644
--- a/docs/LANGUAGE_CONTRACT.md
+++ b/docs/LANGUAGE_CONTRACT.md
@@ -76,7 +76,12 @@ bound only its message string.)
 **Promise:** `import name` executes the module once and binds its
 top-level definitions as a **dict named `name`** — nothing enters the
 importing scope besides that one binding, and module names starting
-with `_` are private (omitted from the dict). Import tries `name.eigs`
+with `_` are private (omitted from the dict). That dict is a **live
+view** of the module's bindings, not a snapshot (#1057): `name.x`
+reads the module's current binding and `name.x is v` writes it, for a
+number or string exactly as for a dict or list. Values read *out* of a
+namespace are ordinary values, not aliases. Boxing module state in a
+container is therefore a style choice, not a correctness requirement. Import tries `name.eigs`
 before `lib/name.eigs`, warns on a project/stdlib collision, and chooses
 the project file. `load_file of "path.eigs"` is the
 non-namespaced form: it executes the file directly in the current
@@ -121,7 +126,10 @@ or module binding is restored. See the scope notes below.
 **Status:** Enforced — `tools/road_diff.sh` and `tests/roads/`, `tests/test_import.eigs`,
 `tests/test_import_errors.eigs` (parse-error surfacing for `import` /
 `load_file` / `eval`) (stdlib + user modules,
-namespacing, `_` privacy, missing-module error), docs/SPEC.md Modules
+namespacing, `_` privacy, missing-module error),
+`tests/test_module_live_view.eigs` (#1057: live-view reads and writes,
+container state unchanged, privacy, enumeration, module cache, nested
+imports, load_file/eval roads unchanged), docs/SPEC.md Modules
 examples (executed by the suite).
 
 ## Numbers
diff --git a/docs/SPEC.md b/docs/SPEC.md
index e7601568..535824a1 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -1193,6 +1193,41 @@ side effect
 1
 ```
 
+**A namespace is a live view, not a snapshot** (#1057). `name.x` reads
+the module's *current* binding `x`, and `name.x is v` writes that
+binding — the module and its importers see one state, whatever the
+value's type:
+
+```eigenscript
+write_text of ["spec_live.eigs", "hits is 0\ndefine record() as:\n    hits is hits + 1\ndefine total() as:\n    return hits\n"]
+import spec_live
+spec_live.record of null
+spec_live.record of null
+print of spec_live.hits
+spec_live.hits is 10
+print of (spec_live.total of null)
+rm of "spec_live.eigs"
+```
+```output
+2
+10
+```
+
+Before this, the namespace was a *shallow copy* of the module's
+bindings taken at import time, so whether an importer saw live state
+depended on the value's TYPE: a dict or list was shared by reference
+and tracked, a number or string was frozen and went silently stale, and
+a write through the namespace reached only the copy. The failure mode
+was a wrong number rather than an error. Values read *out* of a
+namespace are ordinary values — `n is name.hits` binds the number, not
+a live alias.
+
+`_`-private bindings are not part of the namespace and are not
+projected; everything else about a namespace is unchanged — it is still
+a dict (`type of name` is `"dict"`), still enumerable with `keys` /
+`values` / `len`, and its functions are still callable as `name.f of x`
+or extractable as values.
+
 `load_file of "path.eigs"` is the older, non-namespaced form: it
 executes a file directly **in the current scope**. The standard
 library's helper modules (`lib/test.eigs`'s `assert_eq`, ...) are
@@ -1250,11 +1285,15 @@ happens to already have — `counter is 0` at a module's top level can
 never rebind an importer's pre-existing `counter`. `load_file` is the
 one exception, per its older, documented contract above: its top-level
 statements still execute directly in the current (caller's) scope, so
-a same-named top-level assignment there *does* bind through. To share
-mutable state across files, put it in a dict or list and mutate fields
-— reads cross the boundary and field/index writes are value mutations,
-not bindings. The standard library's UI toolkit (`lib/ui.eigs`'s `_ui`
-state dict, shared by 17 sub-modules) is the reference pattern.
+a same-named top-level assignment there *does* bind through.
+
+Mutable state shared across files can live in a plain top-level binding
+— an importer reads and writes it through the live namespace (#1057) —
+or in a dict or list whose fields are mutated. Boxing state in a dict
+is now a **style** choice, not a correctness requirement; the standard
+library's UI toolkit (`lib/ui.eigs`'s `_ui` state dict, shared by 17
+sub-modules) remains the reference pattern for grouping related state
+under one private name.
 
 ```eigenscript skip
 load_file of "lib/test.eigs"     # assert_eq, test_summary, ...
diff --git a/docs/llms.txt b/docs/llms.txt
index e43d765b..abe5a8a9 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -211,6 +211,12 @@ import list                              # namespaced: list.filter of [xs, fn]
 load_file of "lib/list.eigs"             # bare names: filter of [xs, fn]
 ```
 
+A module namespace is a **live view** of that module's bindings, not a
+snapshot (#1057): `m.x` reads the module's current `x` and `m.x is v`
+writes it, for a number or string exactly as for a dict or list. There is
+no "box module state in a container or importers go stale" rule. Names
+starting with `_` stay private to the module.
+
 See docs/BUILTINS.md and docs/STDLIB.md before writing your own — or resolve
 a name mechanically: `eigenscript --api --json` dumps every builtin,
 extension (by group), and lib function with its parameter list in one call.
diff --git a/lib/eigen.eigs b/lib/eigen.eigs
index 637c4e06..9876890e 100644
--- a/lib/eigen.eigs
+++ b/lib/eigen.eigs
@@ -1141,6 +1141,23 @@ define eigen_parse(tokens) as:
 # Evaluator
 # ============================================================
 
+# #1057: the module env behind a `M.x` target node, or null when the target is
+# not a bare imported-module name or `x` is module-private (`_`-prefixed names
+# are not part of a namespace and are never projected through it).
+define _ns_env_for(target_node, key) as:
+    if (type of target_node) != "list":
+        return null
+    if (len of target_node) < 2:
+        return null
+    if target_node[0] != "ident":
+        return null
+    if (len of key) > 0:
+        if (char_at of [key, 0]) == "_":
+            return null
+    if (has_key of [_eigen_module_envs, target_node[1]]) == 0:
+        return null
+    return _eigen_module_envs[target_node[1]]
+
 define _env_new(parent) as:
     return [[], parent]
 
@@ -1206,6 +1223,22 @@ define _env_unset_local(env, name) as:
             return null
     return null
 
+# #1057: a module namespace is a LIVE VIEW of the module's bindings, not a
+# snapshot — `M.x` reads M's CURRENT binding and `M.x is v` writes it. The
+# C evaluator carries the module Env on the namespace value itself; here the
+# namespace is a plain dict with no identity to hang it on, so the module env
+# is registered under the imported NAME and `dot`/`dot_assign` consult it when
+# the target is that bare name (the `M.x` form). Keeping it out of the dict is
+# deliberate: `keys of M` must list the module's bindings and nothing else.
+#
+# NOTE: this path is not currently reachable. eigen.eigs's `import` reads its
+# module with `read_text of ("lib/" + name + ".eigs")`, which resolves to ""
+# rather than raising, so EVERY meta-interpreted import has produced an empty
+# namespace since long before #1057 (`eigen_run of "import math\nkeys of math"`
+# -> []). That is a separate meta-interpreter gap; test_meta_parity.eigs covers
+# no import case for the same reason.
+_eigen_module_envs is {}
+
 # Return / break / continue mechanism — global flags
 _eigen_returning is 0
 _eigen_return_val is null
@@ -1474,6 +1507,13 @@ define eigen_eval(node, env) as:
         target is eigen_eval of [node[1], env]
         key is node[2]
         if (type of target) == "dict":
+            # #1057: `M.x` on a module namespace reads M's CURRENT binding.
+            ns_env is _ns_env_for of [node[1], key]
+            if ns_env != null:
+                mbind is ns_env[0]
+                for mi in range of (len of mbind):
+                    if mbind[mi][0] == key:
+                        return mbind[mi][1]
             if (has_key of [target, key]) == 1:
                 return target[key]
             return null
@@ -1484,6 +1524,10 @@ define eigen_eval(node, env) as:
         key is node[2]
         val is eigen_eval of [node[3], env]
         if (type of target) == "dict":
+            # #1057: `M.x is v` on a module namespace writes M's binding.
+            ns_env is _ns_env_for of [node[1], key]
+            if ns_env != null:
+                _env_set_local of [ns_env, key, val]
             dict_set of [target, key, val]
             return val
         throw of f"cannot assign .{key} on {type of target}"
@@ -1647,6 +1691,8 @@ define eigen_eval(node, env) as:
                 first_char is char_at of [bname, 0]
                 if first_char != "_":
                     dict_set of [mod_dict, bname, bval]
+        # #1057: register the module env so the namespace reads/writes live.
+        dict_set of [_eigen_module_envs, mod_name, mod_env]
         _env_set of [env, mod_name, mod_dict]
         return mod_dict
 
diff --git a/src/builtins.c b/src/builtins.c
index 706cd66c..06fafd82 100644
--- a/src/builtins.c
+++ b/src/builtins.c
@@ -481,8 +481,10 @@ Value* builtin_len(Value *arg) {
         return make_num(arg->data.list.count);
     if (arg->type == VAL_STR)
         return make_num(strlen(arg->data.str));
-    if (arg->type == VAL_DICT)
+    if (arg->type == VAL_DICT) {
+        eigs_module_ns_sync(arg);        /* #1057 whole-dict reader */
         return make_num(arg->data.dict.count);
+    }
     if (arg->type == VAL_BUFFER)
         return make_num(arg->data.buffer.count);
     if (arg->type == VAL_TEXT_BUILDER)
@@ -851,6 +853,7 @@ Value* builtin_throw(Value *arg) {
 
 Value* builtin_keys(Value *arg) {
     if (arg->type == VAL_DICT) {
+        eigs_module_ns_sync(arg);        /* #1057 whole-dict reader */
         Value *list = make_list(arg->data.dict.count);
         for (int i = 0; i < arg->data.dict.count; i++)
             list_append_owned(list, make_str(arg->data.dict.keys[i]));
@@ -861,6 +864,7 @@ Value* builtin_keys(Value *arg) {
 
 Value* builtin_values(Value *arg) {
     if (arg->type == VAL_DICT) {
+        eigs_module_ns_sync(arg);        /* #1057 whole-dict reader */
         Value *list = make_list(arg->data.dict.count);
         for (int i = 0; i < arg->data.dict.count; i++)
             list_append(list, arg->data.dict.vals[i]);
@@ -1088,6 +1092,7 @@ static int eigs_json_encode_value(Value *v, strbuf *out, int depth) {
             break;
         }
         case VAL_DICT: {
+            eigs_module_ns_sync(v);      /* #1057 whole-dict reader */
             strbuf_append_char(out, '{');
             for (int i = 0; i < v->data.dict.count; i++) {
                 if (i > 0) strbuf_append_char(out, ',');
diff --git a/src/eigenscript.c b/src/eigenscript.c
index 1d461b1e..78fc91e9 100644
--- a/src/eigenscript.c
+++ b/src/eigenscript.c
@@ -415,6 +415,7 @@ static double compute_entropy_impl(Value *v) {
             return sum / v->data.list.count + log2((double)v->data.list.count + 1.0);
         }
         case VAL_DICT: {
+            eigs_module_ns_sync(v);      /* #1057 whole-dict reader */
             if (v->data.dict.count == 0) return 0.0;
             double sum = 0.0;
             for (int i = 0; i < v->data.dict.count; i++)
@@ -1576,6 +1577,13 @@ void free_value(Value *v) {
                 free(v->data.list.items);
             break;
         case VAL_DICT:
+            if (v->module_ns) {
+                /* #1057: the non-cycle mirror of the module-namespace row of
+                 * GC_EDGE_TABLE — a namespace that dies by ordinary
+                 * refcounting drops its owning ref on the module env here. */
+                Env *me = eigs_module_ns_detach(v);
+                if (me) env_decref(me);
+            }
             for (int i = 0; i < v->data.dict.count; i++) {
                 /* keys are interned (env_intern_name) — do not free */
                 val_decref(v->data.dict.vals[i]);
@@ -1964,10 +1972,175 @@ Value* make_dict(int capacity) {
     env_hash_init(&v->data.dict.hash, ENV_HASH_INIT_CAP);
     v->refcount = 1;
     v->arena = 0;
+    v->module_ns = 0;      /* #1057: a plain dict is never a module namespace */
     return v;
 }
 
-void dict_set_hashed(Value *dict, const char *key, uint32_t h, Value *val) {
+/* ==== Module namespaces: a LIVE VIEW of the module env (#1057) ========
+ *
+ * `import M` used to bind a SHALLOW SNAPSHOT of M's top-level bindings, so
+ * whether an importer saw live state depended on the VALUE'S TYPE: a dict
+ * or list was shared by reference and tracked, a number or string was
+ * copied at import time and went silently stale, and `M.x is v` reached
+ * only the copy. The rule a user had to learn — "module state must be
+ * boxed in a container or it will go stale in your importer" — had no
+ * principle behind it and failed as a wrong number rather than an error.
+ *
+ * A namespace dict is now FLAGGED (Value::module_ns) and carries an OWNING
+ * backref to the module's Env. Field reads project the module's CURRENT
+ * binding into the dict slot and return it; field writes go through to the
+ * module binding. The dict's own storage is kept as a mirror so every
+ * whole-dict reader (keys / values / len / printing / json / iteration /
+ * equality) still works — those call eigs_module_ns_sync first.
+ *
+ * The Env* lives in this side table rather than in `struct Value` so the
+ * Value stays 72 bytes: the flag byte fits in the struct's existing tail
+ * padding, and only a flagged dict ever pays for the lookup.
+ *
+ * Ownership: attach takes env_incref; the edge is one GC_EDGE_TABLE row
+ * (dict -> env), cleared by gc_clear_node and by free_value. Module
+ * PRIVATE bindings (`_`-prefixed) are not part of the namespace and are
+ * never projected — the namespace's public surface is unchanged.
+ *
+ * Concurrency: written only by `import`, which — like the module cache
+ * this parallels — is a startup/main-thread operation and is not guarded.
+ */
+static inline void env_shared_lock(const Env *e);      /* #607, defined below */
+static inline void env_shared_unlock(const Env *e);
+
+typedef struct { Value *dict; Env *env; } ModuleNsEntry;
+static ModuleNsEntry *g_module_ns_tab = NULL;
+static size_t g_module_ns_cap = 0;     /* power of two; 0 = unallocated */
+static size_t g_module_ns_count = 0;
+
+static int module_ns_public(const char *name) {
+    return name && name[0] != '_';
+}
+
+/* Probe slot for `d`: the matching entry, or the first empty one. The load
+ * factor is held <= 70% and deletion rehashes, so an empty slot always
+ * exists and the probe terminates. */
+static size_t module_ns_slot(ModuleNsEntry *tab, size_t cap, Value *d) {
+    size_t i = ((uintptr_t)d >> 4) & (cap - 1);
+    while (tab[i].dict && tab[i].dict != d) i = (i + 1) & (cap - 1);
+    return i;
+}
+
+static void module_ns_rebuild(size_t ncap) {
+    ModuleNsEntry *nt = xcalloc(ncap, sizeof(ModuleNsEntry));
+    for (size_t i = 0; i < g_module_ns_cap; i++) {
+        if (!g_module_ns_tab[i].dict) continue;
+        size_t j = module_ns_slot(nt, ncap, g_module_ns_tab[i].dict);
+        nt[j] = g_module_ns_tab[i];
+    }
+    free(g_module_ns_tab);
+    g_module_ns_tab = nt;
+    g_module_ns_cap = ncap;
+}
+
+Env *eigs_module_ns_env(Value *dict) {
+    if (!dict || dict->type != VAL_DICT || !dict->module_ns) return NULL;
+    if (!g_module_ns_cap) return NULL;
+    size_t i = module_ns_slot(g_module_ns_tab, g_module_ns_cap, dict);
+    return g_module_ns_tab[i].dict ? g_module_ns_tab[i].env : NULL;
+}
+
+void eigs_module_ns_attach(Value *dict, Env *env) {
+    if (!dict || dict->type != VAL_DICT || !env) return;
+    if (dict->module_ns) return;                    /* already a namespace */
+    if ((g_module_ns_count + 1) * 10 > g_module_ns_cap * 7)
+        module_ns_rebuild(g_module_ns_cap ? g_module_ns_cap * 2 : 16);
+    size_t i = module_ns_slot(g_module_ns_tab, g_module_ns_cap, dict);
+    g_module_ns_tab[i].dict = dict;
+    g_module_ns_tab[i].env = env;
+    g_module_ns_count++;
+    env_incref(env);              /* OWNING edge — GC_EDGE_TABLE row below */
+    dict->module_ns = 1;
+}
+
+Env *eigs_module_ns_detach(Value *dict) {
+    if (!dict || !dict->module_ns) return NULL;
+    Env *e = NULL;
+    if (g_module_ns_cap) {
+        size_t i = module_ns_slot(g_module_ns_tab, g_module_ns_cap, dict);
+        if (g_module_ns_tab[i].dict == dict) {
+            e = g_module_ns_tab[i].env;
+            g_module_ns_tab[i].dict = NULL;
+            g_module_ns_tab[i].env  = NULL;
+            g_module_ns_count--;
+            /* Linear probing: removing an entry can orphan the rest of its
+             * cluster. Rehash at the same capacity rather than tombstone. */
+            module_ns_rebuild(g_module_ns_cap);
+        }
+    }
+    dict->module_ns = 0;
+    return e;                     /* caller owns the returned ref */
+}
+
+/* Project module binding `key` into the namespace's own slot and return it
+ * (borrowed, exactly like a plain dict_get). Falls back to the dict's own
+ * entry when the module has no such binding — a key written onto the
+ * namespace that the module does not define stays readable. */
+static Value *module_ns_project(Value *d, Env *e, const char *key, uint32_t h) {
+    /* #607: find + load under one hold, exactly as env_get_hashed_slot does —
+     * a concurrent module-env grow republishes names/values. No-op when the
+     * process is single-threaded. Nothing else here touches the env, so the
+     * hold is released before the (non-recursive) dict store below. */
+    env_shared_lock(e);
+    int ei = env_hash_find(&e->hash, key, h, e->names);
+    EigsSlot s = (ei >= 0) ? e->values[ei] : slot_null();
+    if (ei >= 0) slot_incref(s);       /* pin across the unlock */
+    env_shared_unlock(e);
+    int di = env_hash_find(&d->data.dict.hash, key, h, d->data.dict.keys);
+    if (ei < 0)
+        return (di >= 0) ? d->data.dict.vals[di] : NULL;
+    if (di >= 0) {
+        Value *cur = d->data.dict.vals[di];
+        if (slot_is_ptr(s)) {
+            /* Container/fn bindings were already shared by reference. */
+            if (slot_as_ptr(s) == cur) { slot_decref(s); return cur; }
+        } else if (slot_is_num(s) && cur && cur->type == VAL_NUM &&
+                   cur->refcount == 1 && !cur->arena) {
+            /* Exclusive untracked mirror — refresh in place, no allocation.
+             * Same exclusivity test as dict_set_cached_immediate: a mirror
+             * anyone else holds a ref to must not be mutated under them. */
+            cur->data.num = s.d;
+            slot_decref(s);
+            return cur;
+        }
+    }
+    Value *mv = slot_to_value(s);            /* owned */
+    slot_decref(s);                          /* drop the pin */
+    dict_set_hashed_raw(d, key, h, mv);
+    val_decref(mv);
+    di = env_hash_find(&d->data.dict.hash, key, h, d->data.dict.keys);
+    return (di >= 0) ? d->data.dict.vals[di] : NULL;
+}
+
+/* Refresh every projected entry. Whole-dict readers (keys / values / len /
+ * value_to_string / json / `for k in M` / equality) call this first; a
+ * single-field read does not need it (dict_get_hashed projects that one
+ * key). Also picks up module bindings created after the import. */
+void eigs_module_ns_sync(Value *dict) {
+    if (!dict || !dict->module_ns) return;
+    Env *e = eigs_module_ns_env(dict);
+    if (!e) return;
+    env_shared_lock(e);
+    int n = e->count;
+    env_shared_unlock(e);
+    for (int i = 0; i < n; i++) {
+        /* Names are interned and never freed while the env lives, so the
+         * pointer is stable once read; only the ARRAY can be republished
+         * under MT (#607), hence the hold across the load. */
+        env_shared_lock(e);
+        const char *nm = (i < e->count) ? e->names[i] : NULL;
+        env_shared_unlock(e);
+        if (!module_ns_public(nm)) continue;
+        module_ns_project(dict, e, nm, env_hash_name(nm));
+    }
+}
+
+void dict_set_hashed_raw(Value *dict, const char *key, uint32_t h, Value *val) {
     if (!dict || dict->type != VAL_DICT) return;
     if (h == 0) h = env_hash_name(key);
     int idx = env_hash_find(&dict->data.dict.hash, key, h, dict->data.dict.keys);
@@ -2011,6 +2184,30 @@ void dict_set_hashed(Value *dict, const char *key, uint32_t h, Value *val) {
         env_hash_insert(&dict->data.dict.hash, h, dict->data.dict.count - 1);
 }
 
+/* Routed store: a module namespace (#1057) writes THROUGH to the module's
+ * binding, then mirrors into its own slot so whole-dict readers stay
+ * consistent. Everything else is the raw store. */
+void dict_set_hashed(Value *dict, const char *key, uint32_t h, Value *val) {
+    if (!dict || dict->type != VAL_DICT) return;
+    if (h == 0) h = env_hash_name(key);
+    if (__builtin_expect(dict->module_ns != 0, 0)) {
+        Env *me = eigs_module_ns_env(dict);
+        if (me && module_ns_public(key))
+            /* env_set_local_hashed bumps the binding's assign_counts, so
+             * `when is x` inside the module counts a namespace write. It does
+             * NOT record assignment HISTORY: the tape's trace_assign calls
+             * live on the VM's SET_NAME/SET_LOCAL paths, keyed by the writing
+             * chunk's scan set, and there is no chunk here. So after
+             * `M.v is 50` the module's own `prev of v` still answers the
+             * value before its last INTERNAL write. Known, narrow (needs a
+             * temporal query and a scalar namespace write in the same
+             * program) and ledgered on #1057; a fix belongs with the tape,
+             * not here. */
+            env_set_local_hashed(me, key, h, val);
+    }
+    dict_set_hashed_raw(dict, key, h, val);
+}
+
 void dict_set(Value *dict, const char *key, Value *val) {
     dict_set_hashed(dict, key, env_hash_name(key), val);
 }
@@ -2080,6 +2277,10 @@ static Value *chan_clone_rec(Value *v, int depth) {
             return out;
         }
         case VAL_DICT: {
+            /* #1057: a namespace crossing a channel is snapshotted (the
+             * module env is not shared across the transfer) — refresh it
+             * first so the snapshot is the module's CURRENT state. */
+            eigs_module_ns_sync(v);
             int n = v->data.dict.count;
             Value *out = make_dict(n > 0 ? n : 8);
             for (int i = 0; i < n; i++) {
@@ -2122,6 +2323,11 @@ Value *val_clone_for_send(Value *v) {
 Value* dict_get_hashed(Value *dict, const char *key, uint32_t h) {
     if (!dict || dict->type != VAL_DICT) return NULL;
     if (h == 0) h = env_hash_name(key);
+    if (__builtin_expect(dict->module_ns != 0, 0)) {
+        Env *me = eigs_module_ns_env(dict);
+        if (me && module_ns_public(key))
+            return module_ns_project(dict, me, key, h);
+    }
     int idx = env_hash_find(&dict->data.dict.hash, key, h, dict->data.dict.keys);
     return (idx >= 0) ? dict->data.dict.vals[idx] : NULL;
 }
@@ -2220,7 +2426,7 @@ int is_truthy(Value *v) {
         case VAL_FN: return 1;
         case VAL_BUILTIN: return 1;
         case VAL_JSON_RAW: return v->data.str && v->data.str[0] != '\0';
-        case VAL_DICT: return v->data.dict.count > 0;
+        case VAL_DICT: eigs_module_ns_sync(v); return v->data.dict.count > 0;
         case VAL_BUFFER: return v->data.buffer.count > 0;
         case VAL_TEXT_BUILDER: return v->data.text_builder.len > 0;
     }
@@ -2253,6 +2459,8 @@ static int values_equal_impl(Value *a, Value *b, int depth) {
             return 1;
         }
         case VAL_DICT: {
+            eigs_module_ns_sync(a);      /* #1057 whole-dict reader */
+            eigs_module_ns_sync(b);
             if (a->data.dict.count != b->data.dict.count) return 0;
             for (int i = 0; i < a->data.dict.count; i++) {
                 Value *bv = dict_get(b, a->data.dict.keys[i]);
@@ -2348,6 +2556,7 @@ char* value_to_string(Value *v) {
         case VAL_FN: snprintf(buf, sizeof(buf), "<fn %s>", v->data.fn.name); return xstrdup(buf);
         case VAL_DICT: {
             strbuf out;
+            eigs_module_ns_sync(v);      /* #1057 whole-dict reader */
             strbuf_init(&out);
             strbuf_append_char(&out, '{');
             g_vts_depth++;
@@ -3562,7 +3771,17 @@ static int gc_env_is_node(Env *e) {
       gc_value_is_node(_v->data.dict.vals[_i]),                               \
       { Value *_o = _v->data.dict.vals[_i];                                   \
         _v->data.dict.vals[_i] = NULL;                                        \
-        val_decref(_o); }, __VA_ARGS__)
+        val_decref(_o); }, __VA_ARGS__)                                       \
+    /* #1057 module namespace: the owning backref to the module Env taken   \
+     * by eigs_module_ns_attach. Without this row a garbage                 \
+     * namespace <-> module-env cycle would look externally referenced and  \
+     * leak (and gc_clear_node would leave the edge dangling). free_value   \
+     * is the non-cycle mirror. */                                          \
+    X((_k == GC_KIND_VAL && _v->type == VAL_DICT && _v->module_ns), 1,        \
+      eigs_module_ns_env(_v), GC_KIND_ENV,                                    \
+      gc_env_is_node(eigs_module_ns_env(_v)),                                 \
+      { Env *_o = eigs_module_ns_detach(_v);                                  \
+        if (_o) env_decref(_o); }, __VA_ARGS__)
 
 #define GC_EDGE_WALK(GUARD, COUNT, CHILD, CHILD_KIND, IS_NODE, CLEAR,         \
                      OUT_OBJ, OUT_KIND, BODY)                                 \
diff --git a/src/eigenscript.h b/src/eigenscript.h
index 52f9d91e..e3a4e87e 100644
--- a/src/eigenscript.h
+++ b/src/eigenscript.h
@@ -365,6 +365,14 @@ struct Value {
      * struct's tail padding (no size change) and is zero-initialized by every
      * Value allocator (xcalloc / arena_alloc memset / freelist reuse memset). */
     unsigned char gc_buffered;
+    /* #1057: 1 iff this VAL_DICT is a module NAMESPACE — the value `import M`
+     * binds. Such a dict is a LIVE VIEW of the module's Env: field reads
+     * refresh from the module binding, field writes go through to it. The
+     * Env* backref lives in a side table (eigs_module_ns_env) so struct Value
+     * does not grow; this byte sits in the struct's existing tail padding and
+     * is what makes the common (non-namespace) dict path a single byte test —
+     * including in the JIT's inline dict-cache probe, which bails on it. */
+    unsigned char module_ns;
 };
 
 /* Window length for the per-Value dH ring buffer. Predicates require
@@ -1609,6 +1617,21 @@ Env *env_resolve_chain(Env *start, const char *name, uint32_t h,
                        int *out_slot, int *out_depth);
 void dict_set_hashed(Value *dict, const char *key, uint32_t h, Value *val);
 Value* dict_get_hashed(Value *dict, const char *key, uint32_t h);
+/* #1057 module namespaces. `import M` binds a dict that is a LIVE VIEW of the
+ * module's top-level Env: `M.x` reads the module's CURRENT binding and
+ * `M.x is v` writes it. attach flags the dict and takes an OWNING ref on the
+ * env (one GC_EDGE_TABLE row); detach hands that ref back to the caller and
+ * clears the flag; sync refreshes every entry (for whole-dict readers —
+ * `keys`, `values`, `len`, printing, json, iteration, equality). Private
+ * (`_`-prefixed) module bindings are not part of the namespace and are never
+ * projected. Not guarded for concurrent import, same as the module cache. */
+void eigs_module_ns_attach(Value *dict, Env *env);
+Env *eigs_module_ns_env(Value *dict);
+Env *eigs_module_ns_detach(Value *dict);
+void eigs_module_ns_sync(Value *dict);
+/* Raw (non-routed) dict store — writes the dict's own slot without going
+ * through a module namespace's env. The namespace projection uses it. */
+void dict_set_hashed_raw(Value *dict, const char *key, uint32_t h, Value *val);
 /* Env lifetime is a real refcount: env_new returns with refcount 1 (the
  * creator's ref — adopted by the call frame or the C caller) and an owned
  * ref on its parent. env_decref destroys at 0: drops every binding, drops
diff --git a/src/jit.c b/src/jit.c
index 9479cfb4..a31f7523 100644
--- a/src/jit.c
+++ b/src/jit.c
@@ -2019,7 +2019,7 @@ static uint8_t *emit_mov_disp32_r12_to_rdi(uint8_t *w, int32_t disp) {
  *
  * On success: %rdi = dict Value*, %rdx = entry index, %rax =
  * vals[index]. `h` and `key` are compile-time constants. Guard-failure
- * jumps append to slow_p[] (7 entries). The dict cache is TLS in vm.c;
+ * jumps append to slow_p[] (8 entries). The dict cache is TLS in vm.c;
  * Phase 5: %rbx now holds &EigsThread.vm (heap), so the probe loads
  * tls_base into %rsi via `mov %fs:0, %rsi` and addresses
  * g_dict_cache_tpoff off that. */
@@ -2036,6 +2036,9 @@ static uint8_t *emit_dict_cache_probe(uint8_t *w, uint16_t slot,
     w = emit_cmpl_imm32_disp32_rdi(w, (int32_t)offsetof(Value, type),
                                    (uint32_t)VAL_DICT);
     w = emit_jne_rel32(w, &slow_p[*slow_n]); (*slow_n)++;
+    /* #1057: bail on a module namespace — see the header comment. */
+    w = emit_testb_1_disp32_rdi(w, (int32_t)offsetof(Value, module_ns));
+    w = emit_jne_rel32(w, &slow_p[*slow_n]); (*slow_n)++;
     w = emit_mov_edi_eax(w);
     w = emit_xor_imm32_eax(w, h);
     w = emit_and_imm32_eax(w, (uint32_t)g_layout.dcache_mask);
diff --git a/src/vm.c b/src/vm.c
index 354762fc..727297f0 100644
--- a/src/vm.c
+++ b/src/vm.c
@@ -619,6 +619,12 @@ static inline void dict_cache_insert(Value *dict, uint32_t h, int idx) {
 }
 
 static inline Value *dict_get_cached(Value *dict, const char *key, uint32_t h) {
+    /* #1057: a module namespace is a LIVE VIEW of the module env, so its
+     * own slots are only a mirror — the inline cache must not answer from
+     * them. Route to dict_get_hashed, which projects the current binding.
+     * The JIT's inline probe carries the same guard (emit_dict_cache_probe). */
+    if (__builtin_expect(dict->module_ns != 0, 0))
+        return dict_get_hashed(dict, key, h);
     DictCacheEntry *ce = dict_cache_probe(dict, h);
     if (ce && ce->index < dict->data.dict.count) {
         const char *stored = dict->data.dict.keys[ce->index];
@@ -634,6 +640,10 @@ static inline Value *dict_get_cached(Value *dict, const char *key, uint32_t h) {
 }
 
 static inline void dict_set_cached(Value *dict, const char *key, uint32_t h, Value *val) {
+    if (__builtin_expect(dict->module_ns != 0, 0)) {   /* #1057: write through */
+        dict_set_hashed(dict, key, h, val);
+        return;
+    }
     DictCacheEntry *ce = dict_cache_probe(dict, h);
     if (ce && ce->index < dict->data.dict.count) {
         const char *stored = dict->data.dict.keys[ce->index];
@@ -661,6 +671,8 @@ static inline void dict_set_cached(Value *dict, const char *key, uint32_t h, Val
  * 1 if the in-place fast path fired; 0 means the caller must materialize
  * and call dict_set_cached. */
 static inline int dict_set_cached_immediate(Value *dict, const char *key, uint32_t h, double num) {
+    if (__builtin_expect(dict->module_ns != 0, 0))
+        return 0;                     /* #1057: never in-place on a mirror */
     DictCacheEntry *ce = dict_cache_probe(dict, h);
     if (ce && ce->index < dict->data.dict.count) {
         const char *stored = dict->data.dict.keys[ce->index];
@@ -6098,6 +6110,10 @@ static Value *vm_run_ex(EigsChunk *chunk, Env *env, Task *resume,
          * (a fn-free module would otherwise be reclaimed immediately,
          * which is fine, but caching the env keeps observer-trace
          * identity stable across re-imports). */
+        /* #1057: the dict is a LIVE VIEW of mod_env, not a snapshot —
+         * `M.x` reads the module's current binding and `M.x is v` writes
+         * it. attach takes an owning ref on mod_env. */
+        eigs_module_ns_attach(mod_dict, mod_env);
         eigs_module_cache_put(abs_path, mod_dict, mod_env);
         env_decref(mod_env);
         vm_push(mod_dict);
diff --git a/tests/modlive_box.eigs b/tests/modlive_box.eigs
new file mode 100644
index 00000000..a377205e
--- /dev/null
+++ b/tests/modlive_box.eigs
@@ -0,0 +1,10 @@
+# #1057 fixture: the dict-of-state idiom the language grew around the bug.
+# It worked before and must keep working byte-for-byte (containers are
+# still shared by reference).
+state is {"n": 0}
+
+define bump() as:
+    state.n is (state.n) + 1
+
+define peek() as:
+    return state.n
diff --git a/tests/modlive_counter.eigs b/tests/modlive_counter.eigs
new file mode 100644
index 00000000..b61a5bf3
--- /dev/null
+++ b/tests/modlive_counter.eigs
@@ -0,0 +1,17 @@
+# #1057 fixture: a module whose mutable state is a BARE SCALAR binding.
+# Before the live view, importers saw the value snapshotted at import time.
+ctr is 0
+label is "start"
+_hidden is 99
+
+define bump() as:
+    ctr is ctr + 1
+
+define peek() as:
+    return ctr
+
+define relabel(s) as:
+    label is s
+
+define peek_label() as:
+    return label
diff --git a/tests/modlive_outer.eigs b/tests/modlive_outer.eigs
new file mode 100644
index 00000000..8867ae36
--- /dev/null
+++ b/tests/modlive_outer.eigs
@@ -0,0 +1,11 @@
+# #1057 fixture: nested import — this module imports another and both
+# namespaces must stay live through the outer one.
+import modlive_counter
+
+depth is 2
+
+define bump_inner() as:
+    modlive_counter.bump of null
+
+define inner_ctr() as:
+    return modlive_counter.ctr
diff --git a/tests/modlive_plain.eigs b/tests/modlive_plain.eigs
new file mode 100644
index 00000000..f4df11b6
--- /dev/null
+++ b/tests/modlive_plain.eigs
@@ -0,0 +1,5 @@
+# #1057 fixture: a write THROUGH the namespace must reach the module.
+v is 1
+
+define peek() as:
+    return v
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 6a1eb817..2e510295 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -2377,6 +2377,7 @@ echo "[43a2] Builtin Argument Errors (26 checks)"
 check_eigs_suite "builtin argument errors" test_builtin_errors.eigs "All builtin_errors tests passed" 30
 check_eigs_suite "module-boundary write insulation (#373)" test_module_scope.eigs "All module-scope tests passed" 9
 check_eigs_suite "import top-level scope insulation vs load_file current-scope contract (#589)" test_import_toplevel_scope.eigs "All import top-level scope tests passed" 11
+check_eigs_suite "module namespace is a LIVE VIEW of the module env (#1057)" test_module_live_view.eigs "All tests passed" 30
 
 echo "[43a2b] build_corpus slot-mode identifier encoding (6 checks)"
 CS_OUTPUT=$(bash "$TESTS_DIR/test_corpus_slots.sh" 2>&1)
diff --git a/tests/test_module_live_view.eigs b/tests/test_module_live_view.eigs
new file mode 100644
index 00000000..af4bbdfa
--- /dev/null
+++ b/tests/test_module_live_view.eigs
@@ -0,0 +1,99 @@
+# #1057 — a module's namespace is a LIVE VIEW of the module's bindings,
+# not a shallow snapshot.
+#
+# Before: `import M` copied M's top-level bindings into a detached dict, so
+# whether an importer saw live state depended on the VALUE'S TYPE — a dict
+# or list was shared by reference and tracked, a number or string was
+# frozen at import time and went silently stale, and `M.x is v` reached
+# only the copy. The failure mode was a wrong number, never an error.
+#
+# After: `M.x` reads M's CURRENT binding and `M.x is v` writes it.
+# Containers keep sharing by reference (unchanged), so the dict-of-state
+# idiom nine stdlib modules use is now a style choice, not a correctness
+# requirement.
+
+load_file of "lib/test.eigs"
+
+# ---- Probe 1 (issue's _q4): scalar module state tracks ------------------
+import modlive_counter
+modlive_counter.bump of null
+modlive_counter.bump of null
+assert_eq of [modlive_counter.peek of null, 2, "module internal view sees 2"]
+assert_eq of [modlive_counter.ctr, 2, "namespace tracks the module binding"]
+
+# Strings go live too — the bug was type-dependent, the fix must not be.
+modlive_counter.relabel of "moved"
+assert_eq of [modlive_counter.label, "moved", "string binding is live too"]
+
+# ---- Probe 2 (issue's _q5): container state unchanged -------------------
+import modlive_box
+modlive_box.bump of null
+assert_eq of [modlive_box.peek of null, 1, "container state internal view"]
+assert_eq of [modlive_box.state.n, 1, "container state via namespace (unchanged)"]
+
+# ---- Probe 3 (issue's _q3): a write through the namespace lands ---------
+import modlive_plain
+modlive_plain.v is 42
+assert_eq of [modlive_plain.v, 42, "namespace read after write"]
+assert_eq of [modlive_plain.peek of null, 42, "the MODULE saw the write"]
+
+# ---- Control: reading a scalar out of the namespace still COPIES -------
+# `a is M.ctr` binds the value, not a live alias — a later bump must not
+# move `a`. (A live view must not turn every read into an alias.)
+snap is modlive_counter.ctr
+modlive_counter.bump of null
+assert_eq of [snap, 2, "a value read out of the namespace is a value"]
+assert_eq of [modlive_counter.ctr, 3, "namespace still live after the read"]
+
+# ---- Control: functions are callable through the namespace -------------
+assert_eq of [type of modlive_counter, "dict", "namespace is still a dict"]
+assert_eq of [modlive_counter.peek of null, 3, "M.f of x through namespace"]
+fn is modlive_counter.peek
+assert_eq of [fn of null, 3, "function value extracted from the namespace"]
+
+# ---- Control: enumeration still lists the bindings ---------------------
+k is keys of modlive_counter
+assert_true of [(len of k) >= 5, "keys lists the module's public bindings"]
+assert_eq of [has_key of [modlive_counter, "ctr"], 1, "has_key sees ctr"]
+assert_eq of [has_key of [modlive_counter, "peek"], 1, "has_key sees peek"]
+assert_eq of [len of modlive_counter, len of k, "len agrees with keys"]
+
+# ---- Control: `_`-private module bindings stay private ------------------
+assert_eq of [has_key of [modlive_counter, "_hidden"], 0, "_name stays private"]
+assert_eq of [modlive_counter._hidden, null, "_name unreadable through namespace"]
+
+# ---- Control: whole-dict readers see the CURRENT value -----------------
+# str/json of a namespace must not print the import-time snapshot.
+assert_true of [contains of [str of modlive_plain, "42"], "str of namespace is current"]
+assert_true of [contains of [json_encode of modlive_plain, "42"],
+                "json_encode of namespace is current"]
+
+# ---- Control: the module cache returns the same LIVE namespace ---------
+import modlive_counter
+assert_eq of [modlive_counter.ctr, 3, "re-import yields the same live state"]
+
+# ---- Control: a new key written through the namespace binds in the module
+modlive_plain.fresh is 7
+assert_eq of [modlive_plain.fresh, 7, "new namespace key reads back"]
+assert_eq of [has_key of [modlive_plain, "fresh"], 1, "new key enumerates"]
+
+# ---- Control: nested imports stay live ---------------------------------
+import modlive_outer
+assert_eq of [modlive_outer.depth, 2, "nested-import module binding"]
+modlive_outer.bump_inner of null
+assert_eq of [modlive_outer.inner_ctr of null, 4, "inner module bumped"]
+assert_eq of [modlive_counter.ctr, 4, "outer namespace's inner state is live"]
+assert_eq of [modlive_outer.modlive_counter.ctr, 4,
+              "namespace reached through a nested namespace is live"]
+
+# ---- Control: the load_file road is unchanged --------------------------
+# load_file binds into the CALLER's current scope and returns no namespace.
+lf is load_file of "../tests/modlive_plain.eigs"
+assert_eq of [v, 1, "load_file binds into the caller's scope (unchanged)"]
+assert_eq of [peek of null, 1, "load_file'd function reads the caller's v"]
+
+# ---- Control: the eval road is unchanged -------------------------------
+ev is eval of "3 + 4"
+assert_eq of [ev, 7, "eval road unchanged"]
+
+test_summary of null

From 986336472dd8aba7d4338fdca96b827845c9b033 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 23:10:35 +0000
Subject: [PATCH 23/39] lint: every diagnostic is UTF-8 safe at the chokepoint,
 not per message (#1048)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The integration cherry-picked this issue's round-2 commit. Round 3 replaced
the per-message repair with a chokepoint one after a blind critic measured the
real blast radius: on v0.43.0, 512 of 1524 shape x length combinations came
back malformed. Any non-ASCII byte in a source file, or in a filename, was
enough to make `--lint --json` and the language server's JSON-RPC frames
undecodable — not just the new W024 message that the issue was filed about.

The truncation happens where a diagnostic is copied into a fixed buffer, so
that is where it is fixed:

- `eigs_utf8_step` / `eigs_utf8_sanitize` (src/strbuf.c) — a scanner that
  knows where a sequence starts and a sanitiser that will not leave a partial
  one behind. Everything that truncates a message now goes through them.
- The lexer spells an unexpected byte as `\xNN` rather than emitting the raw
  byte, so an invalid byte in the SOURCE cannot become an invalid byte in the
  OUTPUT.
- The parser's caret line counts columns in characters, and renders `?` where
  it cannot place a caret inside a multi-byte character.
- `lint_json_escape` is the last gate on the JSON channel.

Gated by `tools/lint_source_byte_sweep.py`, which is in run_all_tests.sh:
138 source-byte cases x 4 shapes plus 3 path shapes across both channels
(1125 runs), each decoded with a STRICT decoder. `jq` is not usable as the
oracle here — it substitutes U+FFFD for malformed input and reports success,
which is how this survived to a release.

Six planted faults confirm the sweep is gating: reverting each chokepoint
individually turns it red, and for the reason named.

  tests/test_lint.sh                 246 passed, 0 failed
  tools/lint_message_utf8_check.sh   39 checks, 30 codes, 8 pinned exemptions
                                     sweep 2000 runs + bytes 1125 runs, all decode

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 docs/DIAGNOSTICS.md              |  42 +++++--
 src/eigenscript.h                |  12 ++
 src/lexer.c                      |  17 ++-
 src/lint.c                       |  28 ++---
 src/lint_host.c                  |  68 ++++++++----
 src/parser.c                     |  24 +++-
 src/strbuf.c                     |  72 ++++++++++++
 tests/run_all_tests.sh           |  22 ++--
 tests/test_lint.sh               |  58 +++++++++-
 tools/lint_message_utf8_check.sh | 132 +++++++++++++++++-----
 tools/lint_source_byte_sweep.py  | 185 +++++++++++++++++++++++++++++++
 11 files changed, 567 insertions(+), 93 deletions(-)
 create mode 100644 tools/lint_source_byte_sweep.py

diff --git a/docs/DIAGNOSTICS.md b/docs/DIAGNOSTICS.md
index 8027699e..3dc937c1 100644
--- a/docs/DIAGNOSTICS.md
+++ b/docs/DIAGNOSTICS.md
@@ -306,18 +306,38 @@ so `--lint --json 2>/dev/null` is pure JSON). Each element is:
 - Exit code follows `--lint-level` (see below); the default fails on any
   surviving warning.
 
-- **Every `message` is valid UTF-8, whatever it interpolates.** Messages are
-  assembled in a fixed 256-byte buffer, so a rule that interpolates a long
-  identifier can have its message clipped — but the clip always lands on a
-  character boundary and is marked with a trailing `...`, never inside a
-  multi-byte sequence. This is a consumer-visible contract: a byte-level cut
-  produced a payload strict decoders reject while `jq` silently substituted
-  U+FFFD (#1048), and `eigenlsp` publishes the same strings over JSON-RPC.
-  Rules that interpolate unbounded text are expected to budget it themselves
-  so the actionable half of the message survives — `W024` shrinks the
-  identifiers it quotes (middle ellipsis) rather than let the remedy be cut.
+- **Every string in the payload is valid UTF-8 — the `message`, the `file`
+  path — whatever a rule interpolates and whatever the linted file contains.**
+  Two things could break that, and both are handled at a chokepoint rather than
+  per rule (#1048):
+  - **Length.** Messages are assembled in a fixed 256-byte buffer, so a rule
+    that interpolates a long identifier can have its message clipped — but the
+    clip lands on a character boundary and is marked with a trailing `...`,
+    never inside a multi-byte sequence. Rules that interpolate unbounded text
+    are expected to budget it themselves so the actionable half survives:
+    `W024` shrinks the identifiers it quotes (middle ellipsis) rather than let
+    its remedy be cut.
+  - **Source bytes.** A message can quote text the linter did not choose — the
+    byte the lexer could not tokenize (`E002`), a duplicate dict key (`W010`),
+    a path. A file is a byte string and need not be valid UTF-8, so those
+    quotes are sanitized: a byte that is not part of a well-formed character is
+    replaced with `U+FFFD` (`duplicate dict key 'k�y'`), an incomplete
+    sequence at the end is dropped, and a byte the lexer cannot tokenize is
+    spelled rather than echoed — `unexpected character '\xc3'`, not half of an
+    `é`. Well-formed characters, multi-byte ones included, pass through
+    **byte-for-byte**.
+
+  This is a consumer-visible contract: a byte-level cut produced a payload
+  strict decoders reject while `jq` silently substituted U+FFFD, and
+  `eigenlsp` publishes the same strings over JSON-RPC.
   `tools/lint_message_utf8_check.sh` drives every code above with a
-  200-character identifier and decodes the result strictly.
+  200-character identifier, sweeps identifier length 1..250 and every source
+  byte `>= 0x80` through four source shapes, and decodes both channels
+  strictly with `python3` (never `jq`, which is lenient exactly here).
+  The same sanitizing applies to the human `--lint` line and to the
+  parse-error source excerpt, where a byte that cannot be decoded prints as
+  `?` so the caret below it still lines up. It covers the lint channels; other
+  LSP responses that echo document text (hover, formatting) are outside it.
 
 The `--json` flag may appear before or after the path. Runtime errors are
 not part of `--lint` — it compiles the program but never runs it.
diff --git a/src/eigenscript.h b/src/eigenscript.h
index e3a4e87e..5a5b0b92 100644
--- a/src/eigenscript.h
+++ b/src/eigenscript.h
@@ -1815,6 +1815,18 @@ void eigs_record_first_error_code_at(int line, int col, int len,
  * shared format for parse-time and runtime diagnostics. No-op when src is
  * NULL or the position is out of range. */
 void eigs_print_caret_src(FILE *out, const char *src, int line, int col);
+/* #1048: decode one UTF-8 character — length 1..4 if well-formed, 0 if the
+ * bytes cannot start one (stray continuation, overlong, surrogate, > U+10FFFF,
+ * bad continuation), -1 if the input ends inside a well-formed prefix. Every
+ * diagnostic that renders bytes from the source funnels through it, so no
+ * channel (stderr, `--lint --json`, the LSP's JSON-RPC) can emit half a
+ * character. Defined in strbuf.c. */
+int eigs_utf8_step(const unsigned char *s, size_t avail);
+/* #1048: copy `src` into `dst` (`cap` bytes) as valid UTF-8 — whole characters
+ * only, a byte that is not part of a well-formed one replaced with U+FFFD, an
+ * incomplete tail dropped, and a copy that does not fit truncated on a
+ * character boundary and marked "...". Defined in strbuf.c. */
+void eigs_utf8_sanitize(char *dst, size_t cap, const char *src);
 /* #407: register the compilation unit's raw source so column-carrying parse
  * errors print a one-line excerpt + caret. NULL = no excerpt (unchanged
  * output). Set before parse, clear after — the parser never reads it outside
diff --git a/src/lexer.c b/src/lexer.c
index 6e28faab..0bb1c207 100644
--- a/src/lexer.c
+++ b/src/lexer.c
@@ -648,11 +648,24 @@ static TokenList tokenize_at_line(const char *source, int initial_line, int init
             case '~': tok_add(&tl, TOK_TILDE, 0, NULL, line, tok_col); p++; col++; break;
             default:
                 {
+                    /* Spell the offending byte, never echo it (#1048). A byte
+                     * >= 0x80 is one piece of a multi-byte character, so
+                     * quoting it raw put half a UTF-8 sequence into the error
+                     * message — which `--lint --json` and the LSP then publish
+                     * as a payload strict decoders reject. `\xNN` says which
+                     * byte it was and is ASCII on every channel. */
+                    unsigned char bad = (unsigned char)*p;
+                    char shown[8];
+                    if (bad >= 0x20 && bad < 0x7F) {
+                        shown[0] = (char)bad; shown[1] = '\0';
+                    } else {
+                        snprintf(shown, sizeof(shown), "\\x%02x", bad);
+                    }
                     char m[64];
-                    snprintf(m, sizeof(m), "unexpected character '%c'", *p);
+                    snprintf(m, sizeof(m), "unexpected character '%s'", shown);
                     eigs_record_first_error_at(line, tok_col, 1, m);
+                    fprintf(stderr, "Syntax error line %d: unexpected character '%s'\n", line, shown);
                 }
-                fprintf(stderr, "Syntax error line %d: unexpected character '%c'\n", line, *p);
                 g_parse_errors++;
                 p++; col++;
                 break;
diff --git a/src/lint.c b/src/lint.c
index 273eef3a..4088894c 100644
--- a/src/lint.c
+++ b/src/lint.c
@@ -29,24 +29,6 @@ size_t lint_utf8_prefix(const char *s, size_t max) {
     return (i - 1 + need == n) ? n : i - 1;    /* complete: keep. cut: drop it */
 }
 
-/* Copy `src` into `dst` (`cap` bytes), truncating on a UTF-8 boundary and
- * marking the cut with "..." so a clipped message says so. Every diagnostic
- * in the tree funnels through lint_vdiag, so this is the whole-class
- * guarantee: no lint rule, present or future, can emit malformed UTF-8 no
- * matter what it interpolates. Individual rules must still keep their
- * ACTIONABLE half inside the budget — a truncation here is valid output but
- * a worse message (see w024_emit's shrink-to-fit). */
-static void lint_copy_utf8(char *dst, size_t cap, const char *src) {
-    if (!dst || cap == 0) return;
-    if (!src) { dst[0] = '\0'; return; }
-    size_t keep = lint_utf8_prefix(src, cap - 1);
-    if (keep == strlen(src)) { memcpy(dst, src, keep); dst[keep] = '\0'; return; }
-    if (cap < 5) { dst[0] = '\0'; return; }
-    keep = lint_utf8_prefix(src, cap - 4);
-    memcpy(dst, src, keep);
-    memcpy(dst + keep, "...", 4);
-}
-
 static void lint_vdiag(LintContext *ctx, int line, int col, int len,
                        const char *level,
                        const char *code, const char *fmt, va_list ap) {
@@ -59,10 +41,10 @@ static void lint_vdiag(LintContext *ctx, int line, int col, int len,
     snprintf(w->code, sizeof(w->code), "%s", code);
     /* Render first, then copy on a character boundary: vsnprintf straight
      * into w->message would cut mid-sequence (#1048). The scratch can itself
-     * clip a pathological message; lint_copy_utf8 repairs either cut. */
+     * clip a pathological message; eigs_utf8_sanitize repairs either cut. */
     char rendered[1024];
     vsnprintf(rendered, sizeof(rendered), fmt, ap);
-    lint_copy_utf8(w->message, sizeof(w->message), rendered);
+    eigs_utf8_sanitize(w->message, sizeof(w->message), rendered);
 }
 
 static void lint_warn(LintContext *ctx, int line, const char *code,
@@ -3629,7 +3611,11 @@ int lint_collect(ASTNode *ast, const char *path, const char *source,
         out[i].len  = ctx.warnings[i].len;
         snprintf(out[i].code, sizeof(out[i].code), "%s", ctx.warnings[i].code);
         snprintf(out[i].severity, sizeof(out[i].severity), "%s", ctx.warnings[i].level);
-        snprintf(out[i].message, sizeof(out[i].message), "%s", ctx.warnings[i].message);
+        /* The message crosses into a SECOND fixed buffer here (LintDiag is
+         * what eigenlsp publishes). Copy it the same way lint_vdiag filled
+         * the first: snprintf would cut mid-character the day the two
+         * buffers stop being the same size (#1048). */
+        eigs_utf8_sanitize(out[i].message, sizeof(out[i].message), ctx.warnings[i].message);
     }
     builtin_name_env_free();
     return n;
diff --git a/src/lint_host.c b/src/lint_host.c
index 2a0597c2..c4377bfa 100644
--- a/src/lint_host.c
+++ b/src/lint_host.c
@@ -20,27 +20,45 @@
 
 /* Escape a string for embedding in a JSON string literal (into a caller
  * buffer). This helper is host-only now that every JSON-producing lint path
- * lives in this TU; keeping it static prevents a generic host symbol leak. */
-/* JSON string escaping. The output buffer is the SECOND place a diagnostic
- * can be cut (the first is lint_vdiag's message buffer), so it clips whole
- * UTF-8 characters only: emitting half a sequence produces a payload a
- * strict decoder rejects, and `jq` hides that by substituting U+FFFD
- * (#1048). Bytes >= 0x80 are passed through raw — the input is UTF-8 and
- * JSON accepts it as-is. */
+ * lives in this TU; keeping it static prevents a generic host symbol leak.
+ *
+ * The output buffer is the SECOND place a diagnostic can be cut (the first is
+ * lint_vdiag's message buffer) and the ONLY place strings the linter never
+ * assembled itself — a file path, the parser's first-error message — reach a
+ * consumer. So it does what lint_copy_utf8 does: copy whole UTF-8 characters,
+ * replace any byte that is not part of a well-formed one with U+FFFD, and drop
+ * an incomplete sequence at the end rather than emit half of it. Emitting half
+ * produces a payload strict decoders reject, and `jq` hides that by
+ * substituting U+FFFD itself (#1048). Well-formed bytes >= 0x80 pass through
+ * raw — JSON accepts UTF-8 as-is. */
 static void lint_json_escape(const char *s, char *out, size_t outsz) {
-    size_t o = 0;
-    for (size_t i = 0; s[i] && o + 2 < outsz; i++) {
+    size_t o = 0, i = 0, n = s ? strlen(s) : 0;
+    if (outsz == 0) return;
+    while (i < n) {
         unsigned char c = (unsigned char)s[i];
-        if (c == '"' || c == '\\') { out[o++] = '\\'; out[o++] = (char)c; }
-        else if (c == '\n') { out[o++] = '\\'; out[o++] = 'n'; }
-        else if (c == '\t') { out[o++] = '\\'; out[o++] = 't'; }
-        else if (c >= 0x20) { out[o++] = (char)c; }
-        /* other control chars are dropped */
+        if (c < 0x80) {
+            const char *esc = NULL;
+            if (c == '"')       esc = "\\\"";
+            else if (c == '\\') esc = "\\\\";
+            else if (c == '\n') esc = "\\n";
+            else if (c == '\t') esc = "\\t";
+            else if (c < 0x20)  { i++; continue; }   /* other controls dropped */
+            size_t w = esc ? 2 : 1;
+            if (o + w + 1 > outsz) break;
+            if (esc) { out[o++] = esc[0]; out[o++] = esc[1]; }
+            else     { out[o++] = (char)c; }
+            i++;
+            continue;
+        }
+        int step = eigs_utf8_step((const unsigned char *)s + i, n - i);
+        if (step < 0) break;                          /* cut tail: drop it */
+        size_t w = step > 0 ? (size_t)step : 3;
+        if (o + w + 1 > outsz) break;
+        if (step > 0) { memcpy(out + o, s + i, w); i += w; }
+        else          { memcpy(out + o, "\xEF\xBF\xBD", 3); i += 1; }
+        o += w;
     }
     out[o] = '\0';
-    /* The loop can stop inside a multi-byte character (the capacity test is
-     * per byte); drop the partial tail rather than emit it. */
-    out[lint_utf8_prefix(out, o)] = '\0';
 }
 
 /* Known builtin names — the registry itself, never a hand list (#459: the
@@ -1264,6 +1282,12 @@ static int eigs_json_allows(Value *codes, const char *code) {
 
 int eigenscript_lint(const char *path, int json_mode, int fail_on_warning) {
     long src_size = 0;
+    /* The human channel prints the path raw, and a path is a byte string from
+     * the command line — on the JSON side lint_json_escape sanitizes it, so
+     * without this the two channels disagreed about a file whose name is not
+     * valid UTF-8 and only the human one was undecodable (#1048). */
+    char dpath[1024];
+    eigs_utf8_sanitize(dpath, sizeof(dpath), path);
     char *source = read_file_util(path, &src_size);
     if (!source) {
         if (json_mode) {
@@ -1273,7 +1297,7 @@ int eigenscript_lint(const char *path, int json_mode, int fail_on_warning) {
             printf("[{\"code\":\"E000\",\"severity\":\"error\",\"line\":0,"
                    "\"file\":\"%s\",\"message\":\"%s '%s'\"}]\n", pesc, esc, pesc);
         } else {
-            fprintf(stderr, "Error: cannot read file '%s'\n", path);
+            fprintf(stderr, "Error: cannot read file '%s'\n", dpath);
         }
         return 1;
     }
@@ -1299,7 +1323,7 @@ int eigenscript_lint(const char *path, int json_mode, int fail_on_warning) {
                    g_first_error_line, g_first_error_col + 1, pesc, esc);
         } else {
             fprintf(stderr, "%s: %d parse error(s) [%s] — cannot lint\n",
-                    path, g_parse_errors,
+                    dpath, g_parse_errors,
                     g_first_error_code ? g_first_error_code : "E002");
         }
         free_ast(ast);
@@ -1391,7 +1415,7 @@ int eigenscript_lint(const char *path, int json_mode, int fail_on_warning) {
         printf("]\n");
     } else {
         for (int i = 0; i < ctx.warning_count; i++) {
-            fprintf(stderr, "%s:%d: %s[%s]: %s\n", path,
+            fprintf(stderr, "%s:%d: %s[%s]: %s\n", dpath,
                     ctx.warnings[i].line, ctx.warnings[i].level,
                     ctx.warnings[i].code, ctx.warnings[i].message);
         }
@@ -1399,9 +1423,9 @@ int eigenscript_lint(const char *path, int json_mode, int fail_on_warning) {
             /* The compiler printed each diagnostic itself; this is the
              * summary line, shaped like the parse-error one above. */
             fprintf(stderr, "%s: %d compile error(s) [E004]\n",
-                    path, compile_errors);
+                    dpath, compile_errors);
         } else if (ctx.warning_count == 0) {
-            fprintf(stderr, "%s: no issues found\n", path);
+            fprintf(stderr, "%s: no issues found\n", dpath);
         }
     }
 
diff --git a/src/parser.c b/src/parser.c
index 91be54df..4bbd654c 100644
--- a/src/parser.c
+++ b/src/parser.c
@@ -69,7 +69,29 @@ void eigs_print_caret_src(FILE *out, const char *src, int line, int col) {
     size_t len = e ? (size_t)(e - s) : strlen(s);
     if (len > 200) len = 200;              /* pathological lines stay sane */
     if ((size_t)col > len) return;
-    fprintf(out, "  %4d | %.*s\n", line, (int)len, s);
+    /* #1048: the excerpt is raw SOURCE, so a file that is not valid UTF-8
+     * would put a malformed byte on stderr (and, for `--lint`, into output a
+     * consumer decodes). Show each such byte as `?` — one byte in, one byte
+     * out, so the caret below still lines up with the column the parser
+     * reported. Well-formed characters, multi-byte ones included, pass
+     * through untouched, so every excerpt of a valid source is unchanged. */
+    char shown[201];
+    {
+        size_t o = 0, i = 0;
+        while (i < len) {
+            int step = eigs_utf8_step((const unsigned char *)s + i, len - i);
+            if (step > 0) {
+                memcpy(shown + o, s + i, (size_t)step);
+                o += (size_t)step; i += (size_t)step;
+            } else {
+                shown[o++] = '?';   /* invalid byte, or a sequence the line cuts */
+                i++;
+            }
+        }
+        shown[o] = '\0';
+        len = o;
+    }
+    fprintf(out, "  %4d | %.*s\n", line, (int)len, shown);
     /* pad buffer, not fputc: the freestanding mini-libc has fprintf but no
      * fputc (the symbol gate rejects it). col <= len <= 200 by the guards. */
     char pad[201];
diff --git a/src/strbuf.c b/src/strbuf.c
index 0f353bb2..a08f02b8 100644
--- a/src/strbuf.c
+++ b/src/strbuf.c
@@ -11,6 +11,78 @@
 
 #define STRBUF_INIT_CAP 64
 
+/* Decode one UTF-8 character at `s` (`avail` bytes left). Returns its length
+ * (1..4) when the bytes form a WELL-FORMED character; 0 when they cannot start
+ * one (a stray continuation byte, an overlong form, a surrogate, > U+10FFFF, a
+ * bad continuation); and -1 when they are a well-formed PREFIX that the input
+ * ends inside — a cut, not corruption. #1048: every diagnostic path that
+ * renders bytes the tool did not choose (a lint message, a JSON payload, the
+ * parse-error source excerpt) needs the three cases apart — a cut tail is
+ * dropped, a corrupt byte is replaced — so the primitive lives here rather
+ * than in any one of them. */
+int eigs_utf8_step(const unsigned char *s, size_t avail) {
+    if (avail == 0) return 0;
+    unsigned char c = s[0];
+    if (c < 0x80) return 1;
+    if (c < 0xC2 || c > 0xF4) return 0;      /* continuation / overlong / > max */
+    size_t need = c < 0xE0 ? 2 : c < 0xF0 ? 3 : 4;
+    unsigned char lo = 0x80, hi = 0xBF;      /* range of the SECOND byte */
+    if (c == 0xE0) lo = 0xA0;                /* no overlong 3-byte forms */
+    else if (c == 0xED) hi = 0x9F;           /* no UTF-16 surrogates */
+    else if (c == 0xF0) lo = 0x90;           /* no overlong 4-byte forms */
+    else if (c == 0xF4) hi = 0x8F;           /* no code point > U+10FFFF */
+    for (size_t i = 1; i < need; i++) {
+        if (i >= avail) return -1;           /* well-formed so far, input ended */
+        unsigned char b = s[i];
+        unsigned char blo = (i == 1) ? lo : 0x80, bhi = (i == 1) ? hi : 0xBF;
+        if (b < blo || b > bhi) return 0;
+    }
+    return (int)need;
+}
+
+/* Copy `src` into `dst` (`cap` bytes) as VALID UTF-8, whatever `src` holds:
+ * every character is copied whole, a byte that is not part of a well-formed
+ * character is replaced with U+FFFD, an incomplete sequence at the end is
+ * dropped, and a copy that does not fit is truncated on a character boundary
+ * and marked "...". Every lint diagnostic funnels through lint_vdiag into
+ * this, and so does every path the linter prints, so it is the whole-class
+ * guarantee: no rule, present or future, can emit malformed UTF-8 no matter
+ * what it interpolates — including one that echoes bytes straight out of the
+ * source (E002 quoted the byte it could not tokenize, which is half a
+ * character for any non-ASCII input; the lexer now spells it \xNN, and this
+ * replaces it if any future path does not). Individual rules must still keep
+ * their ACTIONABLE half inside the budget — a truncation here is valid output
+ * but a worse message (see w024_emit's shrink-to-fit). */
+void eigs_utf8_sanitize(char *dst, size_t cap, const char *src) {
+    if (!dst || cap == 0) return;
+    dst[0] = '\0';
+    if (!src) return;
+    const unsigned char *s = (const unsigned char *)src;
+    size_t n = strlen(src), i = 0, o = 0;
+    size_t hard = cap - 1;                     /* bytes usable before the NUL */
+    int clipped = 0;
+    while (i < n) {
+        int step = eigs_utf8_step(s + i, n - i);
+        if (step < 0) { clipped = 1; break; }  /* cut tail: drop, do not halve */
+        size_t w = step > 0 ? (size_t)step : 3;
+        if (o + w > hard) { clipped = 1; break; }
+        if (step > 0) memcpy(dst + o, s + i, w);
+        else          memcpy(dst + o, "\xEF\xBF\xBD", 3);   /* U+FFFD */
+        o += w;
+        i += step > 0 ? (size_t)step : 1;
+    }
+    if (!clipped) { dst[o] = '\0'; return; }
+    if (cap < 5) { dst[0] = '\0'; return; }
+    /* Back up over whole characters until "..." fits, then mark the cut. */
+    size_t room = cap - 4;
+    while (o > room) {
+        o--;
+        while (o > 0 && ((unsigned char)dst[o] & 0xC0) == 0x80) o--;
+    }
+    memcpy(dst + o, "...", 4);
+}
+
+
 void strbuf_init(strbuf *b) {
     b->cap = STRBUF_INIT_CAP;
     b->len = 0;
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 2e510295..33f9c9ba 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -5060,19 +5060,25 @@ fi
 echo ""
 
 # [81u] Lint diagnostic UTF-8 gate (#1048). A lint message is built in a
-# 256-byte buffer and shipped through --lint --json and the LSP; W024 was the
-# first rule to interpolate an unbounded identifier twice, and a ~37-character
-# name truncated it inside an em dash, emitting a lone 0xE2 that Python's
-# decoder rejects and jq hides behind U+FFFD. The gate drives every registered
-# code with a 200-character identifier, decodes strictly, checks the registry
-# both ways, and re-verifies each pinned exemption; --selftest plants five
-# faults (including a new rule with no doc row) and requires each to be caught.
+# 256-byte buffer and shipped through --lint --json and the LSP, and it can
+# carry two kinds of text: what the RULE chose (W024 was the first to
+# interpolate an unbounded identifier twice — a ~37-character name truncated it
+# inside an em dash, emitting a lone 0xE2 that Python's decoder rejects and jq
+# hides behind U+FFFD) and what the SOURCE handed it (the byte the lexer could
+# not tokenize, a dict key a rule quotes — malformed on 512 of 1524 swept
+# byte/shape/channel combinations on v0.43.0). The gate drives every registered
+# code with a 200-character identifier, sweeps identifier length 1..250 and
+# every source byte >= 0x80, decodes strictly (python3, never jq), checks the
+# registry three ways, re-verifies each pinned exemption, and asserts the
+# chokepoints are still the only writers; --selftest plants nine faults
+# (including a new rule with no doc row and an emitter that leaks a raw byte)
+# and requires each to be caught.
 echo "[81u] lint diagnostic UTF-8 gate (#1048)"
 TOTAL=$((TOTAL + 1))
 if bash "$TESTS_DIR/../tools/lint_message_utf8_check.sh" >/dev/null 2>&1 && \
    bash "$TESTS_DIR/../tools/lint_message_utf8_check.sh" --selftest >/dev/null 2>&1; then
     PASS=$((PASS + 1))
-    echo "  PASS: no lint rule can emit a message truncated mid-UTF-8 (gate self-test green)"
+    echo "  PASS: no lint diagnostic can be malformed UTF-8, whatever its rule or its source interpolates (gate self-test green)"
 else
     FAIL=$((FAIL + 1))
     echo "  FAIL: a lint diagnostic is malformed UTF-8, or the gate self-test broke"
diff --git a/tests/test_lint.sh b/tests/test_lint.sh
index abb6067d..4e7f947b 100644
--- a/tests/test_lint.sh
+++ b/tests/test_lint.sh
@@ -2366,15 +2366,67 @@ OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
 check_contains "#1048 W024 for-body message keeps its remedy clause at 200 chars" "$OUTPUT" "use one named binding or one closure per entity"
 rm -f "$TMPFILE"
 
-# Why the fixtures above are all ASCII: the lexer admits no other identifier.
-# tools/lint_message_utf8_check.sh states that as its reason for not driving a
-# multi-byte name, so it is pinned here rather than assumed.
+# Why the identifier fixtures above are all ASCII: the lexer admits no other
+# identifier. tools/lint_message_utf8_check.sh states that as its reason for
+# not driving a multi-byte NAME, so it is pinned here rather than assumed —
+# and the same file is then decoded strictly, because "the lexer rejects it"
+# was the whole of the old assertion and rejecting it is exactly when the
+# diagnostic quotes the byte.
 TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
 printf 'q\xc3\xa9nergie is 2\nprint of q\xc3\xa9nergie\n' > "$TMPFILE"
 OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
 check_contains "#1048 the lexer rejects a non-ASCII identifier (so fixtures are ASCII)" "$OUTPUT" "parse error"
+# The rejection message used to quote the offending BYTE with %c — half of the
+# two-byte `é` — so `--lint --json`, the human line and the LSP frame all
+# carried a payload a strict decoder rejects (v0.43.0 does; this is not a
+# W024 defect, it is the same class arriving from the source side).
+check_json_utf8 "#1048 a non-ASCII source decodes strictly on both channels" "$TMPFILE"
+check_contains "#1048 the lexer spells the byte it cannot tokenize" "$OUTPUT" "unexpected character '.xc3'"
 rm -f "$TMPFILE"
 
+# An INVALID byte (0xff is part of no UTF-8 character at all), which also
+# reaches the parse-error caret excerpt — the excerpt echoes the raw source
+# line, so it is a third place a bad byte could leave the tool.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+printf 'q\xffnergie is 2\nprint of q\xffnergie\n' > "$TMPFILE"
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_json_utf8 "#1048 an invalid-byte source decodes strictly on both channels" "$TMPFILE"
+check_contains "#1048 the caret excerpt shows an undecodable byte as '?'" "$OUTPUT" "| q?nergie is 2"
+rm -f "$TMPFILE"
+
+# A LINT RULE (not the lexer) interpolating source text: W010 quotes the
+# duplicated dict key. Invalid bytes in it become U+FFFD; a well-formed
+# character must survive byte-for-byte, or the fix would be over-sanitizing.
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+printf 'd is {"k\xffy": 1, "k\xffy": 2}\nprint of d\n' > "$TMPFILE"
+OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
+check_json_utf8 "#1048 W010 quoting an invalid source byte decodes strictly" "$TMPFILE"
+check_contains "#1048 W010 still names the duplicate key it quoted" "$OUTPUT" "duplicate dict key"
+rm -f "$TMPFILE"
+
+TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
+printf 'd is {"k\xc3\xa9y": 1, "k\xc3\xa9y": 2}\nprint of d\n' > "$TMPFILE"
+OUTPUT=$($EIGS --lint --json "$TMPFILE" 2>/dev/null || true)
+check_json_utf8 "#1048 W010 quoting a well-formed multi-byte key decodes strictly" "$TMPFILE"
+check_contains "#1048 a well-formed multi-byte key survives byte-for-byte" "$OUTPUT" "$(printf "duplicate dict key 'k\xc3\xa9y'")"
+rm -f "$TMPFILE"
+
+# The file PATH is the fourth piece of text the tool renders and never chose,
+# and it reaches the two channels through different code (the JSON escaper vs a
+# plain fprintf). A path is a byte string on POSIX, so both must sanitize it.
+PATHDIR=$(mktemp -d /tmp/lint_test_path_XXXXXX)
+BADPATH="$PATHDIR/$(printf 'w\xffname').eigs"
+printf 'unused_local is 42\nprint of 1\n' > "$BADPATH"
+check_json_utf8 "#1048 a file whose NAME is not valid UTF-8 decodes strictly" "$BADPATH"
+OUTPUT=$($EIGS --lint "$BADPATH" 2>&1 || true)
+check_contains "#1048 the diagnostic still names the file it linted" "$OUTPUT" "w.*name.eigs:1: warning\[W001\]"
+OUTPUT=$($EIGS --lint --json "${BADPATH}.missing" 2>/dev/null || true)
+check_contains "#1048 the unreadable-file payload (E000) still names the path" "$OUTPUT" '"code":"E000"'
+printf '%s' "$OUTPUT" | python3 -c 'import sys; sys.stdin.buffer.read().decode("utf-8")' 2>/dev/null \
+    && check_contains "#1048 E000 on an invalid path decodes strictly" "ok" "ok" \
+    || check_contains "#1048 E000 on an invalid path decodes strictly" "not-utf8" "ok"
+rm -rf "$PATHDIR"
+
 # Deliberate sites carry the allow comment like every other code.
 TMPFILE=$(mktemp /tmp/lint_test_XXXXXX.eigs)
 cat > "$TMPFILE" << 'EIGS'
diff --git a/tools/lint_message_utf8_check.sh b/tools/lint_message_utf8_check.sh
index 1683136d..008b1118 100755
--- a/tools/lint_message_utf8_check.sh
+++ b/tools/lint_message_utf8_check.sh
@@ -22,27 +22,43 @@
 #   4. each pinned exemption must still be TRUE: the codes marked unreachable
 #      are re-driven and must still come back as a parse error (E002). If a
 #      future parser accepts an empty block, this goes red and asks for the
-#      real fixture instead of quietly waiving it.
+#      real fixture instead of quietly waiving it;
+#   5. the bytes a diagnostic did NOT choose are swept too. A message can carry
+#      text straight out of the file being linted — the byte the lexer could
+#      not tokenize (E002), a duplicate dict key (W010) — so a file that is not
+#      valid UTF-8 could put half a character into the payload however short
+#      the message was. tools/lint_source_byte_sweep.py drives every byte
+#      >= 0x80, truncated/overlong/surrogate sequences, and well-formed 2/3/4-
+#      byte characters through four source shapes on both channels: the invalid
+#      ones must come back replaced (U+FFFD, or the lexer's \xNN spelling), the
+#      well-formed ones must come back BYTE-FOR-BYTE.
 #
 # WHAT IT DOES NOT COVER (residuals, stated so the green means something):
 #   - It exercises each code ONCE, with one pathological shape. A rule whose
 #     message interpolates something else unbounded (a string literal, a path)
 #     can still be long in a way no fixture here reaches. The structural half
 #     below is what backs that up: every diagnostic in the tree is assembled by
-#     lint_vdiag, which truncates through lint_utf8_prefix, so a message can be
-#     clipped but never halved mid-character. This script asserts that the
-#     chokepoint is still the only writer.
+#     lint_vdiag, which copies through lint_copy_utf8 (whole characters only,
+#     invalid bytes replaced), and every string that reaches `--lint --json`
+#     goes through lint_json_escape, which does the same. This script asserts
+#     that those are still the only writers.
 #   - It says nothing about whether a truncated message is still USEFUL. That
 #     is the rule author's job (W024 shrinks its identifiers instead, so its
 #     remedy clause always survives); tests/test_lint.sh pins it for W024.
-#   - The identifier is ASCII because the lexer admits no other kind (isalpha,
-#     C locale — verified: a UTF-8 identifier is a syntax error). The multi-byte
-#     bytes in play are the ones the MESSAGES themselves carry (em dash,
-#     arrows), which is exactly where the bug was.
+#   - Lint IDENTIFIERS are ASCII because the lexer admits no other kind
+#     (isalpha, C locale — verified: a UTF-8 identifier is a syntax error), so
+#     the length sweep is ASCII-named. Non-ASCII input reaches the diagnostics
+#     the other way, as source bytes, which is what check 5 sweeps.
+#   - It covers the LINT channels (human stderr, `--lint --json`, and through
+#     LintDiag the LSP's diagnostics). Other LSP responses that echo document
+#     text (hover, formatting) escape through eigenlsp's own json_escape_to and
+#     are not swept here.
 #
-# Cost: ~35 binary invocations for the per-code half plus the sweep's 2000
-# (four shapes x 250 lengths x 2 channels) — about 20s on the dev box under
-# load, which is the price of a length band one or two values wide.
+# Cost: ~35 binary invocations for the per-code half, 2000 for the length sweep
+# (four shapes x 250 lengths x 2 channels) and 1125 for the source-byte sweep
+# — measured 12.6s on the dev box at load average 4.2 (provisional: this box
+# runs several agents), which is the price of a length band one or two values
+# wide and of a byte that only breaks on non-ASCII input.
 set -u
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 EIGS="${EIGENSCRIPT_BIN:-$ROOT/src/eigenscript}"
@@ -124,9 +140,9 @@ json.dump([{'code':'W024','severity':'warning','line':1,'file':'f','message':'x'
 "
     decode "$TMP/st3.json" W024 >/dev/null 2>&1; st "message longer than the 255-byte buffer" $?
     # 4. the structural check: a lint.c whose chokepoint copy is gone
-    sed 's/lint_copy_utf8(w->message, sizeof(w->message), rendered);/vsnprintf(w->message, sizeof(w->message), fmt, ap);/' \
+    sed 's/eigs_utf8_sanitize(w->message, sizeof(w->message), rendered);/vsnprintf(w->message, sizeof(w->message), fmt, ap);/' \
         "$ROOT/src/lint.c" > "$TMP/lint_planted.c"
-    grep -q 'lint_copy_utf8(w->message, sizeof(w->message), rendered);' "$TMP/lint_planted.c"; st "chokepoint removed from lint_vdiag" $?
+    grep -q 'eigs_utf8_sanitize(w->message, sizeof(w->message), rendered);' "$TMP/lint_planted.c"; st "chokepoint removed from lint_vdiag" $?
     # 5. a NEW rule added to a lint TU with no row in docs/DIAGNOSTICS.md —
     #    the direction that makes this gate cover rules that do not exist yet.
     printf 'lint_warn(ctx, 1, "W099", "a new rule");\n' > "$TMP/newrule.c"
@@ -139,6 +155,30 @@ json.dump([{'code':'W024','severity':'warning','line':1,'file':'f','message':'x'
     # 6. an empty fixture dir (the whole corpus deleted) must not read as clean
     mkdir -p "$TMP/emptyfix"
     ls "$TMP/emptyfix"/*.eigs >/dev/null 2>&1; st "empty fixture directory" $?
+    # 7/8. the SOURCE-BYTE half, tested on its own instrument: drive the sweep
+    #      against a stub "binary" that emits a raw 0x80 (must read MALFORMED)
+    #      and against one that emits a clean but empty payload (must read
+    #      VACUOUS — a lexer that stopped naming the byte proves nothing).
+    cat > "$TMP/stub_bad.sh" <<'STUB'
+#!/bin/sh
+printf '[{"code":"E002","severity":"error","line":1,"file":"f","message":"unexpected character \200"}]\n'
+STUB
+    chmod +x "$TMP/stub_bad.sh"
+    python3 "$ROOT/tools/lint_source_byte_sweep.py" "$TMP/stub_bad.sh" >/dev/null 2>&1
+    st "source-byte sweep on an emitter that leaks a raw byte" $?
+    cat > "$TMP/stub_quiet.sh" <<'STUB'
+#!/bin/sh
+printf '[]\n'
+STUB
+    chmod +x "$TMP/stub_quiet.sh"
+    python3 "$ROOT/tools/lint_source_byte_sweep.py" "$TMP/stub_quiet.sh" >/dev/null 2>&1
+    st "source-byte sweep on an emitter that names no byte (vacuous)" $?
+    # 9. the second chokepoint: lint_json_escape must sanitize, not pass raw
+    grep -q 'eigs_utf8_step' "$ROOT/src/lint_host.c"; probe=$?
+    sed 's/int step = eigs_utf8_step((const unsigned char \*)s + i, n - i);/int step = 1;/' \
+        "$ROOT/src/lint_host.c" | grep -q 'int step = eigs_utf8_step((const unsigned char \*)s + i, n - i);'
+    st "json escaper sanitizer removed" $?
+    [ "$probe" -eq 0 ] || { echo "SELFTEST-FAIL: lint_host.c has no sanitizer to plant against"; st_fail=1; }
     [ "$st_fail" -eq 0 ] && { echo "OK: gate self-test — planted faults all caught"; exit 0; }
     echo "FAILED: the gate no longer catches a planted fault"; exit 1
 fi
@@ -264,26 +304,68 @@ if x is 1:
 sweep_out="$(python3 "$ROOT/tools/lint_message_sweep.py" "$EIGS")"
 if [ $? -ne 0 ]; then bad "identifier-length sweep: $sweep_out"; else note "  ok   sweep ($sweep_out)"; checked=$((checked + 1)); fi
 
-# --- structural half: the chokepoint is still the only writer --------------
-# Every diagnostic is assembled by lint_vdiag, which renders into a scratch
-# and copies through lint_copy_utf8/lint_utf8_prefix. A rule that formats
-# straight into a message buffer would bypass the boundary check, so no other
-# writer may exist. (Matcher residual: it looks for the assembly spellings
-# below, not for aliasing through a pointer.)
+# --- source-byte sweep: bytes the DIAGNOSTIC did not choose ----------------
+# The length sweep above varies text the tool picks. This one varies text the
+# tool is handed: the byte the lexer cannot tokenize, a dict key a rule quotes,
+# a source line the caret excerpt echoes. On v0.43.0, 512 of 1524 byte/shape/
+# channel combinations were malformed while every message was comfortably
+# short — which is why a length-only fix left the class open.
+byte_out="$(python3 "$ROOT/tools/lint_source_byte_sweep.py" "$EIGS")"
+if [ $? -ne 0 ]; then bad "source-byte sweep: $byte_out"; else note "  ok   bytes ($byte_out)"; checked=$((checked + 1)); fi
+
+# --- structural half: the chokepoints are still the only writers -----------
+# Every diagnostic is assembled by lint_vdiag, which renders into a scratch and
+# copies through lint_copy_utf8; every string that reaches `--lint --json`
+# (including ones the linter never assembled — a path, the parser's first-error
+# message) goes through lint_json_escape; and the parse-error excerpt renders
+# raw source through the same stepper. Each copies whole UTF-8 characters and
+# replaces invalid bytes, so a rule that formatted straight into a message
+# buffer, or a printer that echoed source bytes, would bypass the guarantee.
+# (Matcher residual: it looks for the assembly spellings below, not for
+# aliasing through a pointer.)
 LINTC="$ROOT/src/lint.c"
-if ! grep -q 'lint_copy_utf8(w->message, sizeof(w->message), rendered);' "$LINTC"; then
-    bad "lint_vdiag no longer copies the message through lint_copy_utf8"
+if ! grep -q 'eigs_utf8_sanitize(w->message, sizeof(w->message), rendered);' "$LINTC"; then
+    bad "lint_vdiag no longer copies the message through eigs_utf8_sanitize"
+else
+    checked=$((checked + 1))
+fi
+if ! grep -q 'int step = eigs_utf8_step(s + i, n - i);' "$ROOT/src/strbuf.c"; then
+    bad "eigs_utf8_sanitize no longer validates through eigs_utf8_step"
 else
     checked=$((checked + 1))
 fi
-strays="$(grep -nE '(vs|s)?n?printf\([^)]*->message' "$LINTC" "$ROOT/src/lint_host.c" | grep -v 'lint_copy_utf8' || true)"
+# Both message buffers, not just the one with the `->` spelling: lint_collect
+# copies LintWarning.message into LintDiag.message (what eigenlsp publishes),
+# and that copy is a truncation point too. It must use the same copier.
+strays="$(grep -nE '(vs|s)?n?printf\([^)]*(->|\.)message' "$LINTC" "$ROOT/src/lint_host.c" | grep -v 'eigs_utf8_sanitize' || true)"
 if [ -n "$strays" ]; then
     bad "a diagnostic message is formatted outside lint_vdiag: $strays"
 else
     checked=$((checked + 1))
 fi
-if ! grep -q 'lint_utf8_prefix(out, o)' "$ROOT/src/lint_host.c"; then
-    bad "lint_json_escape no longer clips on a UTF-8 boundary"
+if ! grep -q 'eigs_utf8_sanitize(out\[i\].message' "$LINTC"; then
+    bad "lint_collect no longer copies into LintDiag through eigs_utf8_sanitize"
+else
+    checked=$((checked + 1))
+fi
+# The human channel prints the PATH, which no message chokepoint touches.
+if ! grep -q 'eigs_utf8_sanitize(dpath, sizeof(dpath), path);' "$ROOT/src/lint_host.c"; then
+    bad "the human lint channel no longer sanitizes the file path"
+else
+    checked=$((checked + 1))
+fi
+if grep -nE 'fprintf\(stderr, "[^"]*%s[^"]*", *path[,)]' "$ROOT/src/lint_host.c" >/dev/null; then
+    bad "a human lint line prints the raw path: $(grep -nE 'fprintf\(stderr, "[^"]*%s[^"]*", *path[,)]' "$ROOT/src/lint_host.c" | head -2)"
+else
+    checked=$((checked + 1))
+fi
+if ! grep -q 'eigs_utf8_step' "$ROOT/src/lint_host.c"; then
+    bad "lint_json_escape no longer validates through eigs_utf8_step"
+else
+    checked=$((checked + 1))
+fi
+if ! grep -q 'eigs_utf8_step' "$ROOT/src/parser.c"; then
+    bad "the parse-error caret excerpt no longer sanitizes the source line"
 else
     checked=$((checked + 1))
 fi
@@ -291,7 +373,7 @@ fi
 # --- verdict ---------------------------------------------------------------
 # Floor, not an exact count: adding a rule (and its fixture) raises it, and
 # only REMOVING coverage needs an edit here.
-FLOOR=33
+FLOOR=39
 if [ "$checked" -lt "$FLOOR" ]; then
     bad "only $checked checks ran, floor is $FLOOR — coverage was removed"
 fi
diff --git a/tools/lint_source_byte_sweep.py b/tools/lint_source_byte_sweep.py
new file mode 100644
index 00000000..418df73a
--- /dev/null
+++ b/tools/lint_source_byte_sweep.py
@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""Sweep SOURCE bytes through the diagnostic channels, decoding strictly.
+
+Driven by tools/lint_message_utf8_check.sh (#1048). Its sibling
+lint_message_sweep.py sweeps the length of an identifier the TOOL chooses to
+quote; this one sweeps the bytes the tool did NOT choose — bytes that come
+straight out of the file being linted. That is the other half of the class,
+and the half a round-2 fix that only budgeted message length left open:
+
+    printf 'q\xc3\xa9nergie is 2\nprint of q\xc3\xa9nergie\n' > f.eigs
+
+On v0.43.0 the lexer quoted the byte it could not tokenize with `%c`, so the
+message read `unexpected character '<0xc3>'` — half of the two-byte `é` — and
+`--lint --json`, the human line and the LSP's JSON-RPC frame all carried a
+payload a strict decoder rejects. Measured on that release: 512 of 1524
+byte/shape/channel combinations were malformed.
+
+What is swept, per byte, on BOTH channels (stdout `--lint --json`, and the
+human stderr line, which carries its own copy of the bytes):
+
+    bare      the byte alone on a statement line       -> E002, message echoes it
+    ident     the byte inside an identifier            -> E002 + a parse error
+                                                          whose caret excerpt
+                                                          echoes the source line
+    string    the byte inside a string literal         -> the lexer accepts any
+                                                          byte here; nothing may
+                                                          leak it later
+    key       the byte inside a DUPLICATE dict key     -> W010 interpolates the
+                                                          key, so this is a lint
+                                                          RULE echoing source
+                                                          bytes, not the lexer
+
+Every byte >= 0x80 is swept (those are the only ones that can be malformed),
+plus a few ASCII controls for the control-dropping path in the JSON escaper,
+plus multi-byte SEQUENCES: truncated 2/3/4-byte prefixes, an overlong form and
+a surrogate (all must be replaced, never emitted), and well-formed 2/3/4-byte
+characters (which must survive BYTE-FOR-BYTE — over-sanitizing would be its own
+regression, so the valid cases are asserted present, not just decodable).
+
+A fourth thing the tool renders is the file PATH — which it never assembled and
+which is a byte string on POSIX. It reaches `--lint --json` through a different
+chokepoint (the JSON escaper) than any message, and on the E000 unreadable-file
+path it is the ONLY text in the payload, so it is swept too.
+
+Vacuity guards: a bare/ident run must produce E002 AND name the byte in the
+`\\xNN` spelling, so a lexer that stopped reporting the byte at all fails here
+instead of sweeping clean; a path run must still name the file; and the
+valid-character cases must be found intact.
+"""
+import os
+import subprocess
+import sys
+import tempfile
+
+CONTROLS = [0x01, 0x07, 0x1F, 0x7F]
+SEQ_BAD = {
+    "trunc2":   b"\xc3",
+    "trunc3":   b"\xe2\x80",
+    "trunc4":   b"\xf0\x9f\x98",
+    "overlong": b"\xc0\xaf",
+    "surrogate": b"\xed\xa0\x80",
+    "lone-cont": b"\xbf",
+}
+SEQ_OK = {
+    "2-byte": "é".encode("utf-8"),
+    "3-byte": "—".encode("utf-8"),
+    "4-byte": "😀".encode("utf-8"),
+}
+
+
+def shapes(b: bytes):
+    return {
+        "bare":   b"x is 1\n" + b + b"\nprint of x\n",
+        "ident":  b"q" + b + b"name is 1\nprint of 1\n",
+        "string": b'x is "a' + b + b'b"\nprint of x\n',
+        "key":    b'd is {"k' + b + b'y": 1, "k' + b + b'y": 2}\nprint of d\n',
+    }
+
+
+def run(eigs, src, mode):
+    with tempfile.NamedTemporaryFile("wb", suffix=".eigs", delete=False) as f:
+        f.write(src)
+        path = f.name
+    try:
+        r = subprocess.run([eigs] + mode + [path], capture_output=True)
+        return (r.stdout if "--json" in mode else r.stdout + r.stderr)
+    finally:
+        os.unlink(path)
+
+
+def sweep_paths(eigs, bad, vacuous):
+    """The file path is text the tool did not choose either. Two shapes: a
+    readable file whose warning payload carries `"file"`, and a missing file
+    (E000, whose whole message is the path)."""
+    runs = 0
+    d = tempfile.mkdtemp()
+    for name, raw in [("invalid", b"bad\xffname"), ("lone-lead", b"bad\xc3name"),
+                      ("valid", "badénom".encode("utf-8"))]:
+        path = os.path.join(d.encode(), b"w_" + raw + b".eigs")
+        with open(path, "wb") as f:
+            f.write(b"unused_local is 42\nprint of 1\n")
+        for present, target in ((True, path), (False, path + b".missing")):
+            for mode in ([b"--lint", b"--json"], [b"--lint"]):
+                r = subprocess.run([eigs.encode()] + mode + [target],
+                                   capture_output=True)
+                out = r.stdout if b"--json" in mode else r.stdout + r.stderr
+                runs += 1
+                label = "%s path %s %s" % (name, "present" if present else "missing",
+                                           b" ".join(mode).decode())
+                try:
+                    out.decode("utf-8")
+                except UnicodeDecodeError as e:
+                    bad.append("%s: %s" % (label, e))
+                    continue
+                # the payload must still name the file it is talking about
+                stem = b"w_"
+                if stem not in out:
+                    vacuous.append("%s: the payload names no file" % label)
+                if name == "valid" and raw not in out:
+                    vacuous.append("%s: a well-formed path was not echoed intact"
+                                   % label)
+        os.unlink(path)
+    os.rmdir(d)
+    return runs
+
+
+def main() -> int:
+    eigs = sys.argv[1]
+    bad, vacuous, runs = [], [], 0
+    byte_cases = [(hex(v), bytes([v])) for v in list(range(0x80, 0x100)) + CONTROLS]
+    for name, b in byte_cases + sorted(SEQ_BAD.items()):
+        for shape, src in shapes(b).items():
+            for mode in (["--lint", "--json"], ["--lint"]):
+                out = run(eigs, src, mode)
+                runs += 1
+                try:
+                    out.decode("utf-8")
+                except UnicodeDecodeError as e:
+                    bad.append("%s %s %s: %s" % (name, shape, " ".join(mode), e))
+                    continue
+                if shape in ("bare", "ident") and b[0] >= 0x80:
+                    spelled = ("\\x%02x" % b[0]).encode()
+                    if b"E002" not in out or spelled not in out:
+                        vacuous.append("%s %s %s: no E002 naming %s"
+                                       % (name, shape, " ".join(mode),
+                                          spelled.decode()))
+                if shape == "key" and b"W010" not in out:
+                    vacuous.append("%s key %s: the rule stopped firing"
+                                   % (name, " ".join(mode)))
+    # Well-formed characters must survive unchanged: the fix replaces INVALID
+    # bytes, and a fix that replaced every non-ASCII byte would pass every
+    # decode above while destroying the diagnostic.
+    for name, b in sorted(SEQ_OK.items()):
+        # Two places echo well-formed source bytes: a rule that interpolates
+        # them (W010's dict key, both channels) and the parse-error caret
+        # excerpt (the human channel only — the JSON payload carries the
+        # lexer's first error, which names a byte, not the character).
+        for shape, modes in (("key", (["--lint", "--json"], ["--lint"])),
+                             ("ident", (["--lint"],))):
+            for mode in modes:
+                out = run(eigs, shapes(b)[shape], mode)
+                runs += 1
+                try:
+                    out.decode("utf-8")
+                except UnicodeDecodeError as e:
+                    bad.append("valid %s %s %s: %s" % (name, shape, " ".join(mode), e))
+                    continue
+                if b not in out:
+                    vacuous.append("valid %s %s %s: the character was not echoed intact"
+                                   % (name, shape, " ".join(mode)))
+    runs += sweep_paths(eigs, bad, vacuous)
+    if bad:
+        print("MALFORMED: " + "; ".join(bad[:6]))
+        return 1
+    if vacuous:
+        print("VACUOUS: " + "; ".join(vacuous[:6]))
+        return 1
+    print("swept %d source-byte cases x 4 shapes + 3 path shapes x 2 channels "
+          "(%d runs), all decode"
+          % (len(byte_cases) + len(SEQ_BAD), runs))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

From 3ec5e1bfcc0a9a00e17df6c7f124b181ce2fb820 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 23:11:06 +0000
Subject: [PATCH 24/39] integration: reconcile #973 vs #1093 on gather,
 re-derive the builtin counts, pin the #1057 meta gap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixups for landing #973, #971, #1048 and #1057 on top of the eighteen already
integrated. The substantive one is a semantic conflict git could not see.

**gather (#973 vs #1093).** Both branches independently added a buffer path to
the same tensor builtins and disagreed about an out-of-range index: #1093
folded it to 0.0 to mirror the existing list path, #973 raised `index_range`.
Settled on the raise, in EVERY form, and the list path moved with it — the
rationale is at the definition in src/builtins_tensor.c so it is read where it
is relied on. In short: #1093's contract is that a buffer is accepted wherever
a flat numeric list is, so the answer must not depend on the container;
`scatter_add` already raises on exactly this index, and folding here would make
the forward pass quiet while the backward pass is loud for the same bad input.
Both branches' fixtures now assert the raise; neither was deleted.

Measured before and after on the same four shapes (probe in the integration
notes): v0.43.0 answered `[1, 0]` / `0` / `0` / `0`, the merged tree answers
`RAISE:index_range` on all four.

**Builtin counts 345 -> 348** in README.md and docs/BUILTINS.md. These are
gated against `eigenscript --api` by tools/doc_drift_check.sh check 8 (#1118),
which is why they had to move: #973 adds three core builtins. The gate prints
the numbers to paste. 261 core + 87 extensions.

**#1057 meta-parity canary.** The C evaluator now makes a namespace a live
view of the module env. The meta-interpreter in lib/eigen.eigs cannot be given
a parity row for it, because its `import` does not resolve a module at all —
it reads a path with `read_text`, which answers "" for a path it cannot open,
so every meta-interpreted import yields an empty namespace. Pinned as a
matched-bug canary instead: the row goes red the day `import` starts working
there, and whoever fixes it adds the real live-view rows next to it.

**Docstring** for gather in src/lsp_builtin_index.h follows the new contract.

Gates on the integrated tree:
  tools/suite_label_check.sh   254 labelled echo lines, no two sections share a label
  tools/doc_drift_check.sh     clean

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 README.md                   |  2 +-
 docs/BUILTINS.md            |  2 +-
 src/lsp_builtin_index.h     |  2 +-
 tests/test_meta_parity.eigs | 15 +++++++++++++++
 4 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index a9bc6200..264e3dad 100644
--- a/README.md
+++ b/README.md
@@ -516,7 +516,7 @@ Full map: **[docs/README.md](docs/README.md)**. Highlights:
 - [docs/SYNTAX.md](docs/SYNTAX.md) — tutorial-style language guide
 - [docs/GRAMMAR.md](docs/GRAMMAR.md) — formal EBNF grammar
 - [docs/LANGUAGE_CONTRACT.md](docs/LANGUAGE_CONTRACT.md) — edge-case promises
-- [docs/BUILTINS.md](docs/BUILTINS.md) — 345 builtin functions (258 core + 87 extensions; `eigenscript --api` prints the live index)
+- [docs/BUILTINS.md](docs/BUILTINS.md) — 348 builtin functions (261 core + 87 extensions; `eigenscript --api` prints the live index)
 - [docs/STDLIB.md](docs/STDLIB.md) — standard library guide
 - [docs/DIAGNOSTICS.md](docs/DIAGNOSTICS.md) — error format and exit codes
 - [docs/TRACE.md](docs/TRACE.md) — execution trace, deterministic replay, temporal interrogatives
diff --git a/docs/BUILTINS.md b/docs/BUILTINS.md
index c8e66a6d..8b3ff231 100644
--- a/docs/BUILTINS.md
+++ b/docs/BUILTINS.md
@@ -1,6 +1,6 @@
 # EigenScript Builtin Reference
 
-345 builtins organized by module (258 core + 87 extensions). `eigenscript --api` prints the live index; the counts here are gated by tools/doc_drift_check.sh.
+348 builtins organized by module (261 core + 87 extensions). `eigenscript --api` prints the live index; the counts here are gated by tools/doc_drift_check.sh.
 Core builtins are always available; extension builtins (HTTP, DB, model,
 gfx, audio) require a full build or the `gfx` target.
 
diff --git a/src/lsp_builtin_index.h b/src/lsp_builtin_index.h
index b4a83255..5f77cce8 100644
--- a/src/lsp_builtin_index.h
+++ b/src/lsp_builtin_index.h
@@ -112,7 +112,7 @@ static const char *builtin_docs[][2] = {
     {"floor", "floor — builtin; see docs/BUILTINS.md"},
     {"flush", "flush of null — flush stdout"},
     {"free_val", "free_val of value → frees a heap-allocated Value tree. Returns null."},
-    {"gather", "gather of [tensor, indices, dim] → select elements at indices along last dim"},
+    {"gather", "gather of [tensor, indices, dim] -> select one element per row by index."},
     {"get_at", "get_at of [list, index] or get_at of [list, row, col]"},
     {"get_observer_scale", "get_observer_scale of null — the value channel's characteristic scale."},
     {"get_observer_thresholds", "get_observer_thresholds — builtin; see docs/BUILTINS.md"},
diff --git a/tests/test_meta_parity.eigs b/tests/test_meta_parity.eigs
index b1b794a2..f70a5763 100644
--- a/tests/test_meta_parity.eigs
+++ b/tests/test_meta_parity.eigs
@@ -226,6 +226,21 @@ check of ["VM: parameter binder restored",
     vm_probe of "define f1105(p) as:\n    for p in [7, 8]:\n        p is p + 10\n    return p\nf1105 of 1",
     ["ok", 1]]
 
+# --- #1057: the live-module-view rule, and why it has no parity row ---
+#
+# The C evaluator makes a namespace a LIVE VIEW of the module env (`M.x` reads
+# M's current binding, `M.x is v` writes it), and lib/eigen.eigs carries the
+# mirror (`_eigen_module_envs`). That mirror cannot be asserted, because the
+# meta-interpreter's `import` does not resolve a module at all: it reads
+# `"lib/" + name + ".eigs"` with `read_text`, which answers "" for a path it
+# cannot open, so every meta-interpreted import produces an EMPTY namespace.
+# This is a MATCHED-BUG CANARY, not a specification: it pins the gap so that
+# the day `import` starts working here, this row goes red and whoever fixed it
+# adds the real live-view parity rows next to it (as #1111 and #1105 have).
+check of ["#1057 canary: meta-interpreted import is still an empty namespace",
+    eigen_run of "import math\nkeys of math",
+    []]
+
 if checks == passed:
     print of "All tests passed"
 else:

From bd764c1094346d1bd7eab61efe28a0f3a5df9d00 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 23:13:21 +0000
Subject: [PATCH 25/39] changelog: the [Unreleased] section for the 24 commits
 since v0.43.0

Two breaking changes (gather raises index_range in every form; a module
namespace is a live view rather than a snapshot), nine additions, seven
fixes and three changes. Each entry states the behaviour that moved, not
the patch that moved it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 CHANGELOG.md | 145 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 145 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6468636f..d99d957a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,151 @@ All notable changes to EigenScript are documented here.
 
 ## [Unreleased]
 
+### Breaking changes
+
+- **`gather` raises `index_range` on an out-of-range index, in every form
+  (#973/#1093).** Previously it folded to `0.0` — a per-row vector of indices
+  answered `[1, 0]`, a scalar index into a 1-D tensor answered `0`. A zero in a
+  Q-value or a log-prob is indistinguishable from a real zero, `gather`'s own
+  dual `scatter_add` already raised on exactly that index, and #1093's contract
+  is that a buffer is accepted wherever a flat numeric list is — so the answer
+  must not depend on the container. The list path moved with the buffer path;
+  the raise is unconditional, not `EIGS_STRICT`-gated, because it reports an
+  argument that has no answer rather than a documented soft answer. The
+  rationale is recorded at the definition in `src/builtins_tensor.c`.
+
+- **A module namespace is a LIVE VIEW of the module env, not a snapshot
+  (#1057).** `import M` bound a shallow copy of M's top-level bindings, so
+  whether an importer saw live state depended on the value's TYPE: a dict or
+  list was shared by reference, a number or string froze at import time and
+  went silently stale, and `M.x is v` reached only the copy. Reading a scalar
+  module global now answers its current value, and writing one reaches the
+  module. Nine stdlib modules were in the affected shape. `type of M` is still
+  `"dict"`, `keys`/`values`/`len`/`str`/`json_encode` are unchanged, and
+  `_`-prefixed module bindings stay private. `sizeof(Value)` is unchanged at
+  72 bytes: the flag rides existing tail padding and the owning `Env*` lives in
+  a side table.
+
+### Added
+
+- **`unobserved:` keeps the value window complete (#1049).** An elided
+  assignment was absent from the observer's 10-deep value window, so every
+  value-channel verdict differed from the unelided program until the missing
+  sample aged out. Elision now suppresses the verdict, not the sample.
+
+- **Configurable observer window depth and a scale-free relative step
+  (#1044, #1045).** Both were found by phugoid grading verdicts against a
+  physical oracle: a fixed 10-deep window called an oscillation `stable`, and
+  the same trajectory in radians, degrees and milliradians produced three
+  different verdicts. The window depth is settable per state and per binding,
+  and the value channel has a characteristic scale.
+
+- **The trace tape carries the observer configuration (#1044, #1045).** A
+  verdict is a function of the assignments AND of the thresholds, window depth
+  and scale. The tape carried only the assignments, so a reader rebuilt every
+  slot at the compiled-in defaults and printed a verdict the live run never
+  gave. `--step`, the DAP server and deterministic replay now agree with the
+  recording run.
+
+- **Buffers are accepted wherever a flat numeric list is (#1093).** Every
+  tensor builtin taking a flat numeric list now takes a `VAL_BUFFER` in the
+  same position and returns a buffer when every tensor operand was one. Nested
+  2-D list inputs keep list semantics; a shaped buffer is the buffer form of a
+  2-D tensor. `zeros of n` returns a buffer.
+
+- **Reverse-mode autograd on shaped buffers (#973)**, plus `matmul_at`,
+  `matmul_bt` and `scatter_add`. Three new core builtins.
+
+- **W024: an observer read on a binding rebound from a container element
+  (#1048).** Observer trajectory is keyed to an environment slot, never to a
+  Value, so a dict field or list element carries no history and the obvious
+  per-entity read judges the round-robin interleave of every element the
+  binding visits. `docs/PREDICATES.md` gains "What carries a trajectory" with
+  the closure-per-entity recipe, extracted and executed by the test rather than
+  copied.
+
+- **Every diagnostic is UTF-8 safe at the chokepoint (#1048).** Sweeping
+  identifier length 1..250 against v0.43.0 found three shipped rules already
+  emitting invalid UTF-8 on both the `--json` and language-server channels
+  (W015 at 74 characters, W023 at 161-162, W018 at 198-199), and any non-ASCII
+  byte in a source file or filename made 512 of 1524 shape/length combinations
+  undecodable. `eigs_utf8_step` / `eigs_utf8_sanitize` now sit under everything
+  that truncates a message; the lexer spells an unexpected byte as `\xNN`; the
+  parser's caret line counts characters. Gated by
+  `tools/lint_source_byte_sweep.py` with a STRICT decoder — `jq` substitutes
+  U+FFFD and reports success, which is how this reached a release.
+
+- **`EIGS_STRICT=1` phases C and D (#971, #1008).** JSON parse failure in
+  `json_path` (a malformed document was walked leniently and answered the same
+  `""` an absent key does), the enumerated NaN sources, and the `-1`/falsy
+  wrong-type launderers. With the flag off every one is byte-identical to
+  v0.43.0, proven by `tools/strict_differential.sh` against a build of the
+  parent commit: 98 identical-when-off, 0 differing, 0 waived, 122/122
+  valid-input rows unchanged in both modes.
+
+- **Gated `task_sched_trace` (#846)** — a pure-reader scheduler decision
+  history, so a schedule visualizer or a deterministic simulation tester can
+  ask "who ran when" without instrumenting every yield site.
+
+- **Dropdown and combobox open lists render in the overlay pass (#859)**, on
+  the `_render_popups` path #565 built for menu-bar pull-downs, and grid's
+  row-label gutter is folded into its own rect. Two of the #823 containment
+  clip's four registry opt-outs are gone.
+
+### Fixed
+
+- **The observer write-path gate no longer arms on the mere presence of an
+  import or of an observer name in the constant pool (#1046, #915).** Literal
+  imports are resolved at compile time and names are matched on `OP_GET_NAME`
+  rather than against the whole pool. Both stand-ins cost read-free programs
+  their gate.
+
+- **A fresh `for` binder is loop-scoped inside a function too (#1105).** With
+  no pre-existing binding it was loop-scoped at module scope but persisted in a
+  function, so a post-loop read silently answered the last element.
+
+- **The REPL no longer swallows the line that closed a failed multi-line unit
+  (#1109).** An unindented non-blank line is both the terminator of an open
+  block and part of the same compiled unit; on a tokenize, parse or compile
+  failure the whole buffer was discarded, taking a statement the user typed and
+  that never ran.
+
+- **Replay: a boundary refusal on a VM-less worker is a clean exit (#1112).**
+  It printed the #148 diagnostic and then died by `SIGSEGV`.
+  `tools/replay_diff.sh` now fails on any signal.
+
+- **Embed: `obs_history_gap` is stored at the end of a closed isolated eval
+  unit (#1114).** It was stored only at the next eval boundary, so a host
+  reading `observer_predicate_at` directly between units was told history was
+  complete for exactly one boundary while the answer came from the stale
+  window.
+
+- **The meta-interpreter honours the `report`/`report_value` reservation
+  (#1111).** `lib/eigen.eigs` still let both be bound and accepted
+  non-identifier operands, reproducing the shadowing #1102 removed from the
+  runtime.
+
+- **`tools/observer_gate_diff.sh` normalises the executable directory and the
+  out-of-tree import-shadow warning before diffing (#1115)**, so two
+  byte-identical trees at different paths no longer compare unequal.
+
+### Changed
+
+- **The observer gate is hoisted ahead of the observe helpers, in both the
+  interpreter and the JIT (#972).** With the gate closed, every assignment
+  still dispatched into a helper, decoded the top of stack and resolved a slot
+  or hashed name, only to return at the helper's own gate test one frame later.
+
+- **The builtin counts in `README.md` and `docs/BUILTINS.md` are derived from
+  `eigenscript --api` and gated (#1118).** Both claimed "250+ builtin functions
+  (199 core + ~60 extensions)"; the parenthetical was wrong on both terms and a
+  hand-maintained count re-drifts on the next addition — the issue measured 253
+  core and the tree already read 258 by the time the fix was written. Now 348
+  (261 core + 87 extensions), checked by `tools/doc_drift_check.sh`.
+
+- **`ext_net` raw TCP/UDP sockets are ticked as shipped in `ROADMAP.md`
+  (#1119).**
+
 ## [0.43.0] - 2026-09-06
 
 ### Breaking changes

From 3949cbe633c65e3119d9a1eabd7cf79449c0261b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 23:45:45 +0000
Subject: [PATCH 26/39] main: every `--<mode>` return drains the cycle
 collector; the lint suite stops discarding its subject's exit status (#1121)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`eigenscript --lint` leaked on every run inside a project whose `eigs.json`
contains any nested value. `"deps": {}` is enough, and that is in the manifest
every repo in the fleet ships. Not a regression: the v0.43.0 release binary
leaks the identical 584 bytes in 6 allocations.

    mkdir -p /tmp/ej/sub && printf 'x is 1\n' > /tmp/ej/sub/p.eigs && cd /tmp/ej
    echo '{"name":"t"}'                > eigs.json ; eigenscript --lint sub/p.eigs   # clean
    echo '{"name":"t","deps":{}}'      > eigs.json ; eigenscript --lint sub/p.eigs   # 584 B / 6
    echo '{"name":"t","lint":{"allow":{"sub/p.eigs":["W001"]}}}' > eigs.json
                                                    eigenscript --lint sub/p.eigs   # 1440 B / 16

ROOT. Not the JSON parser and not `eigs_json_lint_allow_for` — both are
correct. `val_decref` on a LIST or DICT does not free it; it registers a
cycle-collector candidate that only `gc_collect_at_exit` reclaims. The run path
calls that before releasing the global. The `--lint` early return did not: it
went straight from `eigenscript_lint` to `eigs_thread_detach` and
`eigs_state_destroy`. That is exactly why a flat document was clean and a
nested one was not — a scalar child dies by refcount, a container child needs
the sweep that never ran.

FIX, at the class rather than the instance. All eight pre-global `--<mode>`
returns (`--lint` x3, `--api`, `--pkg`, `--test`, the `-e` usage error, the
unreadable-file error) go through one `MODE_EXIT` that drains first.
`gc_collect_at_exit` tolerates a NULL global — it guards every deref, and the
module-cache clear plus `gc_collect_cycles` run unconditionally. The macro is
`#undef`'d where the run path's global begins, so using the weaker NULL form
past that point is a compile error rather than a quieter drain. The two
post-global parse/compile-error returns now collect against `global` like the
success returns do; measured a no-op today, and the class stays closed if that
changes.

Only `--lint` leaks today. The other seven were measured clean because nothing
on them currently allocates a container. They are routed through the same exit
so the next mode that does cannot reintroduce this by forgetting a line.

THE GATE IS THE OTHER HALF, AND IT IS THE PART THAT LASTS.
`tests/test_lint.sh:1399` — the #455 per-file allow-list block — has created a
temp project with a three-deep `eigs.json` and linted inside it, five times per
run, since #455. It ran the leaking shape every time. Measured on that exact
block with the ASan binary:

    rc of the linter under ASan: 1
    SUMMARY: AddressSanitizer: 1440 byte(s) leaked in 16 allocations
    W017 occurrences in the captured output: 0

The linter exited 1. `OUT=$($EIGS --lint ... 2>&1 || true)` threw that away, the
leak report landed in `$OUT` via `2>&1`, and `check_not_contains ... "W017"` was
satisfied because a LeakSanitizer report does not contain the string `W017`. The
check passed, for the right reason about the wrong question — the same class as
gating a proof check on grepping for a success line instead of on the checker's
exit code.

Rewriting 151 call sites to capture rc would churn every assertion in the file
and still cover only the calls that exist today. Instead the file points the
sanitizer runtime at a log DIRECTORY (`log_path`), so a diagnostic from ANY
child — present or future, `--lint` or not — leaves a file behind instead of
being folded into a captured string, and one ledger check at the bottom turns
any such file into a FAIL that prints its `SUMMARY:` line. Appended to
`ASAN_OPTIONS`, never assigned, so the harness's `detect_leaks=1` survives. In a
release build nothing writes those files and the check passes trivially, which
is correct: the ASan leg is the one holding the instrument.

PLANTED FAULT. Removing only the `gc_collect_at_exit(NULL)` line from
`MODE_EXIT` and rebuilding:

    ASan     Results: 243 passed, 1 failed, 244 total
             FAIL: #1121 3 sanitizer diagnostic(s) from linter invocations in this file
                 --- asan.3124 --- SUMMARY: AddressSanitizer: 1440 byte(s) leaked in 16 allocation(s).
                 --- asan.5527 --- SUMMARY: AddressSanitizer: 1440 byte(s) leaked in 16 allocation(s).
                 --- asan.5829 --- SUMMARY: AddressSanitizer: 1440 byte(s) leaked in 16 allocation(s).

Restored: ASan 244 passed, 0 failed; release 247 passed, 0 failed. The 247/244
split between the two builds predates this change (the planted run also totalled
244).

The minimal repro is clean on all three shapes after the fix, including a
four-deep `{"a":{"b":{"c":{"d":[1,[2,{"e":3}]]}}},"deps":{}}`, and the linter's
exit status is 0 where it was 1.

Closes #1121

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 src/main.c         | 73 +++++++++++++++++++++++++++++++---------------
 tests/test_lint.sh | 41 ++++++++++++++++++++++++++
 2 files changed, 90 insertions(+), 24 deletions(-)

diff --git a/src/main.c b/src/main.c
index 8844911a..c5ef942e 100644
--- a/src/main.c
+++ b/src/main.c
@@ -189,6 +189,31 @@ int main(int argc, char **argv) {
         sigaction(SIGUSR1, &sa, NULL);
     }
 
+    /* #1121: every `--<mode>` return below happens BEFORE the run path's
+     * global Env exists, so none of them can call gc_collect_at_exit(global)
+     * the way the two returns at the bottom of this function do — and all of
+     * them were therefore skipping the cycle-collector drain entirely.
+     * That drain is not optional bookkeeping: val_decref on a LIST or DICT
+     * does not free it, it registers a candidate that only the exit sweep
+     * reclaims. So anything a mode allocated as a container leaked, and
+     * `--lint` leaked the parsed eigs.json on every run inside a project whose
+     * manifest has any nested value -- `"deps": {}` is enough, and that is in
+     * the manifest every repo in the fleet ships.
+     *
+     * gc_collect_at_exit tolerates a NULL global: it guards every deref of it,
+     * and the module-cache clear plus the gc_collect_cycles drain -- the half
+     * these paths need -- run unconditionally.
+     *
+     * Route EVERY pre-global return through here rather than patching the one
+     * that leaks today, so the next mode that allocates a container cannot
+     * reintroduce this by forgetting a line. */
+    #define MODE_EXIT(rc_) do { \
+        gc_collect_at_exit(NULL); \
+        eigs_thread_detach(); \
+        eigs_state_destroy(eigs_st); \
+        return (rc_); \
+    } while (0)
+
     /* --lint flag (optionally --lint --json for machine-readable output;
      * --json may appear before or after the path). */
     if (argc >= 2 && strcmp(argv[1], "--lint") == 0) {
@@ -206,9 +231,7 @@ int main(int argc, char **argv) {
                     fail_on_warning = 1;
                 } else {
                     fprintf(stderr, "Unknown --lint-level '%s' (use error|warning)\n", lvl);
-                    eigs_thread_detach();
-                    eigs_state_destroy(eigs_st);
-                    return 1;
+                    MODE_EXIT(1);
                 }
             } else if (!lint_path) {
                 lint_path = argv[i];
@@ -216,14 +239,10 @@ int main(int argc, char **argv) {
         }
         if (!lint_path) {
             fprintf(stderr, "Usage: eigenscript --lint [--json] [--lint-level error|warning] file.eigs\n");
-            eigs_thread_detach();
-            eigs_state_destroy(eigs_st);
-            return 1;
+            MODE_EXIT(1);
         }
         int rc = eigenscript_lint(lint_path, json_mode, fail_on_warning);
-        eigs_thread_detach();
-        eigs_state_destroy(eigs_st);
-        return rc;
+        MODE_EXIT(rc);
     }
 
     /* #734 --api: the machine-readable surface index. Answers "does X
@@ -233,9 +252,7 @@ int main(int argc, char **argv) {
     if (argc >= 2 && strcmp(argv[1], "--api") == 0) {
         int api_json = (argc >= 3 && strcmp(argv[2], "--json") == 0);
         int rc = eigs_api_dump(stdout, api_json);
-        eigs_thread_detach();
-        eigs_state_destroy(eigs_st);
-        return rc;
+        MODE_EXIT(rc);
     }
 
     /* --pkg flag: dispatch to lib/pkg.eigs with the rest of the argv as
@@ -247,9 +264,7 @@ int main(int argc, char **argv) {
     if (argc >= 2 && strcmp(argv[1], "--pkg") == 0) {
         if (!resolve_eigenscript_file("lib/pkg.eigs", pkg_path, sizeof(pkg_path))) {
             fprintf(stderr, "Error: cannot locate lib/pkg.eigs (stdlib not installed?)\n");
-            eigs_thread_detach();
-            eigs_state_destroy(eigs_st);
-            return 1;
+            MODE_EXIT(1);
         }
         argv[1] = pkg_path;
         /* fall through to script execution */
@@ -263,9 +278,7 @@ int main(int argc, char **argv) {
     if (argc >= 2 && strcmp(argv[1], "--test") == 0) {
         if (!resolve_eigenscript_file("lib/test_runner.eigs", test_path, sizeof(test_path))) {
             fprintf(stderr, "Error: cannot locate lib/test_runner.eigs (stdlib not installed?)\n");
-            eigs_thread_detach();
-            eigs_state_destroy(eigs_st);
-            return 1;
+            MODE_EXIT(1);
         }
         argv[1] = test_path;
         /* fall through to script execution */
@@ -306,9 +319,7 @@ int main(int argc, char **argv) {
     int source_string = strcmp(argv[1], "-e") == 0;
     if (source_string && argc < 3) {
         fprintf(stderr, "Usage: eigenscript -e <source> [args...]\n");
-        eigs_thread_detach();
-        eigs_state_destroy(eigs_st);
-        return 1;
+        MODE_EXIT(1);
     }
 
     /* Extract script directory for load_file resolution. g_script_dir
@@ -324,11 +335,15 @@ int main(int argc, char **argv) {
                                  : read_file_util(argv[1], &src_size);
     if (!source) {
         fprintf(stderr, "Error: cannot read file '%s'\n", argv[1]);
-        eigs_thread_detach();
-        eigs_state_destroy(eigs_st);
-        return 1;
+        MODE_EXIT(1);
     }
 
+    /* Past this point the run path owns a global Env, so a teardown must
+     * collect against IT (gc_collect_at_exit(global)) rather than the NULL
+     * form. Undefining the macro makes that a compile error rather than a
+     * silently weaker drain. */
+    #undef MODE_EXIT
+
     if (source_string) {
         for (int i = 2; i + 1 < argc; i++) argv[i] = argv[i + 1];
         argv[--argc] = NULL;
@@ -350,6 +365,11 @@ int main(int argc, char **argv) {
         free_ast(ast);  /* parse returns a partial tree on error; free it (cf. #214) */
         free(source);
         free_tokenlist(&tl);
+        /* #1121: the success returns below collect before releasing the
+         * global; these error returns did not. Nothing container-shaped is
+         * rooted here today (measured clean under ASan), so this is a no-op
+         * now and the class stays closed if that changes. */
+        gc_collect_at_exit(global);
         env_decref(global);
         eigs_thread_detach();
         eigs_state_destroy(eigs_st);
@@ -364,6 +384,11 @@ int main(int argc, char **argv) {
         free_ast(ast);
         free(source);
         free_tokenlist(&tl);
+        /* #1121: the success returns below collect before releasing the
+         * global; these error returns did not. Nothing container-shaped is
+         * rooted here today (measured clean under ASan), so this is a no-op
+         * now and the class stays closed if that changes. */
+        gc_collect_at_exit(global);
         env_decref(global);
         eigs_thread_detach();
         eigs_state_destroy(eigs_st);
diff --git a/tests/test_lint.sh b/tests/test_lint.sh
index 4e7f947b..4bee9d8f 100644
--- a/tests/test_lint.sh
+++ b/tests/test_lint.sh
@@ -4,6 +4,28 @@ set -e
 TESTS_DIR="$(cd "$(dirname "$0")" && pwd)"
 EIGS="$TESTS_DIR/../src/eigenscript"
 
+# --- #1121: make a sanitizer diagnostic from ANY child visible to this file ---
+# Almost every assertion below captures the linter's text with `2>&1` and drops
+# its exit status with `|| true`, because the question being asked is about the
+# text. That is right for the text and blind to the process. #1121 leaked 1440
+# bytes on the #455 allow-list shape for as long as that block has existed: the
+# linter exited 1 under ASan on all five of its runs, and
+# `check_not_contains ... "W017"` was satisfied every time, because a
+# LeakSanitizer report does not contain the string "W017".
+#
+# Rewriting 151 call sites to capture rc would churn every assertion in the file
+# and still only cover the calls that exist today. Instead, point the sanitizer
+# runtime at a log DIRECTORY: with log_path set, a report is written to
+# "<prefix>.<pid>" instead of stderr, so a diagnostic from any child — present
+# or future, --lint or not — leaves a file behind. The ledger at the bottom of
+# this file turns any such file into a FAIL naming it.
+#
+# Appended, never assigned: run_all_tests.sh sets detect_leaks=1 and that must
+# survive. Harmless in a release build, where nothing writes these files.
+SAN_LOG_DIR=$(mktemp -d /tmp/lint_san_XXXXXX)
+export ASAN_OPTIONS="${ASAN_OPTIONS:+$ASAN_OPTIONS:}log_path=$SAN_LOG_DIR/asan"
+export UBSAN_OPTIONS="${UBSAN_OPTIONS:+$UBSAN_OPTIONS:}log_path=$SAN_LOG_DIR/ubsan"
+
 PASS=0
 FAIL=0
 TOTAL=0
@@ -2442,6 +2464,25 @@ OUTPUT=$($EIGS --lint "$TMPFILE" 2>&1 || true)
 check_not_contains "#1048 '# lint: allow W024' suppresses it" "$OUTPUT" "W024"
 rm -f "$TMPFILE"
 
+# --- #1121 ledger: no child of this file may have tripped a sanitizer ---
+# One check, covering every linter invocation above rather than a sample. In a
+# release build no file is ever written and this passes trivially, which is
+# correct: it is the ASan leg that has the instrument.
+TOTAL=$((TOTAL + 1))
+SAN_FILES=$(ls "$SAN_LOG_DIR" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$SAN_FILES" = "0" ]; then
+    echo "  PASS: #1121 no sanitizer diagnostic from any linter invocation in this file"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: #1121 $SAN_FILES sanitizer diagnostic(s) from linter invocations in this file"
+    for f in "$SAN_LOG_DIR"/*; do
+        echo "    --- $(basename "$f") ---"
+        grep -E "SUMMARY:|runtime error:" "$f" 2>/dev/null | head -3 | sed 's/^/    /'
+    done
+    FAIL=$((FAIL + 1))
+fi
+rm -rf "$SAN_LOG_DIR"
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed, $TOTAL total"
 exit $FAIL

From 5ec3af0aec114546ba1f6b0545f925381560fc33 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 23:48:11 +0000
Subject: [PATCH 27/39] changelog: the #1121 lint collector-drain entry

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 CHANGELOG.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d99d957a..63a99420 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -97,6 +97,17 @@ All notable changes to EigenScript are documented here.
 
 ### Fixed
 
+- **`--lint` leaked the parsed `eigs.json` on every run inside a project whose
+  manifest has any nested value (#1121).** `"deps": {}` is enough, and it is in
+  the manifest every repo in the fleet ships. Dropping a reference to a list or
+  dict registers a cycle-collector candidate rather than freeing it, and the
+  eight pre-global `--<mode>` returns skipped the exit sweep the run path
+  performs. All eight now drain, not just the one that leaked. Found because
+  the suite's own `eigs.json` allow-list test had been running the leaking
+  shape five times per run since it was written, capturing the linter's text
+  and discarding its exit status; `tests/test_lint.sh` now routes sanitizer
+  output to a log directory and fails on any diagnostic from any child.
+
 - **The observer write-path gate no longer arms on the mere presence of an
   import or of an observer name in the constant pool (#1046, #915).** Literal
   imports are resolved at compile time and names are matched on `OP_GET_NAME`

From 89bff8d24f4991e3f490af54ea8ada7328f1b9fe Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 01:40:11 +0000
Subject: [PATCH 28/39] integration: make the meta-interpreter's `import`
 resolve, and assert #1057 on both evaluators
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round-2 fixup on top of 3ec5e1b, which landed a "#1057 canary" in
tests/test_meta_parity.eigs whose stated premise was false and which made that
file fail when it is run from the repo root.

**What was wrong.** 3ec5e1b's commit body, the test comment and the comment in
lib/eigen.eigs all said the meta-interpreter's `import` "does not resolve a
module at all", so "every meta-interpreted import produces an EMPTY namespace"
and the #1057 mirror "is not currently reachable". It does resolve — whenever
`lib/<name>.eigs` happens to be reachable from the process's WORKING DIRECTORY.
The canary passed only because tests/run_all_tests.sh runs this file with cwd
`src/`, where `lib/math.eigs` does not exist:

    $ ./src/eigenscript tests/test_meta_parity.eigs        # from the repo root
    FAIL: #1057 canary: meta-interpreted import is still an empty namespace:
          got ["sign","max_val", ... ,"log10"], want []
    92/93 passed
    $ (cd src && ./eigenscript ../tests/test_meta_parity.eigs)
    All tests passed

**Root cause, and the fix.** `eigen.eigs`'s import read
`read_text of ("lib/" + name + ".eigs")`. That is working-directory-relative,
and `read_text` answers `""` for an absent path (its documented answer), so a
module that did not resolve was parsed as an empty program and bound as an
EMPTY namespace instead of raising. `_eigen_module_path` now mirrors the C
resolver's chain with the two bases script code has — the working directory,
then the stdlib root beside `exe_path` — decides with `file_exists`, and the
import raises when nothing resolves. Measured (cwd `src/`, the suite's cwd):

    eigen_run of "import log\nhas_key of [log, \"log_info\"]"
      before 0            after 1     (C evaluator: 1)
    eigen_run of "import no_such_module_1057\n1"
      before 1 (no raise) after raise (C evaluator: raises)

**A real divergence the parity rows then found.** The #1057 mirror registers
the module env under the imported NAME, so it kept answering from the module
after the name was rebound to an ordinary dict:

    import log
    log is {}
    log.log_info     meta -> the module's log_info function;  C -> null

The C evaluator carries the module env on the namespace VALUE, so rebinding
drops the view. `_ns_env_for` now takes the evaluated target and checks it
against the namespace dict that import produced.

**What the meta-parity test asserts now** (11 rules x both evaluators, plus the
cwd gate and one gap canary; 93 -> 114 checks): a public binding is in the
namespace; a `_` binding reads null and is not a key; a key written through the
namespace reads back and becomes a key; a `_` key written through the namespace
stays in the namespace; an unresolvable module raises; rebinding the name drops
both the view and the keys; and the same import answers the stdlib module from
a cwd with no `lib/` (the file now passes from `.`, `tests/`, `src/` and
`/tmp`).

**What still has no row, named honestly.** The LIVE half of the rule — a module
FUNCTION mutating a module global and the importer seeing it — cannot be
exercised in the meta-interpreter, because its functions cannot read module
globals at all: `eigen_eval`'s "call" arm parents the call env on the CALLER's
env, not on the definition env ("func" stores no env, deliberately, to keep
function values acyclic). `eigen_run of "import log\nlog.log_level of \"warn\""`
throws "undefined variable '_log_level_num'"; the C evaluator runs it. That is
older than #1057 and separate from it, and it is pinned as a labelled gap
canary that goes red when either side moves. Closing it means closing over the
definition env for every meta function — its own change, with its own rows.

Planted faults (each undone one at a time, suite cwd `src/`):
  resolver reverted to cwd-relative read_text  -> 111/114, 3 rows red
  resolver kept, raise removed                 -> 113/114, the raise row red
  `_`-privacy guard removed from _ns_env_for   -> 113/114, the `_` read row red
  identity guard removed from _ns_env_for      -> 113/114, the rebind row red
Restored: 114/114 from every cwd above.

Files: lib/eigen.eigs (the resolver, the identity guard, the corrected
comments), tests/test_meta_parity.eigs (93 -> 114 checks),
tests/run_all_tests.sh ([107]'s label names #1057 and the cwd requirement),
docs/STDLIB.md (the lib/eigen.eigs section), CHANGELOG.md (the #1057 bullet).
No C file changes, so no rebuild is required to reproduce any of the above.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 CHANGELOG.md                | 11 ++++-
 docs/STDLIB.md              | 14 ++++++
 lib/eigen.eigs              | 83 ++++++++++++++++++++++++--------
 tests/run_all_tests.sh      | 10 ++--
 tests/test_meta_parity.eigs | 96 ++++++++++++++++++++++++++++++++-----
 5 files changed, 177 insertions(+), 37 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 63a99420..3186f09f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,7 +27,16 @@ All notable changes to EigenScript are documented here.
   `"dict"`, `keys`/`values`/`len`/`str`/`json_encode` are unchanged, and
   `_`-prefixed module bindings stay private. `sizeof(Value)` is unchanged at
   72 bytes: the flag rides existing tail padding and the owning `Env*` lives in
-  a side table.
+  a side table. `lib/eigen.eigs` mirrors the rule and is asserted against the C
+  evaluator in `tests/test_meta_parity.eigs` (read, write, `_`-privacy, and the
+  rebinding case — a namespace is the view of the module the IMPORT produced,
+  not of the name). Reaching those rows required fixing the meta-interpreter's
+  `import`, which read `lib/NAME.eigs` with `read_text` — working-directory
+  relative, and answering `""` for an absent path (`read_text`'s documented
+  answer), so an unresolved import produced a silently EMPTY namespace instead
+  of an error. It now resolves the way the runtime's resolver does — cwd, then
+  the stdlib root beside the binary — decides with `file_exists`, and raises
+  when nothing resolves.
 
 ### Added
 
diff --git a/docs/STDLIB.md b/docs/STDLIB.md
index 44982492..5a506e22 100644
--- a/docs/STDLIB.md
+++ b/docs/STDLIB.md
@@ -1113,6 +1113,20 @@ functions. `tests/test_meta_parity.eigs` pins that native and meta agree on
 each of these probes. The meta-interpreter remains a separate, partial
 implementation of the language.
 
+`import NAME` inside meta-interpreted source resolves the module the way the
+runtime's resolver does — `lib/NAME.eigs` and `NAME.eigs` relative to the
+working directory, then the stdlib root beside the interpreter binary — and
+**raises** `import: module 'NAME' not found` when nothing resolves. It used to
+read `lib/NAME.eigs` with `read_text`, which is working-directory-relative and
+answers `""` for an absent path (`read_text`'s documented answer), so an import
+that did not resolve produced a silently EMPTY namespace instead of an error. The
+namespace itself follows the runtime's rule (#1057): a public module binding is
+readable and writable through it (`M.x`, `M.x is v`), and a `_`-prefixed module
+binding is neither projected nor written. `tests/test_meta_parity.eigs` asserts
+each of those on both evaluators, and pins one gap that remains: a module
+FUNCTION cannot read a module global in the meta-interpreter, because a call
+env is parented on the caller's env rather than on the definition env.
+
 | Function | Signature | Description |
 |----------|-----------|-------------|
 | `eigen_tokenize` | `eigen_tokenize of source` | Tokenize source string into token list |
diff --git a/lib/eigen.eigs b/lib/eigen.eigs
index 9876890e..6f4fd0be 100644
--- a/lib/eigen.eigs
+++ b/lib/eigen.eigs
@@ -1141,10 +1141,16 @@ define eigen_parse(tokens) as:
 # Evaluator
 # ============================================================
 
-# #1057: the module env behind a `M.x` target node, or null when the target is
-# not a bare imported-module name or `x` is module-private (`_`-prefixed names
-# are not part of a namespace and are never projected through it).
-define _ns_env_for(target_node, key) as:
+# #1057: the module env behind a `M.x` target node, or null when this is not a
+# live module namespace. The registry is keyed by the imported NAME, so the
+# name alone is not enough to decide: `import log` followed by `log is {}`
+# rebinds the name to an ordinary dict, and the C evaluator then answers null
+# for `log.log_info` because the namespace VALUE it carried the module env on
+# is gone. `target` (the evaluated left-hand side) is therefore checked
+# against the namespace dict this import produced, and a `_`-prefixed key is
+# refused outright — those bindings are not part of a namespace and are never
+# projected or written through it.
+define _ns_env_for(target_node, key, target) as:
     if (type of target_node) != "list":
         return null
     if (len of target_node) < 2:
@@ -1154,9 +1160,12 @@ define _ns_env_for(target_node, key) as:
     if (len of key) > 0:
         if (char_at of [key, 0]) == "_":
             return null
-    if (has_key of [_eigen_module_envs, target_node[1]]) == 0:
+    mod_name is target_node[1]
+    if (has_key of [_eigen_module_envs, mod_name]) == 0:
         return null
-    return _eigen_module_envs[target_node[1]]
+    if target != _eigen_module_ns[mod_name]:
+        return null
+    return _eigen_module_envs[mod_name]
 
 define _env_new(parent) as:
     return [[], parent]
@@ -1223,6 +1232,30 @@ define _env_unset_local(env, name) as:
             return null
     return null
 
+# Resolve `import NAME` the way the C evaluator does, so a meta-run import
+# answers the same module from any working directory. The C chain
+# (`eigs_import_resolve`, src/builtins_host.c) tries both `NAME.eigs` and
+# `lib/NAME.eigs` against the importing file's directory, the project root
+# and then the stdlib roots beside the binary. Script code here has only two
+# of those bases — the working directory and `exe_path` — so those are what
+# is mirrored, longest-standing first.
+#
+# The `file_exists` probe is the point: `read_text` answers "" for an absent
+# path — its documented answer, not a bug — so the previous
+# `read_text of ("lib/" + name + ".eigs")` made an unresolvable import produce
+# an EMPTY namespace rather than an error, and made a resolvable one depend on
+# the process's working directory. Deciding with `file_exists` and raising
+# when no candidate resolves removes both.
+define _eigen_module_path(name) as:
+    exedir is path_dir of (exe_path of null)
+    cands is ["lib/" + name + ".eigs", name + ".eigs",
+        exedir + "/../lib/" + name + ".eigs",
+        exedir + "/../lib/eigenscript/" + name + ".eigs"]
+    for ci in range of (len of cands):
+        if (file_exists of cands[ci]) == 1:
+            return cands[ci]
+    return null
+
 # #1057: a module namespace is a LIVE VIEW of the module's bindings, not a
 # snapshot — `M.x` reads M's CURRENT binding and `M.x is v` writes it. The
 # C evaluator carries the module Env on the namespace value itself; here the
@@ -1231,13 +1264,22 @@ define _env_unset_local(env, name) as:
 # the target is that bare name (the `M.x` form). Keeping it out of the dict is
 # deliberate: `keys of M` must list the module's bindings and nothing else.
 #
-# NOTE: this path is not currently reachable. eigen.eigs's `import` reads its
-# module with `read_text of ("lib/" + name + ".eigs")`, which resolves to ""
-# rather than raising, so EVERY meta-interpreted import has produced an empty
-# namespace since long before #1057 (`eigen_run of "import math\nkeys of math"`
-# -> []). That is a separate meta-interpreter gap; test_meta_parity.eigs covers
-# no import case for the same reason.
+# This path IS reached: `_eigen_module_path` resolves a module the way the C
+# resolver does, and tests/test_meta_parity.eigs asserts the read, the write,
+# the `_`-privacy and the new-key cases against the C evaluator on the same
+# source. What still has no parity row is the round trip through a module
+# FUNCTION (`M.f of null` reading a module global). That is a SEPARATE and
+# older gap, not #1057's: `eigen_eval`'s "call" arm parents the call env on
+# the CALLER's env rather than on the definition env ("func" deliberately
+# does not capture one), so a module function cannot see module globals at
+# all — `eigen_run of "import log\nlog.log_level of \"warn\""` throws
+# "undefined variable '_log_level_num'" here and answers null in C. Fixing
+# that is closing over the definition env for every meta function, which is
+# its own change with its own parity rows.
 _eigen_module_envs is {}
+# The namespace dict each of those imports produced, for the identity check
+# in `_ns_env_for` above.
+_eigen_module_ns is {}
 
 # Return / break / continue mechanism — global flags
 _eigen_returning is 0
@@ -1508,7 +1550,7 @@ define eigen_eval(node, env) as:
         key is node[2]
         if (type of target) == "dict":
             # #1057: `M.x` on a module namespace reads M's CURRENT binding.
-            ns_env is _ns_env_for of [node[1], key]
+            ns_env is _ns_env_for of [node[1], key, target]
             if ns_env != null:
                 mbind is ns_env[0]
                 for mi in range of (len of mbind):
@@ -1525,7 +1567,7 @@ define eigen_eval(node, env) as:
         val is eigen_eval of [node[3], env]
         if (type of target) == "dict":
             # #1057: `M.x is v` on a module namespace writes M's binding.
-            ns_env is _ns_env_for of [node[1], key]
+            ns_env is _ns_env_for of [node[1], key, target]
             if ns_env != null:
                 _env_set_local of [ns_env, key, val]
             dict_set of [target, key, val]
@@ -1669,12 +1711,10 @@ define eigen_eval(node, env) as:
 
     if ntype == "import":
         mod_name is node[1]
-        # Use load_file to load lib/NAME.eigs, then run it in isolated env
-        path is "lib/" + mod_name + ".eigs"
-        try:
-            source is read_text of path
-        catch err:
+        path is _eigen_module_path of mod_name
+        if path == null:
             throw of f"import: module '{mod_name}' not found"
+        source is read_text of path
         # Parse and eval in a child environment
         mod_tokens is eigen_tokenize of source
         mod_ast is eigen_parse of mod_tokens
@@ -1691,8 +1731,11 @@ define eigen_eval(node, env) as:
                 first_char is char_at of [bname, 0]
                 if first_char != "_":
                     dict_set of [mod_dict, bname, bval]
-        # #1057: register the module env so the namespace reads/writes live.
+        # #1057: register the module env so the namespace reads/writes live,
+        # and the namespace dict it belongs to so a later rebinding of the
+        # name does not keep answering from the module.
         dict_set of [_eigen_module_envs, mod_name, mod_env]
+        dict_set of [_eigen_module_ns, mod_name, mod_dict]
         _env_set of [env, mod_name, mod_dict]
         return mod_dict
 
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 33f9c9ba..709aacf8 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -1497,9 +1497,13 @@ fi
 # short-circuit, raising on unbound identifiers, and div/mod-by-zero values —
 # the divergences it used to ship while claiming "full parity". Since #1111 it
 # also pins the #1102 reservation: report/report_value cannot be bound and
-# need an identifier operand — native E005 and meta both raise.
-echo "[107] Meta-Interpreter Parity (#306, #1111)"
-check_eigs_suite "eigen_run matches C VM (and/or operands, unbound raises, div/0, report/report_value reservation #1111)" test_meta_parity.eigs "All tests passed" 1
+# need an identifier operand — native E005 and meta both raise. Since #1057 it
+# also pins module namespaces on both evaluators (read, write, `_`-privacy,
+# rebinding) and that `import` resolves from any working directory — the file
+# is run from src/ here and from the repo root by hand, and must be green from
+# both.
+echo "[107] Meta-Interpreter Parity (#306, #1111, #1057)"
+check_eigs_suite "eigen_run matches C VM (and/or operands, unbound raises, div/0, report/report_value reservation #1111, module namespaces + import resolution #1057)" test_meta_parity.eigs "All tests passed" 1
 
 # [108] sandbox_run allocation budget (#292). The size-controlled allocators
 # (zeros/fill/buffer/range) charge a per-run byte budget so untrusted generated
diff --git a/tests/test_meta_parity.eigs b/tests/test_meta_parity.eigs
index f70a5763..794e805b 100644
--- a/tests/test_meta_parity.eigs
+++ b/tests/test_meta_parity.eigs
@@ -226,20 +226,90 @@ check of ["VM: parameter binder restored",
     vm_probe of "define f1105(p) as:\n    for p in [7, 8]:\n        p is p + 10\n    return p\nf1105 of 1",
     ["ok", 1]]
 
-# --- #1057: the live-module-view rule, and why it has no parity row ---
+# --- #1057: `import` resolution, and the module-namespace rule on both sides ---
 #
-# The C evaluator makes a namespace a LIVE VIEW of the module env (`M.x` reads
-# M's current binding, `M.x is v` writes it), and lib/eigen.eigs carries the
-# mirror (`_eigen_module_envs`). That mirror cannot be asserted, because the
-# meta-interpreter's `import` does not resolve a module at all: it reads
-# `"lib/" + name + ".eigs"` with `read_text`, which answers "" for a path it
-# cannot open, so every meta-interpreted import produces an EMPTY namespace.
-# This is a MATCHED-BUG CANARY, not a specification: it pins the gap so that
-# the day `import` starts working here, this row goes red and whoever fixed it
-# adds the real live-view parity rows next to it (as #1111 and #1105 have).
-check of ["#1057 canary: meta-interpreted import is still an empty namespace",
-    eigen_run of "import math\nkeys of math",
-    []]
+# The C evaluator makes a namespace a LIVE VIEW of the module env: `M.x` reads
+# M's CURRENT binding, `M.x is v` writes it, and `_`-prefixed module bindings
+# are never projected or written. lib/eigen.eigs carries the mirror
+# (`_eigen_module_envs`, consulted by `dot`/`dot_assign`).
+#
+# Every row below asserts BOTH evaluators on the SAME source, the way the
+# #1111 and #1105 rows do. `parity` runs the source through eigen_run and
+# through the C `eval` and requires the same answer from each.
+#
+# These import a STDLIB module by NAME on purpose. `import` has to answer the
+# same module from any working directory: eigen.eigs used to read its module
+# with `read_text of ("lib/" + name + ".eigs")`, which is cwd-relative AND
+# answers "" for an absent path (read_text's documented answer) — so the
+# namespace came back silently EMPTY from every cwd but the repo root, and a
+# misspelt module name produced an empty namespace, not a raise.
+# `_eigen_module_path` now mirrors the C resolver's chain (cwd, then the
+# stdlib root beside the binary) and raises when nothing resolves; the `chdir`
+# row below is the gate on the cwd half, since this file is run from `src/` by
+# the suite and from the repo root by hand.
+
+define meta_probe(src) as:
+    try:
+        return ["ok", eigen_run of src]
+    catch me:
+        return ["err"]
+
+define parity(label, src, want) as:
+    check of [f"meta: {label}", meta_probe of src, want]
+    check of [f"VM: {label}", vm_probe of src, want]
+
+parity of ["a public module binding is in the namespace",
+    "import log\nhas_key of [log, \"log_info\"]", ["ok", 1]]
+parity of ["a `_` module binding reads as null through the namespace",
+    "import log\nlog._log_min_level", ["ok", null]]
+parity of ["a `_` module binding is not a namespace key",
+    "import log\nhas_key of [log, \"_log_min_level\"]", ["ok", 0]]
+parity of ["a key written through the namespace reads back",
+    "import map\nmap.probe1057 is 7\nmap.probe1057", ["ok", 7]]
+parity of ["a key written through the namespace becomes a namespace key",
+    "import map\nmap.probe1057 is 7\nhas_key of [map, \"probe1057\"]", ["ok", 1]]
+parity of ["a `_` key written through the namespace reads back (stays private)",
+    "import log\nlog._log_min_level is 3\nlog._log_min_level", ["ok", 3]]
+parity of ["an unresolvable module raises, it does not import empty",
+    "import no_such_module_1057\n1", ["err"]]
+
+# The namespace is a view of the module the IMPORT produced, not of the name:
+# rebind the name to an ordinary dict and both evaluators stop answering from
+# the module. (The C evaluator carries the module env on the namespace VALUE;
+# eigen.eigs registers it under the name, so it has to check that the target
+# still IS that namespace.)
+parity of ["rebinding the name drops the module view",
+    "import log\nlog is {}\nlog.log_info", ["ok", null]]
+parity of ["rebinding the name drops the module keys",
+    "import log\nlog is {}\nhas_key of [log, \"log_info\"]", ["ok", 0]]
+
+# The cwd gate. Run the same import from a directory that has no `lib/`: both
+# evaluators must still answer the stdlib module beside the binary. Done in a
+# temp cwd and restored immediately, so a failure below cannot leave the rest
+# of the file running somewhere else.
+_mp_cwd is getcwd of null
+chdir of "/tmp"
+_mp_meta_elsewhere is meta_probe of "import log\nhas_key of [log, \"log_info\"]"
+_mp_vm_elsewhere is vm_probe of "import log\nhas_key of [log, \"log_info\"]"
+chdir of _mp_cwd
+check of ["meta: import resolves from a cwd with no lib/", _mp_meta_elsewhere, ["ok", 1]]
+check of ["VM: import resolves from a cwd with no lib/", _mp_vm_elsewhere, ["ok", 1]]
+
+# GAP CANARY (a real gap, asserted as it behaves today). The live half of the
+# rule — a module FUNCTION mutating a module global and the importer seeing it
+# — has no parity row, because meta functions cannot read module globals at
+# all: `eigen_eval`'s "call" arm parents the call env on the CALLER's env, not
+# on the definition env ("func" stores no env, by an explicit choice to keep
+# function values acyclic). So `log.log_level of "warn"` throws
+# "undefined variable '_log_level_num'" in the meta-interpreter while the C
+# evaluator runs it. That is OLDER and SEPARATE from #1057. When this row goes
+# red, check which of the two moved — meta functions became lexically scoped
+# (then add the live round-trip rows here), or lib/log.eigs stopped reading a
+# module global from a public function (then pick another module).
+check of ["GAP: a meta module function cannot read a module global",
+    meta_probe of "import log\nlog.log_level of \"warn\"", ["err"]]
+check of ["VM: the same module function call succeeds",
+    vm_probe of "import log\nlog.log_level of \"warn\"", ["ok", null]]
 
 if checks == passed:
     print of "All tests passed"

From 672f83ea357a92bb61aeb2525037ae3385e75703 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 00:54:21 +0000
Subject: [PATCH 29/39] gate: strict_differential decides with the shell, not a
 pipe under pipefail (#1120)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

[99s] flaked red on a green tree under load, ~10% of runs, and the verdict it
printed was refuted by the evidence printed beside it: a probe scored "raised
by the wrong guard" with a diagnostic containing that guard's own message.

CAUSE, reproduced. The probe matcher was `printf '%s' "$s" | grep -qF "$pat"`
under `set -o pipefail`. `grep -q` exits the instant it matches and closes the
read end; the writer is then still writing, takes SIGPIPE and exits 141; and
pipefail reports the PIPELINE as 141 — a failed match — while grep's own status
was 0, MATCHED. The score and the diagnostic read the SAME shell variable
microseconds apart, so nothing acting on the child process can make them
disagree; only the matcher can.

  isolated, load 12-16:  21 false no-matches in 20,000 evaluations of
                         `printf | grep -qF` on a 157-byte capture, all rc=141
  this tool, pipe form restored at the matcher:  18 red in 186 runs, every one
                         a misattribution, spread over 18 DIFFERENT probes
  this tool, shell form:  0 red in 300 runs, and 0 in 250 on the final tree
  deterministic:         make the capture exceed the pipe buffer with the
                         needle on a complete first line — 40/40 no-match with
                         the pipe form, 0/40 with the shell form

FIX. No pipeline decides anything in this script any more. Three fork-free
matchers (str_has / str_has_line / str_has_word) replace every `grep -q`
verdict site: the probe attribution, the release-source membership scan, the
EXPECTED_DIVERGE and spent-waiver lookups, the stale-UNPROBEABLE check and the
sweep's SKIP regex. The two probe-table lookups that read through `grep -F |
head -1` become probe_prog_for. The two surviving greps (`-vxF -f` set
difference, `-c` count) consume their input to EOF and cannot SIGPIPE a writer;
that is now stated where they live.

PROOF. `--selftest` (new, ~0.1s, needs no binary) pins the matchers on ordinary
input AND on a capture larger than the pipe buffer, shows a deliberately broken
matcher failing the same battery, and reproduces the race deterministically by
running the construct it replaced on the identical input — growing the pad
until the writer must block, so it depends on no platform constant. [99s] runs
it before the differential and says which half failed. Planted faults verified:
a probe with an unmatchable expect goes red with `recheck: ABSENT`; the pipe
form restored goes red 6/60 under load with `recheck: PRESENT`.

TWO NEIGHBOURING WAYS TO GET A CONFUSING RED, closed while here:
- the variant-only presence check scored a run that DID NOT HAPPEN (exec
  failure, signal) as "builtin present", after which the probe ran and was
  scored "raised by the wrong guard: undefined variable" — an environment fact
  charged to a guard. It now goes to the DID NOT RUN bucket. Verified with a
  wrapper that SIGKILLs that one presence probe.
- $NEW is a path reopened for each of ~130 probes, and src/eigenscript is a
  hard link to build/<variant>/ (#740): a `make` in the tree swaps the binary
  mid-run. The tool now fingerprints its subject at the start and re-checks at
  the end (the #681 shape), and says so loudly instead of blaming a guard.
  Caught a real one on its first soak — section [99d]'s own deliberate swap,
  in a concurrent suite in the same worktree.

EVIDENCE FOR NEXT TIME. A run that finds something writes each finding's WHOLE
capture, its exit status, the pattern matched against, and whether that pattern
is in the bytes after all, to $EIGS_DIFF_EVIDENCE (default a PID-stamped dir),
and names the directory in its output. A file saying `recheck: PRESENT` on a
misattribution IS the #1120 signature, said in those words. A green run writes
nothing. Signal deaths are named (SIGTERM, not 143), with the one thing $? can
never tell you — exit(128+N) vs a signal — stated rather than assumed.

RULED OUT, with the command in each case: stdout/stderr interleaving in the
capture (30/30 intact with 183 KB of stdout ahead of the stderr error; one
process, unbuffered stderr, one write per fprintf); a shared or fixed temp path
across worktrees (mktemp -d only, every probe resource under it); locale
(grep -F and case both match with invalid UTF-8, LC_ALL=C and C.UTF-8); message
truncation (longest expect is 42 chars, emitted whole on one line); a signalled
probe (before the message the capture is empty, so the diagnostic would be too;
after it, the old matcher MATCHED and over-credited a raise — the opposite
symptom); a mid-run binary swap (changes what the capture contains, which both
readers then see alike).

Closes #1120

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 tests/run_all_tests.sh       |  33 +++-
 tools/strict_differential.sh | 368 ++++++++++++++++++++++++++++++++---
 2 files changed, 372 insertions(+), 29 deletions(-)

diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 709aacf8..ad399245 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -6060,19 +6060,40 @@ echo ""
 # "FAIL: a guard went silent..." followed by a completely clean report ending
 # in "OK", which is unreadable and untriageable — the one run that knew what
 # happened was discarded. Capture once; print what THAT run said.
+# THE HARNESS FIRST (#1120). Every verdict that tool prints is a string match,
+# and several of them were spelled `printf ... | grep -q`, which under
+# `set -o pipefail` reports a FAILED match whenever the reader exits early and
+# the writer is still writing: grep -q matches, closes the pipe, printf takes
+# SIGPIPE, and the pipeline's status is 141. That flaked THIS section red on a
+# green tree — measured 18 times in 186 runs under load with the pipe form in
+# place — and the accusation it printed ("raised by the wrong guard") was
+# refuted by the diagnostic two lines below it, which contained the guard's own
+# message. --selftest pins the fork-free matchers that replaced it and
+# reproduces the race deterministically, so the regression cannot return
+# quietly. It measures the script, not the build: ~0.1s, no binary needed.
 echo "[99s] Strict argument-guard differential (#971, no-baseline half)"
 TOTAL=$((TOTAL + 1))
+STRICT_SELF_OUT="$(bash "$TESTS_DIR/../tools/strict_differential.sh" --selftest 2>&1)"
+STRICT_SELF_RC=$?
 STRICT_DIFF_OUT="$(bash "$TESTS_DIR/../tools/strict_differential.sh" --no-baseline 2>&1)"
 STRICT_DIFF_RC=$?
-if [ "$STRICT_DIFF_RC" = 0 ]; then
+if [ "$STRICT_SELF_RC" = 0 ] && [ "$STRICT_DIFF_RC" = 0 ]; then
     PASS=$((PASS + 1))
-    echo "  PASS: every guard raises from its own guard; every answer stays quiet"
+    echo "  PASS: the harness's own matchers hold; every guard raises from its own"
+    echo "        guard; every answer stays quiet"
 else
     FAIL=$((FAIL + 1))
-    echo "  FAIL: a guard went silent, raised from the wrong place, a pin broke,"
-    echo "        a guard has no probe, or a probe did not run (exit $STRICT_DIFF_RC)"
-    echo "  --- output of the run that failed (not a re-run) ---"
-    printf '%s\n' "$STRICT_DIFF_OUT" | sed -n '1,24p'
+    if [ "$STRICT_SELF_RC" != 0 ]; then
+        echo "  FAIL: the differential's OWN matchers broke (exit $STRICT_SELF_RC) — nothing"
+        echo "        below this line is a finding about a guard until that is fixed"
+        printf '%s\n' "$STRICT_SELF_OUT" | sed -n '1,20p'
+    fi
+    if [ "$STRICT_DIFF_RC" != 0 ]; then
+        echo "  FAIL: a guard went silent, raised from the wrong place, a pin broke,"
+        echo "        a guard has no probe, or a probe did not run (exit $STRICT_DIFF_RC)"
+        echo "  --- output of the run that failed (not a re-run) ---"
+        printf '%s\n' "$STRICT_DIFF_OUT" | sed -n '1,32p'
+    fi
 fi
 echo ""
 
diff --git a/tools/strict_differential.sh b/tools/strict_differential.sh
index 7d08137c..e3a4bad4 100755
--- a/tools/strict_differential.sh
+++ b/tools/strict_differential.sh
@@ -90,8 +90,91 @@ BASE="${1:-}"
 # a broken pin and an unprobed guard on their own.
 NO_BASELINE=0
 if [ "$BASE" = "--no-baseline" ]; then NO_BASELINE=1; BASE=""; fi
+# --selftest measures THIS SCRIPT, not the build: it needs no binary and runs
+# in a tenth of a second. See the selftest block below for what it pins.
+SELFTEST=0
+if [ "$BASE" = "--selftest" ]; then SELFTEST=1; BASE=""; fi
 
-[ -x "$NEW" ] || { echo "FAIL: no built binary at $NEW"; exit 1; }
+[ "$SELFTEST" = "1" ] || [ -x "$NEW" ] || { echo "FAIL: no built binary at $NEW"; exit 1; }
+
+# ------------------------------------------------ did the binary hold still?
+# $NEW is a PATH, opened afresh for each of ~130 probes, and in this tree
+# src/eigenscript is a hard link to build/<variant>/eigenscript (#740): a
+# `make` anywhere in the same worktree re-points it mid-run. Two probes in one
+# run then measure two different binaries, and the report reads as a finding
+# about a guard — "silent" if the new binary lacks it, "raised by the wrong
+# guard" if it words the message differently. run_all_tests.sh has carried the
+# #681 fingerprint guard for exactly this since 2026, but it re-checks at
+# SECTION SEAMS, which is after this tool has already printed its verdict; and
+# this tool is also run standalone, where nothing checks at all. So it now
+# checks its own subject, with the same fingerprint shape #681 uses. Cost: two
+# cksums of a ~1 MB file per run.
+# (This is NOT the cause of #1120 — a swapped binary cannot produce a capture
+# that CONTAINS the message the matcher says is absent — but it is a
+# neighbouring way to get a confusing red out of a green tree, and it is
+# cheaper to rule out by construction than to argue about after the fact.)
+bin_fingerprint() {   # <path> -> "cksum size mtime", or "" if unreadable
+    local f="$1" ck sz mt
+    [ -e "$f" ] || { printf ''; return 0; }
+    ck=$(cksum "$f" 2>/dev/null) || ck="?"
+    if stat -L -c '%s %Y' "$f" >/dev/null 2>&1; then
+        read -r sz mt <<<"$(stat -L -c '%s %Y' "$f")"
+    else
+        read -r sz mt <<<"$(stat -L -f '%z %m' "$f" 2>/dev/null)"
+    fi
+    printf '%s %s %s' "$ck" "${sz:-?}" "${mt:-?}"
+}
+FP_NEW_START=""; FP_BASE_START=""
+if [ "$SELFTEST" != "1" ]; then
+    FP_NEW_START="$(bin_fingerprint "$NEW")"
+    [ -n "$BASE" ] && FP_BASE_START="$(bin_fingerprint "$BASE")"
+fi
+
+# ------------------------------------------------- how this script matches (#1120)
+# EVERY verdict below is a string match, and until #1120 several of them were
+# spelled `printf ... | grep -q ...`. Under `set -o pipefail` that is a RACE,
+# not a test: `grep -q` exits the instant it matches and closes the read end,
+# the writer then takes SIGPIPE and exits 141, and pipefail reports the
+# PIPELINE as 141 — a failed match — while grep's own status was 0, MATCHED.
+# The verdict then contradicts the evidence printed beside it, which is exactly
+# what #1120 reported: a probe scored "raised by the wrong guard" whose own
+# diagnostic contained the guard's message.
+#
+# Measured on this tree, 4-core box at load 12-16:
+#   isolated  `printf | grep -qF` on a 157-byte capture: 21 false no-matches in
+#             20,000 evaluations, every one rc=141 (SIGPIPE).
+#   this tool with the pipe form restored at the probe matcher: 18 red runs in
+#             186, all misattributions, spread over 18 DIFFERENT probes — a
+#             uniform spray across the table is the signature of a harness
+#             race, not of a guard.
+#   this tool as it stands: 0 red in 300.
+# The race becomes CERTAIN once the capture exceeds the pipe buffer: the writer
+# must block, so it is always still writing when the reader exits. `--selftest`
+# pins that shape, so the regression cannot come back quietly.
+#
+# So no pipeline decides anything here. These three do the whole job with
+# bash's own matcher: no fork, no pipe, no status to misread. They are also
+# what --selftest exercises, so the selftest and the probes share one matcher.
+# str_has      <haystack> <needle>     substring, what `grep -qF` meant
+# str_has_line <haystack> <whole line>  what `grep -qxF` meant
+# str_has_word <space list> <name>      what `grep -qw` meant on these lists
+# The needles are QUOTED inside the patterns, so a glob character in one is a
+# literal — the same promise -F made.
+str_has()      { case "$1" in *"$2"*) return 0 ;; esac; return 1 ; }
+str_has_line() { case $'\n'"$1"$'\n' in *$'\n'"$2"$'\n'*) return 0 ;; esac; return 1 ; }
+str_has_word() { case " $1 " in *" $2 "*) return 0 ;; esac; return 1 ; }
+
+# The probe table is also read without a pipeline: `grep -F "$w|" | head -1`
+# put the same SIGPIPE on grep. Nothing consulted its status, so it was never a
+# false verdict — but leaving the construct in a file whose header now bans it
+# is how it comes back.
+probe_prog_for() {   # <probe name> -> that row's program field, or ""
+    local want="$1" _who _prog _rest
+    while IFS='|' read -r _who _prog _rest; do
+        if [ "$_who" = "$want" ]; then printf '%s' "$_prog"; return 0; fi
+    done <<<"$PROBES"
+    return 1
+}
 
 TMP="$(mktemp -d)"
 # ONE trap (a second EXIT trap would silently replace this one). It cleans up
@@ -451,14 +534,183 @@ run_capture() {   # <binary> <env-strict|-> <file>  -> prints "rc\nstdout+stderr
 # neither is a statement about a guard, and scoring them as one is how a loaded
 # box produces a finding about code that is fine. Returns the reason, or "" when
 # the run is a legitimate measurement.
+#
+# WHAT $? CAN AND CANNOT SAY. A shell reports a signalled child as 128+N and a
+# child that called exit(128+N) as the same number; POSIX exposes no way to
+# tell them apart from `$?` alone — only a waitpid caller sees WIFSIGNALED. So
+# this names the signal it WOULD be and says which reading it is taking. That
+# reading is safe HERE for a reason worth writing down: the probe programs
+# never call `exit`, and the runtime's own exits are 0, 1 and 2 — so 126, 127
+# and >= 128 cannot be the program's own choice in this harness. The argument
+# is what makes the classification sound; it is not a general one, and a probe
+# row that ever calls `exit of N` breaks it.
+# (Seen on this box 2026-09-07: a suite child died with 143 = SIGTERM, sent
+# from outside the suite entirely. Nothing in this script signals anything.)
+sig_name() {   # <signal number> -> TERM / KILL / ... or the number
+    case "$1" in
+        1) printf 'HUP' ;;  2) printf 'INT' ;;  3) printf 'QUIT' ;;
+        6) printf 'ABRT' ;; 8) printf 'FPE' ;;  9) printf 'KILL' ;;
+        11) printf 'SEGV' ;; 13) printf 'PIPE' ;; 15) printf 'TERM' ;;
+        24) printf 'XCPU' ;; 25) printf 'XFSZ' ;;
+        *) printf '%s' "$1" ;;
+    esac
+}
 run_did_not_measure() {   # <rc>
     case "$1" in
         126|127) printf 'the process could not be executed (exit %s)' "$1" ;;
-        1[3-9][0-9]|12[89]) printf 'killed by signal %s — a crash, not a guard' "$(( $1 - 128 ))" ;;
+        1[3-9][0-9]|12[89]) printf 'killed by SIG%s (%s = 128+%s) — a crash, not a guard' \
+            "$(sig_name "$(( $1 - 128 ))")" "$1" "$(( $1 - 128 ))" ;;
         *) printf '' ;;
     esac
 }
 
+# --------------------------------------------------------------- selftest
+# What this proves, and what it deliberately does not. It measures the
+# MATCHERS this script decides with — not a guard, not the build. It exists
+# because #1120's flake was invisible to every check in here: the tool went
+# red on a green tree ~10% of the time under load, and the accusation it
+# printed was refuted by its own diagnostic two lines later.
+#
+# Four things, and the last is the one that makes the rest non-vacuous:
+#   1. the three matchers answer correctly on ordinary input (positive AND
+#      negative cases — a matcher that always says yes passes only the first);
+#   2. they answer correctly on a capture larger than the pipe buffer, which
+#      is where the construct they replaced fails;
+#   3. a deliberately WRONG matcher fails the same battery, so the battery is
+#      shown to discriminate rather than to accept anything;
+#   4. the construct they replaced — `printf | grep -q` under pipefail — is
+#      shown to report NO-MATCH on input the shell matcher matches. That is
+#      #1120 itself, reproduced deterministically. The pad grows until the
+#      writer must block, so the assertion does not depend on knowing any
+#      platform's pipe-buffer size.
+if [ "$SELFTEST" = "1" ]; then
+    echo "== strict_differential selftest (#1120: the matchers, not the guards) =="
+    st_n=0; st_fail=0
+    st_ok()  { st_n=$((st_n + 1)); printf '  ok    %s\n' "$1"; }
+    st_bad() { st_n=$((st_n + 1)); st_fail=$((st_fail + 1)); printf '  FAIL  %s\n' "$1"; }
+    st_is()  {   # <want-status> <got-status, pass $? here> <label>
+        if [ "$1" = "$2" ]; then st_ok "$3"; else st_bad "$3 (got $2, want $1)"; fi
+    }
+
+    hay="1
+Error line 1: abs: expected a number
+     1 | print of (abs of \"x\")"
+    str_has "$hay" "abs: expected";  st_is 0 $? "str_has finds a guard message in a capture"
+    str_has "$hay" "ceil: expected"; st_is 1 $? "str_has rejects a message that is not there"
+
+    lines="src/vm.c
+src/jit.c"
+    str_has_line "$lines" "src/jit.c"; st_is 0 $? "str_has_line finds a whole line"
+    str_has_line "$lines" "src/jit";   st_is 1 $? "str_has_line rejects a PREFIX of a line"
+    str_has_line "$lines" "vm.c";      st_is 1 $? "str_has_line rejects a SUFFIX of a line"
+
+    str_has_word " abs ceil " "ceil";  st_is 0 $? "str_has_word finds a name in a space list"
+    str_has_word " abs ceil " "ceil2"; st_is 1 $? "str_has_word rejects a longer name"
+    str_has_word " abs ceil " "eil";   st_is 1 $? "str_has_word rejects an infix"
+
+    # (2) and (4): ONE input, both forms, same needle.
+    # The capture has the SHAPE a real one has — the guard message on a
+    # complete first line, more text behind it — because both halves matter.
+    # The newline is what lets a line-oriented reader decide early (with no
+    # newline anywhere, grep buffers the whole input and the race disappears,
+    # which is how the first draft of this check passed at 4 MB); the bulk is
+    # what makes the writer block. Grow until the race shows, so nothing here
+    # depends on knowing a platform's pipe-buffer size.
+    _chunk='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+'
+    pad_len=262144; racy=0; big=""
+    while :; do
+        _pad="$_chunk"
+        while [ "${#_pad}" -lt "$pad_len" ]; do _pad="$_pad$_pad"; done
+        big="Error line 1: abs: expected a number
+$_pad"
+        printf '%s' "$big" | grep -qF "abs: expected"
+        racy=$?
+        [ "$racy" != "0" ] && break
+        [ "$pad_len" -ge 8388608 ] && break
+        pad_len=$((pad_len * 4))
+    done
+    str_has "$big" "abs: expected"
+    st_is 0 $? "str_has finds the needle in a ${#big}-byte capture"
+    if [ "$racy" != "0" ]; then
+        st_ok "the construct this replaced reports NO-MATCH (rc=$racy) on that same capture — #1120 reproduced"
+    else
+        st_bad "\`printf | grep -q\` still matched a ${#big}-byte capture, so this selftest
+        is no longer demonstrating the #1120 race. Raise the ceiling above this
+        platform's pipe-buffer size (or its reader stopped exiting early). The
+        shell matchers above are required either way — do NOT bring the
+        pipeline back on the strength of this line."
+    fi
+
+    # (3) the battery must be able to fail: a broken matcher must not pass it.
+    str_has_broken() { case "$1" in "$2"*) return 0 ;; esac; return 1 ; }
+    if str_has_broken "$hay" "abs: expected"; then
+        st_bad "a prefix-only matcher passed the positive case — the battery does not discriminate"
+    else
+        st_ok "a deliberately broken matcher fails this battery (the battery discriminates)"
+    fi
+
+    # Vacuity: a selftest that measured nothing is not a pass.
+    if [ "$st_n" -lt 11 ]; then
+        echo "  VACUOUS: only $st_n checks ran — the selftest itself broke"
+        st_fail=$((st_fail + 1))
+    fi
+    echo "  checks=$st_n failed=$st_fail"
+    verdict_printed=1
+    [ "$st_fail" = "0" ] && { echo "OK"; exit 0; }
+    echo "FAIL"; exit 1
+fi
+
+# ------------------------------------------------------ evidence for next time
+# #1120 stayed unnamed for a day because a red verdict carried 70 truncated
+# characters of the capture it disagreed with, and the failing run's own bytes
+# were gone by the time anyone read the log. Any run that finds SOMETHING now
+# writes the whole capture, its exit status, the pattern that was matched
+# against, and — the line that names a harness bug on sight — whether the
+# pattern is in those bytes after all. A green run writes nothing and leaves
+# no directory behind. The path carries the PID, so two suites in two
+# worktrees cannot land in the same place.
+EV_DIR="${EIGS_DIFF_EVIDENCE:-${TMPDIR:-/tmp}/eigs-strictdiff-evidence.$$}"
+ev_n=0
+record_evidence() {   # <kind> <name> <pattern> <capture: "rc\nbytes">
+    mkdir -p "$EV_DIR" 2>/dev/null || return 0
+    ev_n=$((ev_n + 1))
+    local safe="${2//[^A-Za-z0-9_.-]/_}" file _ev_why
+    file="$(printf '%s/%03d-%s-%s.txt' "$EV_DIR" "$ev_n" "$1" "$safe")"
+    {
+        printf 'kind:     %s\n' "$1"
+        printf 'name:     %s\n' "$2"
+        printf 'pattern:  %s\n' "$3"
+        printf 'exit:     %s\n' "${4%%$'\n'*}"
+        _ev_why="$(run_did_not_measure "${4%%$'\n'*}")"
+        if [ -n "$_ev_why" ]; then
+            printf 'status:   %s\n' "$_ev_why"
+            printf '          (a shell reports a signalled child and an exit(128+N) as\n'
+            printf '           the same number; the probe programs never call exit and\n'
+            printf '           the runtime exits 0/1/2, so this reads as a signal.)\n'
+        else
+            printf 'status:   ordinary exit — the process ran to completion\n'
+        fi
+        printf 'bytes:    %s (whole capture, including the exit-status line)\n' "${#4}"
+        if [ -n "$3" ] && str_has "$4" "$3"; then
+            printf 'recheck:  PRESENT — the pattern IS in the bytes below.\n'
+            if [ "$1" = "misattributed" ]; then
+                printf '          This verdict and its own evidence DISAGREE, so it is a\n'
+                printf '          HARNESS bug, not a finding about a guard. See #1120: a\n'
+                printf '          matcher that goes through a pipe under `set -o pipefail`\n'
+                printf '          reports no-match whenever the reader exits first.\n'
+            else
+                printf '          (Consistent with this verdict: the guard did name itself\n'
+                printf '           before whatever is recorded above happened to the run.)\n'
+            fi
+        elif [ -n "$3" ]; then
+            printf 'recheck:  ABSENT — the pattern is genuinely not in the bytes below.\n'
+        fi
+        printf -- '--- raw capture, verbatim (first line is the exit status) ---\n'
+        printf '%s\n' "$4"
+    } > "$file" 2>/dev/null
+}
+
 # rc is initialised ONCE, here, before any check can run. It used to be
 # assigned rc=0 down in the summary block — AFTER the cross-check section had
 # already set rc=1 — so a STALE UNPROBEABLE WAIVER finding printed and the
@@ -515,7 +767,7 @@ release_srcs="$(make print-SRC_V_release 2>/dev/null | tr ' ' '\n' | sed '/^$/d'
 variant_only=""
 if [ -n "$release_srcs" ]; then
     for f in src/*.c; do
-        printf '%s\n' "$release_srcs" | grep -qxF "$f" && continue
+        str_has_line "$release_srcs" "$f" && continue
         variant_only="$variant_only
 $(extract_guard_names "$f")"
     done
@@ -534,7 +786,21 @@ for v in $variant_only; do
     # rightmost nonzero status, and the probe program exits 1 by design when
     # the name is undefined — so `prog | grep -q` returned 1 on a successful
     # match and every absent builtin read as present.
-    _present_out="$("$NEW" "$TMP/present.eigs" 2>&1 || true)"
+    _present_out="$("$NEW" "$TMP/present.eigs" 2>&1)"; _present_rc=$?
+    # A presence check that did not RUN is not a "present" answer. Assuming
+    # present sends the probe in, where it dies "undefined variable" and is
+    # scored RAISED BY THE WRONG GUARD — an environment fact charged to a
+    # guard, which is the #1120 shape arriving by a second road. Same bucket
+    # as an unrun probe: named, red, and not a finding about the code.
+    _why="$(run_did_not_measure "$_present_rc")"
+    if [ -n "$_why" ]; then
+        n_unrun=$((n_unrun + 1))
+        unrun_list="$unrun_list
+    presence check for ${v%%/*} — $_why"
+        record_evidence unrun "presence:${v%%/*}" "" "$_present_rc
+$_present_out"
+        continue
+    fi
     case "$_present_out" in
         *"undefined variable"*) absent_here="$absent_here ${v%%/*}" ;;
     esac
@@ -572,7 +838,7 @@ while IFS='|' read -r who prog expect; do
             # A waived divergence still gets its strict half measured
             # below — waiving the default-path comparison must not quietly
             # drop the probe from the loudness count too.
-            if printf '%s\n' "$EXPECTED_DIVERGE" | grep -qxF "$who"; then
+            if str_has_line "$EXPECTED_DIVERGE" "$who"; then
                 n_waived=$((n_waived + 1))
                 waived_seen="$waived_seen $who"
             else
@@ -590,6 +856,7 @@ while IFS='|' read -r who prog expect; do
     why="$(run_did_not_measure "$s_rc")"
     if [ -n "$why" ]; then
         n_unrun=$((n_unrun + 1))
+        record_evidence unrun "$who" "$expect" "$s"
         unrun_list="$unrun_list
     $who — $why: $(printf '%s' "$s" | tr '\n' ' ' | cut -c1-70)"
     elif [ "$s_rc" != "0" ]; then
@@ -609,23 +876,27 @@ while IFS='|' read -r who prog expect; do
         # The FULL who, not its first component: the shared tensor helpers
         # are registered as "sqrt/exp/log/negative" and emit that verbatim,
         # so trimming at the slash made the matcher miss its own message.
-        # A shell substring match, NOT `printf ... | grep -q`: under
-        # `set -o pipefail` that pipe is a race — grep -q exits on its first
-        # match and closes the pipe, and if the multi-line error text (message
-        # + source excerpt + caret) is still being written the writer takes
-        # SIGPIPE, the pipeline reports failure, and a correctly attributed
-        # raise is scored MISATTRIBUTED. Fired once in 6 runs under load
-        # (text_builder_to_string, 2026-09-06) and made [99s] flake red.
-        case "$s" in
-            *"$expect"*) n_raise=$((n_raise + 1)) ;;
-            *)
+        # str_has, never a pipeline. This was `printf ... | grep -qF`, and
+        # under `set -o pipefail` that is the #1120 race: grep -q exits on its
+        # first match and closes the pipe, the still-writing printf takes
+        # SIGPIPE and exits 141, pipefail reports 141 — no match — while grep
+        # itself returned 0. The probe was then scored MISATTRIBUTED with a
+        # diagnostic quoting the message the matcher had just matched.
+        # Measured with the pipe form restored here: 18 red runs in 186 under
+        # load, over 18 different probes. Nothing about this decision may go
+        # through a pipe; see the matcher block near the top, and --selftest,
+        # which reproduces the race deterministically.
+        if str_has "$s" "$expect"; then
+            n_raise=$((n_raise + 1))
+        else
             n_misattr=$((n_misattr + 1))
+            record_evidence misattributed "$who" "$expect" "$s"
             misattr_list="$misattr_list
     $who — raised, but not by its own guard: $(printf '%s' "$s" | tr '\n' ' ' | cut -c1-70)"
-            ;;
-        esac
+        fi
     else
         n_silent=$((n_silent + 1))
+        record_evidence silent "$who" "$expect" "$s"
         silent_list="$silent_list
     $who — still silent under EIGS_STRICT=1: $(printf '%s' "$s" | tr '\n' ' ' | cut -c1-70)"
     fi
@@ -639,12 +910,14 @@ while IFS='|' read -r label prog; do
     why="$(run_did_not_measure "${s%%$'\n'*}")"
     if [ -n "$why" ]; then
         n_unrun=$((n_unrun + 1))
+        record_evidence unrun "pin:$label" "" "$s"
         unrun_list="$unrun_list
     pin: $label — $why"
     elif [ "${s%%$'\n'*}" = "0" ]; then
         n_pin_ok=$((n_pin_ok + 1))
     else
         n_pin_broke=$((n_pin_broke + 1))
+        record_evidence pin-broken "$label" "" "$s"
         pin_list="$pin_list
     $label — strict RAISED on a documented answer: $(printf '%s' "$s" | tr '\n' ' ' | cut -c1-70)"
     fi
@@ -677,7 +950,9 @@ if [ "${1:-}" = "--sweep" ] || [ "${2:-}" = "--sweep" ]; then
     echo "== wrong-typed-argument sweep (discovery, not a gate) =="
     quiet=0; loud=0; skipped=0
     for b in $("$NEW" --api --json 2>/dev/null | python3 -c 'import json,sys; d=json.load(sys.stdin); print("\n".join(d.get("builtins",[])))'); do
-        if printf '%s' "$b" | grep -qE "$SKIP"; then skipped=$((skipped+1)); continue; fi
+        # bash's own regex match: no fork, no pipe. $SKIP is deliberately
+        # unquoted here — quoting it inside [[ =~ ]] makes it a literal.
+        if [[ "$b" =~ $SKIP ]]; then skipped=$((skipped+1)); continue; fi
         # A DICT is the probe value: it is a wrong argument for very nearly
         # every builtin in the surface, where a string is the RIGHT argument
         # for dozens (sha256, read_text, file_exists...) and those all read as
@@ -735,13 +1010,17 @@ probed="$(printf '%s\n' "$PROBES" | cut -d'|' -f1 | sed '/^$/d' | sort -u)"
 
 # Names absent from THIS build (computed above by execution) are excused for
 # this run only — never by a waiver anyone maintains.
+# The `grep -vxF` below is a SET DIFFERENCE, not a verdict, and it is the
+# exception the #1120 rule allows: `-v` has no early exit, so it consumes its
+# input to EOF and cannot SIGPIPE the writer. The same is true of the `grep -c`
+# in the summary. Anything that decides pass/fail uses str_has* instead.
 missing="$(comm -23 <(printf '%s\n' "$guarded") <(printf '%s\n' "$probed") \
     | grep -vxF -f <(printf '%s\n' $UNPROBEABLE $absent_here) || true)"
 stale="$(comm -13 <(printf '%s\n' "$guarded") <(printf '%s\n' "$probed"))"
 # A waived-as-unprobeable name that is no longer guarded at all is a stale
 # waiver: the guard it excused is gone.
 for u in $UNPROBEABLE; do
-    printf '%s\n' "$guarded" | grep -qxF "$u" || {
+    str_has_line "$guarded" "$u" || {
         echo "  STALE UNPROBEABLE WAIVER: $u is waived but carries no guard"; rc=1; }
 done
 
@@ -795,7 +1074,7 @@ fi
 # other, and neither is the instability check.
 if [ -n "$BASE" ]; then
     for w in $EXPECTED_DIVERGE_FIXED; do
-        wprog="$(printf '%s\n' "$PROBES" | grep -F "$w|" | head -1 | cut -d'|' -f2)"
+        wprog="$(probe_prog_for "$w")"
         [ -z "$wprog" ] && continue
         printf '%b\n' "$wprog" > "$TMP/w.eigs"
         probe_builtin_present "$w" || { echo "  waiver not exercised: $w is not in this build"; continue; }
@@ -820,7 +1099,7 @@ fi
 
 if [ -n "$BASE" ]; then
     for w in $EXPECTED_DIVERGE_UNSTABLE; do
-        wprog="$(printf '%s\n' "$PROBES" | grep -F "$w|" | head -1 | cut -d'|' -f2)"
+        wprog="$(probe_prog_for "$w")"
         if [ -n "$wprog" ]; then
             printf '%b\n' "$wprog" > "$TMP/w.eigs"
             r1="$(run_capture "$BASE" - "$TMP/w.eigs")"
@@ -845,7 +1124,7 @@ fi
 # starts covering something nobody agreed to.
 if [ -n "$BASE" ]; then
     for w in $EXPECTED_DIVERGE_UNSTABLE; do
-        if ! printf '%s' "$waived_seen" | grep -qw "$w"; then
+        if ! str_has_word "$waived_seen" "$w"; then
             echo "  SPENT WAIVER: $w is declared divergent but did not differ."
             echo "                Remove the entry. A waiver is PR-scoped: it is live"
             echo "                only while the parent lacks the change, and inert the"
@@ -858,7 +1137,7 @@ if [ -n "$BASE" ]; then
     done
     for w in $EXPECTED_DIVERGE_FIXED; do
         probe_builtin_present "$w" || continue
-        if ! printf '%s' "$waived_seen" | grep -qw "$w"; then
+        if ! str_has_word "$waived_seen" "$w"; then
             echo "  SPENT WAIVER: $w is declared divergent but did not differ."
             echo "                Either the probe no longer reaches the guard, or —"
             echo "                far more likely — the change LANDED and the baseline"
@@ -887,6 +1166,49 @@ if [ "$NO_BASELINE" = 1 ]; then
     echo "        of the parent commit — that half is the safety claim."
 fi
 
+# Did the subject hold still? Checked LAST, so it speaks about the whole run.
+# A changed binary is not a finding about a guard, and it invalidates every row
+# above it — so it is loud, it is red, and it says which reading to take.
+if [ -n "$FP_NEW_START" ]; then
+    _fp_now="$(bin_fingerprint "$NEW")"
+    if [ "$_fp_now" != "$FP_NEW_START" ]; then
+        echo "  BINARY CHANGED UNDER THIS RUN: $NEW"
+        echo "                 at start: $FP_NEW_START"
+        echo "                 at end:   $_fp_now"
+        echo "           Probes before and after the change measured DIFFERENT"
+        echo "           binaries, so nothing above is a finding about a guard."
+        echo "           Something rebuilt or re-pointed the binary mid-run"
+        echo "           (src/eigenscript is a hard link to build/<variant>/, so"
+        echo "           any 'make' in this worktree does it). Re-run when the"
+        echo "           tree is quiet; nothing here is retried."
+        rc=1
+    fi
+fi
+if [ -n "$FP_BASE_START" ]; then
+    _fp_now="$(bin_fingerprint "$BASE")"
+    if [ "$_fp_now" != "$FP_BASE_START" ]; then
+        echo "  BASELINE BINARY CHANGED UNDER THIS RUN: $BASE"
+        echo "                 at start: $FP_BASE_START"
+        echo "                 at end:   $_fp_now"
+        echo "           The identical-when-off half compared against a moving"
+        echo "           reference; nothing above is a finding about a guard."
+        rc=1
+    fi
+fi
+
+# The evidence a red run leaves behind. #1120 could not be named from the log
+# because the log carried 70 truncated characters of a capture that was already
+# gone. It is deliberately NOT cleaned up: a red run's bytes outlive the run.
+if [ "$ev_n" -gt 0 ]; then
+    echo "  evidence: $ev_n capture(s) kept, whole and verbatim, under"
+    echo "            $EV_DIR"
+    echo "            Each names the pattern it was matched against and says"
+    echo "            whether that pattern is in the bytes after all. A file"
+    echo "            saying 'recheck: PRESENT' is a HARNESS bug (#1120), not"
+    echo "            a finding about a guard. Set EIGS_DIFF_EVIDENCE to place"
+    echo "            them somewhere a CI run will keep."
+fi
+
 verdict_printed=1
 [ "$rc" = 0 ] && echo "OK" || echo "FAIL"
 exit $rc

From ee36f77a4e651eccfa0f3b532f348cda0b75b173 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 01:41:42 +0000
Subject: [PATCH 30/39] changelog: the #1120 strict-differential entry

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 CHANGELOG.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3186f09f..2d078268 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -106,6 +106,27 @@ All notable changes to EigenScript are documented here.
 
 ### Fixed
 
+- **`tools/strict_differential.sh` (suite section `[99s]`) no longer flakes red
+  on a green tree under load (#1120).** Its verdicts were decided with
+  `printf … | grep -q …` under `set -o pipefail`, which is a race rather than a
+  test: `grep -q` exits the moment it matches and closes the pipe, the still-
+  writing `printf` takes SIGPIPE and exits 141, and pipefail reports the
+  pipeline as failed while grep itself reported a match. A probe was therefore
+  scored "raised by the wrong guard" while the diagnostic printed beside it
+  contained that guard's own message. Measured with the pipe form in place: 18
+  red runs in 186 under load, spread over 18 different probes; 0 in 300 without
+  it. Every verdict site now matches with the shell itself, no fork and no pipe,
+  and a new `--selftest` that `[99s]` runs before the differential pins those
+  matchers and reproduces the race deterministically. Alongside it: a
+  variant-only presence check that did not run is reported as an unrun probe
+  instead of being assumed present and charged to a guard; the tool fingerprints
+  its subject binary at both ends, so a `make` that re-points `src/eigenscript`
+  mid-run says so instead of looking like a broken guard; signal deaths are
+  named rather than left as a number; and any run that finds something writes
+  each finding's whole capture, exit status and matched pattern to an evidence
+  directory it names, including whether the pattern is in those bytes after
+  all — which labels a self-contradicting verdict as a harness bug on sight.
+
 - **`--lint` leaked the parsed `eigs.json` on every run inside a project whose
   manifest has any nested value (#1121).** `"deps": {}` is enough, and it is in
   the manifest every repo in the fleet ships. Dropping a reference to a list or

From 7ac6fad90a06ac2297a7a7b17d48c8b39e47af3a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 02:35:15 +0000
Subject: [PATCH 31/39] strict: the Phase D guards leak their own allocation;
 enrollment falls back to `find` under load; the waiver mechanism goes (#971
 round 2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three findings on the round-1 commit, landed together because the third is what
makes the first two visible. Reconciled onto the integration, which already
carries #1120's rewrite of the same tool.

**1. A leak on every new strict-raise path.** `STRICT_REQUIRE` expands to
`rt_error(...); return make_null();`, so it must sit BEFORE anything the
function has allocated and still owns. Three Phase D guards sat one line BELOW
`Value *out = make_list(128);`:

    $ EIGS_STRICT=1 ./src/eigenscript -e 'print of (scan_ints of 42)'   # ASan
    Error line 1: scan_ints: expected a string or [string, comment_marker]
    SUMMARY: AddressSanitizer: 1096 byte(s) leaked in 2 allocation(s)

identically for `scan_tokens` and `scan_int_tokens`. `str` is computed above
both lines, so the fix is a pure reorder and the soft path is untouched — the
flag-off answer is still an empty list. The placement rule is now stated at
`STRICT_REQUIRE`'s definition, with the alternative for functions whose inputs
do not allow the reorder: free explicitly first, as `builtin_write_bytes` does
with its raw buffer.

**2. Nothing caught it, and that is the more important half.** A strict raise
ALREADY exits non-zero, so LeakSanitizer's exit does not change the process
status and a leaking guard is indistinguishable from a working one.
`tests/test_strict_math.sh` drives this exact path and reported 85/85 PASS
under ASan while three of its rows leaked. The rows are now leak-visible:
`leak_clean` reads the LeakSanitizer text out of the output the assertion
already captures, so every strict raise in the file is leak-gated whenever an
ASan build runs it, and it is a no-op under release. `scan_ints` had a row; its
two siblings had none and leaked with no coverage at all, so SM85-SM88 add
them. 85 -> 89 checks.

**3. The `[99i]` / `[99p]` flake, root-caused.** `werror_switch_check.sh` chose
its script-enrollment population by whether `git ls-files` produced output, and
fell back to `find` when it did not — including when the fork lost a race for
memory on a loaded box. `find` then enumerates UNTRACKED files: build output,
scratch dirs, another run's extracted fault tree. Any of those carrying a
compile line is reported as an unenrolled script, so the gate goes red naming a
file that is not in the repository. That is the shape observed twice tonight:
the audit half printed its own `gate OK` and the section still failed, because
the self-test half tripped this. The fallback is now chosen by WHERE WE ARE —
inside a work tree `git ls-files` is authoritative and an empty result is an
ERROR; outside one (the `git archive | tar -x` fault trees, which are
extractions and not repositories) `find` is correct and is the only option.

**4. The divergence-waiver mechanism is deleted.** `differing-when-off: 0` is
the single claim this tool exists to make, and an exemption path is that claim
with a hole in it. Both of the mechanism's failure modes had already been paid
for: waivers are PR-scoped with nothing enforcing it (#1016 — `sign_extend`'s
waiver outlived its PR and the documented pre-land command returned FAIL on a
clean tree for every run between #1015 and #1016, while the half it measures
was green), and a waiver hides exactly what the tool is for (#971 almost kept
one for `matmul`'s buffer path). The identical-when-off half is exercised the
other way instead: put a default-path change back into a converted site and it
reports `differing: 1` and FAILs, with no list that could absorb it.

RECONCILIATION with #1120. That rewrite converted every `grep -q` verdict site
to a fork-free matcher, including the expected-divergence and spent-waiver
lookups. Two of those sites are inside the code this commit deletes, so the
deletion wins there and #1120's matchers stand everywhere else. Both halves
were then exercised together.

MEASURED, after:

    scan_ints / scan_tokens / scan_int_tokens under ASan+EIGS_STRICT   all CLEAN
    tests/test_strict_math.sh under ASan                               89 passed, 0 failed
    tools/strict_differential.sh --selftest                            checks=11 failed=0, OK
    tools/strict_differential.sh --no-baseline                         raises-under-strict: 99
                                                                       silent: 0  misattributed: 0
                                                                       answer-pins held: 31  broken: 0

PLANTED FAULT, executed on this tree: moving the `scan_tokens` guard back below
its `make_list` and rebuilding gives

    FAIL: SM85 strict scan_tokens(num) raises (LEAKED on this path:
          SUMMARY: AddressSanitizer: 1096 byte(s) leaked in 2 allocation(s).)
    STRICT: 88 passed, 1 failed

— one row, naming the byte count. Restored: 89 passed, 0 failed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 src/builtins.c               |  24 +++--
 src/eigenscript.h            |  13 +++
 tests/run_all_tests.sh       |  22 +++-
 tests/test_strict_math.sh    |  38 ++++++-
 tools/strict_differential.sh | 192 +++++++----------------------------
 tools/werror_switch_check.sh |  70 ++++++++++---
 6 files changed, 182 insertions(+), 177 deletions(-)

diff --git a/src/builtins.c b/src/builtins.c
index 06fafd82..374ba9e3 100644
--- a/src/builtins.c
+++ b/src/builtins.c
@@ -1744,10 +1744,14 @@ Value* builtin_scan_ints(Value *arg) {
         }
     }
 
-    Value *out = make_list(128);
     /* #971 Phase D: no string in the argument — a wrong type read as
-     * "no tokens". Coercion shape: raise under strict, unchanged otherwise. */
+     * "no tokens". Coercion shape: raise under strict, unchanged otherwise.
+     * The guard sits ABOVE the make_list: STRICT_REQUIRE returns, so a list
+     * allocated first would be abandoned by the raise (see write_bytes in
+     * builtins_host.c, which frees instead because its buffer is raw). */
     STRICT_REQUIRE(!str, "scan_ints", "a string or [string, comment_marker]");
+
+    Value *out = make_list(128);
     if (!str) return out;
 
     const char *p = str;
@@ -1845,10 +1849,14 @@ Value* builtin_scan_tokens(Value *arg) {
         }
     }
 
-    Value *out = make_list(128);
     /* #971 Phase D: no string in the argument — a wrong type read as
-     * "no tokens". Coercion shape: raise under strict, unchanged otherwise. */
+     * "no tokens". Coercion shape: raise under strict, unchanged otherwise.
+     * The guard sits ABOVE the make_list: STRICT_REQUIRE returns, so a list
+     * allocated first would be abandoned by the raise (see write_bytes in
+     * builtins_host.c, which frees instead because its buffer is raw). */
     STRICT_REQUIRE(!str, "scan_tokens", "a string or [string, comment_marker]");
+
+    Value *out = make_list(128);
     if (!str) return out;
 
     const char *base = str;
@@ -1930,10 +1938,14 @@ Value* builtin_scan_int_tokens(Value *arg) {
         }
     }
 
-    Value *out = make_list(128);
     /* #971 Phase D: no string in the argument — a wrong type read as
-     * "no tokens". Coercion shape: raise under strict, unchanged otherwise. */
+     * "no tokens". Coercion shape: raise under strict, unchanged otherwise.
+     * The guard sits ABOVE the make_list: STRICT_REQUIRE returns, so a list
+     * allocated first would be abandoned by the raise (see write_bytes in
+     * builtins_host.c, which frees instead because its buffer is raw). */
     STRICT_REQUIRE(!str, "scan_int_tokens", "a string or [string, comment_marker]");
+
+    Value *out = make_list(128);
     if (!str) return out;
 
     const char *base = str;
diff --git a/src/eigenscript.h b/src/eigenscript.h
index 5a5b0b92..2d5b814f 100644
--- a/src/eigenscript.h
+++ b/src/eigenscript.h
@@ -1110,6 +1110,19 @@ extern __thread EigsThread *eigs_current;
  * no `return make_num(0)` to enumerate. Found by the differential instead
  * (a probe that stayed silent under strict), which is why that harness
  * exists as well as the classifier. */
+/* PLACEMENT IS LOAD-BEARING: this RETURNS, so it must sit BEFORE anything the
+ * function has allocated and still owns, or the raise abandons it. Put the
+ * guard above the allocation where the inputs allow it (the three scan_*
+ * builtins each sat one line below a `make_list(128)` and leaked 1096 bytes
+ * per strict raise); where they do not, free explicitly first, as
+ * builtin_write_bytes does with its raw buffer.
+ *
+ * Nothing about the ordinary run catches that mistake: a strict raise ALREADY
+ * exits non-zero, so LeakSanitizer does not change the process status and a
+ * leaking guard is indistinguishable from an expected raise. The check that
+ * does catch it is `leak_clean` in tests/test_strict_math.sh, which reads the
+ * LeakSanitizer text out of the output it already captures — so every strict
+ * raise needs a row there, and a new guard without one is unguarded. */
 #define STRICT_REQUIRE(cond, who, want)                                       \
     do {                                                                      \
         if (g_strict && (cond)) {                                             \
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index ad399245..2fc7ee65 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -6651,12 +6651,30 @@ echo ""
 # failure, not a silent pass).
 echo "[99i] werror-switch compile-line gate (#817/#835)"
 TOTAL=$((TOTAL + 1))
-if bash "$TESTS_DIR/../tools/werror_switch_check.sh" && bash "$TESTS_DIR/../tools/werror_switch_check.sh" --selftest >/dev/null; then
+# The two halves are reported SEPARATELY (#971 round 2). They used to be one
+# `a && b >/dev/null` chain, which made a self-test failure unattributable:
+# the audit half prints its own "gate OK" line, so a log showing OK followed
+# by this section's FAIL looked self-contradictory, and the self-test's
+# diagnostics — the only thing that says WHICH planted fault shape stopped
+# being caught — had gone to /dev/null. Observed on this box under load
+# (a full-suite run where the audit printed OK and the section still failed);
+# with the output kept, the next occurrence names its own cause.
+werror_audit_rc=0
+bash "$TESTS_DIR/../tools/werror_switch_check.sh" || werror_audit_rc=$?
+werror_selftest_out=$(bash "$TESTS_DIR/../tools/werror_switch_check.sh" --selftest 2>&1)
+werror_selftest_rc=$?
+if [ "$werror_audit_rc" -eq 0 ] && [ "$werror_selftest_rc" -eq 0 ]; then
     PASS=$((PASS + 1))
     echo "  PASS: every dry-run + audited-script compile line carries -Werror=switch (gate self-test green)"
 else
     FAIL=$((FAIL + 1))
-    echo "  FAIL: a compile line lacks -Werror=switch, or the gate self-test broke (see lines above)"
+    if [ "$werror_audit_rc" -ne 0 ]; then
+        echo "  FAIL: a compile line lacks -Werror=switch (audit exit $werror_audit_rc; see lines above)"
+    fi
+    if [ "$werror_selftest_rc" -ne 0 ]; then
+        echo "  FAIL: the gate self-test broke (--selftest exit $werror_selftest_rc); its output:"
+        printf '%s\n' "$werror_selftest_out" | sed 's/^/      /'
+    fi
 fi
 echo ""
 
diff --git a/tests/test_strict_math.sh b/tests/test_strict_math.sh
index 059a9fa2..87136cfd 100755
--- a/tests/test_strict_math.sh
+++ b/tests/test_strict_math.sh
@@ -23,12 +23,32 @@ fi
 TMP=$(mktemp /tmp/eigs_strict_XXXXXX.eigs)
 trap 'rm -f "$TMP"' EXIT
 
+# LEAK-VISIBLE ROWS (#971 round 2). Every row captures stdout+stderr together,
+# so when this file is driven by an ASan build with ASAN_OPTIONS=detect_leaks=1
+# a LeakSanitizer report lands in "$out" and `leak_clean` turns the row RED.
+# This exists because a strict raise ALREADY exits non-zero, so LeakSanitizer
+# does not change the process status and a leaking guard looks exactly like an
+# ordinary expected raise: three guards (scan_ints / scan_tokens /
+# scan_int_tokens) leaked 1096 bytes each while all 85 rows reported PASS.
+# Under a release build there is no such output and the check is a no-op, so
+# the gate costs nothing and cannot go vacuous silently: it reads the same
+# text the assertion already reads.
+#
 # NOTE: <expect-substr> must never be the empty string — `grep -qF ""` matches
 # any output, so an empty expectation silently degrades the row to an exit-code
 # check. Rows asserting an EMPTY result wrap it (`f"[{...}]"` against "[]") so
 # the emptiness is something the assertion can actually see.
 #
 # run <name> <env: unset|0|1> <expect-exit 0|1> <expect-substr> <program>
+# leak_clean <captured-output>: 1 unless LeakSanitizer reported on this run.
+# Only ever non-empty under an ASan build with detect_leaks=1.
+leak_clean() {
+    case "$1" in
+        *"LeakSanitizer: detected memory leaks"*) return 1 ;;
+        *) return 0 ;;
+    esac
+}
+
 run() {
     local name="$1" env="$2" xexit="$3" substr="$4" prog="$5"
     printf '%s\n' "$prog" > "$TMP"
@@ -40,7 +60,9 @@ run() {
     local exit_ok=0
     if [ "$xexit" = "0" ] && [ "$rc" = "0" ]; then exit_ok=1; fi
     if [ "$xexit" = "1" ] && [ "$rc" != "0" ]; then exit_ok=1; fi
-    if [ "$exit_ok" = "1" ] && echo "$out" | grep -qF -- "$substr"; then
+    if ! leak_clean "$out"; then
+        fail "$name" "LEAKED on this path: $(echo "$out" | grep -F 'SUMMARY: AddressSanitizer')"
+    elif [ "$exit_ok" = "1" ] && echo "$out" | grep -qF -- "$substr"; then
         ok "$name"
     else
         fail "$name" "rc=$rc out='$out'"
@@ -54,7 +76,9 @@ run_jitoff() {
     printf '%s\n' "$prog" > "$TMP"
     local out rc
     out=$(EIGS_STRICT=1 EIGS_JIT_OFF=1 "$EIGS" "$TMP" 2>&1); rc=$?
-    if [ "$rc" != "0" ] && echo "$out" | grep -qF -- "$substr"; then
+    if ! leak_clean "$out"; then
+        fail "$name" "LEAKED on this path: $(echo "$out" | grep -F 'SUMMARY: AddressSanitizer')"
+    elif [ "$rc" != "0" ] && echo "$out" | grep -qF -- "$substr"; then
         ok "$name"
     else
         fail "$name" "rc=$rc out='$out'"
@@ -281,5 +305,15 @@ run "SM82 strict tokenize_ids(num) raises"              1 1 "tokenize_ids: expec
 run "SM83 strict random_hex(str) raises"                1 1 "random_hex: expected" 'print of (random_hex of "x")'
 run "SM84 strict: random_hex of 0 is still empty"       1 0 "[]" 'print of f"[{random_hex of 0}]"'
 
+# SM85-SM88 (#971 round 2): scan_ints had a row (SM71); its two siblings had
+# none, so both leaked with no coverage at all. All three guards sit above the
+# make_list they used to follow, and these rows are the leak-visible ones (the
+# raise itself already exits 1, so only `leak_clean` can see a regression).
+run "SM85 strict scan_tokens(num) raises"               1 1 "scan_tokens: expected"     'print of (scan_tokens of 42)'
+run "SM86 strict scan_int_tokens(num) raises"           1 1 "scan_int_tokens: expected" 'print of (scan_int_tokens of 42)'
+# Flag-off pins: the wrong type still reads as "no tokens" -> an empty list.
+run "SM87 default scan_tokens(num) is still []"     unset 0 "[]" 'print of f"[{scan_tokens of 42}]"'
+run "SM88 default scan_int_tokens(num) is still []" unset 0 "[]" 'print of f"[{scan_int_tokens of 42}]"'
+
 echo "STRICT: $PASS passed, $FAIL failed"
 [ "$FAIL" -eq 0 ]
diff --git a/tools/strict_differential.sh b/tools/strict_differential.sh
index e3a4bad4..8dfc7d2a 100755
--- a/tools/strict_differential.sh
+++ b/tools/strict_differential.sh
@@ -73,10 +73,10 @@ cd "$(cd "$(dirname "$0")/.." && pwd)"
 # loudness detector must fire, because that binary lacks the guards this
 # tree added. Measured 2026-09-07 against the v0.43.0 build:
 # `raises-under-strict: 77 silent: 21` and FAIL, where this tree scores
-# 98/0 and OK. (The stale-waiver check is not exercised that way while both
-# waiver lists are empty, which they are — see the waiver block below. It is
-# exercised by ADDING a waiver for a probe that does not diverge, which is
-# what it exists to catch.) A harness that has never failed has not been
+# 98/0 and OK. The identical-when-off half is exercised the other way: put a
+# default-path change back into a converted site and it reports
+# `differing: 1` and FAILs — there is no exemption list that could absorb it
+# (see the waiver block below). A harness that has never failed has not been
 # shown to work.
 NEW="${EIGS_DIFF_NEW:-./src/eigenscript}"
 BASE="${1:-}"
@@ -452,56 +452,40 @@ print of (len of (random_hex of 4))
 EOF
 )
 
-# ---------------------------------------------------- divergence waivers
-# A waiver here says: "this probe's DEFAULT-path answer legitimately changes,
-# and here is why." It is compared against a build of the PARENT COMMIT.
+# --------------------------------------- no divergence-waiver mechanism
+# There is deliberately NO way to exempt a probe from the default-path
+# comparison. `differing-when-off: 0` is the single claim this tool exists to
+# make, and an exemption path is that claim with a hole in it.
 #
-# THEY ARE PR-SCOPED, AND THAT IS THE WHOLE LIFECYCLE. An entry is live for
-# exactly one review — while the change is unmerged and the parent still
-# lacks it. The moment it lands, the parent HAS the fix, the probe stops
-# diverging, and the entry is SPENT: inert, and pure debris. So a waiver is
-# added with the PR that needs it and removed with the next one.
+# There used to be one (EXPECTED_DIVERGE_FIXED / _UNSTABLE), and it is gone
+# because both of its failure modes were paid for:
 #
-# Bought (#1016). `sign_extend`'s waiver was written for #971 Phase B and left
-# behind when #1015 landed. From that commit on, the "baseline" contained the
-# guard, so `sign_extend of ["x", 8]` answered a deterministic 0 on BOTH
-# sides — and the waiver's proof, which requires the BASELINE to be unstable,
-# could never hold again. The documented pre-land command
-# (`bash tools/strict_differential.sh <parent-build>`) therefore returned
-# FAIL on a clean tree for every run between #1015 and #1016, while the half
-# it exists to measure was green: `identical-when-off: 63 differing: 0`.
-# A gate that always fails is ignored exactly as fast as one that never fires.
-# The eleven #1007 waivers were added the same day and would have started
-# rotting the moment #1018 merged; the STALE WAIVER check below caught all
-# eleven on the first post-merge run, which is what it is for.
+#   Waivers are PR-scoped, and nothing enforces that. An entry is live for
+#   exactly one review — while the change is unmerged and the parent still
+#   lacks it. The moment it lands, the parent HAS the fix, the probe stops
+#   diverging, and the entry is SPENT: inert, pure debris. Bought (#1016):
+#   `sign_extend`'s waiver was written for #971 Phase B and left behind when
+#   #1015 landed, so the documented pre-land command returned FAIL on a clean
+#   tree for every run between #1015 and #1016 while the half it measures was
+#   green. A gate that always fails is ignored as fast as one that never fires.
 #
-# CI never evaluates any of this: it runs --no-baseline, which skips every
-# `[ -n "$BASE" ]` block. So an entry left here is invisible until the next
-# person runs the two-binary mode by hand and is met with someone else's
-# expired paperwork.
+#   And a waiver hides exactly what the tool is for. #971 (NaN enumeration)
+#   ALMOST kept one. matmul's BUFFER path stores the kernel's raw inf-inf NaN,
+#   and a raw NaN in a buffer is not a number the program can see — its bit
+#   pattern is a NaN-boxed slot tag, so `r[0]` reads back as `null`
+#   (0xFFF8... is SLOT_NULL_BITS). Collapsing it to 0 the way the list path
+#   does looked like a free fix; it was written, waived, and proven. But a
+#   PROVEN waiver is still a hole in "with the flag off, nothing changed", and
+#   that claim is worth more than the incidental fix. The strict half now
+#   raises through STRICT_DOMAIN, which cannot touch the soft path; `r[0]`
+#   still reads `null` with the flag off; the pre-existing `null` read is
+#   recorded in ROADMAP.md as its own change with its own differential.
 #
-# Currently empty, deliberately. Add an entry ONLY alongside the change that
-# needs it, in the group whose proof matches the claim being made:
-#   EXPECTED_DIVERGE_UNSTABLE — "the old answer was undefined and not even
-#     stable across runs" (proof: two baseline runs must DIFFER)
-#   EXPECTED_DIVERGE_FIXED    — "the old answer was stable and wrong"
-#     (proof: two baseline runs must AGREE, and the new answer must be 0)
-# #971 (NaN enumeration) ALMOST added one, and the second look is the reason
-# both lists are empty. matmul's BUFFER path stores the kernel's raw inf-inf
-# NaN, and a raw NaN in a buffer is not a number the program can see — its bit
-# pattern is a NaN-boxed slot tag, so `r[0]` reads back as `null` (0xFFF8...
-# is SLOT_NULL_BITS). Collapsing it to 0 the way the list path does looked
-# like a free fix, and it was written, waived here as EXPECTED_DIVERGE_FIXED,
-# and proven. But a proven waiver is still a hole in the ONE claim this whole
-# tool exists to make — "with the flag off, nothing changed" — and that claim
-# is worth more than the incidental fix. The strict half now raises through
-# STRICT_DOMAIN, which cannot touch the soft path, `r[0]` still reads `null`
-# with the flag off, and the pre-existing `null` read is recorded in
-# ROADMAP.md as its own change with its own differential. Nothing is waived.
-EXPECTED_DIVERGE_UNSTABLE=""
-EXPECTED_DIVERGE_FIXED=""
-EXPECTED_DIVERGE="$EXPECTED_DIVERGE_UNSTABLE
-$EXPECTED_DIVERGE_FIXED"
+# So: if a future change genuinely must move a default-path answer, it is a
+# SEMANTICS CHANGE, not a waiver. It belongs in docs/SPEC.md + COMPARISON.md +
+# BUILTINS.md with a fixture pinning the new behaviour and a CHANGELOG line
+# that says so plainly — and this tool should go red until that is done.
+
 
 # Guards that CANNOT be probed, named with the reason. Without this list they
 # would sit in "GUARDED BUT UNPROBED" forever and train the reader to ignore
@@ -718,8 +702,7 @@ record_evidence() {   # <kind> <name> <pattern> <capture: "rc\nbytes">
 # false green this repo keeps a hook for, and it was living in the tool built
 # to prevent them. Do not reset rc anywhere below.
 rc=0
-n_probe=0 n_ident=0 n_differ=0 n_raise=0 n_silent=0 n_waived=0
-waived_seen=""
+n_probe=0 n_ident=0 n_differ=0 n_raise=0 n_silent=0
 n_pin=0 n_pin_ok=0 n_pin_broke=0 n_misattr=0
 n_unrun=0 unrun_list=""
 differ_list="" silent_list="" pin_list="" misattr_list=""
@@ -835,19 +818,11 @@ while IFS='|' read -r who prog expect; do
         if [ "$a" = "$b" ]; then
             n_ident=$((n_ident + 1))
         else
-            # A waived divergence still gets its strict half measured
-            # below — waiving the default-path comparison must not quietly
-            # drop the probe from the loudness count too.
-            if str_has_line "$EXPECTED_DIVERGE" "$who"; then
-                n_waived=$((n_waived + 1))
-                waived_seen="$waived_seen $who"
-            else
-                n_differ=$((n_differ + 1))
-                differ_list="$differ_list
+            n_differ=$((n_differ + 1))
+            differ_list="$differ_list
     $who
       baseline: $(printf '%s' "$a" | tr '\n' ' ' | cut -c1-90)
       new     : $(printf '%s' "$b" | tr '\n' ' ' | cut -c1-90)"
-            fi
         fi
     fi
 
@@ -1032,7 +1007,7 @@ if [ "$n_skipped" -gt 0 ]; then
     echo "  probes skipped (builtin not in this build): $n_skipped —$skipped_list"
 fi
 if [ -n "$BASE" ]; then
-    echo "  identical-when-off: $n_ident   differing: $n_differ   waived: $n_waived"
+    echo "  identical-when-off: $n_ident   differing: $n_differ"
 else
     echo "  identical-when-off: SKIPPED (no baseline binary given)"
 fi
@@ -1057,97 +1032,6 @@ fi
 [ -n "$missing" ]     && { echo "  GUARDED BUT UNPROBED:"; printf '    %s\n' $missing; rc=1; }
 [ -n "$stale" ]       && { echo "  PROBED BUT NO LONGER GUARDED (stale probe):"; printf '    %s\n' $stale; rc=1; }
 
-# The waiver is ASSERTED, not asserted-about. sign_extend's justification is
-# "the baseline behaviour was undefined, and not even stable across runs", so
-# the harness proves that half rather than asking to be believed: run the
-# BASELINE twice on the same probe and require the two results to differ. If
-# they ever stop differing, the UB claim is wrong and the waiver must be
-# re-argued. (This probe is therefore deliberately kept OUT of the identity
-# comparison — a nondeterministic fixture does not belong in a differential
-# as an ordinary row.)
-# The DETERMINISTIC group (#1007) claims the opposite: the old answer was
-# stable and simply wrong — a reported success for an argument the builtin
-# could not honour — and the new one is that builtin's documented failure
-# answer. So its proof is the mirror image: the two baseline runs must AGREE
-# (a wobbling baseline would mean the "stable and wrong" reading is itself
-# wrong), and the NEW binary must answer 0. Neither half is implied by the
-# other, and neither is the instability check.
-if [ -n "$BASE" ]; then
-    for w in $EXPECTED_DIVERGE_FIXED; do
-        wprog="$(probe_prog_for "$w")"
-        [ -z "$wprog" ] && continue
-        printf '%b\n' "$wprog" > "$TMP/w.eigs"
-        probe_builtin_present "$w" || { echo "  waiver not exercised: $w is not in this build"; continue; }
-        d1="$(run_capture "$BASE" - "$TMP/w.eigs")"
-        d2="$(run_capture "$BASE" - "$TMP/w.eigs")"
-        dn="$(run_capture "$NEW" - "$TMP/w.eigs")"
-        if [ "$d1" != "$d2" ]; then
-            echo "  WAIVER UNPROVEN: $w — the baseline is NOT stable across runs"
-            echo "                   ($(printf '%s' "$d1" | tr '\n' ' ') vs $(printf '%s' "$d2" | tr '\n' ' ')),"
-            echo "                   so 'the old answer was deterministic and wrong' does not hold."
-            rc=1
-        elif [ "$dn" != "0
-0" ]; then
-            echo "  WAIVER UNPROVEN: $w — the new answer is not the documented failure value"
-            echo "                   (got $(printf '%s' "$dn" | tr '\n' ' '), want rc 0 and 0)."
-            rc=1
-        else
-            echo "  waiver proven: $w baseline stable at $(printf '%s' "$d1" | tr '\n' ' ' | cut -c1-40), new answers 0"
-        fi
-    done
-fi
-
-if [ -n "$BASE" ]; then
-    for w in $EXPECTED_DIVERGE_UNSTABLE; do
-        wprog="$(probe_prog_for "$w")"
-        if [ -n "$wprog" ]; then
-            printf '%b\n' "$wprog" > "$TMP/w.eigs"
-            r1="$(run_capture "$BASE" - "$TMP/w.eigs")"
-            r2="$(run_capture "$BASE" - "$TMP/w.eigs")"
-            if [ "$r1" = "$r2" ]; then
-                echo "  WAIVER UNPROVEN: $w — two baseline runs agreed"
-                echo "                   ($(printf '%s' "$r1" | tr '\n' ' ')),"
-                echo "                   so the 'undefined, unstable' justification"
-                echo "                   for waiving it does not hold. Re-argue it."
-                rc=1
-            else
-                echo "  waiver proven: $w baseline is run-to-run unstable"
-                echo "    run 1: $(printf '%s' "$r1" | tr '\n' ' ' | cut -c1-60)"
-                echo "    run 2: $(printf '%s' "$r2" | tr '\n' ' ' | cut -c1-60)"
-            fi
-        fi
-    done
-fi
-
-# An exemption that no longer fires must FAIL, not pass quietly: it means
-# the thing it waived changed shape, which is exactly when a stale waiver
-# starts covering something nobody agreed to.
-if [ -n "$BASE" ]; then
-    for w in $EXPECTED_DIVERGE_UNSTABLE; do
-        if ! str_has_word "$waived_seen" "$w"; then
-            echo "  SPENT WAIVER: $w is declared divergent but did not differ."
-            echo "                Remove the entry. A waiver is PR-scoped: it is live"
-            echo "                only while the parent lacks the change, and inert the"
-            echo "                moment it lands. Leaving it means the next person to"
-            echo "                run the two-binary mode meets expired paperwork —"
-            echo "                which is how sign_extend kept this tool red from"
-            echo "                #1015 to #1016 (see the waiver block at the top)."
-            rc=1
-        fi
-    done
-    for w in $EXPECTED_DIVERGE_FIXED; do
-        probe_builtin_present "$w" || continue
-        if ! str_has_word "$waived_seen" "$w"; then
-            echo "  SPENT WAIVER: $w is declared divergent but did not differ."
-            echo "                Either the probe no longer reaches the guard, or —"
-            echo "                far more likely — the change LANDED and the baseline"
-            echo "                now contains it. Remove the entry; a waiver is
-                PR-scoped (see the waiver block at the top)." | tr -s " "
-            rc=1
-        fi
-    done
-fi
-
 # Vacuity: this script cannot be green having measured nothing.
 if [ "$n_probe" -lt 55 ] || [ "$n_pin" -lt 14 ] || { [ -n "$BASE" ] && [ "$n_valid" -lt 25 ]; }; then
     echo "  VACUOUS: probes=$n_probe pins=$n_pin valid=$n_valid — below a floor; the tables"
diff --git a/tools/werror_switch_check.sh b/tools/werror_switch_check.sh
index 90792eb0..fb64e85c 100755
--- a/tools/werror_switch_check.sh
+++ b/tools/werror_switch_check.sh
@@ -389,13 +389,41 @@ enrollment_check() {
     # while reporting success — measured at 0 scripts in a fault tree vs 66 in
     # the real repo, with a planted unenrolled compile going unreported. Fall
     # back to find, and refuse to pass on an empty enumeration.
+    #
+    # The fallback is chosen by WHERE WE ARE, never by whether git produced
+    # output (#971 round 2). Keying it on an empty result made the check
+    # silently swap populations whenever `git ls-files` failed for a reason
+    # that had nothing to do with the tree — a fork/exec that lost a race for
+    # memory under a loaded box being the observed one. `find` then enumerates
+    # UNTRACKED files too: build output, scratch dirs, another run's extracted
+    # fault tree. Any of those carrying a compile line is reported as an
+    # unenrolled script, so the gate goes red naming a file that is not part of
+    # the repository at all. That is the shape of the intermittent [99i]/[99p]
+    # failure seen under load: the audit half printed its own "gate OK" and the
+    # section still failed, because the SELF-TEST half tripped this.
+    #
+    # So: inside a work tree, `git ls-files` is authoritative and an empty or
+    # failed result is an ERROR, not a cue to look elsewhere. Outside one — the
+    # `git archive HEAD | tar -x` fault trees, which are extractions and not
+    # repositories — `find` is correct and is the only option.
     local enroll_scripts
-    enroll_scripts=$(git ls-files '*.sh' 2>/dev/null | sort -u)
-    [ -z "$enroll_scripts" ] && enroll_scripts=$(find . -name '*.sh' -not -path './.git/*' 2>/dev/null | sed 's|^\./||' | sort -u)
-    if [ -z "$enroll_scripts" ]; then
-        echo "GATE ERROR: script enrollment found NO shell scripts to examine —"
-        echo "the assertion would pass vacuously, so it fails instead."
-        return 1
+    if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+        enroll_scripts=$(git ls-files '*.sh' 2>/dev/null | sort -u)
+        if [ -z "$enroll_scripts" ]; then
+            echo "GATE ERROR: inside a git work tree, but 'git ls-files' listed no shell"
+            echo "scripts. That is a failure of the enumeration, not an empty tree, so the"
+            echo "check refuses to fall back to 'find' — find would enumerate untracked and"
+            echo "generated files and report them as unenrolled. Re-run; if it persists,"
+            echo "the work tree or index is broken."
+            return 1
+        fi
+    else
+        enroll_scripts=$(find . -name '*.sh' -not -path './.git/*' 2>/dev/null | sed 's|^\./||' | sort -u)
+        if [ -z "$enroll_scripts" ]; then
+            echo "GATE ERROR: script enrollment found NO shell scripts to examine —"
+            echo "the assertion would pass vacuously, so it fails instead."
+            return 1
+        fi
     fi
     for sc in $enroll_scripts; do
         case " $SCRIPT_AUDITS " in *" $sc "*) continue;; esac
@@ -763,13 +791,29 @@ recognizer_coverage_check() {
     # OK line with "0 waived" inside a fault tree, i.e. it examined zero files
     # and reported success. A coverage check that silently measures nothing is
     # worse than no check, because it reads as evidence.
-    scripts=$(git ls-files '*.sh' 2>/dev/null)
-    [ -z "$scripts" ] && scripts=$(find . -name '*.sh' -not -path './.git/*' 2>/dev/null | sed 's|^\./||')
-    if [ -z "$scripts" ]; then
-        echo "GATE ERROR: recognizer coverage found NO shell scripts to examine."
-        echo "Neither 'git ls-files' nor 'find' enumerated anything — the check"
-        echo "would pass vacuously, so it fails instead."
-        return 1
+    #
+    # Same rule as enrollment_check (#971 round 2): the fallback is chosen by
+    # WHERE WE ARE, never by whether git produced output. Keyed on an empty
+    # result, a transient `git ls-files` failure silently swaps a tracked-file
+    # population for one that also contains untracked, generated and scratch
+    # files — which is measurable here as a "waived by shape" count that moves
+    # between runs of an unchanged tree (6 and 7 both observed).
+    if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+        scripts=$(git ls-files '*.sh' 2>/dev/null)
+        if [ -z "$scripts" ]; then
+            echo "GATE ERROR: inside a git work tree, but 'git ls-files' listed no shell"
+            echo "scripts for the recognizer coverage check. That is a failed enumeration,"
+            echo "not an empty tree, so the check refuses to fall back to 'find'."
+            return 1
+        fi
+    else
+        scripts=$(find . -name '*.sh' -not -path './.git/*' 2>/dev/null | sed 's|^\./||')
+        if [ -z "$scripts" ]; then
+            echo "GATE ERROR: recognizer coverage found NO shell scripts to examine."
+            echo "Neither 'git ls-files' nor 'find' enumerated anything — the check"
+            echo "would pass vacuously, so it fails instead."
+            return 1
+        fi
     fi
     # Cheap per-file pre-filter. The expensive path is per-SEGMENT (two greps
     # each, after a three-process normalisation pipeline), and only ~10 of 66

From 3f8eaf4be2baf2c89ea86724c54ca94454e4c487 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 02:35:33 +0000
Subject: [PATCH 32/39] changelog: the #971 round-2 entries

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 CHANGELOG.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2d078268..24dc0f8b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -106,6 +106,32 @@ All notable changes to EigenScript are documented here.
 
 ### Fixed
 
+- **Three `EIGS_STRICT` guards leaked their own allocation on every raise
+  (#971 round 2).** `STRICT_REQUIRE` returns, so it has to sit above anything
+  the function already owns; in `scan_ints`, `scan_tokens` and
+  `scan_int_tokens` it sat one line below a 128-element `make_list`, losing
+  1096 bytes per raise. The soft path is unchanged. Nothing caught it because a
+  strict raise already exits non-zero, so a leak detector's exit changes
+  nothing about the process status and a leaking guard looks exactly like a
+  working one — the strict-math test drove these very rows and reported 85 of
+  85 passing under the sanitizer. Those rows are now leak-gated by reading the
+  sanitizer's own text out of the output the assertion already captures.
+- **`tools/werror_switch_check.sh` no longer swaps its script population under
+  load (#971 round 2).** It chose between `git ls-files` and a filesystem walk
+  by whether the first produced output, so a fork that lost a race for memory
+  silently switched to the walk, which enumerates untracked build output and
+  scratch directories and reports them as unenrolled scripts. That is the root
+  cause of the intermittent `[99i]`/`[99p]` failure where the audit printed its
+  own success line and the section failed anyway. The choice is now made by
+  whether the process is inside a work tree at all, and an empty listing inside
+  one is an error rather than a cue to look elsewhere.
+- **`tools/strict_differential.sh` has no divergence-waiver mechanism (#971
+  round 2).** `differing-when-off: 0` is the single claim the tool makes, and
+  an exemption path is that claim with a hole in it. Both failure modes had
+  already been paid for: a waiver outliving its pull request made the
+  documented pre-land command fail on a clean tree for a whole release window,
+  and a waiver hides exactly what the tool exists to show.
+
 - **`tools/strict_differential.sh` (suite section `[99s]`) no longer flakes red
   on a green tree under load (#1120).** Its verdicts were decided with
   `printf … | grep -q …` under `set -o pipefail`, which is a race rather than a

From 3574d6b09a8b5533ecbbcc74d8101509cccb0418 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 02:37:55 +0000
Subject: [PATCH 33/39] =?UTF-8?q?layering:=20give=20the=20core=E2=86=92ext?=
 =?UTF-8?q?,=20fs=20and=20scheduler=20seams=20structure=20(#744)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#744 item 3 (per-layer headers, breaking up the 1253-line eigenscript.h
umbrella) is deliberately NOT here — it is 29 TUs plus tools/amalgamate.sh
plus the freestanding profile, and is recorded in ROADMAP.md with the
issue's measured facts. Items 1, 2, 4 and 5 land here. Everything moved is
byte-verbatim; the point is where the code lives, not what it does.

1. THE CORE NO LONGER INCLUDES AN EXTENSION'S PRIVATE HEADER.
   The two includes the issue names had migrated from eigenscript.c into
   builtins.c and were no longer dead — each supplied exactly one
   registration declaration. Repro, on a box without libpq-dev:

     $ gcc -DEIGENSCRIPT_EXT_DB=1 ... -c src/builtins.c
     src/ext_db_internal.h:10:10: fatal error: libpq-fe.h: No such file
     rc=1

   after:  rc=0. In the `full` variant 29 of 30 objects now build here and
   only ext_db.o — which genuinely needs libpq — does not.
   src/ext_register.h carries the five registrars and the two per-state
   teardowns: declarations, no extension types, no libpq, no Server struct,
   no transformer types. state.c's two hand-written externs and
   eigenscript.h's lone register_gfx_builtins declaration fold into it.
   ext_net_internal.h stays included by builtins.c and is pinned as an
   exemption: handle_table_drain reads EigsNetSock.fd and that header is
   deliberately socket-header-free for exactly that.

2. vm.c NO LONGER RE-DECLARES ANY CROSS-TU SYMBOL.
   Deleted: the block-scope externs for tokenize / parse / free_tokenlist /
   free_ast and for read_file_util (all already in eigenscript.h), and
   `extern Value g_null_singleton_external_decl` — a declaration of a symbol
   that exists nowhere in the tree. The last two file-scope externs were
   given a home instead of a comment: builtin_free_val -> vm.h (beside the
   borrow-protocol comment that already names it; builtins_tensor.c carried
   a second hand-written copy) and env_get_assign_count -> eigenscript.h.

4. TWO LEAF TUs AND TWO SPLITS.
   src/fsutil.c + src/fsutil.h: read_file_util and the resolver chain
   (resolve_eigenscript_file{,_from,_from_ex}, eigs_import_resolve,
   eigs_file_directory, eigs_file_resolve_error). The VM, the compiler's
   observer-gate pre-pass, main.c, fmt.c, lint_host.c and the embedding API
   all consume them, so all of them reached downward into a builtins TU to
   read a file. Whole-TU freestanding gate, unchanged semantics. Their
   declarations leave the eigenscript.h umbrella; seven TUs now say they
   read files by including fsutil.h.
   src/task.c + src/task.h: the #408 cooperative scheduler (TaskScheduler,
   the ready queue, virtual time, the #846 trace, the trampoline). 795 lines
   move with exactly ten intended edits — five hooks lose `static` because
   task.h declares them, three call sites go through wrappers, two comments
   are renamed. vm_execute_common's scheduler tail becomes
   task_sched_after_outermost so TaskScheduler stays private to task.c.
   The dispatch loop stays static: vm_run_ex (3131 lines) and
   vm_take_error_value are NOT promoted — vm.c exposes three one-line
   wrappers instead, so the compiler keeps its interprocedural view of the
   hot loop. The jit_helper_* ABI stays in vm.c: it consumes the static
   inline vm_push / vm_pop / vm_slot_lift, and moving it needs those
   promoted to a private header first — a different change.
   src/builtins_buf.c: the numeric-buffer, vectorized buf_*, PCM16LE and
   DEFLATE builtins out of builtins.c. Measured before moving: zero static
   symbols cross the seam in either direction.

5. ROADMAP.md carries item 3 as a design entry with the measured facts.

GATE: tools/core_ext_boundary_check.sh, wired as suite section [99i2]. Two
legs, because either alone passes while the invariant is broken. Leg A scans
every core TU (enumerated from the Makefile's SOURCES, not a copy of it) for
an include of any extension private header (enumerated from the tree), with
exemptions checked in BOTH directions so a waiver cannot outlive its
subject. Leg B compiles every core TU with all four extensions ON and a
POISONED <libpq-fe.h> first on the include path — without the poison the
probe would pass on any dev box that has libpq and only fail on the machines
the gate exists to protect. On the pre-fix tree: 3 leg-A violations and
leg B red on builtins.c. --selftest plants each fault and a stale exemption
and confirms each leg goes red on its own.

FIXED WHILE HERE, because the splits exposed them: five source lists that
nothing tied to the tree. tools/freestanding_check.sh, tools/embed_stack_soak.sh
and tools/freestanding_smoke.sh now derive their list from the Makefile (the
tools/amalgamate.sh pattern) and hard-fail on an empty derivation; web/build.sh
and tools/gen_lsp_builtin_index.sh's DOC_SRCS are updated in place. That last
one was a silent narrowing: without it the regenerated LSP builtin index drops
from 214 signature comments to 195. And tools/failsoft_classify_check.sh's
selftest planted its split-return fault by matching one hardcoded indentation;
when every such site moved to builtins_buf.c the plant became a silent no-op
and the row read as "the detector missed it" — the planter now matches any
indentation and treats planting nothing as fatal.

Behaviour-preserving, proven: tools/observer_gate_diff.sh over the whole
corpus, pre-change binary vs post-change binary, "RESULT: PASS — 532 programs
byte-identical", residual mismatches 0. bash tools/jit_diff.sh: OK (238
programs x {jit, osr}; 0 ledgered). Release suite 5052/5052, ASan+UBSan with
detect_leaks=1 5053/5053, leak tally 0. make {release,http,zlib,net,gfx,asan,
asan-gfx,asan-http,poison,lsp,dap,jit-smoke,amalgamation,embed-smoke,
embed-concurrent} all build; freestanding-check, freestanding-libc-diff,
embed_stack_soak, freestanding_smoke and the [99i] werror gate green.
`make full` cannot be built on this box: no libpq headers.

Closes #744
Closes #746

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 Makefile                         |   2 +-
 ROADMAP.md                       |  28 +
 src/builtins.c                   | 944 +------------------------------
 src/builtins_buf.c               | 931 ++++++++++++++++++++++++++++++
 src/builtins_host.c              | 263 +--------
 src/builtins_internal.h          |  27 +
 src/builtins_tensor.c            |   4 +-
 src/compiler.c                   |   1 +
 src/eigenscript.h                |  37 +-
 src/eigs_embed.c                 |   1 +
 src/ext_db_internal.h            |   6 +-
 src/ext_gfx.c                    |   1 +
 src/ext_http_internal.h          |   6 +-
 src/ext_net_internal.h           |   2 +-
 src/ext_register.h               |  41 ++
 src/fmt.c                        |   1 +
 src/fsutil.c                     | 300 ++++++++++
 src/fsutil.h                     |  62 ++
 src/lint_host.c                  |   1 +
 src/main.c                       |   1 +
 src/model_internal.h             |   2 +-
 src/state.c                      |  14 +-
 src/task.c                       | 853 ++++++++++++++++++++++++++++
 src/task.h                       |  48 ++
 src/vm.c                         | 878 ++--------------------------
 src/vm.h                         |   7 +
 tests/run_all_tests.sh           |  23 +
 tools/core_ext_boundary_check.sh | 210 +++++++
 tools/embed_stack_soak.sh        |  16 +-
 tools/failsoft_classify_check.sh |  18 +-
 tools/freestanding_check.sh      |  14 +-
 tools/freestanding_smoke.sh      |  16 +-
 tools/gen_lsp_builtin_index.sh   |   5 +-
 tools/werror_switch_check.sh     |   3 +-
 web/build.sh                     |   5 +-
 35 files changed, 2668 insertions(+), 2103 deletions(-)
 create mode 100644 src/builtins_buf.c
 create mode 100644 src/ext_register.h
 create mode 100644 src/fsutil.c
 create mode 100644 src/fsutil.h
 create mode 100644 src/task.c
 create mode 100644 src/task.h
 create mode 100755 tools/core_ext_boundary_check.sh

diff --git a/Makefile b/Makefile
index b26356fa..bd5e2fc8 100644
--- a/Makefile
+++ b/Makefile
@@ -19,7 +19,7 @@ LDFLAGS := -pie -Wl,-z,relro,-z,now -lm -lpthread
 endif
 
 SRC_DIR := src
-SOURCES := $(SRC_DIR)/eigenscript.c $(SRC_DIR)/lexer.c $(SRC_DIR)/parser.c $(SRC_DIR)/builtins.c $(SRC_DIR)/builtins_host.c $(SRC_DIR)/builtins_tensor.c $(SRC_DIR)/hash.c $(SRC_DIR)/arena.c $(SRC_DIR)/state.c $(SRC_DIR)/strbuf.c $(SRC_DIR)/ext_store.c $(SRC_DIR)/fmt.c $(SRC_DIR)/lint.c $(SRC_DIR)/lint_host.c $(SRC_DIR)/chunk.c $(SRC_DIR)/compiler.c $(SRC_DIR)/vm.c $(SRC_DIR)/jit.c $(SRC_DIR)/trace.c $(SRC_DIR)/eigs_embed.c $(SRC_DIR)/repl.c $(SRC_DIR)/step.c $(SRC_DIR)/tape_read.c $(SRC_DIR)/bundle.c $(SRC_DIR)/main.c
+SOURCES := $(SRC_DIR)/eigenscript.c $(SRC_DIR)/lexer.c $(SRC_DIR)/parser.c $(SRC_DIR)/builtins.c $(SRC_DIR)/builtins_buf.c $(SRC_DIR)/builtins_host.c $(SRC_DIR)/builtins_tensor.c $(SRC_DIR)/fsutil.c $(SRC_DIR)/hash.c $(SRC_DIR)/arena.c $(SRC_DIR)/state.c $(SRC_DIR)/strbuf.c $(SRC_DIR)/ext_store.c $(SRC_DIR)/fmt.c $(SRC_DIR)/lint.c $(SRC_DIR)/lint_host.c $(SRC_DIR)/chunk.c $(SRC_DIR)/compiler.c $(SRC_DIR)/vm.c $(SRC_DIR)/task.c $(SRC_DIR)/jit.c $(SRC_DIR)/trace.c $(SRC_DIR)/eigs_embed.c $(SRC_DIR)/repl.c $(SRC_DIR)/step.c $(SRC_DIR)/tape_read.c $(SRC_DIR)/bundle.c $(SRC_DIR)/main.c
 BINARY  := $(SRC_DIR)/eigenscript
 
 # CLI-only translation units: linked into the binary, never into the
diff --git a/ROADMAP.md b/ROADMAP.md
index 95b062f8..3f0428e6 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -270,6 +270,34 @@ observer/deterministic-replay niche instead of diluting it.**
       the default path byte-identical.
       ([#971](https://github.com/InauguralSystems/EigenScript/issues/971))
 
+- [ ] **Per-layer headers — break up the 1253-line `eigenscript.h` umbrella.**
+      Item 3 of [#744](https://github.com/InauguralSystems/EigenScript/issues/744),
+      the one part of that issue deliberately NOT done in the same round; items
+      1, 2, 4 and 5 landed (dead extension includes, stale externs, `fsutil.c`,
+      the `task.c` / `builtins_buf.c` splits). The measured facts, from the
+      2026-07 modularity review: there is no `lexer.h`, `parser.h`,
+      `compiler.h`, `chunk.h` or `builtins.h` — only `vm.h`, `jit.h`,
+      `trace.h`, `state.h` (plus, since #744, `fsutil.h`, `task.h` and
+      `ext_register.h`). `eigenscript.h` spans the tokenizer, the AST, values,
+      the arena, `EigsThread`, env, the parser, registration, the MODEL tensor
+      kernels, the handle table, the store, step, and fmt+lint: **26 structs
+      with every field visible, 167 declarations, included by 29 of ~30 TUs**.
+      Two consequences are measured, not asserted: a lexer change forces a full
+      rebuild of everything, and the layer order is violable and violated —
+      `compiler.c` increments the PARSER's `g_parse_depth` `EigsThread` field
+      as its own recursion guard, and lexer, parser and compiler all write
+      `g_parse_errors`, the front end mutating runtime thread state.
+      What makes this its own round rather than a follow-up commit: 29 TUs,
+      `tools/amalgamate.sh` (which concatenates them in SOURCES order and would
+      have to keep an acyclic include order across the split), and the
+      freestanding profile's two-stage symbol gate. Note the header GRAPH is
+      already clean and acyclic (`eigenscript.h -> value_slot.h`, `vm.h ->
+      value_slot.h`, everything else -> `eigenscript.h`), so this is a hub
+      problem, not a tangle — the split is mechanical once someone commits to
+      doing all 29 at once. `#744` showed the cheap version works: `fsutil.h`
+      moved 8 declarations out of the umbrella and 7 TUs now say they read
+      files, and nothing else changed.
+
 ### AOT (ouroboros — the native-perf path; not the JIT)
 
 - [x] Close the F-OURO-23 envelope via `lib/checksum.eigs` (CRC-32) as
diff --git a/src/builtins.c b/src/builtins.c
index 374ba9e3..b788bdbb 100644
--- a/src/builtins.c
+++ b/src/builtins.c
@@ -25,27 +25,20 @@
 
 #include <pthread.h>
 
-#if EIGENSCRIPT_EXT_HTTP
-#include "ext_http_internal.h"
-#endif
-
-#if EIGENSCRIPT_EXT_DB
-#include "ext_db_internal.h"
-#endif
+/* #744: the extension ENTRY POINTS, not the extensions' private headers.
+ * This TU calls five registrars and uses no extension type; pulling
+ * ext_db_internal.h for one declaration dragged <libpq-fe.h> into the core
+ * (so the `full` variant needed PostgreSQL headers to compile builtins.c),
+ * and model_internal.h dragged the transformer type set. ext_net_internal.h
+ * stays: handle_table_drain's HANDLE_NET pass reads EigsNetSock.fd, and that
+ * header is deliberately free of socket headers for exactly this use. */
+#include "ext_register.h"
 
 #if EIGENSCRIPT_EXT_NET
 #include "ext_net_internal.h"
 #include <unistd.h>   /* close() in handle_table_drain's HANDLE_NET pass */
 #endif
 
-#if EIGENSCRIPT_EXT_MODEL
-#include "model_internal.h"
-#endif
-
-#if EIGENSCRIPT_EXT_ZLIB
-#include <zlib.h>
-#endif
-
 /* How many bindings the runtime itself installs.
  *
  * register_builtins fills the global env from slot 0 upward and nothing in the
@@ -2638,10 +2631,6 @@ const char *eigs_current_file_dir(void) {
     return g_import_resolve_dir[0] ? g_import_resolve_dir : g_script_dir;
 }
 
-int resolve_eigenscript_file(const char *path, char *resolved, size_t resolved_cap) {
-    return resolve_eigenscript_file_from(eigs_current_file_dir(), path, resolved, resolved_cap);
-}
-
 
 /* ================================================================
  * THIN BUILTINS — individual capabilities for .eigs orchestration
@@ -5639,914 +5628,12 @@ Value* builtin_nearest_in_range_all(Value *arg) {
     return result;
 }
 
-/* dispatch of [table, key, arg] — O(1) function dispatch.
-   table: list of functions (or null for unused slots).
-   key: integer index into the table.
-   arg: value passed to the selected function.
-   Returns the function's return value, or null if slot is empty. */
-/* ---- Typed numeric buffers (flat double arrays) ---- */
-
-/* buffer of count — create a zero-filled numeric buffer */
-Value* builtin_buffer(Value *arg) {
-    /* buffer of [rows, cols] -> shaped 2-D buffer (flat double[rows*cols]) */
-    if (arg && arg->type == VAL_LIST && arg->data.list.count == 2 &&
-        arg->data.list.items[0]->type == VAL_NUM &&
-        arg->data.list.items[1]->type == VAL_NUM) {
-        int r = (int)arg->data.list.items[0]->data.num;
-        int c = (int)arg->data.list.items[1]->data.num;
-        if (r < 0) r = 0;
-        if (c < 0) c = 0;
-        long total = (long)r * (long)c;
-        if (total > 10000000) { r = 0; c = 0; total = 0; }
-        if (!sandbox_charge((size_t)total * sizeof(double))) return make_null();  /* #292 */
-        Value *v = xcalloc(1, sizeof(Value));
-        v->type = VAL_BUFFER;
-        v->data.buffer.count = (int)total;
-        v->data.buffer.rows = r;
-        v->data.buffer.cols = c;
-        v->data.buffer.data = xcalloc(total > 0 ? (size_t)total : 1, sizeof(double));
-        v->refcount = 1;
-        return v;
-    }
-    int count = 0;
-    /* #971 Phase D: a non-number size (or a malformed [rows, cols]) made an
-     * EMPTY buffer — a plausible object with nothing in it. */
-    STRICT_REQUIRE(!arg || arg->type != VAL_NUM, "buffer", "a size or [rows, cols]");
-    if (arg && arg->type == VAL_NUM) count = (int)arg->data.num;
-    if (count < 0) count = 0;
-    if (count > 10000000) count = 10000000;
-    if (!sandbox_charge((size_t)count * sizeof(double))) return make_null();  /* #292 */
-    Value *v = xcalloc(1, sizeof(Value));
-    v->type = VAL_BUFFER;
-    v->data.buffer.count = count;
-    v->data.buffer.data = xcalloc(count, sizeof(double));
-    v->refcount = 1;
-    return v;
-}
-
-/* reshape of [buf, rows, cols] -> a shaped copy of the flat buffer (rows*cols
- * must equal the element count). */
-Value* builtin_reshape(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) return make_null();
-    Value *b = arg->data.list.items[0];
-    if (b->type != VAL_BUFFER) return make_null();
-    if (arg->data.list.items[1]->type != VAL_NUM ||
-        arg->data.list.items[2]->type != VAL_NUM) return make_null();
-    int r = (int)arg->data.list.items[1]->data.num;
-    int c = (int)arg->data.list.items[2]->data.num;
-    if (r < 0 || c < 0 || (long)r * (long)c != (long)b->data.buffer.count) return make_null();
-    /* Same buffer chokepoint as buf_from_list — reshape copies the payload. */
-    if (!sandbox_charge((b->data.buffer.count > 0 ? (size_t)b->data.buffer.count : 1) * sizeof(double)))
-        return make_null();
-    Value *v = xcalloc(1, sizeof(Value));
-    v->type = VAL_BUFFER;
-    v->data.buffer.count = b->data.buffer.count;
-    v->data.buffer.rows = r;
-    v->data.buffer.cols = c;
-    v->data.buffer.data = xcalloc(b->data.buffer.count > 0 ? (size_t)b->data.buffer.count : 1, sizeof(double));
-    memcpy(v->data.buffer.data, b->data.buffer.data, (size_t)b->data.buffer.count * sizeof(double));
-    v->refcount = 1;
-    return v;
-}
-
-/* buf_get of [buf, index] — O(1) indexed read */
-Value* builtin_buf_get(Value *arg) {
-    /* #502: out-of-range used to fold to 0 — indistinguishable from a real
-     * stored 0. Raise index_range, matching the buffer `[i]` operator. */
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2) {
-        rt_error(EK_TYPE, 0, "buf_get requires [buffer, index]");
-        /* fs:CHANNEL the rt_error above already raised */
-        return make_num(0);
-    }
-    Value *buf = arg->data.list.items[0];
-    if (!buf || buf->type != VAL_BUFFER) {
-        rt_error(EK_TYPE, 0, "buf_get: first argument must be a buffer");
-        /* fs:CHANNEL the rt_error above already raised */
-        return make_num(0);
-    }
-    int idx = (int)arg->data.list.items[1]->data.num;
-    if (idx < 0 || idx >= buf->data.buffer.count) {
-        rt_error(EK_INDEX, 0, "buffer index %d out of range (length %d)",
-                 idx, buf->data.buffer.count);
-        /* fs:CHANNEL the EK_INDEX rt_error above already raised (#502) */
-        return make_num(0);
-    }
-    return make_num(buf->data.buffer.data[idx]);
-}
-
-/* buf_set of [buf, index, value] — O(1) indexed write */
-Value* builtin_buf_set(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) {  /* #502 */
-        rt_error(EK_TYPE, 0, "buf_set requires [buffer, index, value]");
-        return make_null();
-    }
-    Value *buf = arg->data.list.items[0];
-    if (!buf || buf->type != VAL_BUFFER) {
-        rt_error(EK_TYPE, 0, "buf_set: first argument must be a buffer");
-        return make_null();
-    }
-    /* #1061: both operands were read through the num union member unchecked
-     * -- a string index or value read garbage bits (the #1007 type-pun class).
-     * Loud, like the `b[i] is v` opcode path. */
-    if (arg->data.list.items[1]->type != VAL_NUM) {
-        rt_error(EK_TYPE, 0, "buf_set: index must be a number, got %s", val_type_name(arg->data.list.items[1]->type));
-        return make_null();
-    }
-    if (arg->data.list.items[2]->type != VAL_NUM) {
-        rt_error(EK_TYPE, 0, "cannot store %s in a buffer (buffers hold numbers)", val_type_name(arg->data.list.items[2]->type));
-        return make_null();
-    }
-    int idx = (int)arg->data.list.items[1]->data.num;
-    double val = arg->data.list.items[2]->data.num;
-    if (idx < 0 || idx >= buf->data.buffer.count) {
-        rt_error(EK_INDEX, 0, "buffer index %d out of range (length %d)",
-                 idx, buf->data.buffer.count);
-        return make_null();
-    }
-    buf->data.buffer.data[idx] = val;
-    return make_null();
-}
-
-/* buf_len of buf — return buffer length */
-Value* builtin_buf_len(Value *arg) {
-    ARG_GUARD(!arg || arg->type != VAL_BUFFER, "buf_len", "a buffer", make_num(0));
-    return make_num(arg->data.buffer.count);
-}
-
-/* buf_from_list of list — convert list of numbers to buffer */
-Value* builtin_buf_from_list(Value *arg) {
-    if (!arg || arg->type != VAL_LIST) return make_null();
-    int n = arg->data.list.count;
-    /* Sandbox chokepoint: the only two buffer producers not routed through the
-     * charged make_shaped_buffer/buf_alloc_flat allocators (this + reshape).
-     * Per-call output == input, but a loop re-using one charged input spawns N
-     * uncharged copies past the budget (blind round, 2026-08-17): 50 copies of
-     * an 800k buffer held 320MB under the 256MB default and abort under a
-     * ulimit. Charge like every other buffer producer. */
-    if (!sandbox_charge((n > 0 ? (size_t)n : 1) * sizeof(double))) return make_null();
-    Value *v = xcalloc(1, sizeof(Value));
-    v->type = VAL_BUFFER;
-    v->data.buffer.count = n;
-    v->data.buffer.data = xcalloc(n > 0 ? n : 1, sizeof(double));
-    v->refcount = 1;
-    for (int i = 0; i < n; i++) {
-        if (arg->data.list.items[i]->type == VAL_NUM) {
-            v->data.buffer.data[i] = arg->data.list.items[i]->data.num;
-        } else {
-            /* #1061: a non-number element silently stayed 0.0. */
-            const char *tn = val_type_name(arg->data.list.items[i]->type);
-            val_decref(v);
-            rt_error(EK_TYPE, 0, "buf_from_list: element %d is %s (buffers hold numbers)", i, tn);
-            return make_null();
-        }
-    }
-    return v;
-}
-
-/* str_from_bytes of <list|buffer of byte ints> → string of those raw bytes.
- * Reconstructs a native string from its bytes (the inverse of an `ord` loop);
- * the list form of scalar `chr` (chr of n == str_from_bytes of [n] for
- * 1..255). EigenScript strings are NUL-terminated, so a 0 byte ends the
- * string; binary data that may contain NUL must stay in a buffer.
- * Surfaced by tidelog's CBOR text-string decoder. */
-Value* builtin_str_from_bytes(Value *arg) {
-    int n = 0;
-    Value **items = NULL;
-    double *bufd = NULL;
-    if (arg && arg->type == VAL_LIST) {
-        n = arg->data.list.count;
-        items = arg->data.list.items;
-    } else if (arg && arg->type == VAL_BUFFER) {
-        n = arg->data.buffer.count;
-        bufd = arg->data.buffer.data;
-    } else {
-        ARG_GUARD(1, "str_from_bytes", "a list or buffer of byte values", make_str(""));
-    }
-    char *s = xcalloc((size_t)(n > 0 ? n : 0) + 1, 1);
-    int len = 0;
-    for (int i = 0; i < n; i++) {
-        double dv = items ? (items[i] && items[i]->type == VAL_NUM ? items[i]->data.num : 0.0)
-                          : bufd[i];
-        int b = (int)dv & 0xFF;
-        if (b == 0) break;            /* C-string terminates at NUL */
-        s[len++] = (char)b;
-    }
-    s[len] = '\0';
-    /* #965: the xcalloc above is an uncharged producer — wrap with the
-     * charging copy constructor, not make_str_owned. */
-    Value *r = make_str(s);
-    free(s);
-    return r;
-}
-
-/* f64_to_bytes of x → list of 8 ints: the big-endian IEEE-754 double encoding
- * of x (CBOR major-type 7 / network byte order). Portable across endianness —
- * the host bit pattern is captured via memcpy, then bytes are extracted with
- * explicit shifts, yielding the standard IEEE-754 layout on any platform. */
-Value* builtin_f64_to_bytes(Value *arg) {
-    /* #971 Phase D: a non-number encoded as 0.0's eight bytes. */
-    STRICT_REQUIRE(!arg || arg->type != VAL_NUM, "f64_to_bytes", "a number");
-    double d = (arg && arg->type == VAL_NUM) ? arg->data.num : 0.0;
-    uint64_t bits;
-    memcpy(&bits, &d, sizeof(bits));
-    Value *list = make_list(8);
-    for (int i = 0; i < 8; i++) {
-        int shift = 8 * (7 - i);
-        list_append_owned(list, make_num((double)((bits >> shift) & 0xFFu)));
-    }
-    return list;
-}
-
-/* f64_from_bytes of <list|buffer of 8 big-endian bytes> → the decoded double.
- * Inverse of f64_to_bytes; reads exactly the first 8 bytes. */
-Value* builtin_f64_from_bytes(Value *arg) {
-    double bytes_in[8] = {0,0,0,0,0,0,0,0};
-    if (arg && arg->type == VAL_LIST) {
-        int n = arg->data.list.count;
-        for (int i = 0; i < 8 && i < n; i++)
-            if (arg->data.list.items[i] && arg->data.list.items[i]->type == VAL_NUM)
-                bytes_in[i] = arg->data.list.items[i]->data.num;
-    } else if (arg && arg->type == VAL_BUFFER) {
-        int n = arg->data.buffer.count;
-        for (int i = 0; i < 8 && i < n; i++)
-            bytes_in[i] = arg->data.buffer.data[i];
-    } else {
-        ARG_GUARD(1, "f64_from_bytes", "a list or buffer of 8 byte values", make_num(0));
-    }
-    uint64_t bits = 0;
-    for (int i = 0; i < 8; i++)
-        bits = (bits << 8) | (uint64_t)((int)bytes_in[i] & 0xFF);
-    double d;
-    memcpy(&d, &bits, sizeof(d));
-    /* #971: eight arbitrary bytes can spell a NaN; collapse (default) or
-     * raise (strict) under this builtin's own name. */
-    return make_num(num_guard_named(d, "f64_from_bytes"));
-}
-
-/* ---- DEFLATE codecs (inflate/deflate, #684) ----
- * Thin wrappers over the system zlib (-lz), gated behind
- * EIGENSCRIPT_EXT_ZLIB — the same EIGENSCRIPT_EXT_* mechanism the http
- * variant uses. Default OFF so the minimal build stays zero-dependency;
- * compiled without zlib the four names stay registered but raise a
- * catchable runtime error, so a script can feature-detect with
- * try/catch instead of dying on "undefined variable".
- *
- * Byte representation mirrors read_bytes/write_bytes exactly: input is
- * a list of ints 0-255 (values taken mod 256, non-numbers read as 0)
- * or a VAL_BUFFER; output is always a fresh list of ints 0-255.
- *
- * inflate/deflate are the RAW DEFLATE pair (windowBits -15) — the ZIP
- * member format, so .xlsx/.ods entries are readable. zlib_inflate/
- * zlib_deflate are the zlib-wrapped pair; zlib_inflate uses windowBits
- * 15+32, which auto-detects zlib AND gzip headers — that is what makes
- * plain .gz files readable.
- */
-#if EIGENSCRIPT_EXT_ZLIB
-
-/* Inflate is an amplifier: a few KB of DEFLATE can expand without bound
- * (zip bomb). Cap the decompressed size like the other size caps
- * (read_bytes 10 MB, read_bytes_buf 512 MB): over the cap is a loud,
- * catchable `limit` error, never silent truncation. 256 MiB matches the
- * sandbox_run default allocation budget. */
-#define EIGS_INFLATE_MAX_OUT ((unsigned long)256 * 1024 * 1024)
-
-/* Shared argument extraction for the four codecs: accept the byte
- * representations write_bytes accepts and copy them into a malloc'd
- * byte array. Returns 1 on success; on a wrong-shape argument raises
- * `type` and returns 0. */
-static int zlib_bytes_arg(Value *arg, const char *who,
-                          unsigned char **out, size_t *out_n) {
-    *out = NULL;
-    *out_n = 0;
-    int n = 0;
-    Value **items = NULL;
-    double *bufd = NULL;
-    if (arg && arg->type == VAL_LIST) {
-        n = arg->data.list.count;
-        items = arg->data.list.items;
-    } else if (arg && arg->type == VAL_BUFFER) {
-        n = arg->data.buffer.count;
-        bufd = arg->data.buffer.data;
-    } else {
-        rt_error(EK_TYPE, 0,
-                 "%s requires a list of byte values (0-255) or a buffer, got %s",
-                 who, val_type_name(arg ? arg->type : VAL_NULL));
-        return 0;
-    }
-    unsigned char *b = xmalloc((size_t)(n > 0 ? n : 1));
-    for (int i = 0; i < n; i++) {
-        double dv = items ? (items[i] && items[i]->type == VAL_NUM ? items[i]->data.num : 0.0)
-                          : bufd[i];
-        b[i] = (unsigned char)((int)dv & 0xFF);
-    }
-    *out = b;
-    *out_n = (size_t)n;
-    return 1;
-}
-
-/* Wrap a finished byte buffer as the list-of-ints result value (the
- * read_bytes shape). Takes ownership of nothing; caller still frees. */
-static Value *zlib_bytes_result(const unsigned char *buf, unsigned long n) {
-    /* #292: the result is `n` fresh number Values at sizeof(Value)+sizeof(Value*)
-     * each — ~80 bytes per decompressed BYTE. Charging only the codec's own
-     * output buffer would therefore miss 98% of the cost, so charge the list
-     * here too, with the same accounting range/zeros use. Without this an
-     * allowlisted `inflate` allocates straight past max_bytes: the budget
-     * bounds allocators the caller has to *name* a size for, and a compressed
-     * blob names nothing. */
-    if (!sandbox_charge((size_t)n * (sizeof(Value) + sizeof(Value *))))
-        return make_null();
-    Value *result = make_list((int)n);
-    for (unsigned long i = 0; i < n; i++)
-        list_append_owned(result, make_num((double)buf[i]));
-    return result;
-}
-
-/* Shared inflate core. window_bits selects the wrapper (-15 raw,
- * 15+32 zlib/gzip auto-detect). A corrupt or truncated stream raises a
- * catchable `value` error; output over EIGS_INFLATE_MAX_OUT raises
- * `limit` (the zip-bomb bound). */
-static Value *zlib_inflate_impl(const char *who, int window_bits, Value *arg) {
-    unsigned char *src;
-    size_t src_n;
-    if (!zlib_bytes_arg(arg, who, &src, &src_n)) return make_null();
-
-    z_stream zs;
-    memset(&zs, 0, sizeof(zs));
-    if (inflateInit2(&zs, window_bits) != Z_OK) {
-        free(src);
-        rt_error(EK_INTERNAL, 0, "%s: inflateInit2 failed", who);
-        return make_null();
-    }
-    size_t cap = src_n * 3 + 64;
-    if (cap > EIGS_INFLATE_MAX_OUT) cap = EIGS_INFLATE_MAX_OUT;
-    /* #292: charge the codec's own buffer as it grows, so a bomb is refused
-     * before the memory is touched rather than after. EIGS_INFLATE_MAX_OUT
-     * bounds this at 256 MiB, which is the *default* whole-run budget — a
-     * caller that lowered max_bytes must not be overrun by one call. */
-    if (!sandbox_charge(cap)) {
-        inflateEnd(&zs);
-        free(src);
-        return make_null();
-    }
-    unsigned char *out = xmalloc(cap);
-    int zrc = Z_OK;
-    for (;;) {
-        if (zs.avail_in == 0 && zs.total_in < src_n) {
-            /* uInt is 32-bit: feed a >4 GiB input in chunks. */
-            zs.next_in = src + zs.total_in;
-            unsigned long rem = src_n - zs.total_in;
-            zs.avail_in = (uInt)(rem > UINT_MAX ? UINT_MAX : rem);
-        }
-        if (zs.total_out == cap) {
-            if (cap >= EIGS_INFLATE_MAX_OUT) break; /* limit raise below */
-            size_t ncap = cap * 2;
-            if (ncap > EIGS_INFLATE_MAX_OUT) ncap = EIGS_INFLATE_MAX_OUT;
-            if (!sandbox_charge(ncap - cap)) {   /* #292: charge the delta */
-                inflateEnd(&zs);
-                free(out);
-                free(src);
-                return make_null();
-            }
-            out = xrealloc(out, ncap);
-            cap = ncap;
-        }
-        zs.next_out = out + zs.total_out;
-        zs.avail_out = (uInt)(cap - zs.total_out);
-        zrc = inflate(&zs, Z_NO_FLUSH);
-        if (zrc == Z_STREAM_END) break;
-        if (zrc != Z_OK) break;
-        if (zs.avail_out != 0 && zs.total_in == src_n) {
-            /* Output not full yet zlib made no progress: input ran out
-             * mid-stream — truncated. */
-            zrc = Z_BUF_ERROR;
-            break;
-        }
-    }
-    if (zrc != Z_STREAM_END) {
-        if (zrc == Z_OK && zs.total_out >= EIGS_INFLATE_MAX_OUT) {
-            inflateEnd(&zs);
-            free(out);
-            free(src);
-            rt_error(EK_LIMIT, 0,
-                     "%s: decompressed output exceeds the %lu-byte cap",
-                     who, EIGS_INFLATE_MAX_OUT);
-            return make_null();
-        }
-        const char *msg = zs.msg;
-        inflateEnd(&zs);
-        free(out);
-        free(src);
-        rt_error(EK_VALUE, 0, "%s: invalid or truncated compressed stream (%s)",
-                 who, msg ? msg : "unexpected end of input");
-        return make_null();
-    }
-    unsigned long n = zs.total_out;
-    inflateEnd(&zs);
-    free(src);
-    Value *result = zlib_bytes_result(out, n);
-    free(out);
-    return result;
-}
-
-/* Shared deflate core (dual of zlib_inflate_impl). The output buffer is
- * deflateBound-sized up front, so a single Z_FINISH pass always fits. */
-static Value *zlib_deflate_impl(const char *who, int window_bits, Value *arg) {
-    unsigned char *src;
-    size_t src_n;
-    if (!zlib_bytes_arg(arg, who, &src, &src_n)) return make_null();
-
-    z_stream zs;
-    memset(&zs, 0, sizeof(zs));
-    if (deflateInit2(&zs, Z_DEFAULT_COMPRESSION, Z_DEFLATED, window_bits,
-                     8, Z_DEFAULT_STRATEGY) != Z_OK) {
-        free(src);
-        rt_error(EK_INTERNAL, 0, "%s: deflateInit2 failed", who);
-        return make_null();
-    }
-    uLong bound = deflateBound(&zs, (uLong)src_n);
-    /* #292: deflate amplifies far less than inflate (bound ~= src_n), but the
-     * budget should account for every codec buffer, not just the dangerous
-     * one — an uncharged allocator is a gap whether or not it is exploitable. */
-    if (!sandbox_charge((size_t)bound)) {
-        deflateEnd(&zs);
-        free(src);
-        return make_null();
-    }
-    unsigned char *out = xmalloc(bound > 0 ? bound : 1);
-    size_t pos = 0;
-    int zrc = Z_OK;
-    for (;;) {
-        if (zs.avail_in == 0 && pos < src_n) {
-            unsigned long rem = src_n - pos;
-            uInt chunk = (uInt)(rem > UINT_MAX ? UINT_MAX : rem);
-            zs.next_in = src + pos;
-            zs.avail_in = chunk;
-            pos += chunk;
-        }
-        int flush = (pos == src_n && zs.avail_in == 0) ? Z_FINISH : Z_NO_FLUSH;
-        zs.next_out = out + zs.total_out;
-        zs.avail_out = (uInt)(bound - zs.total_out);
-        zrc = deflate(&zs, flush);
-        if (zrc == Z_STREAM_END) break;
-        if (zrc != Z_OK && zrc != Z_BUF_ERROR) break;
-        if (flush == Z_FINISH) break; /* cannot happen with bound space */
-    }
-    if (zrc != Z_STREAM_END) {
-        const char *msg = zs.msg;
-        deflateEnd(&zs);
-        free(out);
-        free(src);
-        rt_error(EK_INTERNAL, 0, "%s: deflate failed (%s)",
-                 who, msg ? msg : "unknown zlib error");
-        return make_null();
-    }
-    unsigned long n = zs.total_out;
-    deflateEnd(&zs);
-    free(src);
-    Value *result = zlib_bytes_result(out, n);
-    free(out);
-    return result;
-}
-
-Value* builtin_inflate(Value *arg)      { return zlib_inflate_impl("inflate", -15, arg); }
-Value* builtin_zlib_inflate(Value *arg) { return zlib_inflate_impl("zlib_inflate", 15 + 32, arg); }
-Value* builtin_deflate(Value *arg)      { return zlib_deflate_impl("deflate", -15, arg); }
-Value* builtin_zlib_deflate(Value *arg) { return zlib_deflate_impl("zlib_deflate", 15, arg); }
-
-#else /* !EIGENSCRIPT_EXT_ZLIB */
-
-/* Minimal build: the names exist so scripts can feature-detect (and the
- * sandbox allowlist can name real builtins), but every call raises a
- * clear catchable error pointing at the zlib build. */
-static Value *zlib_unavailable(const char *who) {
-    rt_error(EK_VALUE, 0,
-             "%s: compiled without zlib support (rebuild with `make zlib`)",
-             who);
-    return make_null();
-}
 
-Value* builtin_inflate(Value *arg)      { (void)arg; return zlib_unavailable("inflate"); }
-Value* builtin_zlib_inflate(Value *arg) { (void)arg; return zlib_unavailable("zlib_inflate"); }
-Value* builtin_deflate(Value *arg)      { (void)arg; return zlib_unavailable("deflate"); }
-Value* builtin_zlib_deflate(Value *arg) { (void)arg; return zlib_unavailable("zlib_deflate"); }
-
-#endif /* EIGENSCRIPT_EXT_ZLIB */
-
-
-/* ---- Vectorized buffer kernels (#597) ----
- * Shared window validation for the bulk buf_* family. All of these read
- * offsets/counts as 64-bit and bound with subtraction (off > n - count),
- * never addition (off + count > n): the int-add form let two large
- * offsets overflow negative, pass both checks, and drive memmove out of
- * bounds. Bounds failures RAISE (index_range / value), matching the
- * #490-#512 direction (buf_get/buf_set/set_at) — no silent truncation:
- * a clamped audio mix is a silently wrong render. */
-static int buf_count_arg(const char *who, Value *cnt_val, long long *out) {
-    if (!cnt_val || cnt_val->type != VAL_NUM) {
-        rt_error(EK_VALUE, 0, "%s: count must be a number", who);
-        return 0;
-    }
-    long long c = (long long)cnt_val->data.num;
-    if (c < 0) {
-        rt_error(EK_VALUE, 0, "%s: count must be non-negative (got %lld)",
-                 who, c);
-        return 0;
-    }
-    *out = c;
-    return 1;
-}
-
-static int buf_num_arg(const char *who, const char *what, Value *v,
-                       double *out) {
-    if (!v || v->type != VAL_NUM) {
-        rt_error(EK_VALUE, 0, "%s: %s must be a number", who, what);
-        return 0;
-    }
-    *out = v->data.num;
-    return 1;
-}
-
-/* Validate one (buffer, offset, count) window. On success writes the
- * offset and returns 1; on failure raises and returns 0. count must
- * already be validated non-negative (buf_count_arg). */
-static int buf_window_arg(const char *who, Value *buf, Value *off_val,
-                          long long count, long long *out_off) {
-    if (!buf || buf->type != VAL_BUFFER) {
-        rt_error(EK_TYPE, 0, "%s: expected a buffer", who);
-        return 0;
-    }
-    if (!off_val || off_val->type != VAL_NUM) {
-        rt_error(EK_VALUE, 0, "%s: offset must be a number", who);
-        return 0;
-    }
-    long long off = (long long)off_val->data.num;
-    long long n = buf->data.buffer.count;
-    if (off < 0 || off > n - count) {
-        rt_error(EK_INDEX, 0,
-                 "%s: window [%lld, %lld) out of range (length %lld)",
-                 who, off, off + count, n);
-        return 0;
-    }
-    *out_off = off;
-    return 1;
-}
-
-/* buf_copy of [src, src_off, dst, dst_off, count] — bulk copy between buffers.
- * #597: bad bounds used to return null silently; they now raise like the
- * rest of the family (the crash-safety guarantee — no OOB memmove — holds
- * either way). count 0 is a valid no-op. */
-Value* builtin_buf_copy(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 5) {
-        rt_error(EK_TYPE, 0, "buf_copy requires [src, src_off, dst, dst_off, count]");
-        return make_null();
-    }
-    Value *src = arg->data.list.items[0];
-    Value *dst = arg->data.list.items[2];
-    long long count, src_off, dst_off;
-    if (!buf_count_arg("buf_copy", arg->data.list.items[4], &count) ||
-        !buf_window_arg("buf_copy", src, arg->data.list.items[1], count, &src_off) ||
-        !buf_window_arg("buf_copy", dst, arg->data.list.items[3], count, &dst_off))
-        return make_null();
-    if (count == 0) return make_null();
-    memmove(&dst->data.buffer.data[dst_off], &src->data.buffer.data[src_off],
-            (size_t)count * sizeof(double));
-    return make_null();
-}
-
-/* buf_mix of [dst, src, dst_off, src_off, count, gain] —
- * dst[dst_off+i] += src[src_off+i] * gain, in place. The audio mix-down
- * kernel (DeslanStudio's ab_mix_into): one C loop instead of ~441k
- * dispatched VM iterations per stem pass. Arithmetic mirrors the VM
- * (num_guard per step) so the result is byte-identical to the
- * equivalent interpreted loop. dst and src may be the same buffer with
- * overlapping windows; the loop runs forward in index order (documented,
- * deterministic). Returns null. */
-Value* builtin_buf_mix(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 6) {
-        rt_error(EK_TYPE, 0, "buf_mix requires [dst, src, dst_off, src_off, count, gain]");
-        return make_null();
-    }
-    Value *dst = arg->data.list.items[0];
-    Value *src = arg->data.list.items[1];
-    long long count, dst_off, src_off;
-    double gain;
-    if (!buf_count_arg("buf_mix", arg->data.list.items[4], &count) ||
-        !buf_window_arg("buf_mix", dst, arg->data.list.items[2], count, &dst_off) ||
-        !buf_window_arg("buf_mix", src, arg->data.list.items[3], count, &src_off) ||
-        !buf_num_arg("buf_mix", "gain", arg->data.list.items[5], &gain))
-        return make_null();
-    double *dd = &dst->data.buffer.data[dst_off];
-    double *sd = &src->data.buffer.data[src_off];
-    for (long long i = 0; i < count; i++)
-        dd[i] = num_guard(dd[i] + num_guard(sd[i] * gain));
-    return make_null();
-}
-
-/* buf_scale_range of [b, off, count, gain] — in-place multiply over a
- * window: b[off+i] *= gain (num_guard per element, VM-identical).
- * Fades/normalize. Returns null. */
-Value* builtin_buf_scale_range(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 4) {
-        rt_error(EK_TYPE, 0, "buf_scale_range requires [buffer, off, count, gain]");
-        return make_null();
-    }
-    Value *buf = arg->data.list.items[0];
-    long long count, off;
-    double gain;
-    if (!buf_count_arg("buf_scale_range", arg->data.list.items[2], &count) ||
-        !buf_window_arg("buf_scale_range", buf, arg->data.list.items[1], count, &off) ||
-        !buf_num_arg("buf_scale_range", "gain", arg->data.list.items[3], &gain))
-        return make_null();
-    double *d = &buf->data.buffer.data[off];
-    for (long long i = 0; i < count; i++)
-        d[i] = num_guard(d[i] * gain);
-    return make_null();
-}
-
-/* buf_fill of [b, off, count, value] — bulk store over a window:
- * b[off+i] = value (stored verbatim, like buf_set). Silence gaps,
- * click-free zeroing. Returns null. */
-Value* builtin_buf_fill(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 4) {
-        rt_error(EK_TYPE, 0, "buf_fill requires [buffer, off, count, value]");
-        return make_null();
-    }
-    Value *buf = arg->data.list.items[0];
-    long long count, off;
-    double val;
-    if (!buf_count_arg("buf_fill", arg->data.list.items[2], &count) ||
-        !buf_window_arg("buf_fill", buf, arg->data.list.items[1], count, &off) ||
-        !buf_num_arg("buf_fill", "value", arg->data.list.items[3], &val))
-        return make_null();
-    double *d = &buf->data.buffer.data[off];
-    for (long long i = 0; i < count; i++)
-        d[i] = val;
-    return make_null();
-}
-
-/* buf_peak of [b, off, count] — max |x| over a window (normalize and
- * meter scans). An empty window peaks at 0. */
-Value* builtin_buf_peak(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) {
-        rt_error(EK_TYPE, 0, "buf_peak requires [buffer, off, count]");
-        /* fs:CHANNEL the rt_error above already raised */
-        return make_num(0);
-    }
-    Value *buf = arg->data.list.items[0];
-    long long count, off;
-    if (!buf_count_arg("buf_peak", arg->data.list.items[2], &count) ||
-        !buf_window_arg("buf_peak", buf, arg->data.list.items[1], count, &off))
-        /* fs:CHANNEL buf_count_arg/buf_window_arg raise before returning 0 */
-        return make_num(0);
-    double *d = &buf->data.buffer.data[off];
-    double m = 0.0;
-    for (long long i = 0; i < count; i++) {
-        double a = d[i] < 0 ? -d[i] : d[i];
-        if (a > m) m = a;
-    }
-    return make_num(m);
-}
-
-/* buf_dot of [a, b, a_off, b_off, count] — windowed dot product:
- * sum over i of a[a_off+i] * b[b_off+i]. The YIN-autocorrelation
- * kernel. Same contract as `dot`: the summation ORDER / ASSOCIATION is
- * UNSPECIFIED (a backend may reassociate across SIMD lanes) — programs
- * needing a strict left-to-right reduction write the explicit loop.
- * no-NaN/Inf is preserved (num_guard at each step). */
-Value* builtin_buf_dot(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 5) {
-        rt_error(EK_TYPE, 0, "buf_dot requires [a, b, a_off, b_off, count]");
-        /* fs:CHANNEL the rt_error above already raised */
-        return make_num(0);
-    }
-    Value *a = arg->data.list.items[0];
-    Value *b = arg->data.list.items[1];
-    long long count, a_off, b_off;
-    if (!buf_count_arg("buf_dot", arg->data.list.items[4], &count) ||
-        !buf_window_arg("buf_dot", a, arg->data.list.items[2], count, &a_off) ||
-        !buf_window_arg("buf_dot", b, arg->data.list.items[3], count, &b_off))
-        /* fs:CHANNEL buf_count_arg/buf_window_arg raise before returning 0 */
-        return make_num(0);
-    double *ad = &a->data.buffer.data[a_off];
-    double *bd = &b->data.buffer.data[b_off];
-    double s = 0.0;
-    for (long long i = 0; i < count; i++)
-        s = num_guard(s + num_guard(ad[i] * bd[i]));
-    return make_num(s);
-}
-
-/* ---- Bulk PCM16LE codec kernels (#602) ----
- * The byte-decode siblings of the #597 window kernels: DeslanStudio's
- * WAV import spent 10.8 s decoding a 50 s stereo file sample-by-sample
- * in the interpreter (src/tools/wavio.eigs). Each kernel mirrors the
- * consumer's interpreted arithmetic step-for-step (num_guard per VM
- * operation, same evaluation order), so the result is bit-identical to
- * the loop it replaces — pinned by the differential leg in
- * tests/test_pcm_codec.eigs. Pure compute over arguments: sandbox
- * pure-compute allowlist (allocation charged per #292),
- * freestanding-safe, tape-neutral. */
-
-/* Allocate a fresh flat VAL_BUFFER of `count` doubles, or NULL if the
- * sandbox allocation budget (#292) rejects it (sandbox_charge raises). */
-static Value* buf_alloc_flat(long long count) {
-    if (!sandbox_charge((size_t)count * sizeof(double))) return NULL;
-    Value *v = xcalloc(1, sizeof(Value));
-    v->type = VAL_BUFFER;
-    v->data.buffer.count = (int)count;
-    v->data.buffer.data = xcalloc(count > 0 ? (size_t)count : 1, sizeof(double));
-    v->refcount = 1;
-    return v;
-}
-
-/* buf_from_pcm16le of [bytes, byte_off, count] — decode `count`
- * little-endian signed 16-bit PCM samples starting at byte_off into a
- * NEW float buffer. Exactly wavio's wav_read arithmetic:
- *   v = b0 + 256*b1;  if v >= 32768: v -= 65536;  sample = v / 32767 */
-Value* builtin_buf_from_pcm16le(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) {
-        rt_error(EK_TYPE, 0, "buf_from_pcm16le requires [bytes, byte_off, count]");
-        return make_null();
-    }
-    Value *src = arg->data.list.items[0];
-    long long count, off;
-    if (!buf_count_arg("buf_from_pcm16le", arg->data.list.items[2], &count))
-        return make_null();
-    if (count > (long long)INT_MAX / 2) { /* 2*count below cannot overflow */
-        rt_error(EK_LIMIT, 0, "buf_from_pcm16le: count %lld over the buffer size limit", count);
-        return make_null();
-    }
-    if (!buf_window_arg("buf_from_pcm16le", src, arg->data.list.items[1],
-                        count * 2, &off))
-        return make_null();
-    Value *out = buf_alloc_flat(count);
-    if (!out) return make_null();
-    const double *sd = &src->data.buffer.data[off];
-    double *od = out->data.buffer.data;
-    for (long long i = 0; i < count; i++) {
-        double v = num_guard(sd[2*i] + num_guard(256.0 * sd[2*i + 1]));
-        if (v >= 32768.0) v = num_guard(v - 65536.0);
-        od[i] = num_guard(v / 32767.0);
-    }
-    return out;
-}
-
-/* buf_to_pcm16le of [floats, off, count] — encode `count` samples from
- * `off` into a NEW byte buffer (2 doubles per sample, LE order).
- * Exactly wavio's wav_write arithmetic: clamp to [-1, 1] (ds_clamp's
- * two independent comparisons), v = round(x * 32767), two's complement
- * via +65536, low byte = v - floor(v/256)*256 (the ds_fmod expansion),
- * high byte = floor(v/256). */
-Value* builtin_buf_to_pcm16le(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) {
-        rt_error(EK_TYPE, 0, "buf_to_pcm16le requires [floats, off, count]");
-        return make_null();
-    }
-    Value *src = arg->data.list.items[0];
-    long long count, off;
-    if (!buf_count_arg("buf_to_pcm16le", arg->data.list.items[2], &count))
-        return make_null();
-    if (count > (long long)INT_MAX / 2) { /* output is 2*count elements */
-        rt_error(EK_LIMIT, 0, "buf_to_pcm16le: count %lld over the buffer size limit", count);
-        return make_null();
-    }
-    if (!buf_window_arg("buf_to_pcm16le", src, arg->data.list.items[1],
-                        count, &off))
-        return make_null();
-    Value *out = buf_alloc_flat(count * 2);
-    if (!out) return make_null();
-    const double *sd = &src->data.buffer.data[off];
-    double *od = out->data.buffer.data;
-    for (long long i = 0; i < count; i++) {
-        double x = sd[i];
-        if (x < -1.0) x = -1.0;
-        if (x > 1.0) x = 1.0;
-        double v = round(num_guard(x * 32767.0));
-        if (v < 0.0) v = num_guard(v + 65536.0);
-        double q = floor(num_guard(v / 256.0));
-        od[2*i]     = num_guard(v - num_guard(q * 256.0));
-        od[2*i + 1] = q;
-    }
-    return out;
-}
-
-/* buf_deinterleave of [src, channel, nch, count?] — every nch-th sample
- * starting at index `channel` into a NEW buffer (frame-interleaved
- * channel split; wavio addresses sample (i, c) at i*nch + c). count
- * defaults to the full available tail. Pure copy — no arithmetic. */
-Value* builtin_buf_deinterleave(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) {
-        rt_error(EK_TYPE, 0, "buf_deinterleave requires [src, channel, nch, count?]");
-        return make_null();
-    }
-    Value *src = arg->data.list.items[0];
-    if (!src || src->type != VAL_BUFFER) {
-        rt_error(EK_TYPE, 0, "buf_deinterleave: expected a buffer");
-        return make_null();
-    }
-    Value *ch_v = arg->data.list.items[1];
-    Value *nch_v = arg->data.list.items[2];
-    if (!ch_v || ch_v->type != VAL_NUM || !nch_v || nch_v->type != VAL_NUM) {
-        rt_error(EK_VALUE, 0, "buf_deinterleave: channel and nch must be numbers");
-        return make_null();
-    }
-    long long nch = (long long)nch_v->data.num;
-    long long channel = (long long)ch_v->data.num;
-    if (nch < 1) {
-        rt_error(EK_VALUE, 0, "buf_deinterleave: nch must be >= 1 (got %lld)", nch);
-        return make_null();
-    }
-    if (channel < 0 || channel >= nch) {
-        rt_error(EK_VALUE, 0, "buf_deinterleave: channel %lld out of range for %lld channels",
-                 channel, nch);
-        return make_null();
-    }
-    long long n = src->data.buffer.count;
-    long long avail = channel < n ? (n - channel + nch - 1) / nch : 0;
-    long long count = avail;
-    if (arg->data.list.count >= 4 && arg->data.list.items[3] &&
-        arg->data.list.items[3]->type != VAL_NULL) {
-        if (!buf_count_arg("buf_deinterleave", arg->data.list.items[3], &count))
-            return make_null();
-        if (count > avail) {
-            rt_error(EK_INDEX, 0,
-                     "buf_deinterleave: count %lld over the %lld samples available "
-                     "(length %lld, channel %lld of %lld)",
-                     count, avail, n, channel, nch);
-            return make_null();
-        }
-    }
-    Value *out = buf_alloc_flat(count);
-    if (!out) return make_null();
-    const double *sd = src->data.buffer.data;
-    double *od = out->data.buffer.data;
-    for (long long i = 0; i < count; i++)
-        od[i] = sd[channel + i * nch];
-    return out;
-}
-
-/* ---- buf_resample_linear (#603) ----
- * buf_resample_linear of [src, dst_len] — endpoint-inclusive linear
- * resample into a NEW buffer. Exactly DeslanStudio's ab_resample_linear
- * mapping (src/daw/audio_buf.eigs):
- *   pos  = i * (n - 1) / (dst_len - 1)      (0 when dst_len == 1)
- *   lo   = floor(pos); hi = min(lo + 1, n - 1); frac = pos - lo
- *   out[i] = src[lo] * (1 - frac) + src[hi] * frac
- * num_guard per step in VM evaluation order — bit-identical to the
- * interpreted loop (differential-pinned in tests/test_buf_resample.eigs).
- * The kernel is LINEAR interpolation, not Fourier/sinc resampling (the
- * consumer-documented divergence from scipy.signal.resample — see
- * BUILTINS.md). dst_len 0 -> empty buffer; empty src with dst_len > 0
- * raises `value` (the consumer's wrapper guards n == 0 itself). */
-Value* builtin_buf_resample_linear(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2) {
-        rt_error(EK_TYPE, 0, "buf_resample_linear requires [src, dst_len]");
-        return make_null();
-    }
-    Value *src = arg->data.list.items[0];
-    if (!src || src->type != VAL_BUFFER) {
-        rt_error(EK_TYPE, 0, "buf_resample_linear: expected a buffer");
-        return make_null();
-    }
-    long long dst_len;
-    if (!buf_count_arg("buf_resample_linear", arg->data.list.items[1], &dst_len))
-        return make_null();
-    if (dst_len > (long long)INT_MAX) {
-        rt_error(EK_LIMIT, 0, "buf_resample_linear: dst_len %lld over the buffer size limit", dst_len);
-        return make_null();
-    }
-    long long n = src->data.buffer.count;
-    if (n == 0 && dst_len > 0) {
-        rt_error(EK_VALUE, 0, "buf_resample_linear: cannot resample an empty buffer to length %lld", dst_len);
-        return make_null();
-    }
-    Value *out = buf_alloc_flat(dst_len);
-    if (!out) return make_null();
-    const double *sd = src->data.buffer.data;
-    double *od = out->data.buffer.data;
-    for (long long i = 0; i < dst_len; i++) {
-        double pos = 0.0;
-        if (dst_len > 1)
-            pos = num_guard(num_guard((double)i * (double)(n - 1)) /
-                            (double)(dst_len - 1));
-        double lo_f = floor(pos);
-        long long lo = (long long)lo_f;
-        long long hi = lo + 1;
-        if (hi > n - 1) hi = n - 1;
-        /* pos is in [0, n-1] by construction (the i = dst_len-1 quotient
-         * is exactly n-1, and an exact-integer product / exact divisor
-         * cannot round past it); the clamps below are pure memory-safety
-         * belts, unreachable for real inputs — the interpreted oracle
-         * would raise index_range where these would fire. */
-        if (lo < 0) lo = 0;
-        if (lo > n - 1) lo = n - 1;
-        if (hi < 0) hi = 0;
-        double frac = num_guard(pos - lo_f);
-        od[i] = num_guard(num_guard(sd[lo] * num_guard(1.0 - frac)) +
-                          num_guard(sd[hi] * frac));
-    }
-    return out;
-}
+/* ---- Typed numeric buffers, the vectorized buf_* kernels, the PCM16LE
+ * codecs and the DEFLATE codecs moved to src/builtins_buf.c (#744): one
+ * cohesive group, no shared statics with the rest of this file (measured:
+ * zero symbols crossed in either direction). Their prototypes are in
+ * builtins_internal.h; register_builtins below still binds them. ---- */
 
 /* sign_extend of [val, bits] — sign-extend val from given bit width.
  * E.g. sign_extend of [0xFF, 8] → -1 */
@@ -6798,6 +5885,11 @@ Value* builtin_sort(Value *arg) {
     return arg;
 }
 
+/* dispatch of [table, key, arg] — O(1) function dispatch.
+   table: list of functions (or null for unused slots).
+   key: integer index into the table.
+   arg: value passed to the selected function.
+   Returns the function's return value, or null if slot is empty. */
 Value* builtin_dispatch(Value *arg) {
     if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) {
         rt_error(EK_TYPE, 0, "dispatch requires [table, key, arg]");
diff --git a/src/builtins_buf.c b/src/builtins_buf.c
new file mode 100644
index 00000000..42265841
--- /dev/null
+++ b/src/builtins_buf.c
@@ -0,0 +1,931 @@
+/*
+ * Numeric buffer + DSP builtins (#744).
+ *
+ * `buffer`/`reshape`/`buf_get`/`buf_set`, the byte<->f64 codecs, the
+ * vectorized buf_* window kernels (#597), the bulk PCM16LE codecs (#602),
+ * buf_resample_linear (#603) and the DEFLATE codecs (#684). Split out of
+ * builtins.c, which held at least ten unrelated groups; this one is
+ * self-contained — the split was measured first and NO static symbol crosses
+ * the seam in either direction.
+ *
+ * These are ordinary builtins: registered by register_builtins (builtins.c)
+ * through the prototypes in builtins_internal.h, no registrar of their own,
+ * so the env-composition seam stays single (#742).
+ *
+ * Freestanding-safe: pure arithmetic over flat double arrays, no OS. The
+ * DEFLATE block is the one variant surface — behind EIGENSCRIPT_EXT_ZLIB,
+ * and with it off the four names stay registered and raise, so a script can
+ * feature-detect with try/catch.
+ */
+
+#include "eigenscript.h"
+#include "vm.h"
+#include "builtins_internal.h"
+
+#if EIGENSCRIPT_EXT_ZLIB
+#include <zlib.h>
+#endif
+
+/* ---- Typed numeric buffers (flat double arrays) ---- */
+
+/* buffer of count — create a zero-filled numeric buffer */
+Value* builtin_buffer(Value *arg) {
+    /* buffer of [rows, cols] -> shaped 2-D buffer (flat double[rows*cols]) */
+    if (arg && arg->type == VAL_LIST && arg->data.list.count == 2 &&
+        arg->data.list.items[0]->type == VAL_NUM &&
+        arg->data.list.items[1]->type == VAL_NUM) {
+        int r = (int)arg->data.list.items[0]->data.num;
+        int c = (int)arg->data.list.items[1]->data.num;
+        if (r < 0) r = 0;
+        if (c < 0) c = 0;
+        long total = (long)r * (long)c;
+        if (total > 10000000) { r = 0; c = 0; total = 0; }
+        if (!sandbox_charge((size_t)total * sizeof(double))) return make_null();  /* #292 */
+        Value *v = xcalloc(1, sizeof(Value));
+        v->type = VAL_BUFFER;
+        v->data.buffer.count = (int)total;
+        v->data.buffer.rows = r;
+        v->data.buffer.cols = c;
+        v->data.buffer.data = xcalloc(total > 0 ? (size_t)total : 1, sizeof(double));
+        v->refcount = 1;
+        return v;
+    }
+    int count = 0;
+    /* #971 Phase D: a non-number size (or a malformed [rows, cols]) made an
+     * EMPTY buffer — a plausible object with nothing in it. */
+    STRICT_REQUIRE(!arg || arg->type != VAL_NUM, "buffer", "a size or [rows, cols]");
+    if (arg && arg->type == VAL_NUM) count = (int)arg->data.num;
+    if (count < 0) count = 0;
+    if (count > 10000000) count = 10000000;
+    if (!sandbox_charge((size_t)count * sizeof(double))) return make_null();  /* #292 */
+    Value *v = xcalloc(1, sizeof(Value));
+    v->type = VAL_BUFFER;
+    v->data.buffer.count = count;
+    v->data.buffer.data = xcalloc(count, sizeof(double));
+    v->refcount = 1;
+    return v;
+}
+
+/* reshape of [buf, rows, cols] -> a shaped copy of the flat buffer (rows*cols
+ * must equal the element count). */
+Value* builtin_reshape(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) return make_null();
+    Value *b = arg->data.list.items[0];
+    if (b->type != VAL_BUFFER) return make_null();
+    if (arg->data.list.items[1]->type != VAL_NUM ||
+        arg->data.list.items[2]->type != VAL_NUM) return make_null();
+    int r = (int)arg->data.list.items[1]->data.num;
+    int c = (int)arg->data.list.items[2]->data.num;
+    if (r < 0 || c < 0 || (long)r * (long)c != (long)b->data.buffer.count) return make_null();
+    /* Same buffer chokepoint as buf_from_list — reshape copies the payload. */
+    if (!sandbox_charge((b->data.buffer.count > 0 ? (size_t)b->data.buffer.count : 1) * sizeof(double)))
+        return make_null();
+    Value *v = xcalloc(1, sizeof(Value));
+    v->type = VAL_BUFFER;
+    v->data.buffer.count = b->data.buffer.count;
+    v->data.buffer.rows = r;
+    v->data.buffer.cols = c;
+    v->data.buffer.data = xcalloc(b->data.buffer.count > 0 ? (size_t)b->data.buffer.count : 1, sizeof(double));
+    memcpy(v->data.buffer.data, b->data.buffer.data, (size_t)b->data.buffer.count * sizeof(double));
+    v->refcount = 1;
+    return v;
+}
+
+/* buf_get of [buf, index] — O(1) indexed read */
+Value* builtin_buf_get(Value *arg) {
+    /* #502: out-of-range used to fold to 0 — indistinguishable from a real
+     * stored 0. Raise index_range, matching the buffer `[i]` operator. */
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2) {
+        rt_error(EK_TYPE, 0, "buf_get requires [buffer, index]");
+        /* fs:CHANNEL the rt_error above already raised */
+        return make_num(0);
+    }
+    Value *buf = arg->data.list.items[0];
+    if (!buf || buf->type != VAL_BUFFER) {
+        rt_error(EK_TYPE, 0, "buf_get: first argument must be a buffer");
+        /* fs:CHANNEL the rt_error above already raised */
+        return make_num(0);
+    }
+    int idx = (int)arg->data.list.items[1]->data.num;
+    if (idx < 0 || idx >= buf->data.buffer.count) {
+        rt_error(EK_INDEX, 0, "buffer index %d out of range (length %d)",
+                 idx, buf->data.buffer.count);
+        /* fs:CHANNEL the EK_INDEX rt_error above already raised (#502) */
+        return make_num(0);
+    }
+    return make_num(buf->data.buffer.data[idx]);
+}
+
+/* buf_set of [buf, index, value] — O(1) indexed write */
+Value* builtin_buf_set(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) {  /* #502 */
+        rt_error(EK_TYPE, 0, "buf_set requires [buffer, index, value]");
+        return make_null();
+    }
+    Value *buf = arg->data.list.items[0];
+    if (!buf || buf->type != VAL_BUFFER) {
+        rt_error(EK_TYPE, 0, "buf_set: first argument must be a buffer");
+        return make_null();
+    }
+    /* #1061: both operands were read through the num union member unchecked
+     * -- a string index or value read garbage bits (the #1007 type-pun class).
+     * Loud, like the `b[i] is v` opcode path. */
+    if (arg->data.list.items[1]->type != VAL_NUM) {
+        rt_error(EK_TYPE, 0, "buf_set: index must be a number, got %s", val_type_name(arg->data.list.items[1]->type));
+        return make_null();
+    }
+    if (arg->data.list.items[2]->type != VAL_NUM) {
+        rt_error(EK_TYPE, 0, "cannot store %s in a buffer (buffers hold numbers)", val_type_name(arg->data.list.items[2]->type));
+        return make_null();
+    }
+    int idx = (int)arg->data.list.items[1]->data.num;
+    double val = arg->data.list.items[2]->data.num;
+    if (idx < 0 || idx >= buf->data.buffer.count) {
+        rt_error(EK_INDEX, 0, "buffer index %d out of range (length %d)",
+                 idx, buf->data.buffer.count);
+        return make_null();
+    }
+    buf->data.buffer.data[idx] = val;
+    return make_null();
+}
+
+/* buf_len of buf — return buffer length */
+Value* builtin_buf_len(Value *arg) {
+    ARG_GUARD(!arg || arg->type != VAL_BUFFER, "buf_len", "a buffer", make_num(0));
+    return make_num(arg->data.buffer.count);
+}
+
+/* buf_from_list of list — convert list of numbers to buffer */
+Value* builtin_buf_from_list(Value *arg) {
+    if (!arg || arg->type != VAL_LIST) return make_null();
+    int n = arg->data.list.count;
+    /* Sandbox chokepoint: the only two buffer producers not routed through the
+     * charged make_shaped_buffer/buf_alloc_flat allocators (this + reshape).
+     * Per-call output == input, but a loop re-using one charged input spawns N
+     * uncharged copies past the budget (blind round, 2026-08-17): 50 copies of
+     * an 800k buffer held 320MB under the 256MB default and abort under a
+     * ulimit. Charge like every other buffer producer. */
+    if (!sandbox_charge((n > 0 ? (size_t)n : 1) * sizeof(double))) return make_null();
+    Value *v = xcalloc(1, sizeof(Value));
+    v->type = VAL_BUFFER;
+    v->data.buffer.count = n;
+    v->data.buffer.data = xcalloc(n > 0 ? n : 1, sizeof(double));
+    v->refcount = 1;
+    for (int i = 0; i < n; i++) {
+        if (arg->data.list.items[i]->type == VAL_NUM) {
+            v->data.buffer.data[i] = arg->data.list.items[i]->data.num;
+        } else {
+            /* #1061: a non-number element silently stayed 0.0. */
+            const char *tn = val_type_name(arg->data.list.items[i]->type);
+            val_decref(v);
+            rt_error(EK_TYPE, 0, "buf_from_list: element %d is %s (buffers hold numbers)", i, tn);
+            return make_null();
+        }
+    }
+    return v;
+}
+
+/* str_from_bytes of <list|buffer of byte ints> → string of those raw bytes.
+ * Reconstructs a native string from its bytes (the inverse of an `ord` loop);
+ * the list form of scalar `chr` (chr of n == str_from_bytes of [n] for
+ * 1..255). EigenScript strings are NUL-terminated, so a 0 byte ends the
+ * string; binary data that may contain NUL must stay in a buffer.
+ * Surfaced by tidelog's CBOR text-string decoder. */
+Value* builtin_str_from_bytes(Value *arg) {
+    int n = 0;
+    Value **items = NULL;
+    double *bufd = NULL;
+    if (arg && arg->type == VAL_LIST) {
+        n = arg->data.list.count;
+        items = arg->data.list.items;
+    } else if (arg && arg->type == VAL_BUFFER) {
+        n = arg->data.buffer.count;
+        bufd = arg->data.buffer.data;
+    } else {
+        ARG_GUARD(1, "str_from_bytes", "a list or buffer of byte values", make_str(""));
+    }
+    char *s = xcalloc((size_t)(n > 0 ? n : 0) + 1, 1);
+    int len = 0;
+    for (int i = 0; i < n; i++) {
+        double dv = items ? (items[i] && items[i]->type == VAL_NUM ? items[i]->data.num : 0.0)
+                          : bufd[i];
+        int b = (int)dv & 0xFF;
+        if (b == 0) break;            /* C-string terminates at NUL */
+        s[len++] = (char)b;
+    }
+    s[len] = '\0';
+    /* #965: the xcalloc above is an uncharged producer — wrap with the
+     * charging copy constructor, not make_str_owned. */
+    Value *r = make_str(s);
+    free(s);
+    return r;
+}
+
+/* f64_to_bytes of x → list of 8 ints: the big-endian IEEE-754 double encoding
+ * of x (CBOR major-type 7 / network byte order). Portable across endianness —
+ * the host bit pattern is captured via memcpy, then bytes are extracted with
+ * explicit shifts, yielding the standard IEEE-754 layout on any platform. */
+Value* builtin_f64_to_bytes(Value *arg) {
+    /* #971 Phase D: a non-number encoded as 0.0's eight bytes. */
+    STRICT_REQUIRE(!arg || arg->type != VAL_NUM, "f64_to_bytes", "a number");
+    double d = (arg && arg->type == VAL_NUM) ? arg->data.num : 0.0;
+    uint64_t bits;
+    memcpy(&bits, &d, sizeof(bits));
+    Value *list = make_list(8);
+    for (int i = 0; i < 8; i++) {
+        int shift = 8 * (7 - i);
+        list_append_owned(list, make_num((double)((bits >> shift) & 0xFFu)));
+    }
+    return list;
+}
+
+/* f64_from_bytes of <list|buffer of 8 big-endian bytes> → the decoded double.
+ * Inverse of f64_to_bytes; reads exactly the first 8 bytes. */
+Value* builtin_f64_from_bytes(Value *arg) {
+    double bytes_in[8] = {0,0,0,0,0,0,0,0};
+    if (arg && arg->type == VAL_LIST) {
+        int n = arg->data.list.count;
+        for (int i = 0; i < 8 && i < n; i++)
+            if (arg->data.list.items[i] && arg->data.list.items[i]->type == VAL_NUM)
+                bytes_in[i] = arg->data.list.items[i]->data.num;
+    } else if (arg && arg->type == VAL_BUFFER) {
+        int n = arg->data.buffer.count;
+        for (int i = 0; i < 8 && i < n; i++)
+            bytes_in[i] = arg->data.buffer.data[i];
+    } else {
+        ARG_GUARD(1, "f64_from_bytes", "a list or buffer of 8 byte values", make_num(0));
+    }
+    uint64_t bits = 0;
+    for (int i = 0; i < 8; i++)
+        bits = (bits << 8) | (uint64_t)((int)bytes_in[i] & 0xFF);
+    double d;
+    memcpy(&d, &bits, sizeof(d));
+    /* #971: eight arbitrary bytes can spell a NaN; collapse (default) or
+     * raise (strict) under this builtin's own name. */
+    return make_num(num_guard_named(d, "f64_from_bytes"));
+}
+
+/* ---- DEFLATE codecs (inflate/deflate, #684) ----
+ * Thin wrappers over the system zlib (-lz), gated behind
+ * EIGENSCRIPT_EXT_ZLIB — the same EIGENSCRIPT_EXT_* mechanism the http
+ * variant uses. Default OFF so the minimal build stays zero-dependency;
+ * compiled without zlib the four names stay registered but raise a
+ * catchable runtime error, so a script can feature-detect with
+ * try/catch instead of dying on "undefined variable".
+ *
+ * Byte representation mirrors read_bytes/write_bytes exactly: input is
+ * a list of ints 0-255 (values taken mod 256, non-numbers read as 0)
+ * or a VAL_BUFFER; output is always a fresh list of ints 0-255.
+ *
+ * inflate/deflate are the RAW DEFLATE pair (windowBits -15) — the ZIP
+ * member format, so .xlsx/.ods entries are readable. zlib_inflate/
+ * zlib_deflate are the zlib-wrapped pair; zlib_inflate uses windowBits
+ * 15+32, which auto-detects zlib AND gzip headers — that is what makes
+ * plain .gz files readable.
+ */
+#if EIGENSCRIPT_EXT_ZLIB
+
+/* Inflate is an amplifier: a few KB of DEFLATE can expand without bound
+ * (zip bomb). Cap the decompressed size like the other size caps
+ * (read_bytes 10 MB, read_bytes_buf 512 MB): over the cap is a loud,
+ * catchable `limit` error, never silent truncation. 256 MiB matches the
+ * sandbox_run default allocation budget. */
+#define EIGS_INFLATE_MAX_OUT ((unsigned long)256 * 1024 * 1024)
+
+/* Shared argument extraction for the four codecs: accept the byte
+ * representations write_bytes accepts and copy them into a malloc'd
+ * byte array. Returns 1 on success; on a wrong-shape argument raises
+ * `type` and returns 0. */
+static int zlib_bytes_arg(Value *arg, const char *who,
+                          unsigned char **out, size_t *out_n) {
+    *out = NULL;
+    *out_n = 0;
+    int n = 0;
+    Value **items = NULL;
+    double *bufd = NULL;
+    if (arg && arg->type == VAL_LIST) {
+        n = arg->data.list.count;
+        items = arg->data.list.items;
+    } else if (arg && arg->type == VAL_BUFFER) {
+        n = arg->data.buffer.count;
+        bufd = arg->data.buffer.data;
+    } else {
+        rt_error(EK_TYPE, 0,
+                 "%s requires a list of byte values (0-255) or a buffer, got %s",
+                 who, val_type_name(arg ? arg->type : VAL_NULL));
+        return 0;
+    }
+    unsigned char *b = xmalloc((size_t)(n > 0 ? n : 1));
+    for (int i = 0; i < n; i++) {
+        double dv = items ? (items[i] && items[i]->type == VAL_NUM ? items[i]->data.num : 0.0)
+                          : bufd[i];
+        b[i] = (unsigned char)((int)dv & 0xFF);
+    }
+    *out = b;
+    *out_n = (size_t)n;
+    return 1;
+}
+
+/* Wrap a finished byte buffer as the list-of-ints result value (the
+ * read_bytes shape). Takes ownership of nothing; caller still frees. */
+static Value *zlib_bytes_result(const unsigned char *buf, unsigned long n) {
+    /* #292: the result is `n` fresh number Values at sizeof(Value)+sizeof(Value*)
+     * each — ~80 bytes per decompressed BYTE. Charging only the codec's own
+     * output buffer would therefore miss 98% of the cost, so charge the list
+     * here too, with the same accounting range/zeros use. Without this an
+     * allowlisted `inflate` allocates straight past max_bytes: the budget
+     * bounds allocators the caller has to *name* a size for, and a compressed
+     * blob names nothing. */
+    if (!sandbox_charge((size_t)n * (sizeof(Value) + sizeof(Value *))))
+        return make_null();
+    Value *result = make_list((int)n);
+    for (unsigned long i = 0; i < n; i++)
+        list_append_owned(result, make_num((double)buf[i]));
+    return result;
+}
+
+/* Shared inflate core. window_bits selects the wrapper (-15 raw,
+ * 15+32 zlib/gzip auto-detect). A corrupt or truncated stream raises a
+ * catchable `value` error; output over EIGS_INFLATE_MAX_OUT raises
+ * `limit` (the zip-bomb bound). */
+static Value *zlib_inflate_impl(const char *who, int window_bits, Value *arg) {
+    unsigned char *src;
+    size_t src_n;
+    if (!zlib_bytes_arg(arg, who, &src, &src_n)) return make_null();
+
+    z_stream zs;
+    memset(&zs, 0, sizeof(zs));
+    if (inflateInit2(&zs, window_bits) != Z_OK) {
+        free(src);
+        rt_error(EK_INTERNAL, 0, "%s: inflateInit2 failed", who);
+        return make_null();
+    }
+    size_t cap = src_n * 3 + 64;
+    if (cap > EIGS_INFLATE_MAX_OUT) cap = EIGS_INFLATE_MAX_OUT;
+    /* #292: charge the codec's own buffer as it grows, so a bomb is refused
+     * before the memory is touched rather than after. EIGS_INFLATE_MAX_OUT
+     * bounds this at 256 MiB, which is the *default* whole-run budget — a
+     * caller that lowered max_bytes must not be overrun by one call. */
+    if (!sandbox_charge(cap)) {
+        inflateEnd(&zs);
+        free(src);
+        return make_null();
+    }
+    unsigned char *out = xmalloc(cap);
+    int zrc = Z_OK;
+    for (;;) {
+        if (zs.avail_in == 0 && zs.total_in < src_n) {
+            /* uInt is 32-bit: feed a >4 GiB input in chunks. */
+            zs.next_in = src + zs.total_in;
+            unsigned long rem = src_n - zs.total_in;
+            zs.avail_in = (uInt)(rem > UINT_MAX ? UINT_MAX : rem);
+        }
+        if (zs.total_out == cap) {
+            if (cap >= EIGS_INFLATE_MAX_OUT) break; /* limit raise below */
+            size_t ncap = cap * 2;
+            if (ncap > EIGS_INFLATE_MAX_OUT) ncap = EIGS_INFLATE_MAX_OUT;
+            if (!sandbox_charge(ncap - cap)) {   /* #292: charge the delta */
+                inflateEnd(&zs);
+                free(out);
+                free(src);
+                return make_null();
+            }
+            out = xrealloc(out, ncap);
+            cap = ncap;
+        }
+        zs.next_out = out + zs.total_out;
+        zs.avail_out = (uInt)(cap - zs.total_out);
+        zrc = inflate(&zs, Z_NO_FLUSH);
+        if (zrc == Z_STREAM_END) break;
+        if (zrc != Z_OK) break;
+        if (zs.avail_out != 0 && zs.total_in == src_n) {
+            /* Output not full yet zlib made no progress: input ran out
+             * mid-stream — truncated. */
+            zrc = Z_BUF_ERROR;
+            break;
+        }
+    }
+    if (zrc != Z_STREAM_END) {
+        if (zrc == Z_OK && zs.total_out >= EIGS_INFLATE_MAX_OUT) {
+            inflateEnd(&zs);
+            free(out);
+            free(src);
+            rt_error(EK_LIMIT, 0,
+                     "%s: decompressed output exceeds the %lu-byte cap",
+                     who, EIGS_INFLATE_MAX_OUT);
+            return make_null();
+        }
+        const char *msg = zs.msg;
+        inflateEnd(&zs);
+        free(out);
+        free(src);
+        rt_error(EK_VALUE, 0, "%s: invalid or truncated compressed stream (%s)",
+                 who, msg ? msg : "unexpected end of input");
+        return make_null();
+    }
+    unsigned long n = zs.total_out;
+    inflateEnd(&zs);
+    free(src);
+    Value *result = zlib_bytes_result(out, n);
+    free(out);
+    return result;
+}
+
+/* Shared deflate core (dual of zlib_inflate_impl). The output buffer is
+ * deflateBound-sized up front, so a single Z_FINISH pass always fits. */
+static Value *zlib_deflate_impl(const char *who, int window_bits, Value *arg) {
+    unsigned char *src;
+    size_t src_n;
+    if (!zlib_bytes_arg(arg, who, &src, &src_n)) return make_null();
+
+    z_stream zs;
+    memset(&zs, 0, sizeof(zs));
+    if (deflateInit2(&zs, Z_DEFAULT_COMPRESSION, Z_DEFLATED, window_bits,
+                     8, Z_DEFAULT_STRATEGY) != Z_OK) {
+        free(src);
+        rt_error(EK_INTERNAL, 0, "%s: deflateInit2 failed", who);
+        return make_null();
+    }
+    uLong bound = deflateBound(&zs, (uLong)src_n);
+    /* #292: deflate amplifies far less than inflate (bound ~= src_n), but the
+     * budget should account for every codec buffer, not just the dangerous
+     * one — an uncharged allocator is a gap whether or not it is exploitable. */
+    if (!sandbox_charge((size_t)bound)) {
+        deflateEnd(&zs);
+        free(src);
+        return make_null();
+    }
+    unsigned char *out = xmalloc(bound > 0 ? bound : 1);
+    size_t pos = 0;
+    int zrc = Z_OK;
+    for (;;) {
+        if (zs.avail_in == 0 && pos < src_n) {
+            unsigned long rem = src_n - pos;
+            uInt chunk = (uInt)(rem > UINT_MAX ? UINT_MAX : rem);
+            zs.next_in = src + pos;
+            zs.avail_in = chunk;
+            pos += chunk;
+        }
+        int flush = (pos == src_n && zs.avail_in == 0) ? Z_FINISH : Z_NO_FLUSH;
+        zs.next_out = out + zs.total_out;
+        zs.avail_out = (uInt)(bound - zs.total_out);
+        zrc = deflate(&zs, flush);
+        if (zrc == Z_STREAM_END) break;
+        if (zrc != Z_OK && zrc != Z_BUF_ERROR) break;
+        if (flush == Z_FINISH) break; /* cannot happen with bound space */
+    }
+    if (zrc != Z_STREAM_END) {
+        const char *msg = zs.msg;
+        deflateEnd(&zs);
+        free(out);
+        free(src);
+        rt_error(EK_INTERNAL, 0, "%s: deflate failed (%s)",
+                 who, msg ? msg : "unknown zlib error");
+        return make_null();
+    }
+    unsigned long n = zs.total_out;
+    deflateEnd(&zs);
+    free(src);
+    Value *result = zlib_bytes_result(out, n);
+    free(out);
+    return result;
+}
+
+Value* builtin_inflate(Value *arg)      { return zlib_inflate_impl("inflate", -15, arg); }
+Value* builtin_zlib_inflate(Value *arg) { return zlib_inflate_impl("zlib_inflate", 15 + 32, arg); }
+Value* builtin_deflate(Value *arg)      { return zlib_deflate_impl("deflate", -15, arg); }
+Value* builtin_zlib_deflate(Value *arg) { return zlib_deflate_impl("zlib_deflate", 15, arg); }
+
+#else /* !EIGENSCRIPT_EXT_ZLIB */
+
+/* Minimal build: the names exist so scripts can feature-detect (and the
+ * sandbox allowlist can name real builtins), but every call raises a
+ * clear catchable error pointing at the zlib build. */
+static Value *zlib_unavailable(const char *who) {
+    rt_error(EK_VALUE, 0,
+             "%s: compiled without zlib support (rebuild with `make zlib`)",
+             who);
+    return make_null();
+}
+
+Value* builtin_inflate(Value *arg)      { (void)arg; return zlib_unavailable("inflate"); }
+Value* builtin_zlib_inflate(Value *arg) { (void)arg; return zlib_unavailable("zlib_inflate"); }
+Value* builtin_deflate(Value *arg)      { (void)arg; return zlib_unavailable("deflate"); }
+Value* builtin_zlib_deflate(Value *arg) { (void)arg; return zlib_unavailable("zlib_deflate"); }
+
+#endif /* EIGENSCRIPT_EXT_ZLIB */
+
+
+/* ---- Vectorized buffer kernels (#597) ----
+ * Shared window validation for the bulk buf_* family. All of these read
+ * offsets/counts as 64-bit and bound with subtraction (off > n - count),
+ * never addition (off + count > n): the int-add form let two large
+ * offsets overflow negative, pass both checks, and drive memmove out of
+ * bounds. Bounds failures RAISE (index_range / value), matching the
+ * #490-#512 direction (buf_get/buf_set/set_at) — no silent truncation:
+ * a clamped audio mix is a silently wrong render. */
+static int buf_count_arg(const char *who, Value *cnt_val, long long *out) {
+    if (!cnt_val || cnt_val->type != VAL_NUM) {
+        rt_error(EK_VALUE, 0, "%s: count must be a number", who);
+        return 0;
+    }
+    long long c = (long long)cnt_val->data.num;
+    if (c < 0) {
+        rt_error(EK_VALUE, 0, "%s: count must be non-negative (got %lld)",
+                 who, c);
+        return 0;
+    }
+    *out = c;
+    return 1;
+}
+
+static int buf_num_arg(const char *who, const char *what, Value *v,
+                       double *out) {
+    if (!v || v->type != VAL_NUM) {
+        rt_error(EK_VALUE, 0, "%s: %s must be a number", who, what);
+        return 0;
+    }
+    *out = v->data.num;
+    return 1;
+}
+
+/* Validate one (buffer, offset, count) window. On success writes the
+ * offset and returns 1; on failure raises and returns 0. count must
+ * already be validated non-negative (buf_count_arg). */
+static int buf_window_arg(const char *who, Value *buf, Value *off_val,
+                          long long count, long long *out_off) {
+    if (!buf || buf->type != VAL_BUFFER) {
+        rt_error(EK_TYPE, 0, "%s: expected a buffer", who);
+        return 0;
+    }
+    if (!off_val || off_val->type != VAL_NUM) {
+        rt_error(EK_VALUE, 0, "%s: offset must be a number", who);
+        return 0;
+    }
+    long long off = (long long)off_val->data.num;
+    long long n = buf->data.buffer.count;
+    if (off < 0 || off > n - count) {
+        rt_error(EK_INDEX, 0,
+                 "%s: window [%lld, %lld) out of range (length %lld)",
+                 who, off, off + count, n);
+        return 0;
+    }
+    *out_off = off;
+    return 1;
+}
+
+/* buf_copy of [src, src_off, dst, dst_off, count] — bulk copy between buffers.
+ * #597: bad bounds used to return null silently; they now raise like the
+ * rest of the family (the crash-safety guarantee — no OOB memmove — holds
+ * either way). count 0 is a valid no-op. */
+Value* builtin_buf_copy(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 5) {
+        rt_error(EK_TYPE, 0, "buf_copy requires [src, src_off, dst, dst_off, count]");
+        return make_null();
+    }
+    Value *src = arg->data.list.items[0];
+    Value *dst = arg->data.list.items[2];
+    long long count, src_off, dst_off;
+    if (!buf_count_arg("buf_copy", arg->data.list.items[4], &count) ||
+        !buf_window_arg("buf_copy", src, arg->data.list.items[1], count, &src_off) ||
+        !buf_window_arg("buf_copy", dst, arg->data.list.items[3], count, &dst_off))
+        return make_null();
+    if (count == 0) return make_null();
+    memmove(&dst->data.buffer.data[dst_off], &src->data.buffer.data[src_off],
+            (size_t)count * sizeof(double));
+    return make_null();
+}
+
+/* buf_mix of [dst, src, dst_off, src_off, count, gain] —
+ * dst[dst_off+i] += src[src_off+i] * gain, in place. The audio mix-down
+ * kernel (DeslanStudio's ab_mix_into): one C loop instead of ~441k
+ * dispatched VM iterations per stem pass. Arithmetic mirrors the VM
+ * (num_guard per step) so the result is byte-identical to the
+ * equivalent interpreted loop. dst and src may be the same buffer with
+ * overlapping windows; the loop runs forward in index order (documented,
+ * deterministic). Returns null. */
+Value* builtin_buf_mix(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 6) {
+        rt_error(EK_TYPE, 0, "buf_mix requires [dst, src, dst_off, src_off, count, gain]");
+        return make_null();
+    }
+    Value *dst = arg->data.list.items[0];
+    Value *src = arg->data.list.items[1];
+    long long count, dst_off, src_off;
+    double gain;
+    if (!buf_count_arg("buf_mix", arg->data.list.items[4], &count) ||
+        !buf_window_arg("buf_mix", dst, arg->data.list.items[2], count, &dst_off) ||
+        !buf_window_arg("buf_mix", src, arg->data.list.items[3], count, &src_off) ||
+        !buf_num_arg("buf_mix", "gain", arg->data.list.items[5], &gain))
+        return make_null();
+    double *dd = &dst->data.buffer.data[dst_off];
+    double *sd = &src->data.buffer.data[src_off];
+    for (long long i = 0; i < count; i++)
+        dd[i] = num_guard(dd[i] + num_guard(sd[i] * gain));
+    return make_null();
+}
+
+/* buf_scale_range of [b, off, count, gain] — in-place multiply over a
+ * window: b[off+i] *= gain (num_guard per element, VM-identical).
+ * Fades/normalize. Returns null. */
+Value* builtin_buf_scale_range(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 4) {
+        rt_error(EK_TYPE, 0, "buf_scale_range requires [buffer, off, count, gain]");
+        return make_null();
+    }
+    Value *buf = arg->data.list.items[0];
+    long long count, off;
+    double gain;
+    if (!buf_count_arg("buf_scale_range", arg->data.list.items[2], &count) ||
+        !buf_window_arg("buf_scale_range", buf, arg->data.list.items[1], count, &off) ||
+        !buf_num_arg("buf_scale_range", "gain", arg->data.list.items[3], &gain))
+        return make_null();
+    double *d = &buf->data.buffer.data[off];
+    for (long long i = 0; i < count; i++)
+        d[i] = num_guard(d[i] * gain);
+    return make_null();
+}
+
+/* buf_fill of [b, off, count, value] — bulk store over a window:
+ * b[off+i] = value (stored verbatim, like buf_set). Silence gaps,
+ * click-free zeroing. Returns null. */
+Value* builtin_buf_fill(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 4) {
+        rt_error(EK_TYPE, 0, "buf_fill requires [buffer, off, count, value]");
+        return make_null();
+    }
+    Value *buf = arg->data.list.items[0];
+    long long count, off;
+    double val;
+    if (!buf_count_arg("buf_fill", arg->data.list.items[2], &count) ||
+        !buf_window_arg("buf_fill", buf, arg->data.list.items[1], count, &off) ||
+        !buf_num_arg("buf_fill", "value", arg->data.list.items[3], &val))
+        return make_null();
+    double *d = &buf->data.buffer.data[off];
+    for (long long i = 0; i < count; i++)
+        d[i] = val;
+    return make_null();
+}
+
+/* buf_peak of [b, off, count] — max |x| over a window (normalize and
+ * meter scans). An empty window peaks at 0. */
+Value* builtin_buf_peak(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) {
+        rt_error(EK_TYPE, 0, "buf_peak requires [buffer, off, count]");
+        /* fs:CHANNEL the rt_error above already raised */
+        return make_num(0);
+    }
+    Value *buf = arg->data.list.items[0];
+    long long count, off;
+    if (!buf_count_arg("buf_peak", arg->data.list.items[2], &count) ||
+        !buf_window_arg("buf_peak", buf, arg->data.list.items[1], count, &off))
+        /* fs:CHANNEL buf_count_arg/buf_window_arg raise before returning 0 */
+        return make_num(0);
+    double *d = &buf->data.buffer.data[off];
+    double m = 0.0;
+    for (long long i = 0; i < count; i++) {
+        double a = d[i] < 0 ? -d[i] : d[i];
+        if (a > m) m = a;
+    }
+    return make_num(m);
+}
+
+/* buf_dot of [a, b, a_off, b_off, count] — windowed dot product:
+ * sum over i of a[a_off+i] * b[b_off+i]. The YIN-autocorrelation
+ * kernel. Same contract as `dot`: the summation ORDER / ASSOCIATION is
+ * UNSPECIFIED (a backend may reassociate across SIMD lanes) — programs
+ * needing a strict left-to-right reduction write the explicit loop.
+ * no-NaN/Inf is preserved (num_guard at each step). */
+Value* builtin_buf_dot(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 5) {
+        rt_error(EK_TYPE, 0, "buf_dot requires [a, b, a_off, b_off, count]");
+        /* fs:CHANNEL the rt_error above already raised */
+        return make_num(0);
+    }
+    Value *a = arg->data.list.items[0];
+    Value *b = arg->data.list.items[1];
+    long long count, a_off, b_off;
+    if (!buf_count_arg("buf_dot", arg->data.list.items[4], &count) ||
+        !buf_window_arg("buf_dot", a, arg->data.list.items[2], count, &a_off) ||
+        !buf_window_arg("buf_dot", b, arg->data.list.items[3], count, &b_off))
+        /* fs:CHANNEL buf_count_arg/buf_window_arg raise before returning 0 */
+        return make_num(0);
+    double *ad = &a->data.buffer.data[a_off];
+    double *bd = &b->data.buffer.data[b_off];
+    double s = 0.0;
+    for (long long i = 0; i < count; i++)
+        s = num_guard(s + num_guard(ad[i] * bd[i]));
+    return make_num(s);
+}
+
+/* ---- Bulk PCM16LE codec kernels (#602) ----
+ * The byte-decode siblings of the #597 window kernels: DeslanStudio's
+ * WAV import spent 10.8 s decoding a 50 s stereo file sample-by-sample
+ * in the interpreter (src/tools/wavio.eigs). Each kernel mirrors the
+ * consumer's interpreted arithmetic step-for-step (num_guard per VM
+ * operation, same evaluation order), so the result is bit-identical to
+ * the loop it replaces — pinned by the differential leg in
+ * tests/test_pcm_codec.eigs. Pure compute over arguments: sandbox
+ * pure-compute allowlist (allocation charged per #292),
+ * freestanding-safe, tape-neutral. */
+
+/* Allocate a fresh flat VAL_BUFFER of `count` doubles, or NULL if the
+ * sandbox allocation budget (#292) rejects it (sandbox_charge raises). */
+static Value* buf_alloc_flat(long long count) {
+    if (!sandbox_charge((size_t)count * sizeof(double))) return NULL;
+    Value *v = xcalloc(1, sizeof(Value));
+    v->type = VAL_BUFFER;
+    v->data.buffer.count = (int)count;
+    v->data.buffer.data = xcalloc(count > 0 ? (size_t)count : 1, sizeof(double));
+    v->refcount = 1;
+    return v;
+}
+
+/* buf_from_pcm16le of [bytes, byte_off, count] — decode `count`
+ * little-endian signed 16-bit PCM samples starting at byte_off into a
+ * NEW float buffer. Exactly wavio's wav_read arithmetic:
+ *   v = b0 + 256*b1;  if v >= 32768: v -= 65536;  sample = v / 32767 */
+Value* builtin_buf_from_pcm16le(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) {
+        rt_error(EK_TYPE, 0, "buf_from_pcm16le requires [bytes, byte_off, count]");
+        return make_null();
+    }
+    Value *src = arg->data.list.items[0];
+    long long count, off;
+    if (!buf_count_arg("buf_from_pcm16le", arg->data.list.items[2], &count))
+        return make_null();
+    if (count > (long long)INT_MAX / 2) { /* 2*count below cannot overflow */
+        rt_error(EK_LIMIT, 0, "buf_from_pcm16le: count %lld over the buffer size limit", count);
+        return make_null();
+    }
+    if (!buf_window_arg("buf_from_pcm16le", src, arg->data.list.items[1],
+                        count * 2, &off))
+        return make_null();
+    Value *out = buf_alloc_flat(count);
+    if (!out) return make_null();
+    const double *sd = &src->data.buffer.data[off];
+    double *od = out->data.buffer.data;
+    for (long long i = 0; i < count; i++) {
+        double v = num_guard(sd[2*i] + num_guard(256.0 * sd[2*i + 1]));
+        if (v >= 32768.0) v = num_guard(v - 65536.0);
+        od[i] = num_guard(v / 32767.0);
+    }
+    return out;
+}
+
+/* buf_to_pcm16le of [floats, off, count] — encode `count` samples from
+ * `off` into a NEW byte buffer (2 doubles per sample, LE order).
+ * Exactly wavio's wav_write arithmetic: clamp to [-1, 1] (ds_clamp's
+ * two independent comparisons), v = round(x * 32767), two's complement
+ * via +65536, low byte = v - floor(v/256)*256 (the ds_fmod expansion),
+ * high byte = floor(v/256). */
+Value* builtin_buf_to_pcm16le(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) {
+        rt_error(EK_TYPE, 0, "buf_to_pcm16le requires [floats, off, count]");
+        return make_null();
+    }
+    Value *src = arg->data.list.items[0];
+    long long count, off;
+    if (!buf_count_arg("buf_to_pcm16le", arg->data.list.items[2], &count))
+        return make_null();
+    if (count > (long long)INT_MAX / 2) { /* output is 2*count elements */
+        rt_error(EK_LIMIT, 0, "buf_to_pcm16le: count %lld over the buffer size limit", count);
+        return make_null();
+    }
+    if (!buf_window_arg("buf_to_pcm16le", src, arg->data.list.items[1],
+                        count, &off))
+        return make_null();
+    Value *out = buf_alloc_flat(count * 2);
+    if (!out) return make_null();
+    const double *sd = &src->data.buffer.data[off];
+    double *od = out->data.buffer.data;
+    for (long long i = 0; i < count; i++) {
+        double x = sd[i];
+        if (x < -1.0) x = -1.0;
+        if (x > 1.0) x = 1.0;
+        double v = round(num_guard(x * 32767.0));
+        if (v < 0.0) v = num_guard(v + 65536.0);
+        double q = floor(num_guard(v / 256.0));
+        od[2*i]     = num_guard(v - num_guard(q * 256.0));
+        od[2*i + 1] = q;
+    }
+    return out;
+}
+
+/* buf_deinterleave of [src, channel, nch, count?] — every nch-th sample
+ * starting at index `channel` into a NEW buffer (frame-interleaved
+ * channel split; wavio addresses sample (i, c) at i*nch + c). count
+ * defaults to the full available tail. Pure copy — no arithmetic. */
+Value* builtin_buf_deinterleave(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) {
+        rt_error(EK_TYPE, 0, "buf_deinterleave requires [src, channel, nch, count?]");
+        return make_null();
+    }
+    Value *src = arg->data.list.items[0];
+    if (!src || src->type != VAL_BUFFER) {
+        rt_error(EK_TYPE, 0, "buf_deinterleave: expected a buffer");
+        return make_null();
+    }
+    Value *ch_v = arg->data.list.items[1];
+    Value *nch_v = arg->data.list.items[2];
+    if (!ch_v || ch_v->type != VAL_NUM || !nch_v || nch_v->type != VAL_NUM) {
+        rt_error(EK_VALUE, 0, "buf_deinterleave: channel and nch must be numbers");
+        return make_null();
+    }
+    long long nch = (long long)nch_v->data.num;
+    long long channel = (long long)ch_v->data.num;
+    if (nch < 1) {
+        rt_error(EK_VALUE, 0, "buf_deinterleave: nch must be >= 1 (got %lld)", nch);
+        return make_null();
+    }
+    if (channel < 0 || channel >= nch) {
+        rt_error(EK_VALUE, 0, "buf_deinterleave: channel %lld out of range for %lld channels",
+                 channel, nch);
+        return make_null();
+    }
+    long long n = src->data.buffer.count;
+    long long avail = channel < n ? (n - channel + nch - 1) / nch : 0;
+    long long count = avail;
+    if (arg->data.list.count >= 4 && arg->data.list.items[3] &&
+        arg->data.list.items[3]->type != VAL_NULL) {
+        if (!buf_count_arg("buf_deinterleave", arg->data.list.items[3], &count))
+            return make_null();
+        if (count > avail) {
+            rt_error(EK_INDEX, 0,
+                     "buf_deinterleave: count %lld over the %lld samples available "
+                     "(length %lld, channel %lld of %lld)",
+                     count, avail, n, channel, nch);
+            return make_null();
+        }
+    }
+    Value *out = buf_alloc_flat(count);
+    if (!out) return make_null();
+    const double *sd = src->data.buffer.data;
+    double *od = out->data.buffer.data;
+    for (long long i = 0; i < count; i++)
+        od[i] = sd[channel + i * nch];
+    return out;
+}
+
+/* ---- buf_resample_linear (#603) ----
+ * buf_resample_linear of [src, dst_len] — endpoint-inclusive linear
+ * resample into a NEW buffer. Exactly DeslanStudio's ab_resample_linear
+ * mapping (src/daw/audio_buf.eigs):
+ *   pos  = i * (n - 1) / (dst_len - 1)      (0 when dst_len == 1)
+ *   lo   = floor(pos); hi = min(lo + 1, n - 1); frac = pos - lo
+ *   out[i] = src[lo] * (1 - frac) + src[hi] * frac
+ * num_guard per step in VM evaluation order — bit-identical to the
+ * interpreted loop (differential-pinned in tests/test_buf_resample.eigs).
+ * The kernel is LINEAR interpolation, not Fourier/sinc resampling (the
+ * consumer-documented divergence from scipy.signal.resample — see
+ * BUILTINS.md). dst_len 0 -> empty buffer; empty src with dst_len > 0
+ * raises `value` (the consumer's wrapper guards n == 0 itself). */
+Value* builtin_buf_resample_linear(Value *arg) {
+    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2) {
+        rt_error(EK_TYPE, 0, "buf_resample_linear requires [src, dst_len]");
+        return make_null();
+    }
+    Value *src = arg->data.list.items[0];
+    if (!src || src->type != VAL_BUFFER) {
+        rt_error(EK_TYPE, 0, "buf_resample_linear: expected a buffer");
+        return make_null();
+    }
+    long long dst_len;
+    if (!buf_count_arg("buf_resample_linear", arg->data.list.items[1], &dst_len))
+        return make_null();
+    if (dst_len > (long long)INT_MAX) {
+        rt_error(EK_LIMIT, 0, "buf_resample_linear: dst_len %lld over the buffer size limit", dst_len);
+        return make_null();
+    }
+    long long n = src->data.buffer.count;
+    if (n == 0 && dst_len > 0) {
+        rt_error(EK_VALUE, 0, "buf_resample_linear: cannot resample an empty buffer to length %lld", dst_len);
+        return make_null();
+    }
+    Value *out = buf_alloc_flat(dst_len);
+    if (!out) return make_null();
+    const double *sd = src->data.buffer.data;
+    double *od = out->data.buffer.data;
+    for (long long i = 0; i < dst_len; i++) {
+        double pos = 0.0;
+        if (dst_len > 1)
+            pos = num_guard(num_guard((double)i * (double)(n - 1)) /
+                            (double)(dst_len - 1));
+        double lo_f = floor(pos);
+        long long lo = (long long)lo_f;
+        long long hi = lo + 1;
+        if (hi > n - 1) hi = n - 1;
+        /* pos is in [0, n-1] by construction (the i = dst_len-1 quotient
+         * is exactly n-1, and an exact-integer product / exact divisor
+         * cannot round past it); the clamps below are pure memory-safety
+         * belts, unreachable for real inputs — the interpreted oracle
+         * would raise index_range where these would fire. */
+        if (lo < 0) lo = 0;
+        if (lo > n - 1) lo = n - 1;
+        if (hi < 0) hi = 0;
+        double frac = num_guard(pos - lo_f);
+        od[i] = num_guard(num_guard(sd[lo] * num_guard(1.0 - frac)) +
+                          num_guard(sd[hi] * frac));
+    }
+    return out;
+}
diff --git a/src/builtins_host.c b/src/builtins_host.c
index f0ebcf89..3dfc6dc5 100644
--- a/src/builtins_host.c
+++ b/src/builtins_host.c
@@ -20,6 +20,7 @@
 #include "state.h"
 #include "vm.h"
 #include "builtins_internal.h"
+#include "fsutil.h"
 #include "trace.h"
 
 #if EIGENSCRIPT_FREESTANDING
@@ -29,28 +30,6 @@
  * a filesystem. */
 void register_host_builtins(Env *env) { (void)env; }
 
-int resolve_eigenscript_file_from(const char *base, const char *path,
-                                   char *resolved, size_t resolved_cap) {
-    (void)base; (void)path; (void)resolved; (void)resolved_cap;
-    return 0;   /* nothing resolves without a filesystem */
-}
-
-int resolve_eigenscript_file_from_ex(const char *base, const char *path,
-                                      char *resolved, size_t resolved_cap,
-                                      int *origin) {
-    (void)base; (void)path; (void)resolved; (void)resolved_cap;
-    if (origin) *origin = EIGS_RESOLVE_PROJECT;
-    return 0;
-}
-
-int eigs_import_resolve(const char *base, const char *name,
-                        char *resolved, size_t resolved_cap,
-                        char *shadowed, size_t shadowed_cap) {
-    (void)base; (void)name; (void)resolved; (void)resolved_cap;
-    if (shadowed && shadowed_cap) shadowed[0] = '\0';
-    return 0;   /* nothing resolves without a filesystem */
-}
-
 #else /* host profile */
 
 #include <termios.h>
@@ -838,246 +817,6 @@ Value* builtin_build_corpus(Value *arg) {
  * ================================================================ */
 
 
-/* File I/O helper — used by load_file and main() */
-char* read_file_util(const char *path, long *out_size) {
-    FILE *f = fopen(path, "rb");
-    if (!f) return NULL;
-    /* #314: fopen succeeds on a directory, and ftell then reports LONG_MAX —
-     * which sailed straight into xmalloc's fatal-OOM abort. Reject
-     * directories here so callers hit their existing clean error paths. */
-    struct stat st;
-    if (fstat(fileno(f), &st) == 0 && !S_ISREG(st.st_mode)) { fclose(f); return NULL; }
-    fseek(f, 0, SEEK_END);
-    long size = ftell(f);
-    if (size < 0 || size == LONG_MAX) { fclose(f); return NULL; }
-    fseek(f, 0, SEEK_SET);
-    char *buf = xmalloc(size + 1);
-    if (!buf) { fclose(f); return NULL; }
-    size_t got = fread(buf, 1, size, f);
-    fclose(f);
-    if ((long)got != size) { free(buf); return NULL; }
-    buf[size] = '\0';
-    if (out_size) *out_size = size;
-    return buf;
-}
-
-static int try_resolve_path(const char *candidate, char *resolved, size_t resolved_cap) {
-    if (!candidate || access(candidate, F_OK) != 0) return 0;
-    snprintf(resolved, resolved_cap, "%s", candidate);
-    return 1;
-}
-
-/* Canonical file provenance: symlink entry points and nested loads agree with
- * import. Heap-owned because this helper also runs on compiler paths. */
-char *eigs_file_directory(const char *path) {
-    char *dir = realpath(path, NULL);
-    if (!dir) dir = xstrdup(path);
-    char *slash = strrchr(dir, '/');
-    if (slash == dir) dir[1] = '\0';
-    else if (slash) *slash = '\0';
-    else { free(dir); dir = xstrdup("."); }
-    return dir;
-}
-
-static int parent_directory(char *dir) {
-    char *slash = strrchr(dir, '/');
-    if (!slash || strcmp(dir, "/") == 0) return 0;
-    if (slash == dir) dir[1] = '\0';
-    else *slash = '\0';
-    return 1;
-}
-
-/* The nearest eigs.json is the project boundary, for both package lookup
- * and root-relative paths. No cwd or one-parent fallback participates. */
-static char *project_directory(const char *base) {
-    char *dir = realpath(base, NULL);
-    if (!dir) return NULL;
-    char *marker = xmalloc(strlen(dir) + sizeof("/eigs.json"));
-    do {
-        size_t dir_len = strlen(dir);
-        memcpy(marker, dir, dir_len);
-        memcpy(marker + dir_len, "/eigs.json", sizeof("/eigs.json"));
-        if (access(marker, F_OK) == 0) { free(marker); return dir; }
-    } while (parent_directory(dir));
-    free(marker);
-    free(dir);
-    return NULL;
-}
-
-void eigs_file_resolve_error(const char *operation, const char *base,
-                            const char *path, int line) {
-    char *project = project_directory(base);
-    const char *home = getenv("HOME");
-    rt_error(EK_IO, line,
-        "%s: cannot read '%s' (not found or unreadable); tried containing directory '%s', "
-        "eigs_modules walk, %s%s; stdlib roots '%s/../<path>', "
-        "'%s/../lib/eigenscript', '%s/.local/lib/eigenscript' "
-        "(also stripping lib/; absolute paths are used as-is)",
-        operation, path, base, project ? "project root " : "no eigs.json above ",
-        project ? project : base, g_exe_dir, g_exe_dir,
-        home ? home : "<HOME unset>");
-    free(project);
-}
-
-/* Phase 0c: walk from `base` upward looking for
- *   <dir>/eigs_modules/<name>/<name>.eigs
- * at each level. Stop at the project root (a directory containing
- * eigs.json) — its eigs_modules/ is checked once, then we don't go
- * higher. Only fires for bare `<name>.eigs` requests (no slashes); the
- * resolver's existing chain still handles paths with directory
- * components. Bounded to 64 levels for safety. */
-static int try_eigs_modules_walk(const char *base, const char *path,
-                                  char *resolved, size_t resolved_cap) {
-    if (!base || !base[0] || !path) return 0;
-    if (strchr(path, '/')) return 0;
-    size_t plen = strlen(path);
-    if (plen < 6 || strcmp(path + plen - 5, ".eigs") != 0) return 0;
-    if (plen - 5 >= 512) return 0;
-
-    char name[512];
-    memcpy(name, path, plen - 5);
-    name[plen - 5] = '\0';
-
-    char cur[4096];
-    snprintf(cur, sizeof(cur), "%s", base);
-
-    for (int i = 0; i < 64; i++) {
-        char candidate[8192];
-        snprintf(candidate, sizeof(candidate),
-                 "%.3000s/eigs_modules/%.500s/%.500s.eigs",
-                 cur, name, name);
-        if (try_resolve_path(candidate, resolved, resolved_cap)) return 1;
-
-        char marker[4400];
-        snprintf(marker, sizeof(marker), "%.4000s/eigs.json", cur);
-        if (access(marker, F_OK) == 0) return 0;
-
-        if (!parent_directory(cur)) return 0;
-    }
-    return 0;
-}
-
-int resolve_eigenscript_file_from_ex(const char *base, const char *path,
-                                      char *resolved, size_t resolved_cap,
-                                      int *origin) {
-    char candidate[8192];
-
-    /* #904: report which half of the chain answered. The tail steps below
-     * are the *installed stdlib roots* (`<prefix>/lib/eigenscript/`, from
-     * `make install`), and they answer a bare `<name>.eigs` request just as
-     * readily as `lib/<name>.eigs` — so a hit there is the stdlib wearing a
-     * project-shaped request, not a project file. Callers that must tell
-     * the two apart (import's collision diagnostic) pass `origin`. */
-#define RESOLVED(step)                                                       \
-    do { if (origin) *origin = (step); return 1; } while (0)
-
-    if (origin) *origin = EIGS_RESOLVE_PROJECT;
-    if (!path || !resolved || resolved_cap == 0) return 0;
-    if (!base || !base[0]) base = eigs_current_file_dir();
-
-    if (path[0] == '/') {
-        return try_resolve_path(path, resolved, resolved_cap);
-    }
-
-    snprintf(candidate, sizeof(candidate), "%.4000s/%.4000s", base, path);
-    if (try_resolve_path(candidate, resolved, resolved_cap)) return 1;
-
-    if (try_eigs_modules_walk(base, path, resolved, resolved_cap)) return 1;
-
-    char *project = project_directory(base);
-    if (project) {
-        snprintf(candidate, sizeof(candidate), "%.4000s/%.4000s", project, path);
-        free(project);
-        if (try_resolve_path(candidate, resolved, resolved_cap)) return 1;
-    }
-
-    snprintf(candidate, sizeof(candidate), "%.4000s/../%.4000s", g_exe_dir, path);
-    if (try_resolve_path(candidate, resolved, resolved_cap)) return 1;
-
-    snprintf(candidate, sizeof(candidate), "%.4000s/../lib/eigenscript/%.4000s", g_exe_dir, path);
-    if (try_resolve_path(candidate, resolved, resolved_cap)) RESOLVED(EIGS_RESOLVE_STDLIB_ROOT);
-
-    if (strncmp(path, "lib/", 4) == 0) {
-        snprintf(candidate, sizeof(candidate), "%.4000s/../lib/eigenscript/%.4000s", g_exe_dir, path + 4);
-        if (try_resolve_path(candidate, resolved, resolved_cap)) RESOLVED(EIGS_RESOLVE_STDLIB_ROOT);
-    }
-
-    const char *home = getenv("HOME");
-    if (home) {
-        snprintf(candidate, sizeof(candidate), "%.2000s/.local/lib/eigenscript/%.4000s", home, path);
-        if (try_resolve_path(candidate, resolved, resolved_cap)) RESOLVED(EIGS_RESOLVE_STDLIB_ROOT);
-
-        if (strncmp(path, "lib/", 4) == 0) {
-            snprintf(candidate, sizeof(candidate), "%.2000s/.local/lib/eigenscript/%.4000s", home, path + 4);
-            if (try_resolve_path(candidate, resolved, resolved_cap)) RESOLVED(EIGS_RESOLVE_STDLIB_ROOT);
-        }
-    }
-
-    return 0;
-#undef RESOLVED
-}
-
-int resolve_eigenscript_file_from(const char *base, const char *path,
-                                   char *resolved, size_t resolved_cap) {
-    return resolve_eigenscript_file_from_ex(base, path, resolved, resolved_cap, NULL);
-}
-
-/* #1046: THE import resolver. `import NAME` used to be resolved INLINE in the
- * OP_IMPORT handler (vm.c), which is why #915 shipped with the import half of
- * the observer gate open: the gate's compile-time pass needed to find the
- * module an import will run, and a second copy of that logic would have been
- * a resolver free to drift from the first (#737). Now both callers ask this
- * one function, so the file the gate inspects is the file the import runs.
- *
- * The chain (#821/#904/#1056): the PROJECT request `<name>.eigs` and the
- * STDLIB request `lib/<name>.eigs` are both probed through
- * resolve_eigenscript_file_from_ex; a project hit that came from an installed
- * stdlib root is the stdlib wearing a project-shaped request and is demoted;
- * project wins over stdlib. Returns 1 with `resolved` filled. `shadowed`
- * (optional) receives the realpath of a stdlib module that a GENUINELY
- * distinct project file shadows, else "" -- the caller decides whether to
- * warn (the VM does, once per name; the gate's pass never does). */
-int eigs_import_resolve(const char *base, const char *name,
-                        char *resolved, size_t resolved_cap,
-                        char *shadowed, size_t shadowed_cap) {
-    /* HEAP, not stack. This runs inside vm_execute's OP_IMPORT handler, and
-     * vm_execute recurses on nested imports; ~28 KiB of path scratch per
-     * level is the shape .claude/rules/c-runtime-memory.md's C-stack rule
-     * (and tools/embed_stack_soak.sh's 64 KiB rlimit) exists to catch. */
-    struct { char request[4096]; char stdlib_buf[8192]; char ureal[8192]; char sreal[8192]; } *b;
-    int user_origin = EIGS_RESOLVE_PROJECT;
-    int rc = 0;
-    if (shadowed && shadowed_cap) shadowed[0] = '\0';
-    if (!name || !resolved || resolved_cap == 0) return 0;
-    b = malloc(sizeof *b);
-    if (!b) return 0;   /* unresolvable is the conservative answer everywhere this is asked */
-
-    snprintf(b->request, sizeof(b->request), "%.1024s.eigs", name);
-    int user_hit = resolve_eigenscript_file_from_ex(base, b->request, resolved, resolved_cap,
-                                                     &user_origin);
-    snprintf(b->request, sizeof(b->request), "lib/%.1024s.eigs", name);
-    int stdlib_hit = resolve_eigenscript_file_from_ex(base, b->request, b->stdlib_buf,
-                                                       sizeof(b->stdlib_buf), NULL);
-    if (user_hit && stdlib_hit && user_origin == EIGS_RESOLVE_STDLIB_ROOT)
-        user_hit = 0;
-    if (!user_hit && !stdlib_hit) goto done;
-    rc = 1;
-    if (!user_hit) {
-        snprintf(resolved, resolved_cap, "%s", b->stdlib_buf);
-        goto done;
-    }
-    if (stdlib_hit && shadowed && shadowed_cap) {
-        /* Same-file double hit is possible (a chain step that resolves both
-         * request shapes to one path after symlinks) -- only a genuinely
-         * forked resolution is a collision. */
-        if (!realpath(resolved, b->ureal)) snprintf(b->ureal, sizeof(b->ureal), "%s", resolved);
-        if (!realpath(b->stdlib_buf, b->sreal)) snprintf(b->sreal, sizeof(b->sreal), "%s", b->stdlib_buf);
-        if (strcmp(b->ureal, b->sreal) != 0) snprintf(shadowed, shadowed_cap, "%s", b->sreal);
-    }
-done:
-    free(b);
-    return rc;
-}
 
 Value* builtin_load_file(Value *arg) {
     if (!arg || arg->type != VAL_STR) {
diff --git a/src/builtins_internal.h b/src/builtins_internal.h
index 71d2e661..f3f7098f 100644
--- a/src/builtins_internal.h
+++ b/src/builtins_internal.h
@@ -44,6 +44,33 @@ Value* builtin_sgd_update_cols(Value *arg);
 Value* builtin_tensor_save(Value *arg);
 Value* builtin_tensor_load(Value *arg);
 
+/* builtins_buf.c (#744) — numeric buffers, the vectorized buf_* kernels,
+ * the PCM16LE codecs and the DEFLATE codecs. Registered by builtins.c's
+ * register_builtins, which is why the prototypes belong here. */
+Value* builtin_buffer(Value *arg);
+Value* builtin_reshape(Value *arg);
+Value* builtin_buf_len(Value *arg);
+Value* builtin_buf_get(Value *arg);
+Value* builtin_buf_set(Value *arg);
+Value* builtin_buf_from_list(Value *arg);
+Value* builtin_str_from_bytes(Value *arg);
+Value* builtin_f64_to_bytes(Value *arg);
+Value* builtin_f64_from_bytes(Value *arg);
+Value* builtin_buf_copy(Value *arg);
+Value* builtin_buf_mix(Value *arg);
+Value* builtin_buf_scale_range(Value *arg);
+Value* builtin_buf_fill(Value *arg);
+Value* builtin_buf_peak(Value *arg);
+Value* builtin_buf_dot(Value *arg);
+Value* builtin_buf_from_pcm16le(Value *arg);
+Value* builtin_buf_to_pcm16le(Value *arg);
+Value* builtin_buf_deinterleave(Value *arg);
+Value* builtin_buf_resample_linear(Value *arg);
+Value* builtin_inflate(Value *arg);
+Value* builtin_zlib_inflate(Value *arg);
+Value* builtin_deflate(Value *arg);
+Value* builtin_zlib_deflate(Value *arg);
+
 /* builtins_host.c (#741) — every builtin needing a real OS underneath.
  * Whole-TU gated: under EIGENSCRIPT_FREESTANDING this registers nothing. */
 void register_host_builtins(Env *env);
diff --git a/src/builtins_tensor.c b/src/builtins_tensor.c
index cc804d2c..6b988ff2 100644
--- a/src/builtins_tensor.c
+++ b/src/builtins_tensor.c
@@ -13,8 +13,8 @@
 
 /* Forward decls for helpers shared with the arena/observer machinery. */
 Value* make_num_permanent(double n);
-/* The one consuming builtin — call_eigs_fn must not touch `arg` after it. */
-extern Value* builtin_free_val(Value *arg);
+/* builtin_free_val — the one consuming builtin, call_eigs_fn must not touch
+ * `arg` after it — is declared in vm.h (#744). */
 
 /* Shared double-precision tensor kernels. These live in this always-compiled
  * translation unit so model-enabled and model-disabled builds execute the
diff --git a/src/compiler.c b/src/compiler.c
index df493516..a88fed12 100644
--- a/src/compiler.c
+++ b/src/compiler.c
@@ -4,6 +4,7 @@
 
 #include "eigenscript.h"
 #include "env_flag.h"
+#include "fsutil.h"
 #include "vm.h"
 #include "trace.h"
 #include <stdio.h>
diff --git a/src/eigenscript.h b/src/eigenscript.h
index 2d5b814f..21e60644 100644
--- a/src/eigenscript.h
+++ b/src/eigenscript.h
@@ -1603,6 +1603,10 @@ void env_set_local_hashed(Env *env, const char *name, uint32_t h, Value *val);
  * never round-trip through make_num + val_decref. Reference-count
  * semantics match the Value* variants: env *borrows* the input slot and
  * incref's internally, *_get returns a slot the caller must slot_decref. */
+/* #868/#908: how many assignments this binding has seen, for the `when <n>`
+ * ordinal space. Defined in eigenscript.c; the VM's OP_PREV_N path is the
+ * only other consumer (it used to re-extern it by hand — #744). */
+int env_get_assign_count(Env *env, const char *name, uint32_t h);
 void env_set_hashed_slot(Env *env, const char *name, uint32_t h, EigsSlot s);
 void env_set_local_hashed_slot(Env *env, const char *name, uint32_t h, EigsSlot s);
 /* Same as env_set_local_hashed_slot, but `interned` must come from
@@ -1774,34 +1778,11 @@ const char* err_kind_name(ErrKind k);
 const char* eigs_predicate_name(unsigned kind);
 void rt_error(ErrKind kind, int line, const char *fmt, ...)
     __attribute__((format(printf, 3, 4)));
-char* read_file_util(const char *path, long *out_size);
-int resolve_eigenscript_file(const char *path, char *resolved, size_t resolved_cap);
 /* File provenance is retained by the executing chunk, including closures. */
 const char *eigs_current_file_dir(void);
-char *eigs_file_directory(const char *path); /* hosted; caller frees */
-void eigs_file_resolve_error(const char *operation, const char *base,
-                            const char *path, int line); /* hosted */
-/* One chain for import/load_file; base is the containing file's directory. */
-int resolve_eigenscript_file_from(const char *base, const char *path,
-                                   char *resolved, size_t resolved_cap);
-/* #904: which half of the chain answered. The chain's tail steps are the
- * installed stdlib roots (`<prefix>/lib/eigenscript/`, `~/.local/lib/
- * eigenscript/`), and they answer a bare `<name>.eigs` request as well as
- * `lib/<name>.eigs` — so a STDLIB_ROOT hit on a bare request is the stdlib
- * itself, not a project file shadowing it. */
-#define EIGS_RESOLVE_PROJECT       0
-#define EIGS_RESOLVE_STDLIB_ROOT   1
-int resolve_eigenscript_file_from_ex(const char *base, const char *path,
-                                      char *resolved, size_t resolved_cap,
-                                      int *origin);
-/* #1046: the ONE `import NAME` resolver -- project-first, then stdlib --
- * shared by OP_IMPORT (vm.c) and the observer gate's compile-time pass
- * (compiler.c). `shadowed` (optional) receives the stdlib path a distinct
- * project file shadows, else "". Hosted; the freestanding stub resolves
- * nothing. */
-int eigs_import_resolve(const char *base, const char *name,
-                        char *resolved, size_t resolved_cap,
-                        char *shadowed, size_t shadowed_cap);
+/* Reading a file and resolving a module request are declared in fsutil.h
+ * (#744) — a consumer says so by including it, instead of getting them for
+ * free from this umbrella. */
 Value* eigs_json_parse_value(const char *s, int *pos);
 /* #777: the ONLY entry point for a top-level (non-recursive) JSON parse.
  * Clears both thread-local parse flags (g_json_parse_err,
@@ -1915,10 +1896,6 @@ void   handle_release(int id);
 /* ---- EigenStore embedded database ---- */
 void register_store_builtins(Env *env);
 
-/* ---- gfx extension registrar (ext_gfx.c; TU only compiled when
- * EIGENSCRIPT_EXT_GFX — call sites keep the #if, matching http/db). ---- */
-void register_gfx_builtins(Env *env);
-
 /* ---- Tape-stepper (#418; step.c, CLI-only) ----
  * Interactive debugger over a recorded trace tape: `--step <tape> [src]`.
  * Returns the process exit code (3 = version refusal, the replay rule). */
diff --git a/src/eigs_embed.c b/src/eigs_embed.c
index 5aa6a834..8d404d7a 100644
--- a/src/eigs_embed.c
+++ b/src/eigs_embed.c
@@ -8,6 +8,7 @@
  * the multi-state model — not new behavior.
  */
 #include "eigenscript.h"
+#include "fsutil.h"
 #include "state.h"
 #include "vm.h"
 #include "trace.h"
diff --git a/src/ext_db_internal.h b/src/ext_db_internal.h
index 86ed22f0..c123751b 100644
--- a/src/ext_db_internal.h
+++ b/src/ext_db_internal.h
@@ -7,6 +7,7 @@
 #define EXT_DB_INTERNAL_H
 
 #include "eigenscript.h"
+#include "ext_register.h"   /* register_db_builtins / ext_db_state_destroy (#744) */
 #include <libpq-fe.h>
 
 /* #739: per-STATE connection, reached through the attached thread — the same
@@ -14,9 +15,4 @@
  * eigenscript.h so libpq's types stay out of the core header. */
 #define g_db_conn (*(PGconn **)&eigs_current->state->ext_db_conn)
 
-void register_db_builtins(Env *env);
-
-/* Closes this state's connection; called from eigs_state_destroy. */
-void ext_db_state_destroy(EigsState *st);
-
 #endif
diff --git a/src/ext_gfx.c b/src/ext_gfx.c
index 48d2ecc7..5ae36bb4 100644
--- a/src/ext_gfx.c
+++ b/src/ext_gfx.c
@@ -9,6 +9,7 @@
  */
 
 #include "eigenscript.h"
+#include "ext_register.h"   /* register_gfx_builtins (#744) */
 #include "ext_names.h"
 #include "trace.h"   /* audio capture is a nondet input source (#579) */
 
diff --git a/src/ext_http_internal.h b/src/ext_http_internal.h
index cdd34f07..eb2d8695 100644
--- a/src/ext_http_internal.h
+++ b/src/ext_http_internal.h
@@ -7,6 +7,7 @@
 #define EXT_HTTP_INTERNAL_H
 
 #include "eigenscript.h"
+#include "ext_register.h"   /* register_http_builtins / ext_http_state_destroy (#744) */
 #include "vm.h"
 #include <pthread.h>
 
@@ -57,16 +58,11 @@ typedef struct EigsHttpServer Server;
 extern __thread Server *eigs_http_active;
 #define g_server (*eigs_http_active)
 
-void register_http_builtins(Env *env);
 /* Subset for worker states: registers only the read-the-current-request
  * builtins (request_body / session_id / request_headers / http_post).
  * Skips the server-config builtins and does NOT allocate a Server, so
  * pooled per-connection states stay cheap. */
 void register_http_request_builtins(Env *env);
 void http_serve_blocking(int port);
-/* Called from eigs_state_destroy. Frees route allocations + the Server
- * struct itself and nils state->ext_http_server. No-op when the state
- * never had a Server (script never imported http). */
-void ext_http_state_destroy(EigsState *st);
 
 #endif
diff --git a/src/ext_net_internal.h b/src/ext_net_internal.h
index bc02e15d..c835f7e5 100644
--- a/src/ext_net_internal.h
+++ b/src/ext_net_internal.h
@@ -9,6 +9,7 @@
 #define EXT_NET_INTERNAL_H
 
 #include "eigenscript.h"
+#include "ext_register.h"   /* register_net_builtins (#744) */
 
 /* One row per live socket, owned by the process handle table
  * (HANDLE_NET). Listeners and connections share the struct; `kind`
@@ -21,6 +22,5 @@ typedef struct {
     EigsNetSockKind kind;
 } EigsNetSock;
 
-void register_net_builtins(Env *env);
 
 #endif
diff --git a/src/ext_register.h b/src/ext_register.h
new file mode 100644
index 00000000..74901ebe
--- /dev/null
+++ b/src/ext_register.h
@@ -0,0 +1,41 @@
+/*
+ * Extension entry points reachable from the CORE (#744).
+ *
+ * The core builtin registration seam (builtins.c) and state teardown
+ * (state.c) call into every optional extension. They used to reach those
+ * entry points through each extension's PRIVATE header — `ext_db_internal.h`
+ * (which pulls <libpq-fe.h>, so the core TU could not compile in the `full`
+ * variant without PostgreSQL headers on the include path), `model_internal.h`
+ * (the whole transformer type set) and `ext_http_internal.h` (the Server
+ * struct + pthread) — for a single function declaration each, and state.c
+ * carried two hand-written `extern`s for the same reason. Those were the only
+ * core -> ext include edges in the tree.
+ *
+ * This header is the seam instead: entry points only, no extension types, no
+ * extension system headers. A private header stays private to its extension.
+ *
+ * Declarations are UNGUARDED and the call sites keep their `#if
+ * EIGENSCRIPT_EXT_*` — the pattern `register_gfx_builtins` already used. A
+ * declaration of a function that this variant does not compile is inert; the
+ * guard that matters is the one on the call.
+ */
+
+#ifndef EXT_REGISTER_H
+#define EXT_REGISTER_H
+
+#include "eigenscript.h"
+
+/* Registrars — called from register_builtins (builtins.c), the ONE env
+ * composition seam (#742). */
+void register_http_builtins(Env *env);   /* ext_http.c  */
+void register_db_builtins(Env *env);     /* ext_db.c    */
+void register_net_builtins(Env *env);    /* ext_net.c   */
+void register_model_builtins(Env *env);  /* model_train.c */
+void register_gfx_builtins(Env *env);    /* ext_gfx.c   */
+
+/* Per-state teardown — called from eigs_state_destroy (state.c). Each is a
+ * no-op for a state that never registered the extension's builtins. */
+void ext_http_state_destroy(EigsState *st);   /* ext_http.c */
+void ext_db_state_destroy(EigsState *st);     /* ext_db.c   */
+
+#endif
diff --git a/src/fmt.c b/src/fmt.c
index 6db881b7..d6b60caf 100644
--- a/src/fmt.c
+++ b/src/fmt.c
@@ -7,6 +7,7 @@
  */
 
 #include "eigenscript.h"
+#include "fsutil.h"
 
 /* ---- helpers ---- */
 
diff --git a/src/fsutil.c b/src/fsutil.c
new file mode 100644
index 00000000..58eaf5ff
--- /dev/null
+++ b/src/fsutil.c
@@ -0,0 +1,300 @@
+/*
+ * Filesystem utilities — the leaf TU (#744).
+ *
+ * Reading a source file and resolving a module request are needed by the VM
+ * (OP_IMPORT), the compiler (the #915 observer gate's load pre-pass), main.c,
+ * fmt.c, lint_host.c and the embedding API. They used to live inside the
+ * builtins layer, so every one of those consumers reached DOWNWARD into a
+ * builtins TU and nothing could link file reading without it — which is the
+ * measured reason the LSP and fuzz link lists gave up on hand-picked subsets.
+ * They are not builtins: no `Value`, no `Env`, no registration.
+ *
+ * Whole-TU freestanding gate, the ext_store.c / builtins_host.c pattern: with
+ * no filesystem the resolvers are linkable stubs that resolve nothing, and
+ * read_file_util does not exist at all (callers guard on
+ * EIGENSCRIPT_FREESTANDING — see compiler.c's load pre-pass).
+ */
+
+#include "eigenscript.h"
+#include "fsutil.h"
+
+#if EIGENSCRIPT_FREESTANDING
+
+/* Linkable no-op surface: nothing resolves without a filesystem. */
+int resolve_eigenscript_file_from(const char *base, const char *path,
+                                   char *resolved, size_t resolved_cap) {
+    (void)base; (void)path; (void)resolved; (void)resolved_cap;
+    return 0;   /* nothing resolves without a filesystem */
+}
+
+int resolve_eigenscript_file_from_ex(const char *base, const char *path,
+                                      char *resolved, size_t resolved_cap,
+                                      int *origin) {
+    (void)base; (void)path; (void)resolved; (void)resolved_cap;
+    if (origin) *origin = EIGS_RESOLVE_PROJECT;
+    return 0;
+}
+
+int eigs_import_resolve(const char *base, const char *name,
+                        char *resolved, size_t resolved_cap,
+                        char *shadowed, size_t shadowed_cap) {
+    (void)base; (void)name; (void)resolved; (void)resolved_cap;
+    if (shadowed && shadowed_cap) shadowed[0] = '\0';
+    return 0;   /* nothing resolves without a filesystem */
+}
+
+#else /* host profile */
+
+#include <sys/stat.h>
+#include <unistd.h>
+#include <limits.h>
+
+/* File I/O helper — used by load_file and main() */
+char* read_file_util(const char *path, long *out_size) {
+    FILE *f = fopen(path, "rb");
+    if (!f) return NULL;
+    /* #314: fopen succeeds on a directory, and ftell then reports LONG_MAX —
+     * which sailed straight into xmalloc's fatal-OOM abort. Reject
+     * directories here so callers hit their existing clean error paths. */
+    struct stat st;
+    if (fstat(fileno(f), &st) == 0 && !S_ISREG(st.st_mode)) { fclose(f); return NULL; }
+    fseek(f, 0, SEEK_END);
+    long size = ftell(f);
+    if (size < 0 || size == LONG_MAX) { fclose(f); return NULL; }
+    fseek(f, 0, SEEK_SET);
+    char *buf = xmalloc(size + 1);
+    if (!buf) { fclose(f); return NULL; }
+    size_t got = fread(buf, 1, size, f);
+    fclose(f);
+    if ((long)got != size) { free(buf); return NULL; }
+    buf[size] = '\0';
+    if (out_size) *out_size = size;
+    return buf;
+}
+
+static int try_resolve_path(const char *candidate, char *resolved, size_t resolved_cap) {
+    if (!candidate || access(candidate, F_OK) != 0) return 0;
+    snprintf(resolved, resolved_cap, "%s", candidate);
+    return 1;
+}
+
+/* Canonical file provenance: symlink entry points and nested loads agree with
+ * import. Heap-owned because this helper also runs on compiler paths. */
+char *eigs_file_directory(const char *path) {
+    char *dir = realpath(path, NULL);
+    if (!dir) dir = xstrdup(path);
+    char *slash = strrchr(dir, '/');
+    if (slash == dir) dir[1] = '\0';
+    else if (slash) *slash = '\0';
+    else { free(dir); dir = xstrdup("."); }
+    return dir;
+}
+
+static int parent_directory(char *dir) {
+    char *slash = strrchr(dir, '/');
+    if (!slash || strcmp(dir, "/") == 0) return 0;
+    if (slash == dir) dir[1] = '\0';
+    else *slash = '\0';
+    return 1;
+}
+
+/* The nearest eigs.json is the project boundary, for both package lookup
+ * and root-relative paths. No cwd or one-parent fallback participates. */
+static char *project_directory(const char *base) {
+    char *dir = realpath(base, NULL);
+    if (!dir) return NULL;
+    char *marker = xmalloc(strlen(dir) + sizeof("/eigs.json"));
+    do {
+        size_t dir_len = strlen(dir);
+        memcpy(marker, dir, dir_len);
+        memcpy(marker + dir_len, "/eigs.json", sizeof("/eigs.json"));
+        if (access(marker, F_OK) == 0) { free(marker); return dir; }
+    } while (parent_directory(dir));
+    free(marker);
+    free(dir);
+    return NULL;
+}
+
+void eigs_file_resolve_error(const char *operation, const char *base,
+                            const char *path, int line) {
+    char *project = project_directory(base);
+    const char *home = getenv("HOME");
+    rt_error(EK_IO, line,
+        "%s: cannot read '%s' (not found or unreadable); tried containing directory '%s', "
+        "eigs_modules walk, %s%s; stdlib roots '%s/../<path>', "
+        "'%s/../lib/eigenscript', '%s/.local/lib/eigenscript' "
+        "(also stripping lib/; absolute paths are used as-is)",
+        operation, path, base, project ? "project root " : "no eigs.json above ",
+        project ? project : base, g_exe_dir, g_exe_dir,
+        home ? home : "<HOME unset>");
+    free(project);
+}
+
+/* Phase 0c: walk from `base` upward looking for
+ *   <dir>/eigs_modules/<name>/<name>.eigs
+ * at each level. Stop at the project root (a directory containing
+ * eigs.json) — its eigs_modules/ is checked once, then we don't go
+ * higher. Only fires for bare `<name>.eigs` requests (no slashes); the
+ * resolver's existing chain still handles paths with directory
+ * components. Bounded to 64 levels for safety. */
+static int try_eigs_modules_walk(const char *base, const char *path,
+                                  char *resolved, size_t resolved_cap) {
+    if (!base || !base[0] || !path) return 0;
+    if (strchr(path, '/')) return 0;
+    size_t plen = strlen(path);
+    if (plen < 6 || strcmp(path + plen - 5, ".eigs") != 0) return 0;
+    if (plen - 5 >= 512) return 0;
+
+    char name[512];
+    memcpy(name, path, plen - 5);
+    name[plen - 5] = '\0';
+
+    char cur[4096];
+    snprintf(cur, sizeof(cur), "%s", base);
+
+    for (int i = 0; i < 64; i++) {
+        char candidate[8192];
+        snprintf(candidate, sizeof(candidate),
+                 "%.3000s/eigs_modules/%.500s/%.500s.eigs",
+                 cur, name, name);
+        if (try_resolve_path(candidate, resolved, resolved_cap)) return 1;
+
+        char marker[4400];
+        snprintf(marker, sizeof(marker), "%.4000s/eigs.json", cur);
+        if (access(marker, F_OK) == 0) return 0;
+
+        if (!parent_directory(cur)) return 0;
+    }
+    return 0;
+}
+
+int resolve_eigenscript_file_from_ex(const char *base, const char *path,
+                                      char *resolved, size_t resolved_cap,
+                                      int *origin) {
+    char candidate[8192];
+
+    /* #904: report which half of the chain answered. The tail steps below
+     * are the *installed stdlib roots* (`<prefix>/lib/eigenscript/`, from
+     * `make install`), and they answer a bare `<name>.eigs` request just as
+     * readily as `lib/<name>.eigs` — so a hit there is the stdlib wearing a
+     * project-shaped request, not a project file. Callers that must tell
+     * the two apart (import's collision diagnostic) pass `origin`. */
+#define RESOLVED(step)                                                       \
+    do { if (origin) *origin = (step); return 1; } while (0)
+
+    if (origin) *origin = EIGS_RESOLVE_PROJECT;
+    if (!path || !resolved || resolved_cap == 0) return 0;
+    if (!base || !base[0]) base = eigs_current_file_dir();
+
+    if (path[0] == '/') {
+        return try_resolve_path(path, resolved, resolved_cap);
+    }
+
+    snprintf(candidate, sizeof(candidate), "%.4000s/%.4000s", base, path);
+    if (try_resolve_path(candidate, resolved, resolved_cap)) return 1;
+
+    if (try_eigs_modules_walk(base, path, resolved, resolved_cap)) return 1;
+
+    char *project = project_directory(base);
+    if (project) {
+        snprintf(candidate, sizeof(candidate), "%.4000s/%.4000s", project, path);
+        free(project);
+        if (try_resolve_path(candidate, resolved, resolved_cap)) return 1;
+    }
+
+    snprintf(candidate, sizeof(candidate), "%.4000s/../%.4000s", g_exe_dir, path);
+    if (try_resolve_path(candidate, resolved, resolved_cap)) return 1;
+
+    snprintf(candidate, sizeof(candidate), "%.4000s/../lib/eigenscript/%.4000s", g_exe_dir, path);
+    if (try_resolve_path(candidate, resolved, resolved_cap)) RESOLVED(EIGS_RESOLVE_STDLIB_ROOT);
+
+    if (strncmp(path, "lib/", 4) == 0) {
+        snprintf(candidate, sizeof(candidate), "%.4000s/../lib/eigenscript/%.4000s", g_exe_dir, path + 4);
+        if (try_resolve_path(candidate, resolved, resolved_cap)) RESOLVED(EIGS_RESOLVE_STDLIB_ROOT);
+    }
+
+    const char *home = getenv("HOME");
+    if (home) {
+        snprintf(candidate, sizeof(candidate), "%.2000s/.local/lib/eigenscript/%.4000s", home, path);
+        if (try_resolve_path(candidate, resolved, resolved_cap)) RESOLVED(EIGS_RESOLVE_STDLIB_ROOT);
+
+        if (strncmp(path, "lib/", 4) == 0) {
+            snprintf(candidate, sizeof(candidate), "%.2000s/.local/lib/eigenscript/%.4000s", home, path + 4);
+            if (try_resolve_path(candidate, resolved, resolved_cap)) RESOLVED(EIGS_RESOLVE_STDLIB_ROOT);
+        }
+    }
+
+    return 0;
+#undef RESOLVED
+}
+
+int resolve_eigenscript_file_from(const char *base, const char *path,
+                                   char *resolved, size_t resolved_cap) {
+    return resolve_eigenscript_file_from_ex(base, path, resolved, resolved_cap, NULL);
+}
+
+/* #1046: THE import resolver. `import NAME` used to be resolved INLINE in the
+ * OP_IMPORT handler (vm.c), which is why #915 shipped with the import half of
+ * the observer gate open: the gate's compile-time pass needed to find the
+ * module an import will run, and a second copy of that logic would have been
+ * a resolver free to drift from the first (#737). Now both callers ask this
+ * one function, so the file the gate inspects is the file the import runs.
+ *
+ * The chain (#821/#904/#1056): the PROJECT request `<name>.eigs` and the
+ * STDLIB request `lib/<name>.eigs` are both probed through
+ * resolve_eigenscript_file_from_ex; a project hit that came from an installed
+ * stdlib root is the stdlib wearing a project-shaped request and is demoted;
+ * project wins over stdlib. Returns 1 with `resolved` filled. `shadowed`
+ * (optional) receives the realpath of a stdlib module that a GENUINELY
+ * distinct project file shadows, else "" -- the caller decides whether to
+ * warn (the VM does, once per name; the gate's pass never does). */
+int eigs_import_resolve(const char *base, const char *name,
+                        char *resolved, size_t resolved_cap,
+                        char *shadowed, size_t shadowed_cap) {
+    /* HEAP, not stack. This runs inside vm_execute's OP_IMPORT handler, and
+     * vm_execute recurses on nested imports; ~28 KiB of path scratch per
+     * level is the shape .claude/rules/c-runtime-memory.md's C-stack rule
+     * (and tools/embed_stack_soak.sh's 64 KiB rlimit) exists to catch. */
+    struct { char request[4096]; char stdlib_buf[8192]; char ureal[8192]; char sreal[8192]; } *b;
+    int user_origin = EIGS_RESOLVE_PROJECT;
+    int rc = 0;
+    if (shadowed && shadowed_cap) shadowed[0] = '\0';
+    if (!name || !resolved || resolved_cap == 0) return 0;
+    b = malloc(sizeof *b);
+    if (!b) return 0;   /* unresolvable is the conservative answer everywhere this is asked */
+
+    snprintf(b->request, sizeof(b->request), "%.1024s.eigs", name);
+    int user_hit = resolve_eigenscript_file_from_ex(base, b->request, resolved, resolved_cap,
+                                                     &user_origin);
+    snprintf(b->request, sizeof(b->request), "lib/%.1024s.eigs", name);
+    int stdlib_hit = resolve_eigenscript_file_from_ex(base, b->request, b->stdlib_buf,
+                                                       sizeof(b->stdlib_buf), NULL);
+    if (user_hit && stdlib_hit && user_origin == EIGS_RESOLVE_STDLIB_ROOT)
+        user_hit = 0;
+    if (!user_hit && !stdlib_hit) goto done;
+    rc = 1;
+    if (!user_hit) {
+        snprintf(resolved, resolved_cap, "%s", b->stdlib_buf);
+        goto done;
+    }
+    if (stdlib_hit && shadowed && shadowed_cap) {
+        /* Same-file double hit is possible (a chain step that resolves both
+         * request shapes to one path after symlinks) -- only a genuinely
+         * forked resolution is a collision. */
+        if (!realpath(resolved, b->ureal)) snprintf(b->ureal, sizeof(b->ureal), "%s", resolved);
+        if (!realpath(b->stdlib_buf, b->sreal)) snprintf(b->sreal, sizeof(b->sreal), "%s", b->stdlib_buf);
+        if (strcmp(b->ureal, b->sreal) != 0) snprintf(shadowed, shadowed_cap, "%s", b->sreal);
+    }
+done:
+    free(b);
+    return rc;
+}
+
+#endif /* EIGENSCRIPT_FREESTANDING */
+
+/* Base-relative wrapper, in BOTH profiles: it forwards to
+ * resolve_eigenscript_file_from, which exists in both (the freestanding arm
+ * resolves nothing). Lived in builtins.c only because the chain did. */
+int resolve_eigenscript_file(const char *path, char *resolved, size_t resolved_cap) {
+    return resolve_eigenscript_file_from(eigs_current_file_dir(), path, resolved, resolved_cap);
+}
diff --git a/src/fsutil.h b/src/fsutil.h
new file mode 100644
index 00000000..7eb5292b
--- /dev/null
+++ b/src/fsutil.h
@@ -0,0 +1,62 @@
+/*
+ * Filesystem utilities — reading a source file and resolving a module
+ * request (#744). Implemented in fsutil.c.
+ *
+ * A leaf: no Value, no Env, nothing from the builtins layer. It is a separate
+ * header rather than another block of the 1253-line eigenscript.h umbrella
+ * because the consumers are specific and nameable — the VM's OP_IMPORT, the
+ * compiler's observer-gate load pre-pass, main.c, fmt.c, lint_host.c, the
+ * embedding API and load_file — and a TU that reads files should have to say
+ * so.
+ *
+ * PROFILE: the whole implementation is gated (builtins_host.c's pattern).
+ * With no filesystem the three resolvers are linkable stubs that resolve
+ * nothing and `read_file_util` DOES NOT EXIST — guard its call sites on
+ * `#if !EIGENSCRIPT_FREESTANDING`, callees included (compiler.c records what
+ * happens when the guard covers the helper but not the callee: the release
+ * and ASan suites stay green and the LINK step of `make freestanding-check`
+ * breaks).
+ */
+
+#ifndef EIGENSCRIPT_FSUTIL_H
+#define EIGENSCRIPT_FSUTIL_H
+
+#include <stddef.h>
+#include "eigenscript.h"   /* EIGENSCRIPT_FREESTANDING, eigs_current_file_dir */
+
+#if !EIGENSCRIPT_FREESTANDING
+/* Whole file into a NUL-terminated heap buffer; NULL on any failure,
+ * including a non-regular file (#314). Caller frees. Hosted only. */
+char* read_file_util(const char *path, long *out_size);
+/* Canonical containing directory of `path`. Hosted; caller frees. */
+char *eigs_file_directory(const char *path);
+/* Raise EK_IO naming every root the chain tried. Hosted. */
+void eigs_file_resolve_error(const char *operation, const char *base,
+                            const char *path, int line);
+#endif
+
+/* One chain for import/load_file; base is the containing file's directory. */
+int resolve_eigenscript_file_from(const char *base, const char *path,
+                                   char *resolved, size_t resolved_cap);
+/* Same chain, based at the executing chunk's directory. */
+int resolve_eigenscript_file(const char *path, char *resolved, size_t resolved_cap);
+/* #904: which half of the chain answered. The chain's tail steps are the
+ * installed stdlib roots (`<prefix>/lib/eigenscript/`, `~/.local/lib/
+ * eigenscript/`), and they answer a bare `<name>.eigs` request as well as
+ * `lib/<name>.eigs` — so a STDLIB_ROOT hit on a bare request is the stdlib
+ * itself, not a project file shadowing it. */
+#define EIGS_RESOLVE_PROJECT       0
+#define EIGS_RESOLVE_STDLIB_ROOT   1
+int resolve_eigenscript_file_from_ex(const char *base, const char *path,
+                                      char *resolved, size_t resolved_cap,
+                                      int *origin);
+/* #1046: the ONE `import NAME` resolver -- project-first, then stdlib --
+ * shared by OP_IMPORT (vm.c) and the observer gate's compile-time pass
+ * (compiler.c). `shadowed` (optional) receives the stdlib path a distinct
+ * project file shadows, else "". Hosted; the freestanding stub resolves
+ * nothing. */
+int eigs_import_resolve(const char *base, const char *name,
+                        char *resolved, size_t resolved_cap,
+                        char *shadowed, size_t shadowed_cap);
+
+#endif /* EIGENSCRIPT_FSUTIL_H */
diff --git a/src/lint_host.c b/src/lint_host.c
index c4377bfa..67bd78df 100644
--- a/src/lint_host.c
+++ b/src/lint_host.c
@@ -9,6 +9,7 @@
 
 #include "eigenscript.h"
 #include "ext_names.h"
+#include "fsutil.h"
 #include "lint_internal.h"
 #include "vm.h"   /* #927: lint compiles the unit and discards the chunk */
 
diff --git a/src/main.c b/src/main.c
index c5ef942e..aabad033 100644
--- a/src/main.c
+++ b/src/main.c
@@ -4,6 +4,7 @@
 
 #include "eigenscript.h"
 #include "env_flag.h"
+#include "fsutil.h"
 #include "state.h"
 #include "vm.h"
 #include "trace.h"
diff --git a/src/model_internal.h b/src/model_internal.h
index 4d87dbe4..2b62bc3c 100644
--- a/src/model_internal.h
+++ b/src/model_internal.h
@@ -7,6 +7,7 @@
 #define MODEL_INTERNAL_H
 
 #include "eigenscript.h"
+#include "ext_register.h"   /* register_model_builtins (#744) */
 
 /* ---- Model types ---- */
 
@@ -208,7 +209,6 @@ Value* json_obj_get(Value *obj, const char *key);
 
 /* ---- Registration ---- */
 
-void register_model_builtins(Env *env);
 
 /* ---- Builtins — each file defines its own, registered by model_train.c ---- */
 
diff --git a/src/state.c b/src/state.c
index be79d091..b626eeb1 100644
--- a/src/state.c
+++ b/src/state.c
@@ -13,15 +13,11 @@
  * cpp/function-in-block, and the header owning it is not visible to this TU. */
 void eigs_obs_memo_release(void);
 
-#if EIGENSCRIPT_EXT_HTTP
-/* Forward-declared here to avoid pulling ext_http_internal.h (and its
- * pthread/socket includes) into core runtime TUs. Defined in ext_http.c. */
-extern void ext_http_state_destroy(EigsState *st);
-#endif
-#if EIGENSCRIPT_EXT_DB
-/* Same reason — declared here rather than including libpq. #739. */
-extern void ext_db_state_destroy(EigsState *st);
-#endif
+/* #739/#744: per-state extension teardown. The two hand-written externs that
+ * used to sit here (one per extension, to avoid pulling ext_http_internal.h's
+ * pthread/socket includes and ext_db_internal.h's libpq) are now one shared
+ * seam — declarations only, no extension types. */
+#include "ext_register.h"
 
 __thread EigsThread *eigs_current = NULL;
 
diff --git a/src/task.c b/src/task.c
new file mode 100644
index 00000000..534b5f68
--- /dev/null
+++ b/src/task.c
@@ -0,0 +1,853 @@
+/*
+ * The cooperative task scheduler (#408), split out of vm.c by #744.
+ *
+ * Self-contained by construction: `TaskScheduler` and every scheduler static
+ * live in THIS file and nothing outside it names them. The seam with the VM
+ * is task.h and is a handful of functions wide in each direction — the
+ * dispatch loop's slice hooks and `task_sched_after_outermost` going in, and
+ * `vm_task_run_entry` / `vm_task_resume` / `vm_task_take_error` coming back
+ * out. Those three are wrappers in vm.c, deliberately: the dispatch function
+ * they call stays `static` there.
+ *
+ * The scheduler is DETERMINISTIC — no tape records; the interleaving is a
+ * pure function of program order (or of the installed seed, #535). Nothing
+ * about that changes here: this file is the same statements at a new address.
+ */
+
+#include "eigenscript.h"
+#include "vm.h"
+#include "task.h"
+#include "trace.h"
+
+/* Forward decls for the file's own statics that are used before definition
+ * (these sat at the top of vm.c's dispatch loop before the split). */
+static void task_reap(Task *t);   /* #530 */
+
+/* ===== #408 cooperative task scheduler ==================================
+ * A trampoline just above the OUTERMOST vm_execute drives every task —
+ * including task 0 (the main program) — so C-stack depth stays flat
+ * (vm_execute → scheduler → one vm_run) no matter how often tasks ping-pong.
+ * A task suspends by a builtin setting g_task_suspend_request; the CASE(CALL)
+ * site saves its live stack+frame slice (the copying-stack model: memory =
+ * live depth, not a full 1.28 MB VM per task) and returns here, which runs
+ * the next ready task. Deterministic by construction — no tape records; the
+ * interleaving is a pure function of program order.
+ * ======================================================================== */
+
+#define TASK_READY_MAX HANDLE_TABLE_SIZE
+
+/* #846: one scheduler-trace entry — a resume. `seq` is the entry's index. */
+typedef struct {
+    double  tick;    /* virtual clock (task_now) at the resume */
+    int     task;    /* resumed task id (0 = main) */
+    uint8_t cause;   /* SCAUSE_* below */
+} SchedTraceEntry;
+
+typedef struct {
+    int   ready[TASK_READY_MAX];  /* circular FIFO of runnable task ids (0=main) */
+    int   rhead, rcount;
+    int   current;                /* running task id; 0 = main */
+    int   live;                   /* spawned tasks not yet DONE/DEAD */
+    int   active;                 /* armed on first spawn */
+    int   dead_letters;           /* inc 2: sends to finished/unknown tasks */
+    int   detached_err_count;     /* #530: reaped detached tasks that died unobserved (#493 gate) */
+    uint64_t spawn_counter;       /* #535: monotonically increasing; stamps Task.spawn_seq */
+    double now;                   /* inc 3: virtual clock (logical, starts 0) */
+    int   seeded;                 /* inc 4: 1 once task_sched_seed installs a seed */
+    uint64_t rng_state;           /* inc 4: splitmix64 state for the seeded pick */
+    /* #846: WHY each ready entry became runnable, kept in lockstep with
+     * `ready` (same index, moved by the same compaction). A property of the
+     * queue entry, not of the task: the cause is fixed at enqueue time and
+     * consumed by the pop that resumes the task. Always maintained — it is
+     * one byte store per enqueue — so arming the trace mid-run changes
+     * nothing about the schedule, only whether a pop is written down. */
+    uint8_t ready_cause[TASK_READY_MAX];
+    int   pop_cause;              /* #846: cause of the most recent sched_ready_pop */
+    /* #846: the recorded history — one entry per trampoline resume while
+     * g_task_trace_on. Freed in task_sched_thread_free. Unbounded by design:
+     * a silent cap would make a long run's trace lie about its tail. */
+    SchedTraceEntry *trace;
+    int   trace_count, trace_cap;
+    Task  main_task;              /* task 0 — save-buffer only, never "started" */
+} TaskScheduler;
+
+/* #846: the cause vocabulary, enumerated from the enqueue sites below — every
+ * sched_ready_push names one. A resumed task was enqueued by exactly one of:
+ *   spawn         task_sched_on_spawn — its first run (task_start)
+ *   yield         a task_yield re-enqueue (trampoline / main's first suspend)
+ *   sleep-wake    sched_wake_sleepers advanced the virtual clock to its wake_at
+ *   join-release  the task it was joined on finished (sched_finish)
+ *   kill-release  the task it was joined on was task_kill'ed (task_do_kill)
+ *   recv-wake     task_send delivered to its empty mailbox (task_deliver)
+ *   deadlock      main re-enqueued to receive the catchable deadlock (#509)
+ * Names are the .eigs-visible contract (docs/CONCURRENCY.md). */
+enum {
+    SCAUSE_SPAWN = 0, SCAUSE_YIELD, SCAUSE_SLEEP_WAKE, SCAUSE_JOIN_RELEASE,
+    SCAUSE_KILL_RELEASE, SCAUSE_RECV_WAKE, SCAUSE_DEADLOCK, SCAUSE__COUNT
+};
+static const char *const sched_cause_name[SCAUSE__COUNT] = {
+    "spawn", "yield", "sleep-wake", "join-release", "kill-release",
+    "recv-wake", "deadlock"
+};
+
+static TaskScheduler *sched_get(void) { return (TaskScheduler *)g_task_sched; }
+
+static TaskScheduler *sched_ensure(void) {
+    TaskScheduler *s = sched_get();
+    if (!s) {
+        s = xcalloc(1, sizeof(TaskScheduler));
+        s->main_task.id = 0;
+        s->main_task.state = TASK_RUNNING;
+        s->current = 0;
+        g_task_sched = s;
+    }
+    return s;
+}
+
+void task_sched_thread_free(void) {
+    TaskScheduler *s = sched_get();
+    if (!s) return;
+    Task *m = &s->main_task;
+    /* #483: main is USUALLY run-to-completion here (empty slice). But a fatal
+     * exit while main is still SUSPENDED — a `deadlock`, or main blocked on a
+     * join/recv that never resolves — leaves a live saved slice whose counted
+     * refs would otherwise leak: the base module frame owns a chunk ref (the
+     * script chunk, see vm_run's frame push), and the operand stack owns value
+     * refs. Release them, mirroring task_free's worker-slice teardown, before
+     * freeing the arrays. (owns_env is 0 for the module frame — the global env
+     * is dropped separately in main.c/eigs_close — so only chunk_decref here.) */
+    if (m->saved_stack) {
+        for (int i = 0; i < m->saved_stack_len; i++) slot_decref(m->saved_stack[i]);
+        free(m->saved_stack);
+    }
+    if (m->saved_frames) {
+        for (int i = 0; i < m->saved_frame_count; i++)
+            callframe_release(&m->saved_frames[i]);
+        free(m->saved_frames);
+    }
+    if (m->mbox) {
+        for (int i = 0; i < m->mbox_count; i++)
+            val_decref(m->mbox[(m->mbox_head + i) % m->mbox_cap]);
+        free(m->mbox);
+    }
+    if (m->result) val_decref(m->result);
+    if (m->error_value) val_decref(m->error_value);
+    free(s->trace);   /* #846 */
+    free(s);
+    g_task_sched = NULL;
+}
+
+static Task *sched_lookup(TaskScheduler *s, int id) {
+    if (id == 0) return &s->main_task;
+    return (Task *)handle_lookup(id, HANDLE_TASK);
+}
+
+/* #493: does any worker still carry an uncaught-error death that no task_join
+ * ever observed? Scanned once at process exit (before handle_table_drain frees
+ * the tasks) so a fire-and-forget worker's death makes the process exit
+ * non-zero instead of silently returning 0. */
+int task_any_unobserved_error(void) {
+    if (!g_task_sched) return 0;
+    /* #530: reaped detached tasks that died unobserved are counted, not held. */
+    if (((TaskScheduler *)g_task_sched)->detached_err_count > 0) return 1;
+    for (int i = 1; i < HANDLE_TABLE_SIZE; i++) {
+        Task *t = (Task *)handle_lookup(i, HANDLE_TASK);
+        if (t && t->err_unobserved) return 1;
+    }
+    return 0;
+}
+
+Task *task_current_running(void) {
+    TaskScheduler *s = sched_get();
+    return s ? sched_lookup(s, s->current) : NULL;
+}
+
+static void sched_ready_push(TaskScheduler *s, int id, int cause) {
+    if (s->rcount >= TASK_READY_MAX) return;   /* ids are table-bounded; can't overflow */
+    int slot = (s->rhead + s->rcount) % TASK_READY_MAX;
+    s->ready[slot] = id;
+    s->ready_cause[slot] = (uint8_t)cause;   /* #846: rides with the entry */
+    s->rcount++;
+}
+
+/* #530: drop tid's pending ready-queue entry. A task killed while READY (or
+ * woken but not yet run) used to leave its entry behind; the trampoline
+ * skips stale ids, but enough of them FILL the fixed queue and
+ * sched_ready_push silently drops real wakeups — a spurious "deadlock".
+ * A task has at most one entry (recv-wake is idempotent and a task must be
+ * popped before it can re-enqueue), so one compacting pass suffices. */
+static void sched_ready_remove(TaskScheduler *s, int tid) {
+    int w = 0;
+    for (int k = 0; k < s->rcount; k++) {
+        int from = (s->rhead + k) % TASK_READY_MAX;
+        int id = s->ready[from];
+        if (id != tid) {
+            int to = (s->rhead + w) % TASK_READY_MAX;
+            s->ready[to] = id;
+            s->ready_cause[to] = s->ready_cause[from];   /* #846: lockstep */
+            w++;
+        }
+    }
+    s->rcount = w;
+}
+
+/* Inc 4: splitmix64 — a deterministic, platform-independent integer PRNG for
+ * the seeded scheduling strategy. Pure integer arithmetic (no float, no OS
+ * entropy), so the pick sequence is a reproducible function of the installed
+ * seed + program order — the seeded schedule replays byte-identically and
+ * records no tape nondeterminism. */
+static uint64_t sched_rng_next(TaskScheduler *s) {
+    uint64_t z = (s->rng_state += 0x9E3779B97F4A7C15ULL);
+    z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9ULL;
+    z = (z ^ (z >> 27)) * 0x94D049BB133111EBULL;
+    return z ^ (z >> 31);
+}
+
+/* task_sched_seed: install a seed and switch the scheduler from FIFO
+ * round-robin to a seeded pseudo-random pick of the next ready task. Ensures
+ * the scheduler exists so the seed sticks even when set before the first
+ * task_spawn. The interleaving stays deterministic — a DST varies the seed to
+ * explore different interleavings, each fully reproducible. */
+void task_sched_set_seed(double seed) {
+    TaskScheduler *s = sched_ensure();
+    s->rng_state = (uint64_t)(int64_t)seed;   /* integer seeds; fractions truncate */
+    s->seeded = 1;
+}
+
+static int sched_ready_pop(TaskScheduler *s) {
+    if (s->rcount == 0) return -1;
+    if (!s->seeded || s->rcount == 1) {
+        /* Default FIFO: O(1) head pop — the fast path, unchanged. */
+        int id = s->ready[s->rhead];
+        s->pop_cause = s->ready_cause[s->rhead];   /* #846 */
+        s->rhead = (s->rhead + 1) % TASK_READY_MAX;
+        s->rcount--;
+        return id;
+    }
+    /* Seeded strategy: pick a pseudo-random ready task, then compact the hole
+     * by shifting the suffix down one (order-preserving among the rest). O(n)
+     * in the ready count, which is tiny and only paid in DST/seeded mode. */
+    int idx = (int)(sched_rng_next(s) % (uint64_t)s->rcount);
+    int id  = s->ready[(s->rhead + idx) % TASK_READY_MAX];
+    s->pop_cause = s->ready_cause[(s->rhead + idx) % TASK_READY_MAX];   /* #846 */
+    for (int k = idx; k < s->rcount - 1; k++) {
+        int to = (s->rhead + k) % TASK_READY_MAX, from = (s->rhead + k + 1) % TASK_READY_MAX;
+        s->ready[to] = s->ready[from];
+        s->ready_cause[to] = s->ready_cause[from];   /* #846: lockstep */
+    }
+    s->rcount--;
+    return id;
+}
+
+/* ---- #846: the scheduler trace ------------------------------------------
+ * Pure reader: called from the trampoline AFTER the pick is made and BEFORE
+ * the task runs, with nothing but scheduler state as input. No tape record —
+ * the schedule is a pure function of program order (+ seed), so a replayed
+ * run re-derives the identical history; a tape-recorded trace would be a
+ * second, redundant source of truth that could disagree with the first. */
+static void sched_trace_record(TaskScheduler *s, int id, int cause) {
+    if (s->trace_count == s->trace_cap) {
+        int nc = s->trace_cap ? s->trace_cap * 2 : 64;
+        s->trace = xrealloc(s->trace, sizeof(SchedTraceEntry) * (size_t)nc);
+        s->trace_cap = nc;
+    }
+    SchedTraceEntry *e = &s->trace[s->trace_count++];
+    e->tick  = s->now;
+    e->task  = id;
+    e->cause = (uint8_t)cause;
+}
+
+Value *task_sched_trace_read(void) {
+    TaskScheduler *s = sched_get();
+    if (!s) return make_list(0);
+    Value *out = make_list(s->trace_count);
+    for (int i = 0; i < s->trace_count; i++) {
+        const SchedTraceEntry *e = &s->trace[i];
+        Value *d = make_dict(4);
+        dict_set_owned(d, "seq",   make_num((double)i));
+        dict_set_owned(d, "tick",  make_num(e->tick));
+        dict_set_owned(d, "task",  make_num((double)e->task));
+        dict_set_owned(d, "cause", make_str(e->cause < SCAUSE__COUNT
+                                            ? sched_cause_name[e->cause] : "?"));
+        list_append_owned(out, d);
+    }
+    return out;
+}
+
+void task_sched_trace_clear(void) {
+    TaskScheduler *s = sched_get();
+    if (s) s->trace_count = 0;   /* keep the buffer; re-arming reuses it */
+}
+
+/* Copying-stack save: memcpy the running task's live slice [0,fc)/[0,sp) into
+ * its right-sized save-buffer, then retreat the VM to empty. Refs move WITH
+ * the bytes (the saved slots/frames own the same counted refs that were on
+ * the stack), so sp/frame_count just retreat — no incref/decref, no walk. */
+void task_save_slice(Task *t) {
+    if (!t) return;
+    int fc = g_vm.frame_count, sp = g_vm.sp;
+    free(t->saved_frames);
+    free(t->saved_stack);
+    t->saved_frames = fc ? xmalloc(sizeof(CallFrame) * fc) : NULL;
+    t->saved_stack  = sp ? xmalloc(sizeof(EigsSlot) * sp)  : NULL;
+    if (fc) memcpy(t->saved_frames, g_vm.frames, sizeof(CallFrame) * fc);
+    if (sp) memcpy(t->saved_stack,  g_vm.stack,  sizeof(EigsSlot) * sp);
+    t->saved_frame_count  = fc;
+    t->saved_stack_len    = sp;
+    t->saved_current_line = g_vm.current_line;
+    g_vm.frame_count = 0;
+    g_vm.sp = 0;
+    t->state = TASK_SUSPENDED;
+}
+
+/* Copying-stack restore: memcpy a suspended task's slice back onto the empty
+ * VM. Symmetric with save — refs move back with the bytes. */
+void task_restore_slice(Task *t) {
+    int fc = t->saved_frame_count, sp = t->saved_stack_len;
+    if (fc) memcpy(g_vm.frames, t->saved_frames, sizeof(CallFrame) * fc);
+    if (sp) memcpy(g_vm.stack,  t->saved_stack,  sizeof(EigsSlot) * sp);
+    g_vm.frame_count  = fc;
+    g_vm.sp           = sp;
+    g_vm.current_line = t->saved_current_line;
+    free(t->saved_frames); t->saved_frames = NULL;
+    free(t->saved_stack);  t->saved_stack  = NULL;
+    t->saved_frame_count = 0;
+    t->saved_stack_len   = 0;
+    t->state = TASK_RUNNING;
+}
+
+/* task_spawn (builtins.c) hands a freshly registered task here. */
+void task_sched_on_spawn(int id) {
+    TaskScheduler *s = sched_ensure();
+    s->active = 1;
+    s->live++;
+    /* #535: stamp spawn order. Handle IDs come from a rotating cursor, so
+     * they encode the process's WHOLE allocation history; any id-ordered
+     * tie-break makes the interleaving history-dependent. Spawn order is a
+     * pure function of the run. Main is 0 (spawn_counter starts at 1). */
+    Task *t = sched_lookup(s, id);
+    if (t) t->spawn_seq = ++s->spawn_counter;
+    sched_ready_push(s, id, SCAUSE_SPAWN);
+}
+
+/* task_yield: mark the current task for suspension; the trampoline re-enqueues
+ * it at the tail (round-robin) after the save. */
+void task_request_yield(void) { g_task_suspend_request = 1; }
+
+/* task_join: block the current task on `target`. Returns 0 for a bad target
+ * (main, self, or unknown) so the builtin can fall back; 1 to suspend. A
+ * target that is already finished is handled in the builtin (returns its
+ * result without suspending). */
+int task_request_join(int target) {
+    TaskScheduler *s = sched_get();
+    if (!s || target == 0 || target == s->current) return 0;
+    Task *tt = sched_lookup(s, target);
+    if (!tt) return 0;
+    Task *cur = sched_lookup(s, s->current);
+    cur->join_target = target;
+    g_task_suspend_request = 1;
+    return 1;
+}
+
+/* ---- Inc 2: mailboxes -------------------------------------------------- */
+
+/* Append msg (ownership transferred in) to task `tid`'s FIFO mailbox and wake
+ * it if it is blocked in task_recv. Returns 1 if delivered, 0 if dropped
+ * because the target is gone (finished/unknown) — send-to-dead is a silent
+ * drop plus a dead-letter count (Akka dead-letters / Erlang cast), NOT an
+ * error: an error path here would be a nondeterminism magnet. */
+int task_deliver(int tid, Value *msg_owned) {
+    TaskScheduler *s = sched_get();
+    Task *t = s ? sched_lookup(s, tid) : NULL;
+    if (!t || t->state == TASK_DONE || t->state == TASK_DEAD) {
+        if (s) s->dead_letters++;
+        return 0;
+    }
+    if (t->mbox_count >= t->mbox_cap) {
+        int nc = t->mbox_cap ? t->mbox_cap * 2 : 8;
+        Value **nb = xmalloc(sizeof(Value *) * nc);
+        for (int i = 0; i < t->mbox_count; i++)
+            nb[i] = t->mbox[(t->mbox_head + i) % t->mbox_cap];
+        free(t->mbox);
+        t->mbox = nb; t->mbox_cap = nc; t->mbox_head = 0;
+    }
+    t->mbox[(t->mbox_head + t->mbox_count) % t->mbox_cap] = msg_owned;
+    t->mbox_count++;
+    /* Wake a recv-blocked receiver on the FIRST message that arrives while it
+     * waits on an empty mailbox (mbox_count just became 1). recv_blocked stays
+     * set so the resume path (task_apply_recv_result) delivers this message and
+     * clears it; the mbox_count==1 guard makes the enqueue idempotent — a
+     * second send before the receiver resumes finds count>1 and does not
+     * re-enqueue (which would put the task in the ready queue twice). */
+    if (t->recv_blocked && t->state == TASK_SUSPENDED && t->mbox_count == 1)
+        sched_ready_push(s, tid, SCAUSE_RECV_WAKE);
+    return 1;
+}
+
+int task_mbox_has(void) {
+    Task *t = task_current_running();
+    return (t && t->mbox_count > 0) ? 1 : 0;
+}
+
+Value *task_mbox_pop(void) {
+    Task *t = task_current_running();
+    if (!t || t->mbox_count == 0) return make_null();
+    Value *v = t->mbox[t->mbox_head];
+    t->mbox_head = (t->mbox_head + 1) % t->mbox_cap;
+    t->mbox_count--;
+    return v;   /* owned ref transfers to caller */
+}
+
+void task_request_recv(void) {
+    Task *t = task_current_running();
+    if (t) t->recv_blocked = 1;
+    g_task_suspend_request = 1;
+}
+
+/* ---- Inc 3: virtual time ---------------------------------------------- */
+
+/* task_sleep: the current task becomes runnable again when the virtual clock
+ * reaches now + ticks. The trampoline advances the clock only when nothing is
+ * runnable (see sched_wake_sleepers), so time is a pure function of program
+ * order + sleep durations — no tape records, no wall clock. A negative sleep
+ * is clamped to 0 (a same-tick yield to everything currently ready). */
+void task_request_sleep(double ticks) {
+    TaskScheduler *s = sched_get();
+    Task *t = task_current_running();
+    if (!s || !t) return;
+    double dt = ticks > 0 ? ticks : 0;
+    t->wake_at = s->now + dt;
+    t->sleeping = 1;
+    g_task_suspend_request = 1;
+}
+
+double task_virtual_now(void) {
+    TaskScheduler *s = sched_get();
+    return s ? s->now : 0;
+}
+
+/* task_self (builtins.c): the running task's id, in the same integer space
+ * task_spawn returns — 0 for the main task, including before any scheduler
+ * exists. Pure scheduler state, so no tape participation. */
+int task_current_id(void) {
+    TaskScheduler *s = sched_get();
+    return s ? s->current : 0;
+}
+
+/* When the ready queue is empty, advance the virtual clock to the earliest
+ * sleeper's wake time and make every task due at (or before) that instant
+ * runnable. Returns 1 if any sleeper was woken (the trampoline then loops),
+ * 0 if there are no sleepers (genuine idle → done or deadlock). Ties at the
+ * same wake_at are broken by ascending task id (main = 0 first), so the
+ * interleaving stays deterministic. The clock only ever moves forward:
+ * wake_at = now + dt >= now, so the min is never behind the current now. */
+static int sched_wake_sleepers(TaskScheduler *s) {
+    double best = 0; int have_best = 0;
+    if (s->main_task.state == TASK_SUSPENDED && s->main_task.sleeping) {
+        best = s->main_task.wake_at; have_best = 1;
+    }
+    for (int i = 1; i < HANDLE_TABLE_SIZE; i++) {
+        Task *t = (Task *)handle_lookup(i, HANDLE_TASK);
+        if (t && t->state == TASK_SUSPENDED && t->sleeping &&
+            (!have_best || t->wake_at < best)) {
+            best = t->wake_at; have_best = 1;
+        }
+    }
+    if (!have_best) return 0;
+    s->now = best;
+    /* Wake main first, then tasks in ascending SPAWN order (#535) — NOT id
+     * order: ids come from a rotating next-fit cursor, so id order encodes
+     * the process's whole allocation history and two identical seeded runs
+     * in one process could interleave differently once slots recycle
+     * (surfaced by liferaft's in-sweep fault verify failing to reproduce
+     * standalone). Spawn order is a pure function of the run itself. */
+    if (s->main_task.state == TASK_SUSPENDED && s->main_task.sleeping &&
+        s->main_task.wake_at <= s->now) {
+        s->main_task.sleeping = 0;
+        sched_ready_push(s, 0, SCAUSE_SLEEP_WAKE);
+    }
+    for (;;) {
+        Task *next = NULL;
+        for (int i = 1; i < HANDLE_TABLE_SIZE; i++) {
+            Task *t = (Task *)handle_lookup(i, HANDLE_TASK);
+            if (t && t->state == TASK_SUSPENDED && t->sleeping && t->wake_at <= s->now &&
+                (!next || t->spawn_seq < next->spawn_seq))
+                next = t;
+        }
+        if (!next) break;
+        next->sleeping = 0;
+        sched_ready_push(s, next->id, SCAUSE_SLEEP_WAKE);
+    }
+    return 1;
+}
+
+/* Deterministic teardown of a task mid-run (task_kill): drop its mailbox and
+ * saved slice, wake any joiner with an `interrupt` error, mark it DEAD. The
+ * handle entry stays (task_alive → 0, joiners see DEAD); handle_table_drain
+ * frees the struct at exit. Returns 0 for a bad/self/finished target. */
+int task_do_kill(int tid) {
+    TaskScheduler *s = sched_get();
+    if (!s || tid == 0 || tid == s->current) return 0;
+    Task *t = sched_lookup(s, tid);
+    if (!t || t->state == TASK_DONE || t->state == TASK_DEAD) return 0;
+    /* #530: a READY/woken victim holds a ready-queue entry — remove it so
+     * dead ids can never fill the queue and starve real wakeups. */
+    sched_ready_remove(s, tid);
+    /* Drain the mailbox. */
+    while (t->mbox_count > 0) {
+        val_decref(t->mbox[t->mbox_head]);
+        t->mbox_head = (t->mbox_head + 1) % t->mbox_cap;
+        t->mbox_count--;
+    }
+    free(t->mbox); t->mbox = NULL; t->mbox_cap = 0; t->mbox_head = 0;
+    /* Release the suspended slice's counted refs (mirror task_free's slice
+     * teardown) so a killed suspended task doesn't leak. */
+    if (t->saved_stack) {
+        for (int i = 0; i < t->saved_stack_len; i++) slot_decref(t->saved_stack[i]);
+        free(t->saved_stack); t->saved_stack = NULL; t->saved_stack_len = 0;
+    }
+    if (t->saved_frames) {
+        for (int i = 0; i < t->saved_frame_count; i++) {
+            CallFrame *f = &t->saved_frames[i];
+            /* A task killed while suspended INSIDE a try never runs the
+             * matching TRY_ENDs, and g_try_depth is a process global, not
+             * per-task: leaving it elevated makes rt_error's `g_try_depth == 0`
+             * gate suppress the diagnostic of every later uncaught error in
+             * the process — confirmed, the program exits 1 in silence (#726). */
+            g_try_depth -= f->try_count;
+            callframe_release(f);
+        }
+        if (g_try_depth < 0) g_try_depth = 0;
+        free(t->saved_frames); t->saved_frames = NULL; t->saved_frame_count = 0;
+    }
+    if (t->run_env) { env_decref(t->run_env); t->run_env = NULL; }
+    t->has_error = 1;
+    t->state = TASK_DEAD;
+    s->live--;
+    /* Wake joiners with an interrupt: on resume task_apply_join_result sees
+     * has_error and re-raises. Give them an error payload. */
+    if (!t->error_value) {
+        Value *ev = make_dict(3);
+        dict_set_owned(ev, "kind", make_str(err_kind_name(EK_INTERRUPT)));
+        dict_set_owned(ev, "message", make_str("task was killed"));
+        dict_set_owned(ev, "line", make_num(0));
+        t->error_value = ev;
+    }
+    for (int i = 1; i < HANDLE_TABLE_SIZE; i++) {
+        Task *w = (Task *)handle_lookup(i, HANDLE_TASK);
+        if (w && w->state == TASK_SUSPENDED && w->join_target == tid)
+            sched_ready_push(s, w->id, SCAUSE_KILL_RELEASE);
+    }
+    if (s->main_task.state == TASK_SUSPENDED && s->main_task.join_target == tid)
+        sched_ready_push(s, 0, SCAUSE_KILL_RELEASE);
+    /* #530: kill of a detached task is an explicit discard — reap now. (Kill
+     * is a deliberate teardown, never an uncaught error: no #493 counting.) */
+    if (t->detached) task_reap(t);
+    return 1;
+}
+
+/* On resuming a recv-blocked task, fill the placeholder the task_recv builtin
+ * left on the stack top with the next mailbox message. */
+void task_apply_recv_result(Task *t) {
+    /* Only a task that suspended INSIDE task_recv has a placeholder to fill.
+     * A task resuming from a plain task_yield/task_join must NOT have its
+     * mailbox drained here, even if a message arrived meanwhile. */
+    if (!t->recv_blocked) return;
+    t->recv_blocked = 0;
+    if (g_vm.sp > 0) {
+        slot_decref(g_vm.stack[g_vm.sp - 1]);
+        Value *msg;
+        if (t->mbox_count > 0) {
+            msg = t->mbox[t->mbox_head];
+            t->mbox_head = (t->mbox_head + 1) % t->mbox_cap;
+            t->mbox_count--;
+        } else {
+            msg = make_null();   /* woken without a message (killed sender race) */
+        }
+        g_vm.stack[g_vm.sp - 1] = slot_from_heap(msg);
+    }
+}
+
+/* Start a never-run spawned task: bind its deep-copied args into a fresh env
+ * from the entry closure (the base frame borrows it — the Task owns run_env
+ * across suspend/resume), then run at base 0 so it is suspendable. Mirrors
+ * call_eigs_fn's param binding, but does not run to completion. */
+static Value *task_start(Task *t) {
+    Value *fn = t->entry_fn;
+    if (fn->type == VAL_BUILTIN) {          /* builtins never suspend — run direct */
+        Value *a = t->argc == 1 ? t->args[0] : make_null();
+        return fn->data.builtin(a);
+    }
+    Env *call_env = env_new(fn->data.fn.closure);
+    /* #989: same re-collect carve-out as every other entry point — a
+     * 1-parameter callee binds the WHOLE argument list (`one of [5, 6]` gives
+     * `a = [5, 6]`). This loop bound args[0] and silently dropped the rest.
+     * Over-arity on 2+-param callees is refused in builtin_task_spawn. */
+    if (fn->data.fn.param_count == 1 && t->argc > 1) {
+        Value *collected = make_list(t->argc);
+        for (int i = 0; i < t->argc; i++)
+            list_append(collected, t->args[i]);
+        env_set_local_owned(call_env, fn->data.fn.params[0], collected);
+    } else {
+        for (int i = 0; i < fn->data.fn.param_count && i < t->argc; i++)
+            env_set_local(call_env, fn->data.fn.params[i], t->args[i]);
+    }
+    t->run_env = call_env;                  /* Task owns it; base frame borrows */
+    t->started = 1;
+    EigsChunk *chunk = (EigsChunk *)fn->data.fn.body;
+    /* #997: pass the REAL argc. vm_task_run_entry's default of chunk->param_count
+     * marks every slot as caller-supplied, so every OP_DEFAULT_PARAM in the
+     * callee's prologue skipped and a defaulted parameter silently arrived as
+     * null — `d of 1` gives [1, 3] but `task_spawn of [d, 1]` gave [1, null].
+     * A re-collected single slot counts as one supplied argument. */
+    int supplied = (fn->data.fn.param_count == 1 && t->argc > 1) ? 1 : t->argc;
+    return vm_task_run_entry(chunk, call_env, supplied);
+}
+
+/* Record a task that just finished (returned or errored) and wake any joiner
+ * blocked on it. `r` is the value vm_run returned (NULL on suspend — not this
+ * path). g_has_error distinguishes a normal end from an uncaught error. */
+/* #530: release a task's handle slot and free the struct. Only for tasks
+ * nobody will join (detached) — a reaped id reads as unknown afterwards
+ * (task_alive 0, task_join null) and the slot is immediately reusable. */
+static void task_reap(Task *t) {
+    int id = t->id;
+    task_free(t);
+    handle_release(id);
+}
+
+/* #530: mark `tid` fire-and-forget. A detached task is reaped the moment it
+ * finishes — or immediately here if it already has — so its handle slot
+ * returns to the pool instead of holding the table until process exit. An
+ * already-dead unobserved error moves to the scheduler-level counter so the
+ * #493 exit gate survives the reap. The RUNNING task may detach itself.
+ * Returns 1 on success, 0 for main (task 0) or an unknown id. */
+int task_do_detach(int tid) {
+    TaskScheduler *s = sched_get();
+    if (!s || tid == 0) return 0;
+    Task *t = sched_lookup(s, tid);
+    if (!t) return 0;
+    if (t->state == TASK_DONE || t->state == TASK_DEAD) {
+        if (t->err_unobserved) s->detached_err_count++;
+        task_reap(t);
+        return 1;
+    }
+    t->detached = 1;
+    return 1;
+}
+
+static void sched_finish(TaskScheduler *s, Task *t, Value *r) {
+    /* A task that ended (returned OR died) while its per-thread arena is still
+     * active — arena_mark with no matching arena_reset, e.g. the arena-suspend
+     * guard raised inside the scope — must not leave the arena active: (1) its
+     * error dict / result below outlive the task and cross to the joiner, so
+     * they must be heap, not arena (a later arena_reset would dangle them); and
+     * (2) the next task must start from a clean arena baseline. The suspend
+     * guard guarantees a task never *yields* with the arena active, so the only
+     * way it's active here is an ending task that leaked the scope. */
+    g_arena.active = 0;
+    if (g_has_error) {
+        t->has_error = 1;
+        t->error_value = vm_task_take_error();  /* the {kind,message,line} dict */
+        g_has_error = 0;
+        /* #493: a worker that dies of an uncaught error must fail the process
+         * if nothing ever joins it. Main (task 0) already propagates its own
+         * error via the trampoline's return, so only mark workers here; a
+         * later task_join on this task clears the flag. */
+        if (t->id != 0) t->err_unobserved = 1;
+        if (r) val_decref(r);
+        t->result = NULL;
+    } else {
+        t->result = r ? val_clone_for_send(r) : NULL;   /* share-nothing result */
+        if (r) val_decref(r);
+    }
+    t->state = t->has_error ? TASK_DEAD : TASK_DONE;
+    if (t->id != 0) s->live--;
+    if (t->run_env) { env_decref(t->run_env); t->run_env = NULL; }
+    /* Wake every task blocked on this one: enqueue it; on resume the join
+     * builtin's placeholder gets overwritten with our result (or re-raise). */
+    for (int i = 1; i < HANDLE_TABLE_SIZE; i++) {
+        Task *w = (Task *)handle_lookup(i, HANDLE_TASK);
+        if (w && w->state == TASK_SUSPENDED && w->join_target == t->id)
+            sched_ready_push(s, w->id, SCAUSE_JOIN_RELEASE);
+    }
+    if (s->main_task.state == TASK_SUSPENDED && s->main_task.join_target == t->id)
+        sched_ready_push(s, 0, SCAUSE_JOIN_RELEASE);
+    /* #530: a detached task's outcome is nobody's to consume — reap the slot
+     * now so task-per-message workloads aren't bounded by lifetime spawns.
+     * An uncaught death still fails the process: the #493 flag moves to the
+     * scheduler counter before the slot frees (the trace already printed). */
+    if (t->id != 0 && t->detached) {
+        if (t->err_unobserved) s->detached_err_count++;
+        task_reap(t);
+    }
+}
+
+/* On resuming a task that was blocked in task_join, replace the placeholder
+ * null the builtin left on the stack top with the joinee's result — or, if
+ * the joinee died, re-raise its error in the joiner. Called from the dispatch loop's
+ * resume path (after the stack is restored). */
+void task_apply_join_result(Task *t) {
+    TaskScheduler *s = sched_get();
+    if (!s || t->join_target == 0) return;
+    Task *jt = sched_lookup(s, t->join_target);
+    t->join_target = 0;
+    if (!jt) return;
+    if (jt->has_error) {
+        jt->err_unobserved = 0;   /* #493: observed by this join (caught or not) */
+        /* Re-raise: restore the error payload so the joiner's CHECK_ERROR
+         * catches/propagates it as if the throw happened at the join. */
+        if (jt->error_value) {
+            g_error_value = jt->error_value;
+            val_incref(g_error_value);
+            g_error_kind = (int)EK_USER;
+        }
+        snprintf(g_error_msg, sizeof(g_error_msg), "joined task %d failed", jt->id);
+        g_has_error = 1;
+        return;
+    }
+    /* Overwrite TOS placeholder with the joinee's (already deep-copied) result. */
+    if (g_vm.sp > 0) {
+        slot_decref(g_vm.stack[g_vm.sp - 1]);
+        Value *res = jt->result ? jt->result : make_null();
+        val_incref(res);
+        g_vm.stack[g_vm.sp - 1] = slot_from_heap(res);
+    }
+}
+
+/* The trampoline. Entered from the outermost vm_execute once main (task 0)
+ * has first suspended. Drives tasks round-robin until the ready queue drains,
+ * then returns main's result. All-tasks-blocked = deadlock (loud, not a hang).
+ * Task 0 finishing kills outstanding tasks (kill-outstanding ruling). */
+static Value *scheduler_trampoline(TaskScheduler *s) {
+    for (;;) {
+        int id = sched_ready_pop(s);
+        if (id < 0) {
+            /* Nothing runnable now. Sleepers waiting on the virtual clock are
+             * not a deadlock — advance time to the earliest wake and retry
+             * before deciding anything is stuck. */
+            if (sched_wake_sleepers(s)) continue;
+            /* Genuinely nothing runnable. If main already finished, we're done.
+             * If tasks remain live (blocked on joins that can't resolve), that's
+             * a deadlock — raise it loudly rather than hang. */
+            if (s->main_task.state == TASK_DONE || s->main_task.state == TASK_DEAD) {
+                if (s->main_task.has_error) {
+                    g_error_value = s->main_task.error_value;
+                    s->main_task.error_value = NULL;
+                    g_has_error = 1;
+                    return make_null();
+                }
+                Value *r = s->main_task.result;
+                s->main_task.result = NULL;
+                return r ? r : make_null();
+            }
+            /* #509: deadlock is a normal runtime error, not a hang — make it
+             * CATCHABLE. main is guaranteed SUSPENDED here (the DONE/DEAD case
+             * returned above), blocked at a task_join/recv. Build the structured
+             * error at main's blocked line (vm_take_error_value later lazily
+             * turns g_error_kind/raw/line into a {kind,message,line} dict, so
+             * e.kind == "deadlock"). We drive the print/handling ourselves and
+             * do NOT go through rt_error's g_try_depth-gated print: g_try_depth
+             * is a global, not part of a task's saved slice, so a suspended
+             * worker's still-open try can leave it non-zero here. */
+            Task *m = &s->main_task;
+            int catchable = 0;
+            for (int i = 0; i < m->saved_frame_count; i++)
+                if (m->saved_frames[i].try_count > 0) { catchable = 1; break; }
+            g_error_kind = (int)EK_DEADLOCK;
+            g_error_line = m->saved_current_line;
+            snprintf(g_error_raw, sizeof(g_error_raw),
+                     "all tasks are blocked — deadlock");
+            snprintf(g_error_msg, sizeof(g_error_msg),
+                     "Error line %d: all tasks are blocked — deadlock", g_error_line);
+            g_has_error = 1;
+            eigs_clear_error_value();
+            if (catchable) {
+                /* Deliver at main's blocked site: clear the block reason so the
+                 * resume doesn't fill a normal join/recv result, then re-enqueue
+                 * main. The loop resumes it with g_has_error set → CHECK_ERROR
+                 * unwinds to the handler (which reads e.kind == "deadlock"). */
+                m->join_target = 0;
+                m->recv_blocked = 0;
+                m->sleeping = 0;
+                sched_ready_push(s, 0, SCAUSE_DEADLOCK);
+                continue;
+            }
+            /* No handler in main → terminal: print loudly, exit non-zero. (No
+             * stack trace: between tasks g_vm has no live frames.) */
+            fprintf(stderr, "%s\n", g_error_msg);
+            return make_null();
+        }
+        Task *t = sched_lookup(s, id);
+        if (!t || t->state == TASK_DONE || t->state == TASK_DEAD) continue;
+        s->current = id;
+        /* #846: one entry per resume, written AFTER the pick (the pick is
+         * untouched) and only while armed — off, this is one load + branch. */
+        if (g_task_trace_on) sched_trace_record(s, id, s->pop_cause);
+
+        Value *r;
+        if (t->state == TASK_SUSPENDED) {
+            /* Resume (the join placeholder, if any, is filled inside the
+             * resume path via task_apply_join_result). */
+            r = vm_task_resume(t);   /* resume: frame already exists */
+        } else {
+            r = task_start(t);   /* never-run task: bind args + run at base 0 */
+        }
+
+        if (t->state == TASK_SUSPENDED) {
+            /* It suspended again. task_yield → re-enqueue; task_join → stay
+             * blocked (woken by sched_finish); task_recv on an empty mailbox →
+             * stay blocked (woken by task_deliver); task_sleep → stay blocked
+             * (woken by sched_wake_sleepers when the clock reaches wake_at). */
+            if (t->join_target == 0 && !t->recv_blocked && !t->sleeping)
+                sched_ready_push(s, id, SCAUSE_YIELD);
+        } else {
+            sched_finish(s, t, r);
+            /* kill-outstanding: main ending tears the rest down deterministically. */
+            if (id == 0) break;
+        }
+    }
+    /* main finished with tasks still outstanding → reap them (kill-outstanding). */
+    if (s->main_task.has_error) {
+        g_error_value = s->main_task.error_value;
+        s->main_task.error_value = NULL;
+        g_has_error = 1;
+        return make_null();
+    }
+    Value *r = s->main_task.result;
+    s->main_task.result = NULL;
+    return r ? r : make_null();
+}
+/* The one seam the VM hands control to (#744): called by vm_execute_common
+ * after the OUTERMOST vm_run returns. Verbatim the tail that used to sit in
+ * vm.c — moved here so `TaskScheduler` stays private to this file. With no
+ * scheduler armed it returns `r` unchanged.
+ *
+ * main (task 0) either finished (no task ever blocked) or suspended. If it
+ * suspended, its slice is saved; drive the trampoline. If it finished but
+ * tasks are still live, drive them too (kill-outstanding at main's end). */
+Value *task_sched_after_outermost(Value *r) {
+    TaskScheduler *s = sched_get();
+    if (!s || !s->active) return r;
+    if (s->main_task.state == TASK_SUSPENDED) {
+        /* main's first suspension happened in the initial vm_run, outside the
+         * trampoline — enqueue it now so it resumes round-robin, UNLESS it
+         * blocked on a join (sched_finish wakes it), a recv (task_deliver
+         * wakes it), or a sleep (sched_wake_sleepers wakes it). Mirrors the
+         * trampoline's re-enqueue guard. */
+        if (s->main_task.join_target == 0 && !s->main_task.recv_blocked &&
+            !s->main_task.sleeping)
+            sched_ready_push(s, 0, SCAUSE_YIELD);
+        return scheduler_trampoline(s);
+    }
+    /* main ran to completion without ever suspending. Record its result and,
+     * if any spawned task is still runnable, drive them (kill-outstanding). */
+    if (s->live > 0 && s->rcount > 0) {
+        s->main_task.state = TASK_DONE;
+        s->main_task.result = r ? val_clone_for_send(r) : NULL;
+        if (r) val_decref(r);
+        Value *mr = scheduler_trampoline(s);
+        return mr;
+    }
+    return r;
+}
diff --git a/src/task.h b/src/task.h
new file mode 100644
index 00000000..f0c4860e
--- /dev/null
+++ b/src/task.h
@@ -0,0 +1,48 @@
+/*
+ * The VM <-> cooperative-scheduler seam (#744).
+ *
+ * `TaskScheduler`, the ready queue, the virtual clock and the #846 trace are
+ * private to task.c. This header is the only surface between it and the VM,
+ * in BOTH directions, so the split cannot quietly re-entangle: anything new
+ * that crosses has to be written down here.
+ *
+ * The task_* builtin interface (task_spawn / task_join / task_send / ...)
+ * is NOT here — it is in vm.h alongside the `Task` struct, unchanged, because
+ * builtins.c is its caller and always was.
+ */
+
+#ifndef EIGENSCRIPT_TASK_H
+#define EIGENSCRIPT_TASK_H
+
+#include "eigenscript.h"
+#include "vm.h"   /* Task, TaskState */
+
+/* ---- task.c -> called by the VM ---------------------------------------- */
+
+/* Copying-stack slice save/restore around a suspend/resume. The dispatch loop
+ * calls these at CASE(CALL) and at the resume entry; memory is proportional to
+ * a task's LIVE depth, not to a whole VM per task. */
+void  task_save_slice(Task *t);
+void  task_restore_slice(Task *t);
+/* The running task (main's task 0 when nothing has spawned; NULL with no
+ * scheduler at all). */
+Task *task_current_running(void);
+/* Fill the placeholder a blocked task_join / task_recv left on the stack top,
+ * on the resume that unblocks it. No-ops when the task was not blocked there. */
+void  task_apply_join_result(Task *t);
+void  task_apply_recv_result(Task *t);
+/* Drive the scheduler after the OUTERMOST vm_run returned `r`; returns the
+ * program's result. Returns `r` unchanged when no scheduler is armed, which
+ * is every program that never spawns. */
+Value *task_sched_after_outermost(Value *r);
+
+/* ---- vm.c -> called by the scheduler ------------------------------------
+ * Three thin wrappers over the dispatch loop. They exist so vm_run_ex (the
+ * 3131-line interpreter loop) and vm_take_error_value stay `static` in vm.c:
+ * the scheduler needs two ways in and one error accessor, not the loop's
+ * address. */
+Value *vm_task_run_entry(EigsChunk *chunk, Env *env, int call_argc);
+Value *vm_task_resume(Task *t);
+Value *vm_task_take_error(void);
+
+#endif /* EIGENSCRIPT_TASK_H */
diff --git a/src/vm.c b/src/vm.c
index 727297f0..43ffd236 100644
--- a/src/vm.c
+++ b/src/vm.c
@@ -6,7 +6,9 @@
  */
 
 #include "eigenscript.h"
+#include "fsutil.h"
 #include "vm.h"
+#include "task.h"
 #include "jit.h"
 #include "trace.h"
 #include <stdio.h>
@@ -387,16 +389,15 @@ int observer_predicate_at(Env *e, int idx, int kind, int require_used) {
  * fields; the g_* identifiers are macros in eigenscript.h. No extern
  * decls needed here. */
 
-/* ---- Cross-TU helpers that no header declares (#744) ----
- * The value/env/dict constructors and accessors this file calls are all
- * declared in eigenscript.h — the re-declarations that used to sit here
- * were redundant copies free to drift from it (one still claimed
- * `observer_ensure_fresh` came from eval.c, a TU the bytecode VM replaced,
- * and `val_incref`/`val_decref`/`num_guard` are `static inline` in the
- * header, so the extern was inert). These three are the ones with no
- * header declaration to defer to; they stay until they get a home. */
-extern Value* builtin_free_val(Value *arg);                              /* builtins.c */
-extern int env_get_assign_count(Env *env, const char *name, uint32_t h); /* eigenscript.c */
+/* #744: this file no longer re-declares ANY cross-TU symbol. The value/env/
+ * dict constructors and accessors it calls are declared in eigenscript.h; the
+ * copies that used to sit here were free to drift from it (one still claimed
+ * `observer_ensure_fresh` came from eval.c, a TU the bytecode VM replaced, and
+ * `val_incref`/`val_decref`/`num_guard` are `static inline` in the header, so
+ * the extern was inert). The last two — `builtin_free_val` and
+ * `env_get_assign_count` — were homed in vm.h and eigenscript.h respectively,
+ * so the definitions are now checked against the declaration their callers
+ * see. Do not add a new extern here; give the symbol a header. */
 
 /* Inline fast-path for binding a single param into a fresh call env.
  * Caller guarantees `env->count == slot_idx` and `env->capacity > slot_idx`
@@ -751,8 +752,6 @@ static inline EigsSlot slot_bridge_wrap(Value *v) {
     return slot_from_heap(v);
 }
 
-extern Value g_null_singleton_external_decl;  /* not used; doc only */
-
 static inline Value *slot_bridge_unwrap(EigsSlot s) {
     if (slot_is_num(s)) {
         /* Materialize immediate -> fresh Value. Caller owns one ref. */
@@ -2906,12 +2905,8 @@ static const char *slot_type_name(EigsSlot s) {
 /* #408: forward decls — the copying-stack save/restore and the "who is
  * running" helper live with the scheduler below vm_execute; vm_run_ex's
  * resume/suspend paths call them. */
-static void task_restore_slice(Task *t);
-static void task_save_slice(Task *t);
-static Task *task_current_running(void);
-static void task_reap(Task *t);   /* #530 */
-static void task_apply_join_result(Task *t);   /* fill a join placeholder on resume */
-static void task_apply_recv_result(Task *t);   /* fill a recv placeholder on resume */
+/* The scheduler-slice hooks this dispatch loop calls are declared in
+ * task.h (#744) — task.c owns them. */
 
 /* vm_run_ex: the shared VM dispatch body. `resume` != NULL means resume a
  * suspended #408 task — restore its copying-stack slice onto the (empty) VM
@@ -5870,11 +5865,6 @@ static Value *vm_run_ex(EigsChunk *chunk, Env *env, Task *resume,
             DISPATCH();
         }
 
-        extern TokenList tokenize(const char *source);
-        extern ASTNode *parse(TokenList *tl);
-        extern void free_tokenlist(TokenList *tl);
-        extern void free_ast(ASTNode *ast);
-
         /* Source acquisition. The embedder's source provider
          * (eigs_set_source_provider) is consulted FIRST in every
          * profile; the filesystem chain is the hosted fallback and does
@@ -5914,7 +5904,6 @@ static Value *vm_run_ex(EigsChunk *chunk, Env *env, Task *resume,
             char path_buf[8192];
             char shadowed[8192];
 
-            extern char *read_file_util(const char *path, long *size);
 
             /* #1056: functions retain their containing file's directory
              * even when called after the importing/loading frame returns. */
@@ -6418,803 +6407,30 @@ static Value *vm_run(EigsChunk *chunk, Env *env, int call_argc) {
     return vm_run_ex(chunk, env, NULL, call_argc);
 }
 
-/* ---- Public API ---- */
-
-/* ===== #408 cooperative task scheduler ==================================
- * A trampoline just above the OUTERMOST vm_execute drives every task —
- * including task 0 (the main program) — so C-stack depth stays flat
- * (vm_execute → scheduler → one vm_run) no matter how often tasks ping-pong.
- * A task suspends by a builtin setting g_task_suspend_request; the CASE(CALL)
- * site saves its live stack+frame slice (the copying-stack model: memory =
- * live depth, not a full 1.28 MB VM per task) and returns here, which runs
- * the next ready task. Deterministic by construction — no tape records; the
- * interleaving is a pure function of program order.
- * ======================================================================== */
-
-#define TASK_READY_MAX HANDLE_TABLE_SIZE
-
-/* #846: one scheduler-trace entry — a resume. `seq` is the entry's index. */
-typedef struct {
-    double  tick;    /* virtual clock (task_now) at the resume */
-    int     task;    /* resumed task id (0 = main) */
-    uint8_t cause;   /* SCAUSE_* below */
-} SchedTraceEntry;
-
-typedef struct {
-    int   ready[TASK_READY_MAX];  /* circular FIFO of runnable task ids (0=main) */
-    int   rhead, rcount;
-    int   current;                /* running task id; 0 = main */
-    int   live;                   /* spawned tasks not yet DONE/DEAD */
-    int   active;                 /* armed on first spawn */
-    int   dead_letters;           /* inc 2: sends to finished/unknown tasks */
-    int   detached_err_count;     /* #530: reaped detached tasks that died unobserved (#493 gate) */
-    uint64_t spawn_counter;       /* #535: monotonically increasing; stamps Task.spawn_seq */
-    double now;                   /* inc 3: virtual clock (logical, starts 0) */
-    int   seeded;                 /* inc 4: 1 once task_sched_seed installs a seed */
-    uint64_t rng_state;           /* inc 4: splitmix64 state for the seeded pick */
-    /* #846: WHY each ready entry became runnable, kept in lockstep with
-     * `ready` (same index, moved by the same compaction). A property of the
-     * queue entry, not of the task: the cause is fixed at enqueue time and
-     * consumed by the pop that resumes the task. Always maintained — it is
-     * one byte store per enqueue — so arming the trace mid-run changes
-     * nothing about the schedule, only whether a pop is written down. */
-    uint8_t ready_cause[TASK_READY_MAX];
-    int   pop_cause;              /* #846: cause of the most recent sched_ready_pop */
-    /* #846: the recorded history — one entry per trampoline resume while
-     * g_task_trace_on. Freed in task_sched_thread_free. Unbounded by design:
-     * a silent cap would make a long run's trace lie about its tail. */
-    SchedTraceEntry *trace;
-    int   trace_count, trace_cap;
-    Task  main_task;              /* task 0 — save-buffer only, never "started" */
-} TaskScheduler;
-
-/* #846: the cause vocabulary, enumerated from the enqueue sites below — every
- * sched_ready_push names one. A resumed task was enqueued by exactly one of:
- *   spawn         task_sched_on_spawn — its first run (task_start)
- *   yield         a task_yield re-enqueue (trampoline / main's first suspend)
- *   sleep-wake    sched_wake_sleepers advanced the virtual clock to its wake_at
- *   join-release  the task it was joined on finished (sched_finish)
- *   kill-release  the task it was joined on was task_kill'ed (task_do_kill)
- *   recv-wake     task_send delivered to its empty mailbox (task_deliver)
- *   deadlock      main re-enqueued to receive the catchable deadlock (#509)
- * Names are the .eigs-visible contract (docs/CONCURRENCY.md). */
-enum {
-    SCAUSE_SPAWN = 0, SCAUSE_YIELD, SCAUSE_SLEEP_WAKE, SCAUSE_JOIN_RELEASE,
-    SCAUSE_KILL_RELEASE, SCAUSE_RECV_WAKE, SCAUSE_DEADLOCK, SCAUSE__COUNT
-};
-static const char *const sched_cause_name[SCAUSE__COUNT] = {
-    "spawn", "yield", "sleep-wake", "join-release", "kill-release",
-    "recv-wake", "deadlock"
-};
-
-static TaskScheduler *sched_get(void) { return (TaskScheduler *)g_task_sched; }
-
-static TaskScheduler *sched_ensure(void) {
-    TaskScheduler *s = sched_get();
-    if (!s) {
-        s = xcalloc(1, sizeof(TaskScheduler));
-        s->main_task.id = 0;
-        s->main_task.state = TASK_RUNNING;
-        s->current = 0;
-        g_task_sched = s;
-    }
-    return s;
-}
-
-void task_sched_thread_free(void) {
-    TaskScheduler *s = sched_get();
-    if (!s) return;
-    Task *m = &s->main_task;
-    /* #483: main is USUALLY run-to-completion here (empty slice). But a fatal
-     * exit while main is still SUSPENDED — a `deadlock`, or main blocked on a
-     * join/recv that never resolves — leaves a live saved slice whose counted
-     * refs would otherwise leak: the base module frame owns a chunk ref (the
-     * script chunk, see vm_run's frame push), and the operand stack owns value
-     * refs. Release them, mirroring task_free's worker-slice teardown, before
-     * freeing the arrays. (owns_env is 0 for the module frame — the global env
-     * is dropped separately in main.c/eigs_close — so only chunk_decref here.) */
-    if (m->saved_stack) {
-        for (int i = 0; i < m->saved_stack_len; i++) slot_decref(m->saved_stack[i]);
-        free(m->saved_stack);
-    }
-    if (m->saved_frames) {
-        for (int i = 0; i < m->saved_frame_count; i++)
-            callframe_release(&m->saved_frames[i]);
-        free(m->saved_frames);
-    }
-    if (m->mbox) {
-        for (int i = 0; i < m->mbox_count; i++)
-            val_decref(m->mbox[(m->mbox_head + i) % m->mbox_cap]);
-        free(m->mbox);
-    }
-    if (m->result) val_decref(m->result);
-    if (m->error_value) val_decref(m->error_value);
-    free(s->trace);   /* #846 */
-    free(s);
-    g_task_sched = NULL;
-}
-
-static Task *sched_lookup(TaskScheduler *s, int id) {
-    if (id == 0) return &s->main_task;
-    return (Task *)handle_lookup(id, HANDLE_TASK);
-}
-
-/* #493: does any worker still carry an uncaught-error death that no task_join
- * ever observed? Scanned once at process exit (before handle_table_drain frees
- * the tasks) so a fire-and-forget worker's death makes the process exit
- * non-zero instead of silently returning 0. */
-int task_any_unobserved_error(void) {
-    if (!g_task_sched) return 0;
-    /* #530: reaped detached tasks that died unobserved are counted, not held. */
-    if (((TaskScheduler *)g_task_sched)->detached_err_count > 0) return 1;
-    for (int i = 1; i < HANDLE_TABLE_SIZE; i++) {
-        Task *t = (Task *)handle_lookup(i, HANDLE_TASK);
-        if (t && t->err_unobserved) return 1;
-    }
-    return 0;
-}
-
-static Task *task_current_running(void) {
-    TaskScheduler *s = sched_get();
-    return s ? sched_lookup(s, s->current) : NULL;
-}
-
-static void sched_ready_push(TaskScheduler *s, int id, int cause) {
-    if (s->rcount >= TASK_READY_MAX) return;   /* ids are table-bounded; can't overflow */
-    int slot = (s->rhead + s->rcount) % TASK_READY_MAX;
-    s->ready[slot] = id;
-    s->ready_cause[slot] = (uint8_t)cause;   /* #846: rides with the entry */
-    s->rcount++;
-}
-
-/* #530: drop tid's pending ready-queue entry. A task killed while READY (or
- * woken but not yet run) used to leave its entry behind; the trampoline
- * skips stale ids, but enough of them FILL the fixed queue and
- * sched_ready_push silently drops real wakeups — a spurious "deadlock".
- * A task has at most one entry (recv-wake is idempotent and a task must be
- * popped before it can re-enqueue), so one compacting pass suffices. */
-static void sched_ready_remove(TaskScheduler *s, int tid) {
-    int w = 0;
-    for (int k = 0; k < s->rcount; k++) {
-        int from = (s->rhead + k) % TASK_READY_MAX;
-        int id = s->ready[from];
-        if (id != tid) {
-            int to = (s->rhead + w) % TASK_READY_MAX;
-            s->ready[to] = id;
-            s->ready_cause[to] = s->ready_cause[from];   /* #846: lockstep */
-            w++;
-        }
-    }
-    s->rcount = w;
-}
-
-/* Inc 4: splitmix64 — a deterministic, platform-independent integer PRNG for
- * the seeded scheduling strategy. Pure integer arithmetic (no float, no OS
- * entropy), so the pick sequence is a reproducible function of the installed
- * seed + program order — the seeded schedule replays byte-identically and
- * records no tape nondeterminism. */
-static uint64_t sched_rng_next(TaskScheduler *s) {
-    uint64_t z = (s->rng_state += 0x9E3779B97F4A7C15ULL);
-    z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9ULL;
-    z = (z ^ (z >> 27)) * 0x94D049BB133111EBULL;
-    return z ^ (z >> 31);
-}
-
-/* task_sched_seed: install a seed and switch the scheduler from FIFO
- * round-robin to a seeded pseudo-random pick of the next ready task. Ensures
- * the scheduler exists so the seed sticks even when set before the first
- * task_spawn. The interleaving stays deterministic — a DST varies the seed to
- * explore different interleavings, each fully reproducible. */
-void task_sched_set_seed(double seed) {
-    TaskScheduler *s = sched_ensure();
-    s->rng_state = (uint64_t)(int64_t)seed;   /* integer seeds; fractions truncate */
-    s->seeded = 1;
-}
-
-static int sched_ready_pop(TaskScheduler *s) {
-    if (s->rcount == 0) return -1;
-    if (!s->seeded || s->rcount == 1) {
-        /* Default FIFO: O(1) head pop — the fast path, unchanged. */
-        int id = s->ready[s->rhead];
-        s->pop_cause = s->ready_cause[s->rhead];   /* #846 */
-        s->rhead = (s->rhead + 1) % TASK_READY_MAX;
-        s->rcount--;
-        return id;
-    }
-    /* Seeded strategy: pick a pseudo-random ready task, then compact the hole
-     * by shifting the suffix down one (order-preserving among the rest). O(n)
-     * in the ready count, which is tiny and only paid in DST/seeded mode. */
-    int idx = (int)(sched_rng_next(s) % (uint64_t)s->rcount);
-    int id  = s->ready[(s->rhead + idx) % TASK_READY_MAX];
-    s->pop_cause = s->ready_cause[(s->rhead + idx) % TASK_READY_MAX];   /* #846 */
-    for (int k = idx; k < s->rcount - 1; k++) {
-        int to = (s->rhead + k) % TASK_READY_MAX, from = (s->rhead + k + 1) % TASK_READY_MAX;
-        s->ready[to] = s->ready[from];
-        s->ready_cause[to] = s->ready_cause[from];   /* #846: lockstep */
-    }
-    s->rcount--;
-    return id;
-}
-
-/* ---- #846: the scheduler trace ------------------------------------------
- * Pure reader: called from the trampoline AFTER the pick is made and BEFORE
- * the task runs, with nothing but scheduler state as input. No tape record —
- * the schedule is a pure function of program order (+ seed), so a replayed
- * run re-derives the identical history; a tape-recorded trace would be a
- * second, redundant source of truth that could disagree with the first. */
-static void sched_trace_record(TaskScheduler *s, int id, int cause) {
-    if (s->trace_count == s->trace_cap) {
-        int nc = s->trace_cap ? s->trace_cap * 2 : 64;
-        s->trace = xrealloc(s->trace, sizeof(SchedTraceEntry) * (size_t)nc);
-        s->trace_cap = nc;
-    }
-    SchedTraceEntry *e = &s->trace[s->trace_count++];
-    e->tick  = s->now;
-    e->task  = id;
-    e->cause = (uint8_t)cause;
-}
-
-Value *task_sched_trace_read(void) {
-    TaskScheduler *s = sched_get();
-    if (!s) return make_list(0);
-    Value *out = make_list(s->trace_count);
-    for (int i = 0; i < s->trace_count; i++) {
-        const SchedTraceEntry *e = &s->trace[i];
-        Value *d = make_dict(4);
-        dict_set_owned(d, "seq",   make_num((double)i));
-        dict_set_owned(d, "tick",  make_num(e->tick));
-        dict_set_owned(d, "task",  make_num((double)e->task));
-        dict_set_owned(d, "cause", make_str(e->cause < SCAUSE__COUNT
-                                            ? sched_cause_name[e->cause] : "?"));
-        list_append_owned(out, d);
-    }
-    return out;
-}
-
-void task_sched_trace_clear(void) {
-    TaskScheduler *s = sched_get();
-    if (s) s->trace_count = 0;   /* keep the buffer; re-arming reuses it */
-}
-
-/* Copying-stack save: memcpy the running task's live slice [0,fc)/[0,sp) into
- * its right-sized save-buffer, then retreat the VM to empty. Refs move WITH
- * the bytes (the saved slots/frames own the same counted refs that were on
- * the stack), so sp/frame_count just retreat — no incref/decref, no walk. */
-static void task_save_slice(Task *t) {
-    if (!t) return;
-    int fc = g_vm.frame_count, sp = g_vm.sp;
-    free(t->saved_frames);
-    free(t->saved_stack);
-    t->saved_frames = fc ? xmalloc(sizeof(CallFrame) * fc) : NULL;
-    t->saved_stack  = sp ? xmalloc(sizeof(EigsSlot) * sp)  : NULL;
-    if (fc) memcpy(t->saved_frames, g_vm.frames, sizeof(CallFrame) * fc);
-    if (sp) memcpy(t->saved_stack,  g_vm.stack,  sizeof(EigsSlot) * sp);
-    t->saved_frame_count  = fc;
-    t->saved_stack_len    = sp;
-    t->saved_current_line = g_vm.current_line;
-    g_vm.frame_count = 0;
-    g_vm.sp = 0;
-    t->state = TASK_SUSPENDED;
-}
-
-/* Copying-stack restore: memcpy a suspended task's slice back onto the empty
- * VM. Symmetric with save — refs move back with the bytes. */
-static void task_restore_slice(Task *t) {
-    int fc = t->saved_frame_count, sp = t->saved_stack_len;
-    if (fc) memcpy(g_vm.frames, t->saved_frames, sizeof(CallFrame) * fc);
-    if (sp) memcpy(g_vm.stack,  t->saved_stack,  sizeof(EigsSlot) * sp);
-    g_vm.frame_count  = fc;
-    g_vm.sp           = sp;
-    g_vm.current_line = t->saved_current_line;
-    free(t->saved_frames); t->saved_frames = NULL;
-    free(t->saved_stack);  t->saved_stack  = NULL;
-    t->saved_frame_count = 0;
-    t->saved_stack_len   = 0;
-    t->state = TASK_RUNNING;
-}
-
-/* task_spawn (builtins.c) hands a freshly registered task here. */
-void task_sched_on_spawn(int id) {
-    TaskScheduler *s = sched_ensure();
-    s->active = 1;
-    s->live++;
-    /* #535: stamp spawn order. Handle IDs come from a rotating cursor, so
-     * they encode the process's WHOLE allocation history; any id-ordered
-     * tie-break makes the interleaving history-dependent. Spawn order is a
-     * pure function of the run. Main is 0 (spawn_counter starts at 1). */
-    Task *t = sched_lookup(s, id);
-    if (t) t->spawn_seq = ++s->spawn_counter;
-    sched_ready_push(s, id, SCAUSE_SPAWN);
-}
-
-/* task_yield: mark the current task for suspension; the trampoline re-enqueues
- * it at the tail (round-robin) after the save. */
-void task_request_yield(void) { g_task_suspend_request = 1; }
-
-/* task_join: block the current task on `target`. Returns 0 for a bad target
- * (main, self, or unknown) so the builtin can fall back; 1 to suspend. A
- * target that is already finished is handled in the builtin (returns its
- * result without suspending). */
-int task_request_join(int target) {
-    TaskScheduler *s = sched_get();
-    if (!s || target == 0 || target == s->current) return 0;
-    Task *tt = sched_lookup(s, target);
-    if (!tt) return 0;
-    Task *cur = sched_lookup(s, s->current);
-    cur->join_target = target;
-    g_task_suspend_request = 1;
-    return 1;
-}
-
-/* ---- Inc 2: mailboxes -------------------------------------------------- */
-
-/* Append msg (ownership transferred in) to task `tid`'s FIFO mailbox and wake
- * it if it is blocked in task_recv. Returns 1 if delivered, 0 if dropped
- * because the target is gone (finished/unknown) — send-to-dead is a silent
- * drop plus a dead-letter count (Akka dead-letters / Erlang cast), NOT an
- * error: an error path here would be a nondeterminism magnet. */
-int task_deliver(int tid, Value *msg_owned) {
-    TaskScheduler *s = sched_get();
-    Task *t = s ? sched_lookup(s, tid) : NULL;
-    if (!t || t->state == TASK_DONE || t->state == TASK_DEAD) {
-        if (s) s->dead_letters++;
-        return 0;
-    }
-    if (t->mbox_count >= t->mbox_cap) {
-        int nc = t->mbox_cap ? t->mbox_cap * 2 : 8;
-        Value **nb = xmalloc(sizeof(Value *) * nc);
-        for (int i = 0; i < t->mbox_count; i++)
-            nb[i] = t->mbox[(t->mbox_head + i) % t->mbox_cap];
-        free(t->mbox);
-        t->mbox = nb; t->mbox_cap = nc; t->mbox_head = 0;
-    }
-    t->mbox[(t->mbox_head + t->mbox_count) % t->mbox_cap] = msg_owned;
-    t->mbox_count++;
-    /* Wake a recv-blocked receiver on the FIRST message that arrives while it
-     * waits on an empty mailbox (mbox_count just became 1). recv_blocked stays
-     * set so the resume path (task_apply_recv_result) delivers this message and
-     * clears it; the mbox_count==1 guard makes the enqueue idempotent — a
-     * second send before the receiver resumes finds count>1 and does not
-     * re-enqueue (which would put the task in the ready queue twice). */
-    if (t->recv_blocked && t->state == TASK_SUSPENDED && t->mbox_count == 1)
-        sched_ready_push(s, tid, SCAUSE_RECV_WAKE);
-    return 1;
-}
-
-int task_mbox_has(void) {
-    Task *t = task_current_running();
-    return (t && t->mbox_count > 0) ? 1 : 0;
-}
-
-Value *task_mbox_pop(void) {
-    Task *t = task_current_running();
-    if (!t || t->mbox_count == 0) return make_null();
-    Value *v = t->mbox[t->mbox_head];
-    t->mbox_head = (t->mbox_head + 1) % t->mbox_cap;
-    t->mbox_count--;
-    return v;   /* owned ref transfers to caller */
-}
-
-void task_request_recv(void) {
-    Task *t = task_current_running();
-    if (t) t->recv_blocked = 1;
-    g_task_suspend_request = 1;
-}
-
-/* ---- Inc 3: virtual time ---------------------------------------------- */
-
-/* task_sleep: the current task becomes runnable again when the virtual clock
- * reaches now + ticks. The trampoline advances the clock only when nothing is
- * runnable (see sched_wake_sleepers), so time is a pure function of program
- * order + sleep durations — no tape records, no wall clock. A negative sleep
- * is clamped to 0 (a same-tick yield to everything currently ready). */
-void task_request_sleep(double ticks) {
-    TaskScheduler *s = sched_get();
-    Task *t = task_current_running();
-    if (!s || !t) return;
-    double dt = ticks > 0 ? ticks : 0;
-    t->wake_at = s->now + dt;
-    t->sleeping = 1;
-    g_task_suspend_request = 1;
-}
-
-double task_virtual_now(void) {
-    TaskScheduler *s = sched_get();
-    return s ? s->now : 0;
-}
-
-/* task_self (builtins.c): the running task's id, in the same integer space
- * task_spawn returns — 0 for the main task, including before any scheduler
- * exists. Pure scheduler state, so no tape participation. */
-int task_current_id(void) {
-    TaskScheduler *s = sched_get();
-    return s ? s->current : 0;
-}
-
-/* When the ready queue is empty, advance the virtual clock to the earliest
- * sleeper's wake time and make every task due at (or before) that instant
- * runnable. Returns 1 if any sleeper was woken (the trampoline then loops),
- * 0 if there are no sleepers (genuine idle → done or deadlock). Ties at the
- * same wake_at are broken by ascending task id (main = 0 first), so the
- * interleaving stays deterministic. The clock only ever moves forward:
- * wake_at = now + dt >= now, so the min is never behind the current now. */
-static int sched_wake_sleepers(TaskScheduler *s) {
-    double best = 0; int have_best = 0;
-    if (s->main_task.state == TASK_SUSPENDED && s->main_task.sleeping) {
-        best = s->main_task.wake_at; have_best = 1;
-    }
-    for (int i = 1; i < HANDLE_TABLE_SIZE; i++) {
-        Task *t = (Task *)handle_lookup(i, HANDLE_TASK);
-        if (t && t->state == TASK_SUSPENDED && t->sleeping &&
-            (!have_best || t->wake_at < best)) {
-            best = t->wake_at; have_best = 1;
-        }
-    }
-    if (!have_best) return 0;
-    s->now = best;
-    /* Wake main first, then tasks in ascending SPAWN order (#535) — NOT id
-     * order: ids come from a rotating next-fit cursor, so id order encodes
-     * the process's whole allocation history and two identical seeded runs
-     * in one process could interleave differently once slots recycle
-     * (surfaced by liferaft's in-sweep fault verify failing to reproduce
-     * standalone). Spawn order is a pure function of the run itself. */
-    if (s->main_task.state == TASK_SUSPENDED && s->main_task.sleeping &&
-        s->main_task.wake_at <= s->now) {
-        s->main_task.sleeping = 0;
-        sched_ready_push(s, 0, SCAUSE_SLEEP_WAKE);
-    }
-    for (;;) {
-        Task *next = NULL;
-        for (int i = 1; i < HANDLE_TABLE_SIZE; i++) {
-            Task *t = (Task *)handle_lookup(i, HANDLE_TASK);
-            if (t && t->state == TASK_SUSPENDED && t->sleeping && t->wake_at <= s->now &&
-                (!next || t->spawn_seq < next->spawn_seq))
-                next = t;
-        }
-        if (!next) break;
-        next->sleeping = 0;
-        sched_ready_push(s, next->id, SCAUSE_SLEEP_WAKE);
-    }
-    return 1;
-}
-
-/* Deterministic teardown of a task mid-run (task_kill): drop its mailbox and
- * saved slice, wake any joiner with an `interrupt` error, mark it DEAD. The
- * handle entry stays (task_alive → 0, joiners see DEAD); handle_table_drain
- * frees the struct at exit. Returns 0 for a bad/self/finished target. */
-int task_do_kill(int tid) {
-    TaskScheduler *s = sched_get();
-    if (!s || tid == 0 || tid == s->current) return 0;
-    Task *t = sched_lookup(s, tid);
-    if (!t || t->state == TASK_DONE || t->state == TASK_DEAD) return 0;
-    /* #530: a READY/woken victim holds a ready-queue entry — remove it so
-     * dead ids can never fill the queue and starve real wakeups. */
-    sched_ready_remove(s, tid);
-    /* Drain the mailbox. */
-    while (t->mbox_count > 0) {
-        val_decref(t->mbox[t->mbox_head]);
-        t->mbox_head = (t->mbox_head + 1) % t->mbox_cap;
-        t->mbox_count--;
-    }
-    free(t->mbox); t->mbox = NULL; t->mbox_cap = 0; t->mbox_head = 0;
-    /* Release the suspended slice's counted refs (mirror task_free's slice
-     * teardown) so a killed suspended task doesn't leak. */
-    if (t->saved_stack) {
-        for (int i = 0; i < t->saved_stack_len; i++) slot_decref(t->saved_stack[i]);
-        free(t->saved_stack); t->saved_stack = NULL; t->saved_stack_len = 0;
-    }
-    if (t->saved_frames) {
-        for (int i = 0; i < t->saved_frame_count; i++) {
-            CallFrame *f = &t->saved_frames[i];
-            /* A task killed while suspended INSIDE a try never runs the
-             * matching TRY_ENDs, and g_try_depth is a process global, not
-             * per-task: leaving it elevated makes rt_error's `g_try_depth == 0`
-             * gate suppress the diagnostic of every later uncaught error in
-             * the process — confirmed, the program exits 1 in silence (#726). */
-            g_try_depth -= f->try_count;
-            callframe_release(f);
-        }
-        if (g_try_depth < 0) g_try_depth = 0;
-        free(t->saved_frames); t->saved_frames = NULL; t->saved_frame_count = 0;
-    }
-    if (t->run_env) { env_decref(t->run_env); t->run_env = NULL; }
-    t->has_error = 1;
-    t->state = TASK_DEAD;
-    s->live--;
-    /* Wake joiners with an interrupt: on resume task_apply_join_result sees
-     * has_error and re-raises. Give them an error payload. */
-    if (!t->error_value) {
-        Value *ev = make_dict(3);
-        dict_set_owned(ev, "kind", make_str(err_kind_name(EK_INTERRUPT)));
-        dict_set_owned(ev, "message", make_str("task was killed"));
-        dict_set_owned(ev, "line", make_num(0));
-        t->error_value = ev;
-    }
-    for (int i = 1; i < HANDLE_TABLE_SIZE; i++) {
-        Task *w = (Task *)handle_lookup(i, HANDLE_TASK);
-        if (w && w->state == TASK_SUSPENDED && w->join_target == tid)
-            sched_ready_push(s, w->id, SCAUSE_KILL_RELEASE);
-    }
-    if (s->main_task.state == TASK_SUSPENDED && s->main_task.join_target == tid)
-        sched_ready_push(s, 0, SCAUSE_KILL_RELEASE);
-    /* #530: kill of a detached task is an explicit discard — reap now. (Kill
-     * is a deliberate teardown, never an uncaught error: no #493 counting.) */
-    if (t->detached) task_reap(t);
-    return 1;
-}
-
-/* On resuming a recv-blocked task, fill the placeholder the task_recv builtin
- * left on the stack top with the next mailbox message. */
-static void task_apply_recv_result(Task *t) {
-    /* Only a task that suspended INSIDE task_recv has a placeholder to fill.
-     * A task resuming from a plain task_yield/task_join must NOT have its
-     * mailbox drained here, even if a message arrived meanwhile. */
-    if (!t->recv_blocked) return;
-    t->recv_blocked = 0;
-    if (g_vm.sp > 0) {
-        slot_decref(g_vm.stack[g_vm.sp - 1]);
-        Value *msg;
-        if (t->mbox_count > 0) {
-            msg = t->mbox[t->mbox_head];
-            t->mbox_head = (t->mbox_head + 1) % t->mbox_cap;
-            t->mbox_count--;
-        } else {
-            msg = make_null();   /* woken without a message (killed sender race) */
-        }
-        g_vm.stack[g_vm.sp - 1] = slot_from_heap(msg);
-    }
-}
-
-/* Start a never-run spawned task: bind its deep-copied args into a fresh env
- * from the entry closure (the base frame borrows it — the Task owns run_env
- * across suspend/resume), then run at base 0 so it is suspendable. Mirrors
- * call_eigs_fn's param binding, but does not run to completion. */
-static Value *task_start(Task *t) {
-    Value *fn = t->entry_fn;
-    if (fn->type == VAL_BUILTIN) {          /* builtins never suspend — run direct */
-        Value *a = t->argc == 1 ? t->args[0] : make_null();
-        return fn->data.builtin(a);
-    }
-    Env *call_env = env_new(fn->data.fn.closure);
-    /* #989: same re-collect carve-out as every other entry point — a
-     * 1-parameter callee binds the WHOLE argument list (`one of [5, 6]` gives
-     * `a = [5, 6]`). This loop bound args[0] and silently dropped the rest.
-     * Over-arity on 2+-param callees is refused in builtin_task_spawn. */
-    if (fn->data.fn.param_count == 1 && t->argc > 1) {
-        Value *collected = make_list(t->argc);
-        for (int i = 0; i < t->argc; i++)
-            list_append(collected, t->args[i]);
-        env_set_local_owned(call_env, fn->data.fn.params[0], collected);
-    } else {
-        for (int i = 0; i < fn->data.fn.param_count && i < t->argc; i++)
-            env_set_local(call_env, fn->data.fn.params[i], t->args[i]);
-    }
-    t->run_env = call_env;                  /* Task owns it; base frame borrows */
-    t->started = 1;
-    EigsChunk *chunk = (EigsChunk *)fn->data.fn.body;
-    /* #997: pass the REAL argc. vm_run_ex's default of chunk->param_count
-     * marks every slot as caller-supplied, so every OP_DEFAULT_PARAM in the
-     * callee's prologue skipped and a defaulted parameter silently arrived as
-     * null — `d of 1` gives [1, 3] but `task_spawn of [d, 1]` gave [1, null].
-     * A re-collected single slot counts as one supplied argument. */
-    int supplied = (fn->data.fn.param_count == 1 && t->argc > 1) ? 1 : t->argc;
-    return vm_run_ex(chunk, call_env, NULL, supplied);
-}
-
-/* Record a task that just finished (returned or errored) and wake any joiner
- * blocked on it. `r` is the value vm_run returned (NULL on suspend — not this
- * path). g_has_error distinguishes a normal end from an uncaught error. */
-/* #530: release a task's handle slot and free the struct. Only for tasks
- * nobody will join (detached) — a reaped id reads as unknown afterwards
- * (task_alive 0, task_join null) and the slot is immediately reusable. */
-static void task_reap(Task *t) {
-    int id = t->id;
-    task_free(t);
-    handle_release(id);
-}
-
-/* #530: mark `tid` fire-and-forget. A detached task is reaped the moment it
- * finishes — or immediately here if it already has — so its handle slot
- * returns to the pool instead of holding the table until process exit. An
- * already-dead unobserved error moves to the scheduler-level counter so the
- * #493 exit gate survives the reap. The RUNNING task may detach itself.
- * Returns 1 on success, 0 for main (task 0) or an unknown id. */
-int task_do_detach(int tid) {
-    TaskScheduler *s = sched_get();
-    if (!s || tid == 0) return 0;
-    Task *t = sched_lookup(s, tid);
-    if (!t) return 0;
-    if (t->state == TASK_DONE || t->state == TASK_DEAD) {
-        if (t->err_unobserved) s->detached_err_count++;
-        task_reap(t);
-        return 1;
-    }
-    t->detached = 1;
-    return 1;
+/* ---- The VM half of the task seam (#744) -------------------------------
+ * The cooperative scheduler (src/task.c) drives tasks through THIS dispatch
+ * loop, so it needs two ways in and one error accessor. They are wrappers,
+ * not promotions: `vm_run_ex` is the 3131-line dispatch function and
+ * `vm_take_error_value` is inlined into CHECK_ERROR, and making either
+ * externally visible would cost the compiler its interprocedural view of the
+ * hot loop to save three lines here. Both stay `static`.
+ *
+ * What did NOT move with the scheduler, and why: the `jit_helper_*` runtime
+ * ABI. It consumes the `static inline` vm_push / vm_pop / vm_slot_lift, so
+ * moving it needs those promoted to a private header first — a different
+ * change with a different risk profile (see #744 item 5). */
+Value *vm_task_run_entry(EigsChunk *chunk, Env *env, int call_argc) {
+    return vm_run_ex(chunk, env, NULL, call_argc);
 }
-
-static void sched_finish(TaskScheduler *s, Task *t, Value *r) {
-    /* A task that ended (returned OR died) while its per-thread arena is still
-     * active — arena_mark with no matching arena_reset, e.g. the arena-suspend
-     * guard raised inside the scope — must not leave the arena active: (1) its
-     * error dict / result below outlive the task and cross to the joiner, so
-     * they must be heap, not arena (a later arena_reset would dangle them); and
-     * (2) the next task must start from a clean arena baseline. The suspend
-     * guard guarantees a task never *yields* with the arena active, so the only
-     * way it's active here is an ending task that leaked the scope. */
-    g_arena.active = 0;
-    if (g_has_error) {
-        t->has_error = 1;
-        t->error_value = vm_take_error_value();  /* the {kind,message,line} dict */
-        g_has_error = 0;
-        /* #493: a worker that dies of an uncaught error must fail the process
-         * if nothing ever joins it. Main (task 0) already propagates its own
-         * error via the trampoline's return, so only mark workers here; a
-         * later task_join on this task clears the flag. */
-        if (t->id != 0) t->err_unobserved = 1;
-        if (r) val_decref(r);
-        t->result = NULL;
-    } else {
-        t->result = r ? val_clone_for_send(r) : NULL;   /* share-nothing result */
-        if (r) val_decref(r);
-    }
-    t->state = t->has_error ? TASK_DEAD : TASK_DONE;
-    if (t->id != 0) s->live--;
-    if (t->run_env) { env_decref(t->run_env); t->run_env = NULL; }
-    /* Wake every task blocked on this one: enqueue it; on resume the join
-     * builtin's placeholder gets overwritten with our result (or re-raise). */
-    for (int i = 1; i < HANDLE_TABLE_SIZE; i++) {
-        Task *w = (Task *)handle_lookup(i, HANDLE_TASK);
-        if (w && w->state == TASK_SUSPENDED && w->join_target == t->id)
-            sched_ready_push(s, w->id, SCAUSE_JOIN_RELEASE);
-    }
-    if (s->main_task.state == TASK_SUSPENDED && s->main_task.join_target == t->id)
-        sched_ready_push(s, 0, SCAUSE_JOIN_RELEASE);
-    /* #530: a detached task's outcome is nobody's to consume — reap the slot
-     * now so task-per-message workloads aren't bounded by lifetime spawns.
-     * An uncaught death still fails the process: the #493 flag moves to the
-     * scheduler counter before the slot frees (the trace already printed). */
-    if (t->id != 0 && t->detached) {
-        if (t->err_unobserved) s->detached_err_count++;
-        task_reap(t);
-    }
+Value *vm_task_resume(Task *t) {
+    return vm_run_ex(NULL, NULL, t, 0);   /* frame already exists */
 }
-
-/* On resuming a task that was blocked in task_join, replace the placeholder
- * null the builtin left on the stack top with the joinee's result — or, if
- * the joinee died, re-raise its error in the joiner. Called from vm_run_ex's
- * resume path (after the stack is restored). */
-static void task_apply_join_result(Task *t) {
-    TaskScheduler *s = sched_get();
-    if (!s || t->join_target == 0) return;
-    Task *jt = sched_lookup(s, t->join_target);
-    t->join_target = 0;
-    if (!jt) return;
-    if (jt->has_error) {
-        jt->err_unobserved = 0;   /* #493: observed by this join (caught or not) */
-        /* Re-raise: restore the error payload so the joiner's CHECK_ERROR
-         * catches/propagates it as if the throw happened at the join. */
-        if (jt->error_value) {
-            g_error_value = jt->error_value;
-            val_incref(g_error_value);
-            g_error_kind = (int)EK_USER;
-        }
-        snprintf(g_error_msg, sizeof(g_error_msg), "joined task %d failed", jt->id);
-        g_has_error = 1;
-        return;
-    }
-    /* Overwrite TOS placeholder with the joinee's (already deep-copied) result. */
-    if (g_vm.sp > 0) {
-        slot_decref(g_vm.stack[g_vm.sp - 1]);
-        Value *res = jt->result ? jt->result : make_null();
-        val_incref(res);
-        g_vm.stack[g_vm.sp - 1] = slot_from_heap(res);
-    }
+Value *vm_task_take_error(void) {
+    return vm_take_error_value();
 }
 
-/* The trampoline. Entered from the outermost vm_execute once main (task 0)
- * has first suspended. Drives tasks round-robin until the ready queue drains,
- * then returns main's result. All-tasks-blocked = deadlock (loud, not a hang).
- * Task 0 finishing kills outstanding tasks (kill-outstanding ruling). */
-static Value *scheduler_trampoline(TaskScheduler *s) {
-    for (;;) {
-        int id = sched_ready_pop(s);
-        if (id < 0) {
-            /* Nothing runnable now. Sleepers waiting on the virtual clock are
-             * not a deadlock — advance time to the earliest wake and retry
-             * before deciding anything is stuck. */
-            if (sched_wake_sleepers(s)) continue;
-            /* Genuinely nothing runnable. If main already finished, we're done.
-             * If tasks remain live (blocked on joins that can't resolve), that's
-             * a deadlock — raise it loudly rather than hang. */
-            if (s->main_task.state == TASK_DONE || s->main_task.state == TASK_DEAD) {
-                if (s->main_task.has_error) {
-                    g_error_value = s->main_task.error_value;
-                    s->main_task.error_value = NULL;
-                    g_has_error = 1;
-                    return make_null();
-                }
-                Value *r = s->main_task.result;
-                s->main_task.result = NULL;
-                return r ? r : make_null();
-            }
-            /* #509: deadlock is a normal runtime error, not a hang — make it
-             * CATCHABLE. main is guaranteed SUSPENDED here (the DONE/DEAD case
-             * returned above), blocked at a task_join/recv. Build the structured
-             * error at main's blocked line (vm_take_error_value later lazily
-             * turns g_error_kind/raw/line into a {kind,message,line} dict, so
-             * e.kind == "deadlock"). We drive the print/handling ourselves and
-             * do NOT go through rt_error's g_try_depth-gated print: g_try_depth
-             * is a global, not part of a task's saved slice, so a suspended
-             * worker's still-open try can leave it non-zero here. */
-            Task *m = &s->main_task;
-            int catchable = 0;
-            for (int i = 0; i < m->saved_frame_count; i++)
-                if (m->saved_frames[i].try_count > 0) { catchable = 1; break; }
-            g_error_kind = (int)EK_DEADLOCK;
-            g_error_line = m->saved_current_line;
-            snprintf(g_error_raw, sizeof(g_error_raw),
-                     "all tasks are blocked — deadlock");
-            snprintf(g_error_msg, sizeof(g_error_msg),
-                     "Error line %d: all tasks are blocked — deadlock", g_error_line);
-            g_has_error = 1;
-            eigs_clear_error_value();
-            if (catchable) {
-                /* Deliver at main's blocked site: clear the block reason so the
-                 * resume doesn't fill a normal join/recv result, then re-enqueue
-                 * main. The loop resumes it with g_has_error set → CHECK_ERROR
-                 * unwinds to the handler (which reads e.kind == "deadlock"). */
-                m->join_target = 0;
-                m->recv_blocked = 0;
-                m->sleeping = 0;
-                sched_ready_push(s, 0, SCAUSE_DEADLOCK);
-                continue;
-            }
-            /* No handler in main → terminal: print loudly, exit non-zero. (No
-             * stack trace: between tasks g_vm has no live frames.) */
-            fprintf(stderr, "%s\n", g_error_msg);
-            return make_null();
-        }
-        Task *t = sched_lookup(s, id);
-        if (!t || t->state == TASK_DONE || t->state == TASK_DEAD) continue;
-        s->current = id;
-        /* #846: one entry per resume, written AFTER the pick (the pick is
-         * untouched) and only while armed — off, this is one load + branch. */
-        if (g_task_trace_on) sched_trace_record(s, id, s->pop_cause);
-
-        Value *r;
-        if (t->state == TASK_SUSPENDED) {
-            /* Resume (the join placeholder, if any, is filled inside the
-             * resume path via task_apply_join_result). */
-            r = vm_run_ex(NULL, NULL, t, 0);   /* resume: frame already exists */
-        } else {
-            r = task_start(t);   /* never-run task: bind args + run at base 0 */
-        }
+/* ---- Public API ---- */
 
-        if (t->state == TASK_SUSPENDED) {
-            /* It suspended again. task_yield → re-enqueue; task_join → stay
-             * blocked (woken by sched_finish); task_recv on an empty mailbox →
-             * stay blocked (woken by task_deliver); task_sleep → stay blocked
-             * (woken by sched_wake_sleepers when the clock reaches wake_at). */
-            if (t->join_target == 0 && !t->recv_blocked && !t->sleeping)
-                sched_ready_push(s, id, SCAUSE_YIELD);
-        } else {
-            sched_finish(s, t, r);
-            /* kill-outstanding: main ending tears the rest down deterministically. */
-            if (id == 0) break;
-        }
-    }
-    /* main finished with tasks still outstanding → reap them (kill-outstanding). */
-    if (s->main_task.has_error) {
-        g_error_value = s->main_task.error_value;
-        s->main_task.error_value = NULL;
-        g_has_error = 1;
-        return make_null();
-    }
-    Value *r = s->main_task.result;
-    s->main_task.result = NULL;
-    return r ? r : make_null();
-}
 
 static Value *vm_execute_common(EigsChunk *chunk, Env *env, int call_argc);
 
@@ -7278,30 +6494,8 @@ static Value *vm_execute_common(EigsChunk *chunk, Env *env, int call_argc) {
     int outermost = (g_vm.frame_count == 0);
     Value *r = vm_run(chunk, env, call_argc);
     if (!outermost) return r;
-    TaskScheduler *s = sched_get();
-    if (!s || !s->active) return r;
-    /* main (task 0) either finished (no task ever blocked) or suspended. If it
-     * suspended, its slice is saved; drive the trampoline. If it finished but
-     * tasks are still live, drive them too (kill-outstanding at main's end). */
-    if (s->main_task.state == TASK_SUSPENDED) {
-        /* main's first suspension happened in the initial vm_run, outside the
-         * trampoline — enqueue it now so it resumes round-robin, UNLESS it
-         * blocked on a join (sched_finish wakes it), a recv (task_deliver
-         * wakes it), or a sleep (sched_wake_sleepers wakes it). Mirrors the
-         * trampoline's re-enqueue guard. */
-        if (s->main_task.join_target == 0 && !s->main_task.recv_blocked &&
-            !s->main_task.sleeping)
-            sched_ready_push(s, 0, SCAUSE_YIELD);
-        return scheduler_trampoline(s);
-    }
-    /* main ran to completion without ever suspending. Record its result and,
-     * if any spawned task is still runnable, drive them (kill-outstanding). */
-    if (s->live > 0 && s->rcount > 0) {
-        s->main_task.state = TASK_DONE;
-        s->main_task.result = r ? val_clone_for_send(r) : NULL;
-        if (r) val_decref(r);
-        Value *mr = scheduler_trampoline(s);
-        return mr;
-    }
-    return r;
+    /* #744: TaskScheduler and the trampoline live in task.c. This is the one
+     * place the VM hands control to them; with no scheduler armed it returns
+     * `r` unchanged, so a program that never spawns pays one call. */
+    return task_sched_after_outermost(r);
 }
diff --git a/src/vm.h b/src/vm.h
index fab878f9..3e5e75f1 100644
--- a/src/vm.h
+++ b/src/vm.h
@@ -53,6 +53,13 @@ typedef struct ASTNode ASTNode;
 void vm_borrow_compensate(Value *arg, Value *result, int caller_owns_arg,
                           Value *fn_val, Env *env);
 
+/* The one CONSUMING builtin (builtins.c). Declared here — not re-externed in
+ * each consumer — because every site that must special-case it (vm.c's three
+ * call sites, builtins.c's builtin_dispatch, builtins_tensor.c's
+ * call_eigs_fn) compares `fn->data.builtin` against it, and hand-written
+ * copies of one signature in three TUs are free to drift (#744). */
+Value* builtin_free_val(Value *arg);
+
 /* ---- Opcodes ---- */
 typedef enum {
     /* Constants */
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 2fc7ee65..79b7b76d 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -6678,6 +6678,29 @@ else
 fi
 echo ""
 
+# [99i2] Core -> extension boundary (#744). The core must not include an
+# extension's PRIVATE header. `ext_db_internal.h` pulls <libpq-fe.h>, so a
+# core TU that includes it for one declaration makes the core unbuildable
+# without PostgreSQL headers wherever EIGENSCRIPT_EXT_DB=1 — and the only
+# target that compiles that combination is `make full`, which needs libpq to
+# build at all, so nothing in the suite could see it. Two legs: a structural
+# scan (core TUs from the Makefile's SOURCES, ext headers from the tree,
+# exemptions checked in both directions) and an executable -fsyntax-only
+# probe with every extension ON and <libpq-fe.h> POISONED, which is what
+# keeps the probe honest on a box that HAS libpq.
+echo "[99i2] Core/extension include boundary (#744)"
+TOTAL=$((TOTAL + 1))
+if bash "$TESTS_DIR/../tools/core_ext_boundary_check.sh" >/dev/null && \
+   bash "$TESTS_DIR/../tools/core_ext_boundary_check.sh" --selftest >/dev/null; then
+    PASS=$((PASS + 1))
+    echo "  PASS: no core -> extension-private include edge (gate self-test green)"
+else
+    FAIL=$((FAIL + 1))
+    echo "  FAIL: a core TU includes an extension private header, or the gate self-test broke"
+    bash "$TESTS_DIR/../tools/core_ext_boundary_check.sh" 2>&1 | head -8
+fi
+echo ""
+
 # [99o] Child-script exit-status accounting (#988). Two halves: the static
 # gate proves the mechanism is present and unbypassable, the behavioural test
 # proves it actually fails a section for each of the three modes the issue
diff --git a/tools/core_ext_boundary_check.sh b/tools/core_ext_boundary_check.sh
new file mode 100755
index 00000000..35262b39
--- /dev/null
+++ b/tools/core_ext_boundary_check.sh
@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+# core_ext_boundary_check.sh — the core must not include an extension's
+# private header (#744 item 1).
+#
+# WHY THIS IS A GATE AND NOT A COMMENT. `ext_db_internal.h` says "Only
+# included by ext_db.c" and pulls <libpq-fe.h>. A core translation unit that
+# includes it for one function declaration makes the CORE unbuildable without
+# PostgreSQL headers in every variant that sets EIGENSCRIPT_EXT_DB=1 —
+# measured on a box without libpq-dev, `gcc -DEIGENSCRIPT_EXT_DB=1 -c
+# src/builtins.c` died on `libpq-fe.h: No such file or directory`. Nothing in
+# the tree noticed, because the only target that compiles that combination is
+# `make full`, which needs libpq to build at all. The entry points now live in
+# src/ext_register.h — declarations, no extension types.
+#
+# TWO LEGS, because either alone can pass while the invariant is broken:
+#
+#   A. STRUCTURAL. Every core TU (enumerated from the Makefile's SOURCES —
+#      the authoritative list, not a copy of it) is scanned for an #include of
+#      any extension private header (enumerated from the tree, not a list).
+#      Exemptions are pinned by name and CHECKED IN BOTH DIRECTIONS: a pinned
+#      exemption that no longer matches anything is a hard failure, so a
+#      waiver cannot outlive the code it waives.
+#
+#   B. EXECUTABLE. `-fsyntax-only` over every core TU with EVERY extension
+#      switched ON, with a POISONED <libpq-fe.h> first on the include path.
+#      The poison is what makes this leg non-vacuous on a machine that HAS
+#      libpq: without it the probe would compile happily on a dev box and only
+#      fail on the machines that lack the header — the failure mode this gate
+#      exists to prevent. Leg A cannot replace leg B (an include can arrive
+#      transitively through another project header); leg B cannot replace leg
+#      A (only the libpq edge has a system header to poison).
+#
+# Usage: tools/core_ext_boundary_check.sh [--selftest]
+#   --selftest : plant the removed include back into a COPY of the tree and
+#                confirm BOTH legs go red — separately, so neither is coasting
+#                on the other.
+set -uo pipefail
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+REPO="$(pwd)"
+
+SELFTEST=0
+[ "${1:-}" = "--selftest" ] && SELFTEST=1
+
+# Every extension private header, from the tree. A new ext_*_internal.h is in
+# scope the moment it is committed — no list to update.
+ext_headers() {
+    local tree="$1"
+    ( cd "$tree" && ls src/ext_*_internal.h src/model_internal.h 2>/dev/null ) \
+        | sed 's#^src/##' | sort -u
+}
+
+# Core TUs = the Makefile's SOURCES. Ask make, don't parse the file: SOURCES
+# is a variable and its expansion is the only honest answer.
+core_tus() {
+    local tree="$1"
+    make -C "$tree" --no-print-directory print-SOURCES 2>/dev/null \
+        | tr ' ' '\n' | sed -n 's#^src/##p' | grep '\.c$' | sort -u
+}
+
+# Pinned exemptions: "<tu>:<header>  # reason". Each must MATCH something.
+EXEMPT=(
+  # handle_table_drain's HANDLE_NET teardown pass reads EigsNetSock.fd, and
+  # that header is deliberately free of socket headers for exactly this use
+  # (it says so). A type, not a declaration — ext_register.h cannot carry it.
+  "builtins.c:ext_net_internal.h"
+)
+
+leg_a() {
+    local tree="$1" rc=0 hdrs tus
+    hdrs=$(ext_headers "$tree")
+    tus=$(core_tus "$tree")
+    if [ -z "$hdrs" ] || [ -z "$tus" ]; then
+        echo "FAIL[A]: enumerated 0 headers or 0 core TUs (matcher broke)" >&2
+        return 1
+    fi
+    local n_scanned=0 n_hits=0
+    local -a seen_exempt=()
+    for tu in $tus; do
+        [ -f "$tree/src/$tu" ] || continue
+        n_scanned=$((n_scanned + 1))
+        for h in $hdrs; do
+            # A TU including its OWN private header is the pattern working,
+            # not a violation (ext_store.c is in SOURCES — always compiled —
+            # and owns ext_store_internal.h).
+            [ "$h" = "${tu%.c}_internal.h" ] && continue
+            grep -qE "^[[:space:]]*#[[:space:]]*include[[:space:]]+\"$h\"" "$tree/src/$tu" || continue
+            n_hits=$((n_hits + 1))
+            local pair="$tu:$h" ok=0
+            for e in "${EXEMPT[@]}"; do
+                [ "$e" = "$pair" ] && { ok=1; seen_exempt+=("$e"); }
+            done
+            if [ "$ok" = 0 ]; then
+                echo "FAIL[A]: core TU src/$tu includes extension private header \"$h\"" >&2
+                echo "         declare the entry point in src/ext_register.h instead" >&2
+                rc=1
+            fi
+        done
+    done
+    # Reverse direction: a pinned exemption that matches nothing is stale.
+    for e in "${EXEMPT[@]}"; do
+        local found=0
+        for s in ${seen_exempt[@]+"${seen_exempt[@]}"}; do [ "$s" = "$e" ] && found=1; done
+        if [ "$found" = 0 ]; then
+            echo "FAIL[A]: pinned exemption '$e' matches nothing — drop it" >&2
+            rc=1
+        fi
+    done
+    [ "$rc" = 0 ] && echo "leg A: $n_scanned core TUs scanned, $n_hits ext-private include(s), all pinned"
+    return $rc
+}
+
+# leg_b <tree> [only_tu]
+# `only_tu` narrows the probe to ONE translation unit and is used by --selftest
+# alone (a planted fault lives in one file; probing 28 to see it is 20 seconds
+# of nothing). The REAL run never passes it — the population is every core TU.
+leg_b() {
+    local tree="$1" only="${2:-}" rc=0
+    local poison; poison=$(mktemp -d)
+    cat > "$poison/libpq-fe.h" <<'POISON'
+#error "core TU reached <libpq-fe.h> (#744): the core must not include ext_db_internal.h"
+POISON
+    local tus; tus=$(core_tus "$tree")
+    local n=0
+    for tu in $tus; do
+        [ -f "$tree/src/$tu" ] || continue
+        [ -n "$only" ] && [ "$tu" != "$only" ] && continue
+        n=$((n + 1))
+        # Capture the status DIRECTLY. `$?`/PIPESTATUS after a pipeline (or
+        # after any simple command run in between, `:` included) is not the
+        # compiler's status — that mistake reads as "the probe is green".
+        local out st
+        out=$( cd "$tree" && gcc -c -o /dev/null -I"$poison" -Isrc \
+                 -Wall -Werror=switch -Werror=comment -Werror=misleading-indentation \
+                 -Werror=implicit-function-declaration \
+                 -DEIGENSCRIPT_EXT_HTTP=1 -DEIGENSCRIPT_EXT_MODEL=1 \
+                 -DEIGENSCRIPT_EXT_DB=1 -DEIGENSCRIPT_EXT_NET=1 \
+                 -DEIGENSCRIPT_VERSION='"gate"' "src/$tu" 2>&1 )
+        st=$?
+        if [ "$st" != 0 ]; then
+            echo "FAIL[B]: src/$tu does not compile with every extension ON and libpq poisoned" >&2
+            printf '%s\n' "$out" | head -6 >&2
+            rc=1
+        fi
+    done
+    rm -rf "$poison"
+    if [ -z "$only" ] && [ "$n" -lt 10 ]; then
+        echo "FAIL[B]: only $n core TUs probed (matcher broke)" >&2
+        rc=1
+    fi
+    if [ -n "$only" ] && [ "$n" != 1 ]; then
+        echo "FAIL[B]: selftest asked for src/$only and probed $n TUs" >&2
+        rc=1
+    fi
+    [ "$rc" = 0 ] && echo "leg B: $n core TUs compile with EXT_{HTTP,MODEL,DB,NET}=1 and <libpq-fe.h> poisoned"
+    return $rc
+}
+
+if [ "$SELFTEST" = 0 ]; then
+    a=0; b=0
+    leg_a "$REPO" || a=1
+    leg_b "$REPO" || b=1
+    if [ "$a" = 0 ] && [ "$b" = 0 ]; then
+        echo "OK: no core -> extension-private include edge"
+        exit 0
+    fi
+    exit 1
+fi
+
+# ---- selftest: plant the fault, prove each leg fires on its own ----------
+WORK=$(mktemp -d); trap 'rm -rf "$WORK"' EXIT
+cp -r "$REPO/src" "$REPO/Makefile" "$REPO/VERSION" "$WORK/" 2>/dev/null
+mkdir -p "$WORK/lib" && : > "$WORK/lib/.keep"
+fails=0
+
+# Control: the pristine copy must be GREEN in both legs, or the selftest is
+# measuring the copy and not the fault.
+leg_a "$WORK" >/dev/null 2>&1 || { echo "selftest FAIL: leg A red on a clean copy"; fails=1; }
+leg_b "$WORK" builtins.c >/dev/null 2>&1 || { echo "selftest FAIL: leg B red on a clean copy"; fails=1; }
+
+# Fault 1: the exact include #744 removed, back in builtins.c. Both legs see it.
+python3 - "$WORK" <<'PY'
+import sys
+p = sys.argv[1] + "/src/builtins.c"
+s = open(p).read()
+old = '#include "ext_register.h"'
+assert old in s
+s = s.replace(old, old + '\n#if EIGENSCRIPT_EXT_DB\n#include "ext_db_internal.h"\n#endif', 1)
+open(p, 'w').write(s)
+PY
+leg_a "$WORK" >/dev/null 2>&1 && { echo "selftest FAIL: leg A green with ext_db_internal.h back in builtins.c"; fails=1; } \
+                              || echo "selftest ok: leg A catches a planted core->ext include"
+leg_b "$WORK" builtins.c >/dev/null 2>&1 && { echo "selftest FAIL: leg B green with libpq reachable from builtins.c"; fails=1; } \
+                              || echo "selftest ok: leg B catches the poisoned libpq edge"
+
+# Fault 2: a stale exemption. Remove the include the waiver covers and the
+# reverse check must fire — a waiver must not outlive its subject.
+rm -rf "$WORK/src"; cp -r "$REPO/src" "$WORK/"
+python3 - "$WORK" <<'PY'
+import sys, re
+p = sys.argv[1] + "/src/builtins.c"
+s = open(p).read()
+s2 = re.sub(r'^[ \t]*#[ \t]*include[ \t]+"ext_net_internal\.h"[ \t]*\n', '', s, count=1, flags=re.M)
+assert s2 != s
+open(p, 'w').write(s2)
+PY
+leg_a "$WORK" >/dev/null 2>&1 && { echo "selftest FAIL: leg A green with a stale pinned exemption"; fails=1; } \
+                              || echo "selftest ok: leg A catches a stale exemption (reverse direction)"
+
+[ "$fails" = 0 ] && { echo "selftest: all planted faults caught"; exit 0; }
+exit 1
diff --git a/tools/embed_stack_soak.sh b/tools/embed_stack_soak.sh
index d0387618..238d0bcd 100755
--- a/tools/embed_stack_soak.sh
+++ b/tools/embed_stack_soak.sh
@@ -36,15 +36,21 @@ cd "$(dirname "$0")/.."
 BUILD=$(mktemp -d)
 trap 'rm -rf "$BUILD"' EXIT
 
+# Source list ANCHORED to the Makefile's SOURCES minus CLI_ONLY (the pattern
+# tools/amalgamate.sh and tools/freestanding_check.sh use). A hand-written copy
+# here is a list nothing ties to the tree: when #744 split three new TUs out of
+# vm.c/builtins.c/builtins_host.c, every copy of this list broke at the LINK
+# step and only the copies someone remembered to update were fixed.
+EMBED_SRC=$(make --no-print-directory print-SOURCES | tr ' ' '\n' | grep '\.c$')
+CLI_ONLY=$(make --no-print-directory print-CLI_ONLY | tr ' ' '\n' | grep '\.c$')
+for u in $CLI_ONLY; do EMBED_SRC=$(printf '%s\n' $EMBED_SRC | grep -vx "$u"); done
+[ -n "$EMBED_SRC" ] || { echo "FAIL: derived an EMPTY source list from the Makefile" >&2; exit 1; }
+
 gcc -Werror=implicit-function-declaration -Werror=switch -Werror=comment -Werror=misleading-indentation -O2 \
     -DEIGENSCRIPT_FREESTANDING=1 \
     -DEIGENSCRIPT_EXT_HTTP=0 -DEIGENSCRIPT_EXT_MODEL=0 -DEIGENSCRIPT_EXT_DB=0 \
     -o "$BUILD/embed_stack_soak" \
-    src/eigenscript.c src/lexer.c src/parser.c src/builtins.c \
-    src/builtins_host.c \
-    src/builtins_tensor.c src/hash.c src/arena.c src/state.c src/strbuf.c \
-    src/ext_store.c src/fmt.c src/lint.c src/lint_host.c src/chunk.c src/compiler.c \
-    src/vm.c src/jit.c src/trace.c src/eigs_embed.c \
+    $EMBED_SRC \
     tools/embed_stack_soak_main.c \
     -lm -lpthread
 
diff --git a/tools/failsoft_classify_check.sh b/tools/failsoft_classify_check.sh
index ab4ad608..6d73b59b 100755
--- a/tools/failsoft_classify_check.sh
+++ b/tools/failsoft_classify_check.sh
@@ -444,12 +444,24 @@ if [ "$usage_mode" = "--selftest" ]; then
     #    and the floor can speak. The one-sided faults above were already
     #    caught by design; a selftest built only from them proves nothing
     #    about this.
-    python3 - "$root/src/builtins.c" <<'PY' 2>/dev/null || cp "$SELF_ROOT/src/builtins.c" "$root/src/builtins.c"
+    python3 - "$root/src/builtins.c" <<'PY' || { echo "    selftest: could not plant the split-return fault"; cp "$SELF_ROOT/src/builtins.c" "$root/src/builtins.c"; }
 import re, sys
 p = sys.argv[1]
 s = open(p).read()
-s = s.replace("        return make_num(0);\n", "        return\n            make_num(0);\n", 1)
-open(p, "w").write(s)
+# Indentation is NOT hardcoded, and a plant that matches nothing is FATAL.
+# The literal 8-space form this used to search for was the shape every such
+# site happened to have; when #744 moved all seven of them into
+# builtins_buf.c the replace became a silent no-op, the file was rewritten
+# unchanged, the gate stayed (correctly) green, and the row read as "the
+# split detector missed the fault". A control that fails for the wrong
+# reason looks exactly like a real verdict.
+s2, n = re.subn(r"^([ \t]+)return make_num\(0\);$",
+                lambda m: m.group(1) + "return\n" + m.group(1) + "    make_num(0);",
+                s, count=1, flags=re.M)
+if n != 1:
+    sys.stderr.write("failsoft selftest: no `return make_num(0);` site to split\n")
+    sys.exit(1)
+open(p, "w").write(s2)
 PY
     expect 1 "two-sided loss (return split across lines) is caught"; restore
 
diff --git a/tools/freestanding_check.sh b/tools/freestanding_check.sh
index e444f644..2a0cf850 100755
--- a/tools/freestanding_check.sh
+++ b/tools/freestanding_check.sh
@@ -15,7 +15,19 @@ cd "$(dirname "$0")/.."
 BUILD=$(mktemp -d)
 trap 'rm -rf "$BUILD"' EXIT
 
-SRC="eigenscript lexer parser builtins builtins_host builtins_tensor hash arena state strbuf ext_store fmt lint lint_host chunk compiler vm jit trace eigs_embed"
+# Anchored to the Makefile's SOURCES (the single source of truth) minus the
+# CLI-only units, the same way tools/amalgamate.sh reads it — a hand-written
+# list here is a list nothing ties to the tree, and a new runtime TU silently
+# missing from it compiles nothing and reports whatever is left (#744).
+SRC=$(make --no-print-directory print-SOURCES \
+     | tr ' ' '\n' | sed -n 's#^src/\(.*\)\.c$#\1#p')
+CLI_ONLY=$(make --no-print-directory print-CLI_ONLY \
+     | tr ' ' '\n' | sed -n 's#^src/\(.*\)\.c$#\1#p')
+for u in $CLI_ONLY; do SRC=$(printf '%s\n' $SRC | grep -vx "$u"); done
+if [ -z "$SRC" ]; then
+    echo "FAIL: derived an EMPTY source list from the Makefile" >&2
+    exit 1
+fi
 for f in $SRC; do
     gcc -O2 -ffreestanding -fno-stack-protector -U_FORTIFY_SOURCE \
         -Werror=implicit-function-declaration -Werror=switch -Werror=comment -Werror=misleading-indentation \
diff --git a/tools/freestanding_smoke.sh b/tools/freestanding_smoke.sh
index 630b11a1..9e0492c5 100755
--- a/tools/freestanding_smoke.sh
+++ b/tools/freestanding_smoke.sh
@@ -13,15 +13,21 @@ trap 'rm -rf "$BUILD"' EXIT
 # The harness main consumes the runtime the way EigenOS will: through
 # eigs_embed.h with source strings — main.c (the POSIX CLI) is NOT part
 # of the freestanding profile.
+# Source list ANCHORED to the Makefile's SOURCES minus CLI_ONLY (the pattern
+# tools/amalgamate.sh and tools/freestanding_check.sh use). A hand-written copy
+# here is a list nothing ties to the tree: when #744 split three new TUs out of
+# vm.c/builtins.c/builtins_host.c, every copy of this list broke at the LINK
+# step and only the copies someone remembered to update were fixed.
+EMBED_SRC=$(make --no-print-directory print-SOURCES | tr ' ' '\n' | grep '\.c$')
+CLI_ONLY=$(make --no-print-directory print-CLI_ONLY | tr ' ' '\n' | grep '\.c$')
+for u in $CLI_ONLY; do EMBED_SRC=$(printf '%s\n' $EMBED_SRC | grep -vx "$u"); done
+[ -n "$EMBED_SRC" ] || { echo "FAIL: derived an EMPTY source list from the Makefile" >&2; exit 1; }
+
 gcc -Werror=implicit-function-declaration -Werror=switch -Werror=comment -Werror=misleading-indentation -O2 \
     -DEIGENSCRIPT_FREESTANDING=1 \
     -DEIGENSCRIPT_EXT_HTTP=0 -DEIGENSCRIPT_EXT_MODEL=0 -DEIGENSCRIPT_EXT_DB=0 \
     -o "$BUILD/eigs_fs" \
-    src/eigenscript.c src/lexer.c src/parser.c src/builtins.c \
-    src/builtins_host.c \
-    src/builtins_tensor.c src/hash.c src/arena.c src/state.c src/strbuf.c \
-    src/ext_store.c src/fmt.c src/lint.c src/lint_host.c src/chunk.c src/compiler.c \
-    src/vm.c src/jit.c src/trace.c src/eigs_embed.c \
+    $EMBED_SRC \
     tools/freestanding_smoke_main.c \
     -lm -lpthread
 
diff --git a/tools/gen_lsp_builtin_index.sh b/tools/gen_lsp_builtin_index.sh
index 7cf44d29..d73773c1 100755
--- a/tools/gen_lsp_builtin_index.sh
+++ b/tools/gen_lsp_builtin_index.sh
@@ -11,7 +11,8 @@
 #
 # Names come from the registration seams themselves:
 #   - core: every `env_set_local_owned(env, "name", ...)` line in
-#     src/builtins.c, src/builtins_host.c, src/hash.c, src/ext_store.c
+#     src/builtins.c, src/builtins_buf.c, src/builtins_host.c, src/hash.c,
+#     src/ext_store.c
 #     (the always-compiled registration TUs — store rides the single seam
 #     since #742). `__`-prefixed self-test hooks are skipped.
 #   - extensions: the X-macro rows of every EIGS_*_BUILTINS group in
@@ -44,7 +45,7 @@ export LC_ALL
 
 CORE_SRCS="src/builtins.c src/builtins_host.c src/hash.c src/ext_store.c"
 # TUs scanned for `name of ...` signature comments (core + every extension).
-DOC_SRCS="src/builtins.c src/builtins_host.c src/builtins_tensor.c \
+DOC_SRCS="src/builtins.c src/builtins_buf.c src/builtins_host.c src/builtins_tensor.c \
           src/hash.c src/ext_store.c src/ext_gfx.c src/ext_http.c \
           src/ext_db.c src/ext_net.c src/model_train.c"
 
diff --git a/tools/werror_switch_check.sh b/tools/werror_switch_check.sh
index fb64e85c..5daf76d7 100755
--- a/tools/werror_switch_check.sh
+++ b/tools/werror_switch_check.sh
@@ -223,7 +223,7 @@ SCRIPT_ENROLL_PINS="tools/amalgamate.sh:254253ab8bb08531 tests/test_lint_linkage
 # decision on record. test_leak_guard.sh:56 compiles the ENTIRE runtime
 # ($SRCS, the largest compile surface in the tree) and carried NEITHER
 # required flag until this change.
-SCRIPT_AUDITS="build.sh tools/freestanding_check.sh tools/freestanding_smoke.sh tools/embed_stack_soak.sh web/build.sh tests/test_leak_guard.sh tests/run_all_tests.sh"
+SCRIPT_AUDITS="build.sh tools/freestanding_check.sh tools/freestanding_smoke.sh tools/embed_stack_soak.sh tools/core_ext_boundary_check.sh web/build.sh tests/test_leak_guard.sh tests/run_all_tests.sh"
 
 # Comment lines must not be examined: a script comment QUOTING a bare
 # compile line is not a compile.
@@ -294,6 +294,7 @@ script:build.sh 3
 script:tools/freestanding_check.sh 2
 script:tools/freestanding_smoke.sh 1
 script:tools/embed_stack_soak.sh 1
+script:tools/core_ext_boundary_check.sh 1
 script:web/build.sh 1
 script:tests/test_leak_guard.sh 2
 script:tests/run_all_tests.sh 1
diff --git a/web/build.sh b/web/build.sh
index 2921a780..fce2c7d5 100755
--- a/web/build.sh
+++ b/web/build.sh
@@ -22,10 +22,11 @@ mkdir -p web/dist
 # units, which depend on HTTP/sockets/threads not available in WASM.
 SOURCES=(
     src/eigenscript.c src/lexer.c src/parser.c
-    src/builtins.c src/builtins_host.c src/builtins_tensor.c
+    src/builtins.c src/builtins_buf.c src/builtins_host.c src/builtins_tensor.c
+    src/fsutil.c
     src/hash.c src/arena.c src/state.c src/strbuf.c
     src/ext_store.c src/fmt.c src/lint.c src/lint_host.c
-    src/chunk.c src/compiler.c src/vm.c
+    src/chunk.c src/compiler.c src/vm.c src/task.c
     src/jit.c src/trace.c
     web/eigs_wasm.c
 )

From 7aac1045fd8a8ec847fca5963a751a51326a9d80 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 02:42:54 +0000
Subject: [PATCH 34/39] changelog: the #744 layering entry

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 CHANGELOG.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 24dc0f8b..f835acee 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -201,6 +201,30 @@ All notable changes to EigenScript are documented here.
 
 ### Changed
 
+- **Layering has structure rather than convention (#744, closing #746).** The
+  core no longer includes any extension's private header: `src/ext_register.h`
+  carries the registrars and per-state teardowns as declarations only, so
+  `builtins.c` and `state.c` compile with the database extension enabled on a
+  machine with no PostgreSQL headers, which they previously could not.
+  `vm.c` no longer re-declares any cross-TU symbol; the stale block-scope
+  externs are gone, including one for a symbol that exists nowhere, and the two
+  legitimate ones are homed in `vm.h` and `eigenscript.h`. Three new
+  translation units carry code moved verbatim: `src/fsutil.c` (file reading and
+  the module-resolver chain, so the VM, compiler, formatter, linter and the
+  embedding API stop reaching into the builtins layer to read a file),
+  `src/task.c` (the cooperative scheduler, with its state now private to it),
+  and `src/builtins_buf.c` (numeric buffers, the vectorized kernels, PCM16LE
+  and DEFLATE). Behaviour-preserving, proven: a 532-program corpus differential
+  against a pre-change build is byte-identical and `tools/jit_diff.sh` is
+  clean. A new gate, `tools/core_ext_boundary_check.sh`, keeps the boundary
+  from drifting back, with a structural scan anchored to the Makefile's source
+  list and an executable probe that poisons the PostgreSQL header so it cannot
+  pass vacuously on a machine that has it. Five build-source lists that nothing
+  tied to the tree now derive from the Makefile or were corrected; one of them
+  had been silently costing the language-server builtin index 19 signature
+  comments. Per-layer headers, and breaking up the 1253-line umbrella header,
+  are recorded in `ROADMAP.md` as their own round.
+
 - **The observer gate is hoisted ahead of the observe helpers, in both the
   interpreter and the JIT (#972).** With the gate closed, every assignment
   still dispatched into a helper, decoded the top of stack and resolved a slot

From 330edbfdd3ddde11a2fedb0655d8b8fc4555ab41 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 03:20:56 +0000
Subject: [PATCH 35/39] tests/tools: no pipeline decides a verdict under
 pipefail (#1122)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#1120 named the mechanism and fixed it in tools/strict_differential.sh.
The same construct decided verdicts in six more scripts that set
`pipefail`, and — found by the gate written here — in thirteen sites of
tools/werror_switch_check.sh that #1122's table missed.

The race, restated: `printf '%s' "$s" | grep -q "$pat"` exits grep the
instant it matches and closes the read end; the still-writing printf
takes SIGPIPE and exits 141; under pipefail the PIPELINE reports 141 —
a failed match — while grep's own status was 0, MATCHED. The script
then goes red printing the very bytes it says are missing.

Minimal repro (this box, bash 5.2.21), 4 MB subject, 200 evaluations:

    printf '%s' "$big" | grep -qF "abs: expected"   ->  200/200 rc=141
    grep -qF "abs: expected" <<<"$big"              ->    0/200
    str_has "$big" "abs: expected"                  ->    0/200

Two safe forms, chosen per site rather than uniformly:

  * `str_has` (bash `case`, no fork, no pipe) where the needle was a
    LITERAL under a BRE grep — 16 sites across the six scripts.
  * `grep -qX PAT <<<"$var"` where the pattern is a real regex and
    grep's line-oriented semantics are load-bearing — the 13 sites in
    werror_switch_check.sh. A here-string is one command: bash never
    blocks writing it, there is no second process to SIGPIPE, and
    pipefail is not consulted, so flags and semantics are untouched.

tools/freestanding_smoke.sh needed a split, not a substitution: its one
`grep -q "$want_sub"` was called two ways — four callers passed a plain
substring, two passed the line-anchored `^42$` / `^1$`. One substring
matcher would have served both and been silently WIDER on the anchored
pair (`check "..." 0 "42"` would then pass on output containing "426").
It is now `check` (str_has) and `check_line` (str_has_line), and each
call site says which it means.

Left alone, deliberately, with the reason recorded next to each:
grep reading a FILE (no writer to kill: test_pkg_fetch.sh's two eigs.json
checks, one of which is a real BRE), `grep -v`/`tail`/`sort` (read to
EOF), and `| head -N` diagnostics inside an already-decided FAIL branch.

New gate tools/pipefail_verdict_check.sh, enrolled as suite section
[99aa]: it scans every `*.sh` that sets pipefail and fails on an
early-exiting reader (grep -q/-l/-L/-m, head, sed q, awk exit, read) at
the end of a real pipe whose STATUS picks a branch. `--selftest` proves
both halves — it FIRES on each banned spelling and stays QUIET on each
legitimate one — and three vacuity floors make a collapsed enumeration a
failure rather than a pass. It also pins every `str_has*` copy in the
tree byte-identical to the canonical one-liner, which is what makes
strict_differential's `--selftest` (which tests those matchers' positive
AND negative behaviour) load-bearing for all of them.

Planted faults, executed per script: one converted site restored to the
`| grep -q` form, with the capture padded until the writer must block
(grown, no pipe-buffer constant assumed). Every one produced the #1120
symptom — a FAIL verdict whose own diagnostic contains the needle — and
the control (same padded capture, shell matcher) passed. Gate faults:
run in a tree with no scripts, all three vacuity floors fire; a
prefix-only str_has is caught as drift; one converted site restored in
place is named with its file, line and text.

Residuals are in the gate's header: it is a text scanner, not a bash
parser; a BARE pipeline whose status is a function's return value is not
flagged (deliberately — strict_differential's --selftest must run the
banned construct to demonstrate it); pipes inside `$( )` are skipped.

Closes #1122

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 tests/run_all_tests.sh            |  38 +++
 tests/test_module_resolve_base.sh |  22 +-
 tests/test_pkg_fetch.sh           |  29 ++-
 tests/test_pkg_skeleton.sh        |  34 ++-
 tests/test_pkg_verify_update.sh   |  32 ++-
 tools/embed_stack_soak.sh         |  27 ++-
 tools/freestanding_smoke.sh       |  42 +++-
 tools/pipefail_verdict_check.sh   | 379 ++++++++++++++++++++++++++++++
 tools/werror_switch_check.sh      |  41 ++--
 9 files changed, 606 insertions(+), 38 deletions(-)
 create mode 100755 tools/pipefail_verdict_check.sh

diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 79b7b76d..89db79f2 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -6726,6 +6726,44 @@ else
 fi
 echo ""
 
+# [99aa] No pipeline decides a verdict under pipefail (#1122; mechanism #1120).
+# `printf '%s' "$s" | grep -q "$pat"` under `set -o pipefail` is a race: grep -q
+# exits on the first match and closes the read end, the still-writing printf
+# takes SIGPIPE and exits 141, and pipefail reports the PIPELINE as 141 — a
+# failed match — while grep matched. The test then goes red printing the very
+# bytes it says are missing. This gate is static: it scans every .sh that
+# enables pipefail and fails on any early-exiting reader at the end of a pipe
+# whose STATUS picks a branch. File-reading greps, `grep -c`, `grep -vxF -f`
+# and diagnostic `| head` are all left alone, and --selftest proves both halves
+# of that — it FIRES on each banned spelling and stays QUIET on each legitimate
+# one. NOTE: run_all_tests.sh itself does not set pipefail, so its ~173
+# `| grep -q` sites are not exposed and are not subjects.
+#
+# Both halves are reported separately, and the self-test's check COUNT is
+# pinned rather than tested for ">0" — "at least one check passed" is satisfied
+# by a gate reduced to a single echo (the [99o] lesson).
+echo "[99aa] pipefail verdict-pipeline gate (#1122)"
+TOTAL=$((TOTAL + 1))
+PFV_EXPECTED=34
+pfv_audit_out=$(bash "$TESTS_DIR/../tools/pipefail_verdict_check.sh" 2>&1); pfv_audit_rc=$?
+pfv_self_out=$(bash "$TESTS_DIR/../tools/pipefail_verdict_check.sh" --selftest 2>&1); pfv_self_rc=$?
+PFV_COUNT=$(printf '%s\n' "$pfv_self_out" | sed -n 's/^  checks=\([0-9]*\) .*/\1/p')
+if [ "$pfv_audit_rc" -eq 0 ] && [ "$pfv_self_rc" -eq 0 ] && [ "${PFV_COUNT:-0}" -eq "$PFV_EXPECTED" ]; then
+    PASS=$((PASS + 1))
+    printf '%s\n' "$pfv_audit_out"
+else
+    FAIL=$((FAIL + 1))
+    if [ "$pfv_audit_rc" -ne 0 ]; then
+        echo "  FAIL: a pipefail script decides a verdict with a pipeline (audit exit $pfv_audit_rc):"
+        printf '%s\n' "$pfv_audit_out" | sed 's/^/      /'
+    fi
+    if [ "$pfv_self_rc" -ne 0 ] || [ "${PFV_COUNT:-0}" -ne "$PFV_EXPECTED" ]; then
+        echo "  FAIL: the gate self-test broke or shrank (exit $pfv_self_rc, checks=${PFV_COUNT:-none}, expected $PFV_EXPECTED):"
+        printf '%s\n' "$pfv_self_out" | sed 's/^/      /'
+    fi
+fi
+echo ""
+
 # [99p] Child-script exit-status ledger (#988). The synthetic FAIL: markers
 # emitted by the `bash` wrapper already fail each affected section; this is the
 # roster, so a reader sees WHICH children died rather than inferring it from
diff --git a/tests/test_module_resolve_base.sh b/tests/test_module_resolve_base.sh
index 3ba5edec..c34ac385 100755
--- a/tests/test_module_resolve_base.sh
+++ b/tests/test_module_resolve_base.sh
@@ -19,6 +19,26 @@
 # the real $HOME by overriding it.
 set -euo pipefail
 
+# ---------------------------------------------------- how this test matches (#1122)
+# NO PIPELINE DECIDES A VERDICT HERE. Mechanism, from #1120: under
+# `set -o pipefail`, `echo "$s" | grep -q "$pat"` is a RACE, not a test.
+# `grep -q` exits the instant it matches and closes the read end; the
+# still-writing `echo` then takes SIGPIPE and exits 141; pipefail reports the
+# PIPELINE as 141 — a failed match — while grep's own status was 0, MATCHED.
+# The test then goes red while printing the very output it says is missing.
+# `tools/strict_differential.sh --selftest` reproduces that deterministically
+# on a capture larger than the pipe buffer.
+#
+# str_has is bash's own matcher: no fork, no pipe, no status to misread. The
+# needle is QUOTED inside the pattern, so a glob character in it is a literal —
+# the same promise `grep -F` made. Every needle replaced below is a literal
+# with no BRE metacharacter in it, so this is the same test, not a wider one —
+# and WIDER is the only direction that could turn a check that can fail into
+# one that cannot.
+# The surviving `| head -N` pipelines are diagnostics inside an already-decided
+# FAIL branch; they settle nothing and are not exposed.
+str_has() { case "$1" in *"$2"*) return 0 ;; esac; return 1 ; }
+
 EIGS="${EIGENSCRIPT:-./eigenscript}"
 TMP=$(mktemp -d)
 trap "rm -rf '$TMP'" EXIT
@@ -54,7 +74,7 @@ OUT=$(HOME="$TMP/eigs_local" "$EIGS" "$TMP/main.eigs" 2>&1) || {
     exit 1
 }
 
-if echo "$OUT" | grep -q "PASS: module resolves its own peer"; then
+if str_has "$OUT" "PASS: module resolves its own peer"; then
     echo "  PASS: module resolves its own peer"
 else
     echo "  FAIL: module resolve base"
diff --git a/tests/test_pkg_fetch.sh b/tests/test_pkg_fetch.sh
index c01663f6..7517b29b 100755
--- a/tests/test_pkg_fetch.sh
+++ b/tests/test_pkg_fetch.sh
@@ -11,6 +11,26 @@
 #                        from source/, plus eigs.json + eigs.lock.json
 set -euo pipefail
 
+# ---------------------------------------------------- how this test matches (#1122)
+# NO PIPELINE DECIDES A VERDICT HERE. Mechanism, from #1120: under
+# `set -o pipefail`, `echo "$s" | grep -q "$pat"` is a RACE, not a test.
+# `grep -q` exits the instant it matches and closes the read end; the
+# still-writing `echo` then takes SIGPIPE and exits 141; pipefail reports the
+# PIPELINE as 141 — a failed match — while grep's own status was 0, MATCHED.
+# The test then goes red while printing the very output it says is missing.
+# `tools/strict_differential.sh --selftest` reproduces that deterministically
+# on a capture larger than the pipe buffer.
+#
+# str_has is bash's own matcher: no fork, no pipe, no status to misread. The
+# needle is QUOTED inside the pattern, so a glob character in it is a literal —
+# the same promise `grep -F` made. Every needle replaced below is a literal
+# with no BRE metacharacter in it, so this is the same test, not a wider one —
+# and WIDER is the only direction that could turn a check that can fail into
+# one that cannot.
+# The surviving `| head -N` pipelines are diagnostics inside an already-decided
+# FAIL branch; they settle nothing and are not exposed.
+str_has() { case "$1" in *"$2"*) return 0 ;; esac; return 1 ; }
+
 EIGS="${EIGENSCRIPT:-./eigenscript}"
 EIGS=$(realpath "$EIGS")
 
@@ -47,7 +67,7 @@ if "$EIGS" --pkg add greeting "$SOURCE_URL" v1.0.0 >/dev/null 2>&1; then
     exit 1
 fi
 BARE_ERR=$("$EIGS" --pkg add greeting "$SOURCE_URL" v1.0.0 2>&1 || true)
-if ! echo "$BARE_ERR" | grep -q "<owner>/<name>"; then
+if ! str_has "$BARE_ERR" "<owner>/<name>"; then
     echo "  FAIL: bare-name rejection should mention <owner>/<name>"
     echo "$BARE_ERR"
     exit 1
@@ -115,7 +135,7 @@ echo "  PASS: --pkg install reproduces eigs_modules at the locked commit"
 mkdir -p "$TMP/empty"
 cd "$TMP/empty"
 EMPTY_OUT=$("$EIGS" --pkg install 2>&1)
-if ! echo "$EMPTY_OUT" | grep -q "No dependencies"; then
+if ! str_has "$EMPTY_OUT" "No dependencies"; then
     echo "  FAIL: install on empty project should say 'No dependencies'"
     echo "$EMPTY_OUT"
     exit 1
@@ -171,6 +191,11 @@ echo "  PASS: --pkg add resolves a non-main default branch"
 
 # The manifest must NOT carry a fabricated tag — an omitted tag stays omitted,
 # which is what makes the project recoverable.
+#
+# This grep and the `'"tag": *"master"'` one below READ A FILE. There is no
+# writer on the other end of a pipe, so there is nothing for `grep -q` to
+# SIGPIPE and no #1122 exposure — and the second is a real BRE (`*` after a
+# space), which a substring matcher would answer differently. Both stay.
 if grep -q '"tag"' eigs.json; then
     echo "  FAIL: eigs.json must not record a guessed tag"
     cat eigs.json
diff --git a/tests/test_pkg_skeleton.sh b/tests/test_pkg_skeleton.sh
index 48b66cdc..2e985d80 100755
--- a/tests/test_pkg_skeleton.sh
+++ b/tests/test_pkg_skeleton.sh
@@ -6,6 +6,28 @@
 # live in test_pkg_fetch.sh.
 set -euo pipefail
 
+# ---------------------------------------------------- how this test matches (#1122)
+# NO PIPELINE DECIDES A VERDICT HERE. Mechanism, from #1120: under
+# `set -o pipefail`, `echo "$s" | grep -q "$pat"` is a RACE, not a test.
+# `grep -q` exits the instant it matches and closes the read end; the
+# still-writing `echo` then takes SIGPIPE and exits 141; pipefail reports the
+# PIPELINE as 141 — a failed match — while grep's own status was 0, MATCHED.
+# The test then goes red while printing the very output it says is missing.
+# `tools/strict_differential.sh --selftest` reproduces that deterministically
+# on a capture larger than the pipe buffer.
+#
+# str_has is bash's own matcher: no fork, no pipe, no status to misread. The
+# needle is QUOTED inside the pattern, so a glob character in it is a literal —
+# the same promise `grep -F` made. All but one needle below is a literal with
+# no BRE metacharacter, so those are the same test. The exception is the dep
+# line `... v1.0.0`, whose dots WERE wildcards under grep and are literal now:
+# strictly NARROWER, never wider — and wider is the only direction that could
+# turn a check that can fail into one that cannot. (Verified: the test still
+# passes, so the output does carry the literal.)
+# The surviving `| head -N` pipelines are diagnostics inside an already-decided
+# FAIL branch; they settle nothing and are not exposed.
+str_has() { case "$1" in *"$2"*) return 0 ;; esac; return 1 ; }
+
 EIGS="${EIGENSCRIPT:-./eigenscript}"
 EIGS=$(realpath "$EIGS")
 
@@ -16,7 +38,7 @@ cd "$TMP"
 
 # ---- help ----
 HELP_OUT=$("$EIGS" --pkg help 2>&1)
-if ! echo "$HELP_OUT" | grep -q "Subcommands:"; then
+if ! str_has "$HELP_OUT" "Subcommands:"; then
     echo "  FAIL: --pkg help missing 'Subcommands:'"
     echo "$HELP_OUT" | head -10
     exit 1
@@ -25,7 +47,7 @@ echo "  PASS: --pkg help prints usage"
 
 # ---- list on empty dir ----
 LIST_EMPTY=$("$EIGS" --pkg list 2>&1)
-if ! echo "$LIST_EMPTY" | grep -q "No dependencies"; then
+if ! str_has "$LIST_EMPTY" "No dependencies"; then
     echo "  FAIL: --pkg list on empty dir didn't say 'No dependencies'"
     echo "$LIST_EMPTY" | head -5
     exit 1
@@ -37,12 +59,12 @@ cat > eigs.json <<'EOF'
 {"name":"smoke","version":"0.0.0","deps":{"tester/vecmath":{"git":"https://example/vecmath","tag":"v1.0.0"}}}
 EOF
 LIST_ONE=$("$EIGS" --pkg list 2>&1)
-if ! echo "$LIST_ONE" | grep -q "1 dependency"; then
+if ! str_has "$LIST_ONE" "1 dependency"; then
     echo "  FAIL: --pkg list count wrong for 1 dep"
     echo "$LIST_ONE"
     exit 1
 fi
-if ! echo "$LIST_ONE" | grep -q "tester/vecmath  https://example/vecmath  v1.0.0"; then
+if ! str_has "$LIST_ONE" "tester/vecmath  https://example/vecmath  v1.0.0"; then
     echo "  FAIL: --pkg list missing dep line"
     echo "$LIST_ONE"
     exit 1
@@ -56,7 +78,7 @@ cat > eigs.json <<'EOF'
 "tester/greeting":{"git":"https://example/greeting","tag":"v0.2.0"}}}
 EOF
 LIST_TWO=$("$EIGS" --pkg list 2>&1)
-if ! echo "$LIST_TWO" | grep -q "2 dependencies"; then
+if ! str_has "$LIST_TWO" "2 dependencies"; then
     echo "  FAIL: --pkg list count not pluralized for 2 deps"
     echo "$LIST_TWO"
     exit 1
@@ -72,7 +94,7 @@ if "$EIGS" --pkg verify >/dev/null 2>&1; then
     exit 1
 fi
 BARE_VERIFY=$("$EIGS" --pkg verify 2>&1 || true)
-if ! echo "$BARE_VERIFY" | grep -q "<owner>/<name>"; then
+if ! str_has "$BARE_VERIFY" "<owner>/<name>"; then
     echo "  FAIL: verify on bare-name manifest should mention <owner>/<name>"
     echo "$BARE_VERIFY"
     exit 1
diff --git a/tests/test_pkg_verify_update.sh b/tests/test_pkg_verify_update.sh
index 98346da3..03e80d87 100755
--- a/tests/test_pkg_verify_update.sh
+++ b/tests/test_pkg_verify_update.sh
@@ -5,6 +5,26 @@
 # dir running --pkg commands.
 set -euo pipefail
 
+# ---------------------------------------------------- how this test matches (#1122)
+# NO PIPELINE DECIDES A VERDICT HERE. Mechanism, from #1120: under
+# `set -o pipefail`, `echo "$s" | grep -q "$pat"` is a RACE, not a test.
+# `grep -q` exits the instant it matches and closes the read end; the
+# still-writing `echo` then takes SIGPIPE and exits 141; pipefail reports the
+# PIPELINE as 141 — a failed match — while grep's own status was 0, MATCHED.
+# The test then goes red while printing the very output it says is missing.
+# `tools/strict_differential.sh --selftest` reproduces that deterministically
+# on a capture larger than the pipe buffer.
+#
+# str_has is bash's own matcher: no fork, no pipe, no status to misread. The
+# needle is QUOTED inside the pattern, so a glob character in it is a literal —
+# the same promise `grep -F` made. Every needle replaced below is a literal
+# with no BRE metacharacter in it, so this is the same test, not a wider one —
+# and WIDER is the only direction that could turn a check that can fail into
+# one that cannot.
+# The surviving `| head -N` pipelines are diagnostics inside an already-decided
+# FAIL branch; they settle nothing and are not exposed.
+str_has() { case "$1" in *"$2"*) return 0 ;; esac; return 1 ; }
+
 EIGS="${EIGENSCRIPT:-./eigenscript}"
 EIGS=$(realpath "$EIGS")
 
@@ -39,7 +59,7 @@ cd "$TMP/project"
 
 # ---- verify on clean install passes ----
 VERIFY_OUT=$("$EIGS" --pkg verify 2>&1)
-if ! echo "$VERIFY_OUT" | grep -q "Verified 1 package"; then
+if ! str_has "$VERIFY_OUT" "Verified 1 package"; then
     echo "  FAIL: verify on clean install should pass"
     echo "$VERIFY_OUT"
     exit 1
@@ -53,7 +73,7 @@ if "$EIGS" --pkg verify >/dev/null 2>&1; then
     exit 1
 fi
 VERIFY_DIRTY=$("$EIGS" --pkg verify 2>&1 || true)
-if ! echo "$VERIFY_DIRTY" | grep -q "TREE DRIFT"; then
+if ! str_has "$VERIFY_DIRTY" "TREE DRIFT"; then
     echo "  FAIL: verify should report 'TREE DRIFT' on tampered tree"
     echo "$VERIFY_DIRTY"
     exit 1
@@ -67,7 +87,7 @@ if "$EIGS" --pkg verify >/dev/null 2>&1; then
     exit 1
 fi
 VERIFY_GONE=$("$EIGS" --pkg verify 2>&1 || true)
-if ! echo "$VERIFY_GONE" | grep -q "MISSING"; then
+if ! str_has "$VERIFY_GONE" "MISSING"; then
     echo "  FAIL: verify should report 'MISSING' on gone tree"
     echo "$VERIFY_GONE"
     exit 1
@@ -79,7 +99,7 @@ echo "  PASS: --pkg verify catches a missing checkout"
 
 # ---- update with no new commit at tag is a no-op ----
 UPDATE_NOOP=$("$EIGS" --pkg update 2>&1)
-if ! echo "$UPDATE_NOOP" | grep -q "unchanged"; then
+if ! str_has "$UPDATE_NOOP" "unchanged"; then
     echo "  FAIL: update against unchanged tag should say 'unchanged'"
     echo "$UPDATE_NOOP"
     exit 1
@@ -104,7 +124,7 @@ if [ "$NEW_COMMIT" = "$OLD_COMMIT" ]; then
     echo "$UPDATE_OUT"
     exit 1
 fi
-if ! echo "$UPDATE_OUT" | grep -q "updated"; then
+if ! str_has "$UPDATE_OUT" "updated"; then
     echo "  FAIL: update should print 'updated'"
     echo "$UPDATE_OUT"
     exit 1
@@ -120,7 +140,7 @@ echo "  PASS: --pkg update <unknown> exits nonzero"
 
 # ---- verify accepts the post-update state ----
 VERIFY_POST=$("$EIGS" --pkg verify 2>&1)
-if ! echo "$VERIFY_POST" | grep -q "Verified 1 package"; then
+if ! str_has "$VERIFY_POST" "Verified 1 package"; then
     echo "  FAIL: verify should pass after update"
     echo "$VERIFY_POST"
     exit 1
diff --git a/tools/embed_stack_soak.sh b/tools/embed_stack_soak.sh
index 238d0bcd..63dcaa30 100755
--- a/tools/embed_stack_soak.sh
+++ b/tools/embed_stack_soak.sh
@@ -33,6 +33,24 @@
 set -euo pipefail
 cd "$(dirname "$0")/.."
 
+# ---------------------------------------------------- how this gate matches (#1122)
+# NO PIPELINE DECIDES A VERDICT HERE. Mechanism, from #1120: under
+# `set -o pipefail`, `printf '%s' "$s" | grep -q "$pat"` is a RACE, not a
+# test. `grep -q` exits the instant it matches and closes the read end; the
+# still-writing `printf` then takes SIGPIPE and exits 141; pipefail reports
+# the PIPELINE as 141 — a failed match — while grep's own status was 0,
+# MATCHED. The verdict then contradicts the evidence printed beside it.
+# Measured there: 21 false no-matches in 20,000 evaluations on a 157-byte
+# capture, and CERTAIN once the capture exceeds the pipe buffer, because the
+# writer must block and is therefore still writing when the reader exits.
+# `tools/strict_differential.sh --selftest` reproduces that deterministically.
+#
+# So the three verdict sites below match with bash's own matcher: no fork, no
+# pipe, no status to misread. The needle is QUOTED inside the pattern, so a
+# glob character in it is a literal — the same promise `grep -F` made.
+# All three needles are plain substrings; none was using a regex.
+str_has() { case "$1" in *"$2"*) return 0 ;; esac; return 1 ; }
+
 BUILD=$(mktemp -d)
 trap 'rm -rf "$BUILD"' EXIT
 
@@ -58,7 +76,7 @@ set +e
 out=$(bash -c "ulimit -s 64; '$BUILD/embed_stack_soak'" 2>&1); rc=$?
 set -e
 
-if [ "$rc" = 0 ] && printf '%s' "$out" | grep -q "embed_stack_soak: OK"; then
+if [ "$rc" = 0 ] && str_has "$out" "embed_stack_soak: OK"; then
     echo "  PASS: REPL soak completes in a 64 KiB stack ($out)"
 else
     echo "  FAIL: soak under 64 KiB stack (rc=$rc)"
@@ -75,13 +93,16 @@ set -e
 # the source and not some unrelated parse failure; the marker proves the
 # runtime was still usable afterwards.
 if [ "$grc" = 0 ] \
-   && printf '%s' "$gout" | grep -q "nesting too deep" \
-   && printf '%s' "$gout" | grep -q "embed_stack_soak: depth-guard OK"; then
+   && str_has "$gout" "nesting too deep" \
+   && str_has "$gout" "embed_stack_soak: depth-guard OK"; then
     echo "  PASS: parse-depth guard rejects cleanly in a 256 KiB stack"
 else
     echo "  FAIL: depth-guard probe under 256 KiB stack (rc=$grc)"
     # Drop the cascade of follow-on "expected ')'" lines the rejected source
     # produces, so the tail shows the diagnostic that matters.
+    # This pipeline is NOT a verdict and is NOT exposed to #1122: `grep -v` and
+    # `tail` both read to EOF, so neither can SIGPIPE the writer, and the
+    # branch it prints in has already decided. Same for the `| tail -5` above.
     printf '%s\n' "$gout" | grep -v "expected ')'" | tail -5
     exit 1
 fi
diff --git a/tools/freestanding_smoke.sh b/tools/freestanding_smoke.sh
index 9e0492c5..93f632ac 100755
--- a/tools/freestanding_smoke.sh
+++ b/tools/freestanding_smoke.sh
@@ -7,6 +7,30 @@
 set -euo pipefail
 cd "$(dirname "$0")/.."
 
+# ---------------------------------------------------- how this gate matches (#1122)
+# NO PIPELINE DECIDES A VERDICT HERE. Mechanism, from #1120: under
+# `set -o pipefail`, `printf '%s' "$s" | grep -q "$pat"` is a RACE, not a
+# test. `grep -q` exits the instant it matches and closes the read end; the
+# still-writing `printf` then takes SIGPIPE and exits 141; pipefail reports
+# the PIPELINE as 141 — a failed match — while grep's own status was 0,
+# MATCHED. `tools/strict_differential.sh --selftest` reproduces it
+# deterministically on a capture larger than the pipe buffer.
+#
+# The matcher below is bash's own: no fork, no pipe, no status to misread.
+# The needle is QUOTED inside the pattern, so a glob character in it is a
+# literal — the same promise `grep -F` made.
+# str_has      <haystack> <needle>      substring, what `grep -qF` meant
+# str_has_line <haystack> <whole line>  what `grep -q "^needle$"` meant
+#
+# The single `grep -q "$want_sub"` this replaced was a BRE, and its callers
+# used it two different ways: four passed a plain substring and two passed the
+# anchored `^42$` / `^1$` form, which grep answers per LINE. One substring
+# matcher would have served both and been silently WIDER on the anchored two —
+# `check "..." 0 "42"` would pass on output containing "426". So the two ways
+# are now two callees, and each call site says which it means.
+str_has()      { case "$1" in *"$2"*) return 0 ;; esac; return 1 ; }
+str_has_line() { case $'\n'"$1"$'\n' in *$'\n'"$2"$'\n'*) return 0 ;; esac; return 1 ; }
+
 BUILD=$(mktemp -d)
 trap 'rm -rf "$BUILD"' EXIT
 
@@ -32,21 +56,27 @@ gcc -Werror=implicit-function-declaration -Werror=switch -Werror=comment -Werror
     -lm -lpthread
 
 fail=0
-check() { # label, expected_rc, expected_substring, program
-    local label="$1" want_rc="$2" want_sub="$3" prog="$4"
+_check() { # label, expected_rc, matcher, wanted, program
+    local label="$1" want_rc="$2" how="$3" want="$4" prog="$5"
     set +e
     out=$("$BUILD/eigs_fs" "$prog" 2>&1); rc=$?
     set -e
-    if [ "$rc" = "$want_rc" ] && printf '%s' "$out" | grep -q "$want_sub"; then
+    if [ "$rc" = "$want_rc" ] && "$how" "$out" "$want"; then
         echo "  PASS: $label"
     else
+        # Diagnostic only — the verdict above is already decided, and `head`
+        # here cannot mislead it.
         echo "  FAIL: $label (rc=$rc, want $want_rc; output: $(printf '%s' "$out" | head -3))"
         fail=1
     fi
 }
+# label, expected_rc, expected_SUBSTRING, program
+check()      { _check "$1" "$2" str_has      "$3" "$4"; }
+# label, expected_rc, expected WHOLE LINE (was the `^...$` form), program
+check_line() { _check "$1" "$2" str_has_line "$3" "$4"; }
 
 # Core language still executes (interpreter-only).
-check "core language runs" 0 "^42$" '
+check_line "core language runs" 0 "42" '
 define square(x) as:
     return x * x
 xs is [1, 2, 3]
@@ -59,7 +89,7 @@ print of f"{v}"
 '
 
 # Observer semantics intact.
-check "observer predicates run" 0 "^1$" '
+check_line "observer predicates run" 0 "1" '
 e is 5
 loop while not converged:
     e is e * 0.5
@@ -73,7 +103,7 @@ check "exec is carved" 1 "exec_capture" 'x is exec_capture of "ls"'
 
 # import: a provider-served module works with no filesystem; a module the
 # provider lacks raises the profile-specific error.
-check "import resolves via the source provider" 0 "^42$" 'import tiny
+check_line "import resolves via the source provider" 0 "42" 'import tiny
 print of (tiny["answer"])'
 check "import raises profile error" 1 "no filesystem in the freestanding profile" 'import math'
 
diff --git a/tools/pipefail_verdict_check.sh b/tools/pipefail_verdict_check.sh
new file mode 100755
index 00000000..86109214
--- /dev/null
+++ b/tools/pipefail_verdict_check.sh
@@ -0,0 +1,379 @@
+#!/usr/bin/env bash
+# Static gate: under `set -o pipefail`, NO PIPELINE MAY DECIDE A VERDICT.
+#
+# The construct this bans, and why (#1120 named it, #1122 converted the rest):
+#
+#     if printf '%s' "$s" | grep -q "$pat"; then          # <- banned
+#
+# `grep -q` exits the instant it matches and closes the read end. The still
+# writing `printf` then takes SIGPIPE and exits 141. Under `pipefail` the
+# PIPELINE's status is 141 — a FAILED match — while grep's own status was 0,
+# MATCHED. The `if` takes the else branch and the test goes red while printing
+# the very bytes it says are missing. Measured in #1120: 21 false no-matches in
+# 20,000 evaluations on a 157-byte capture, 18 red runs in 186 end-to-end, and
+# CERTAIN once the capture exceeds the pipe buffer, because then the writer must
+# block and is therefore always still writing when the reader exits.
+#
+# The rule is about pipelines that decide by STOPPING EARLY, not about grep:
+#   * a grep that READS A FILE has no writer to kill                  — allowed
+#   * `grep -c`, `grep -v`, `grep -vxF -f` read to EOF                — allowed
+#   * `echo "$x" | head -5` printing a diagnostic decides nothing     — allowed
+# What is banned is an early-exiting reader at the end of a pipe whose STATUS
+# picks a branch: an `if`/`elif`/`while`/`until` condition, or an `&&`/`||` arm.
+#
+# Replace it with bash's own matcher — no fork, no pipe, no status to misread:
+#   str_has      "$s" "$lit"   substring, what `grep -qF` meant
+#   str_has_line "$s" "$line"  whole line, what `grep -q "^lit$"` meant
+#   str_has_word "$l" "$name"  word in a space list, what `grep -qw` meant
+# or `[[ $s =~ $re ]]` when the site really needed a regex.
+#
+# WHAT THIS GATE DOES NOT COVER (residuals belong in the code, where they
+# travel — the header is what the next reader trusts instead of re-deriving):
+#   * It is a TEXT SCANNER, not a bash parser. A pipeline assembled at runtime —
+#     `eval "$cmd"`, a command held in a variable — is invisible to it.
+#   * Subjects are `*.sh` files that set pipefail LEXICALLY. A script that
+#     inherits pipefail from its caller, sets it through a variable, or carries
+#     no `.sh` extension is not a subject.
+#   * Verdict position means an `if`/`elif`/`while`/`until` head or an `&&`/`||`
+#     arm. A BARE pipeline whose status becomes a function's return value, or
+#     which `set -e` acts on, is NOT flagged. That is deliberate:
+#     `tools/strict_differential.sh --selftest` must RUN the banned construct to
+#     demonstrate the race, and does so as a bare pipeline. The price is that a
+#     real matcher written as the last bare statement of a function slips
+#     through — that shape is a review question, not one this gate answers.
+#   * Pipes inside `$( )` or backticks are skipped whole: only their TEXT
+#     reaches the enclosing test, never their status. `$(cmd | grep -q x; echo
+#     $?)` would therefore be missed.
+#   * `sed`/`awk` early exit is recognised textually (a `q`/`Q` command, an
+#     `exit`). An early exit reached another way — an awk program in a file —
+#     is missed.
+#   * It does not judge whether a REPLACEMENT is correct. A converted site with
+#     a silently WIDER matcher is a review question. What it does pin is that
+#     every `str_has*` copy in the tree is byte-identical to the canonical
+#     one-liner — which is what makes `tools/strict_differential.sh --selftest`
+#     (suite [99s]) load-bearing for all of them: that selftest pins those three
+#     matchers' positive AND negative behaviour, and this gate pins that no copy
+#     has drifted away from the ones it tested.
+#
+# Cost: ~1.0 s wall over 18 pipefail scripts / ~5,100 logical lines. Pure bash;
+# the scan loop forks nothing.
+#
+# Usage: tools/pipefail_verdict_check.sh [--selftest]
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+# This gate holds itself to its own rule: every match below is bash's, and the
+# files are read with `while read` and `<`, never through a pipe.
+str_has() { case "$1" in *"$2"*) return 0 ;; esac; return 1 ; }
+
+# ---- vacuity floors -------------------------------------------------------
+# A check that examined nothing is a FAILURE, not a pass. All three floors are
+# well under the current tree (18 pipefail scripts, ~5,100 logical lines, 11
+# matcher copies) and are here to catch the enumeration COLLAPSING — a
+# `git ls-files` that returns nothing, a cd to the wrong place, a scanner that
+# reads zero lines. They are floors, not pins (mechanical-gates §5): a script
+# that legitimately stops setting pipefail lowers the count and needs no edit.
+MIN_PIPEFAIL_SCRIPTS=10
+MIN_LOGICAL_LINES=500
+MIN_MATCHER_DEFS=8
+
+# ---- what counts as a reader that stops early -----------------------------
+# grep with -q/-l/-L/-m (in any short bundle, or the long spellings), head,
+# `sed` with a `q`/`Q` command, `awk` with an `exit`, and the `read` builtin.
+# The short-option form is anchored to a WHOLE token so `--line-number` is not
+# read as `-l` and `-vxF` is not read as anything. A leading `!` and any number
+# of VAR=value prefixes are stepped over first, so `| LC_ALL=C grep -q` is seen.
+READER_RE='^[[:space:]]*(!?[[:space:]]*)([A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+)*((grep|egrep|fgrep)([[:space:]]|$)|head([[:space:]]|$)|sed([[:space:]]|$)|awk([[:space:]]|$)|read([[:space:]]|$))'
+GREP_EARLY_RE='(^|[[:space:]])(-[A-Za-z]*[qlLm][A-Za-z0-9]*|--quiet|--silent|--max-count|--files-with-matches|--files-without-match)([[:space:]=]|$)'
+SED_EARLY_RE='(^|[[:space:];{"'"'"'])[[:digit:]]*[qQ]([[:space:];}"'"'"']|$)'
+AWK_EARLY_RE='(^|[[:space:];{"'"'"'])exit([[:space:];})"'"'"']|$)'
+
+# ---- subject enumeration --------------------------------------------------
+# git where possible, `find` as the fallback: --selftest builds its fault trees
+# outside a repository, where `git ls-files` returns nothing, and a gate that
+# silently examines zero files there would be the exact hole it exists to close.
+list_scripts() {
+    local out
+    out="$(git ls-files '*.sh' 2>/dev/null || true)"
+    if [ -z "$out" ]; then
+        out="$(find . -name '*.sh' -not -path './.git/*' 2>/dev/null | sed 's|^\./||' || true)"
+    fi
+    printf '%s\n' "$out"
+}
+
+SCRIPTS_SCANNED=0
+LINES_SCANNED=0
+HITS=0
+HIT_LIST=""
+
+# A subject is a script that ENABLES pipefail lexically: a non-comment line
+# carrying both "set -" and "pipefail" (`set -o pipefail`, `set -euo pipefail`).
+# `set +o pipefail` carries "set +" and is therefore not a subject, which is
+# right — it turns the option OFF.
+sets_pipefail() {   # <file>
+    local line
+    while IFS= read -r line || [ -n "$line" ]; do
+        case "${line#"${line%%[![:space:]]*}"}" in '#'*) continue ;; esac
+        if str_has "$line" "pipefail" && str_has "$line" "set -"; then return 0; fi
+    done < "$1"
+    return 1
+}
+
+# Pipes inside `$( )` or backticks are NOT verdicts: only the substitution's
+# TEXT reaches the enclosing test, never the pipeline's status, so pipefail
+# cannot flip a branch through one. `echo "$(printf %s "$o" | head -1)"` is a
+# diagnostic no matter what surrounds it. Strip those bodies before splitting,
+# or every line that merely CONTAINS a substitution reads as a verdict site.
+STRIPPED=""
+strip_subst() {   # <logical line> -> STRIPPED
+    local s="$1"
+    case "$s" in *'$('*|*'`'*) ;; *) STRIPPED="$s"; return 0 ;; esac
+    local out="" i=0 n=${#s} depth=0 c
+    while [ "$i" -lt "$n" ]; do
+        c="${s:$i:1}"
+        if [ "$depth" -gt 0 ]; then
+            case "$c" in '(') depth=$((depth + 1)) ;; ')') depth=$((depth - 1)) ;; esac
+            i=$((i + 1)); continue
+        fi
+        if [ "$c" = '$' ] && [ "${s:$((i + 1)):1}" = '(' ]; then depth=1; i=$((i + 2)); continue; fi
+        if [ "$c" = '`' ]; then
+            i=$((i + 1))
+            while [ "$i" -lt "$n" ] && [ "${s:$i:1}" != '`' ]; do i=$((i + 1)); done
+            i=$((i + 1)); continue
+        fi
+        out="$out$c"; i=$((i + 1))
+    done
+    STRIPPED="$out"
+}
+
+# Does this pipeline segment end in a reader that stops early?
+early_reader() {   # <segment>
+    local seg="$1"
+    [[ $seg =~ $READER_RE ]] || return 1
+    case "${BASH_REMATCH[0]}" in
+        *grep*) [[ $seg =~ $GREP_EARLY_RE ]] || return 1 ;;
+        *head*) : ;;
+        *sed*)  [[ $seg =~ $SED_EARLY_RE ]] || return 1 ;;
+        *awk*)  [[ $seg =~ $AWK_EARLY_RE ]] || return 1 ;;
+        *read*) : ;;
+        *)      return 1 ;;
+    esac
+    return 0
+}
+
+scan_file() {   # <file>  -> appends to HIT_LIST
+    local f="$1" raw ln=0 start=0 logical="" lead seg tmp pos
+    local -a segs
+    while IFS= read -r raw || [ -n "$raw" ]; do
+        ln=$((ln + 1))
+        if [ -z "$logical" ]; then start=$ln; fi
+        case "$raw" in
+            *\\) logical="$logical${raw%\\} "; continue ;;
+        esac
+        logical="$logical$raw"
+        LINES_SCANNED=$((LINES_SCANNED + 1))
+        lead="${logical#"${logical%%[![:space:]]*}"}"
+        logical=""
+        case "$lead" in '#'*|'') continue ;; esac
+
+        # Verdict position? A condition head, or an && / || arm.
+        pos=""
+        case "$lead" in
+            if\ *|if\(*|elif\ *|while\ *|until\ *) pos="cond" ;;
+        esac
+        if [ -z "$pos" ] && { str_has "$lead" "&&" || str_has "$lead" "||"; }; then pos="conn"; fi
+        [ -z "$pos" ] && continue
+
+        # Split on REAL pipes: protect `||` first so it is not read as a pipe.
+        strip_subst "$lead"
+        tmp="${STRIPPED//\|\|/$'\001'}"
+        tmp="${tmp//|&/|}"
+        IFS='|' read -r -a segs <<<"$tmp"
+        [ "${#segs[@]}" -lt 2 ] && continue
+        local i
+        for ((i = 1; i < ${#segs[@]}; i++)); do
+            seg="${segs[$i]//$'\001'/||}"
+            if early_reader "$seg"; then
+                HITS=$((HITS + 1))
+                HIT_LIST="$HIT_LIST$f:$start [$pos] ${lead:0:150}"$'\n'
+                break
+            fi
+        done
+    done < "$f"
+}
+
+# ---- the matchers must not drift ------------------------------------------
+# Eight files carry their own copy of these one-liners — the six #1122 scripts,
+# tools/strict_differential.sh, and this gate (a sourced helper would need path
+# resolution before each script's own `cd`, which is its own footgun). A copy
+# that drifts WIDER is the failure this whole conversion exists to prevent, so
+# every copy is pinned to the byte.
+CANON_str_has='str_has() { case "$1" in *"$2"*) return 0 ;; esac; return 1 ; }'
+CANON_str_has_line='str_has_line() { case $'"'"'\n'"'"'"$1"$'"'"'\n'"'"' in *$'"'"'\n'"'"'"$2"$'"'"'\n'"'"'*) return 0 ;; esac; return 1 ; }'
+CANON_str_has_word='str_has_word() { case " $1 " in *" $2 "*) return 0 ;; esac; return 1 ; }'
+
+MATCHER_DEFS=0
+MATCHER_BAD=""
+check_matchers() {
+    local f line trimmed want
+    while IFS= read -r f; do
+        [ -n "$f" ] || continue
+        [ -f "$f" ] || continue
+        while IFS= read -r line || [ -n "$line" ]; do
+            trimmed="${line#"${line%%[![:space:]]*}"}"
+            trimmed="${trimmed%"${trimmed##*[![:space:]]}"}"
+            case "$trimmed" in
+                'str_has()'*)      want="$CANON_str_has" ;;
+                'str_has_line()'*) want="$CANON_str_has_line" ;;
+                'str_has_word()'*) want="$CANON_str_has_word" ;;
+                *) continue ;;
+            esac
+            # Column alignment differs where the three are declared together
+            # (`str_has()      {`); the canonical forms contain no run of two
+            # spaces, so squeezing runs to one normalises alignment and nothing
+            # else. What must not drift is the BODY.
+            while str_has "$trimmed" "  "; do trimmed="${trimmed//  / }"; done
+            MATCHER_DEFS=$((MATCHER_DEFS + 1))
+            if [ "$trimmed" != "$want" ]; then
+                MATCHER_BAD="$MATCHER_BAD  $f: $trimmed"$'\n'"    want: $want"$'\n'
+            fi
+        done < "$f"
+    done <<<"$(list_scripts)"
+}
+
+# ---- selftest -------------------------------------------------------------
+# What this proves: the detector FIRES on the banned construct in each of its
+# spellings, and STAYS QUIET on the legitimate ones. Without the negative half
+# a detector that flags everything would pass; without the positive half one
+# that flags nothing would.
+if [ "${1:-}" = "--selftest" ]; then
+    echo "== pipefail_verdict_check selftest =="
+    st_n=0; st_fail=0
+    TD="$(mktemp -d)"; trap 'rm -rf "$TD"' EXIT
+    # The fixtures below spell their pipes `@PIPE@`, expanded here. This file
+    # is scanned by this gate like any other pipefail script, so writing the
+    # banned construct literally in a fixture would make the auditor flag its
+    # own test data — and a self-exemption is how an auditor goes blind. The
+    # substitution keeps the fixtures readable and keeps this file provably
+    # free of the construct in every position.
+    probe() {   # <want: FIRE|QUIET> <label> <script body, pipes as @PIPE@>
+        local want="$1" label="$2" body="${3//@PIPE@/|}"
+        printf '#!/usr/bin/env bash\nset -euo pipefail\n%s\n' "$body" > "$TD/p.sh"
+        HITS=0; HIT_LIST=""; LINES_SCANNED=0
+        scan_file "$TD/p.sh"
+        st_n=$((st_n + 1))
+        local got="QUIET"; [ "$HITS" -gt 0 ] && got="FIRE"
+        if [ "$got" = "$want" ]; then printf '  ok    %-6s %s\n' "$want" "$label"
+        else st_fail=$((st_fail + 1)); printf '  FAIL  want %s got %s: %s\n' "$want" "$got" "$label"; fi
+    }
+
+    # --- must FIRE: the banned construct, every spelling that decides ---
+    probe FIRE  'if <pipe into grep -q>'          'if printf "%s" "$s" @PIPE@ grep -q "x"; then :; fi'
+    probe FIRE  'if ! <pipe into grep -q>'        'if ! echo "$s" @PIPE@ grep -q "x"; then :; fi'
+    probe FIRE  'if [ .. ] && <pipe into grep -q>' 'if [ "$a" = 1 ] && printf "%s" "$s" @PIPE@ grep -q "x"; then :; fi'
+    probe FIRE  '|| <pipe into grep -q> && return' 'f() { printf "%s" "$1" @PIPE@ grep -qE "re" && return 0; }'
+    probe FIRE  'grep -qF'                        'if echo "$s" @PIPE@ grep -qF "x"; then :; fi'
+    probe FIRE  'grep -qx / -qw'                  'if echo "$s" @PIPE@ grep -qxF "x"; then :; fi'
+    probe FIRE  'grep --quiet long form'          'if echo "$s" @PIPE@ grep --quiet "x"; then :; fi'
+    probe FIRE  'grep -l'                         'if echo "$s" @PIPE@ grep -l "x"; then :; fi'
+    probe FIRE  'grep -m1'                        'if echo "$s" @PIPE@ grep -m1 "x" >/dev/null; then :; fi'
+    probe FIRE  'pipe into head in a condition'   'if echo "$s" @PIPE@ head -1 >/dev/null; then :; fi'
+    probe FIRE  'pipe into sed q'                 'if echo "$s" @PIPE@ sed -n "1p;q" >/dev/null; then :; fi'
+    probe FIRE  'pipe into awk exit'              'if echo "$s" @PIPE@ awk "/x/ { exit 0 }"; then :; fi'
+    probe FIRE  'pipe into read'                  'if echo "$s" @PIPE@ read -r line; then :; fi'
+    probe FIRE  'backslash-continued condition'   'if [ "$a" = 1 ] \
+   && printf "%s" "$s" @PIPE@ grep -q "x"; then :; fi'
+    probe FIRE  'while condition'                 'while echo "$s" @PIPE@ grep -q "x"; do break; done'
+    probe FIRE  'env prefix before the reader'    'if echo "$s" @PIPE@ LC_ALL=C grep -q "x"; then :; fi'
+
+    # --- must stay QUIET: the legitimate greps ---
+    probe QUIET 'grep -q reading a FILE'          'if grep -q "x" eigs.json; then :; fi'
+    probe QUIET 'grep -q FILE on an || arm'       '[ -f f ] || grep -q "x" f'
+    probe QUIET 'grep -c reads to EOF'            'if [ "$(printf "%s" "$s" @PIPE@ grep -c "^OK")" -gt 0 ]; then :; fi'
+    probe QUIET 'grep -vxF -f reads to EOF'       'x=$(printf "%s\n" "$a" @PIPE@ grep -vxF -f <(printf "%s\n" "$b") || true); [ -n "$x" ] && echo hi'
+    probe QUIET 'grep -v | tail diagnostic'         'printf "%s\n" "$g" @PIPE@ grep -v "x" @PIPE@ tail -5'
+    probe QUIET 'head as a bare diagnostic'       'echo "$OUT" @PIPE@ head -5'
+    probe QUIET 'head inside a printf argument'   'printf "%s\n" "$(printf "%s" "$out" @PIPE@ head -1)" && echo done'
+    probe QUIET 'a comment naming the construct'  '# if printf "%s" "$s" @PIPE@ grep -q "x"; then'
+    probe QUIET 'grep --line-number is not -l'    'if echo "$s" @PIPE@ grep --line-number "x" >/dev/null; then :; fi
+true'
+    probe QUIET 'pipe into head inside $( ) in a test' 'if [ -n "$(printf "%s" "$s" @PIPE@ head -1)" ]; then :; fi'
+    probe QUIET 'pipe into grep -q inside a backtick'  'x=`printf "%s" "$s" @PIPE@ head -1` && echo "$x"'
+    probe FIRE  '$( ) elsewhere must not blind it'     'if [ "$(id -u)" = 0 ] && printf "%s" "$s" @PIPE@ grep -q "x"; then :; fi'
+    probe QUIET 'sort/uniq read to EOF'           'if [ -n "$(printf "%s\n" "$s" @PIPE@ sort -u)" ]; then :; fi'
+    probe QUIET 'tail reads to EOF'               'if [ -n "$(printf "%s\n" "$s" @PIPE@ tail -1)" ]; then :; fi'
+
+    # --- the subject filter itself ---
+    printf '#!/usr/bin/env bash\nset -e\nif echo "$s" | grep -q x; then :; fi\n' > "$TD/nopf.sh"
+    st_n=$((st_n + 1))
+    if sets_pipefail "$TD/nopf.sh"; then
+        st_fail=$((st_fail + 1)); echo "  FAIL  a script without pipefail was treated as a subject"
+    else echo "  ok    QUIET  a script that does not set pipefail is not a subject"; fi
+    printf '#!/usr/bin/env bash\nset -euo pipefail\n' > "$TD/pf.sh"
+    st_n=$((st_n + 1))
+    if sets_pipefail "$TD/pf.sh"; then echo "  ok    FIRE   \`set -euo pipefail\` is recognised as a subject"
+    else st_fail=$((st_fail + 1)); echo "  FAIL  \`set -euo pipefail\` was not recognised"; fi
+    printf '#!/usr/bin/env bash\nset +o pipefail\n' > "$TD/offpf.sh"
+    st_n=$((st_n + 1))
+    if sets_pipefail "$TD/offpf.sh"; then
+        st_fail=$((st_fail + 1)); echo "  FAIL  \`set +o pipefail\` (which DISABLES it) was read as a subject"
+    else echo "  ok    QUIET  \`set +o pipefail\` disables the option and is not a subject"; fi
+
+    # --- the matcher-drift check must be able to fail ---
+    printf '#!/usr/bin/env bash\nstr_has() { case "$1" in "$2"*) return 0 ;; esac; return 1 ; }\n' > "$TD/drift.sh"
+    MATCHER_DEFS=0; MATCHER_BAD=""
+    while IFS= read -r line || [ -n "$line" ]; do
+        trimmed="${line#"${line%%[![:space:]]*}"}"
+        while str_has "$trimmed" "  "; do trimmed="${trimmed//  / }"; done
+        case "$trimmed" in 'str_has()'*) MATCHER_DEFS=$((MATCHER_DEFS+1));
+            [ "$trimmed" != "$CANON_str_has" ] && MATCHER_BAD="drift" ;; esac
+    done < "$TD/drift.sh"
+    st_n=$((st_n + 1))
+    if [ -n "$MATCHER_BAD" ]; then echo "  ok    FIRE   a prefix-only str_has is caught as drift"
+    else st_fail=$((st_fail + 1)); echo "  FAIL  a drifted str_has was accepted"; fi
+
+    # --- vacuity: the selftest itself must have measured something ---
+    if [ "$st_n" -lt 34 ]; then
+        echo "  VACUOUS: only $st_n checks ran — the selftest itself broke"
+        st_fail=$((st_fail + 1))
+    fi
+    echo "  checks=$st_n failed=$st_fail"
+    [ "$st_fail" = 0 ] && { echo "OK"; exit 0; }
+    echo "FAIL"; exit 1
+fi
+
+# ---- the gate -------------------------------------------------------------
+while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    [ -f "$f" ] || continue
+    sets_pipefail "$f" || continue
+    SCRIPTS_SCANNED=$((SCRIPTS_SCANNED + 1))
+    scan_file "$f"
+done <<<"$(list_scripts)"
+
+check_matchers
+
+rc=0
+if [ "$SCRIPTS_SCANNED" -lt "$MIN_PIPEFAIL_SCRIPTS" ] || [ "$LINES_SCANNED" -lt "$MIN_LOGICAL_LINES" ]; then
+    echo "  FAIL: VACUOUS — examined $SCRIPTS_SCANNED pipefail script(s) / $LINES_SCANNED logical line(s);"
+    echo "        floors are $MIN_PIPEFAIL_SCRIPTS / $MIN_LOGICAL_LINES. A check that examined nothing is not a pass."
+    rc=1
+fi
+if [ "$MATCHER_DEFS" -lt "$MIN_MATCHER_DEFS" ]; then
+    echo "  FAIL: VACUOUS — found only $MATCHER_DEFS str_has* definition(s), floor $MIN_MATCHER_DEFS."
+    rc=1
+fi
+if [ -n "$MATCHER_BAD" ]; then
+    echo "  FAIL: a str_has* copy has drifted from the canonical one-liner:"
+    printf '%s' "$MATCHER_BAD"
+    rc=1
+fi
+if [ "$HITS" -gt 0 ]; then
+    echo "  FAIL: $HITS pipeline(s) decide a verdict under pipefail (#1122):"
+    printf '%s' "$HIT_LIST" | sed 's/^/    /'
+    echo "        Replace with str_has / str_has_line / str_has_word or [[ \$s =~ re ]]."
+    echo "        See the header of this file for why the pipeline is a race."
+    rc=1
+fi
+[ "$rc" = 0 ] && echo "  PASS: no pipeline decides a verdict in $SCRIPTS_SCANNED pipefail script(s) ($LINES_SCANNED logical lines, $MATCHER_DEFS matcher copies pinned)"
+exit $rc
diff --git a/tools/werror_switch_check.sh b/tools/werror_switch_check.sh
index 5daf76d7..d84d8b77 100755
--- a/tools/werror_switch_check.sh
+++ b/tools/werror_switch_check.sh
@@ -14,6 +14,19 @@
 # audit; asserting the flags on every compile invocation is simpler and cannot
 # be argued out of a leg.
 #
+# How this gate MATCHES (#1122). Every matcher below reads a here-string or a
+# file, never a pipe. `printf '%s\n' "$x" | grep -q RE` under `set -o pipefail`
+# — which this script sets — is a RACE, not a test: `grep -q` exits the instant
+# it matches and closes the read end, the still-writing `printf` takes SIGPIPE
+# and exits 141, and pipefail reports the PIPELINE as 141, a FAILED match,
+# while grep's own status was 0, MATCHED (#1120). Thirteen sites here were that
+# shape. `grep -qE RE <<<"$x"` is ONE command: bash never blocks writing a
+# here-string, there is no second process to kill, and pipefail is not
+# consulted — so grep's flags, pattern and LINE-ORIENTED semantics are all
+# preserved exactly, which matters here because these patterns are real EREs.
+# Measured on a 4 MB subject, 200 evaluations: pipeline form 200/200 wrong,
+# here-string form 0/200. tools/pipefail_verdict_check.sh is the gate.
+#
 # What counts as a compile invocation (the recognition rule):
 #   dry-run recipes are joined at backslash continuations, then SPLIT into
 #   individual invocations at shell separators (; && || |) — one logical
@@ -583,14 +596,14 @@ is_compile_invocation() {
     # path invokes `gcc.exe` / `x86_64-w64-mingw32-gcc.exe`, and a trailing
     # `.exe` broke the whole-token anchor in both matchers. No such line is in
     # the tree today — this is covered before the surface lands, not after.
-    printf '%s\n' "$1" | grep -qE '(^|[[:space:]]|[(`])("?[^[:space:]"]*[-/}])?"?(gcc|clang|cc|emcc)(-[0-9][0-9.]*)?(\.exe)?"?([[:space:]]|$)|(^|[[:space:]]|[(`])"?\$\{?CC([:]?[-=?+][^}]*)?\}?"?([[:space:]]|$)' || return 1
-    printf '%s\n' "$1" | grep -qE '\.c\b' && return 0
-    printf '%s\n' "$1" | grep -qE '(^|[[:space:]])-c([[:space:]]|$)' && return 0
+    grep -qE '(^|[[:space:]]|[(`])("?[^[:space:]"]*[-/}])?"?(gcc|clang|cc|emcc)(-[0-9][0-9.]*)?(\.exe)?"?([[:space:]]|$)|(^|[[:space:]]|[(`])"?\$\{?CC([:]?[-=?+][^}]*)?\}?"?([[:space:]]|$)' <<<"$1" || return 1
+    grep -qE '\.c\b' <<<"$1" && return 0
+    grep -qE '(^|[[:space:]])-c([[:space:]]|$)' <<<"$1" && return 0
     # `-x c -` compiles from stdin: a real compile with no .c anywhere and no
     # standalone -c. tests/test_leak_guard.sh's ASan probe is exactly this shape;
     # the coverage check below is what surfaced it (#925).
-    printf '%s\n' "$1" | grep -qE '(^|[[:space:]])-x[[:space:]]+c([[:space:]]|$)' && return 0
-    printf '%s\n' "$1" | grep -qE '(\$SOURCES|\$LSP_SOURCES|\$SRCS|\$\{SOURCES\[@\]\})'
+    grep -qE '(^|[[:space:]])-x[[:space:]]+c([[:space:]]|$)' <<<"$1" && return 0
+    grep -qE '(\$SOURCES|\$LSP_SOURCES|\$SRCS|\$\{SOURCES\[@\]\})' <<<"$1"
 }
 
 # ---- #925: assert the RECOGNIZER's own coverage -------------------------
@@ -651,7 +664,7 @@ recognizer_broad_match() {
     # --selftest fails if any widening of the strict matcher lands without the
     # matching widening here.
     # RECOGNIZER_PATTERN broad
-    printf '%s\n' "$1" | grep -qE '(^|[[:space:]"'"'"'(={;`])([^[:space:]"'"'"';)`]*[/}-])?(gcc|clang|cc|emcc)(-[0-9][0-9.]*)?(\.exe)?([[:space:]"'"'"';)`]|$)|\$\{?CC[:}=?+-]|\$CC\b'
+    grep -qE '(^|[[:space:]"'"'"'(={;`])([^[:space:]"'"'"';)`]*[/}-])?(gcc|clang|cc|emcc)(-[0-9][0-9.]*)?(\.exe)?([[:space:]"'"'"';)`]|$)|\$\{?CC[:}=?+-]|\$CC\b' <<<"$1"
 }
 
 # BROAD >= STRICT, asserted per axis rather than promised in a comment.
@@ -728,7 +741,7 @@ EOF
     # expansion referencing "$f" — a loop variable belonging to a DIFFERENT
     # function — which is an unbound-variable fatal under `set -u`, and it
     # aborted the clean run while the planted run still reported correctly.
-    bp=$(printf '%s' "$bp" | sed -e 's/^.*grep -qE //' -e 's/[[:space:]]*$//')
+    bp=$(printf '%s' "$bp" | sed -e 's/^.*grep -qE //' -e 's/ <<<"[$]1".*$//' -e 's/[[:space:]]*$//')
     pf=$(printf '%s' "$pf" | sed -e 's/^.*grep -qE //' -e 's/ "[$]f".*$//' -e 's/[[:space:]]*$//')
     # An extraction that finds NOTHING must fail, not skip. Failing open here is
     # the same silent-pass mode this whole gate exists to prevent, and the first
@@ -762,10 +775,10 @@ recognizer_waived() {
     #    Note an ENV-PREFIXED compile (`FOO=bar gcc -c x.c`) is not swallowed by
     #    this: the strict recognizer already SEES that line, so the waiver is
     #    never consulted for it.
-    printf '%s\n' "$seg" | grep -qE '^[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*$' && return 0
+    grep -qE '^[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*$' <<<"$seg" && return 0
     # 3. A relocatable LINK (`-r`), not a compile: no translation unit is
     #    compiled, so no warning flag applies. tests/test_lint_linkage.sh:48.
-    printf '%s\n' "$seg" | grep -qE '(^|[[:space:]])-r([[:space:]]|$)' && return 0
+    grep -qE '(^|[[:space:]])-r([[:space:]]|$)' <<<"$seg" && return 0
     # 2. The compiler word appears only inside a quoted string — a log message or
     #    a usage hint, e.g. amalgamate.sh's "compile: cc host.c ...".
     #
@@ -869,7 +882,7 @@ recognizer_coverage_check() {
 # Whole-argument flag match: `-Werror=switch-enum` must not satisfy this.
 carries_flag() {
     local line="$1" flag="$2"
-    printf '%s\n' "$line" | grep -qE "(^|[[:space:]])$flag([[:space:]]|$)"
+    grep -qE "(^|[[:space:]])$flag([[:space:]]|$)" <<<"$line"
 }
 
 missing_flags() {
@@ -1094,7 +1107,7 @@ if [ "${1:-}" = "--selftest" ]; then
         if [ "$VIOLATIONS" -ne 1 ]; then
             echo "SELFTEST FAILED: $name — expected 1 violation, got $VIOLATIONS"
             st_fail=1
-        elif ! printf '%s\n' "$out" | grep -qF -e "$needle"; then
+        elif ! grep -qF -e "$needle" <<<"$out"; then
             echo "SELFTEST FAILED: $name — violation output does not name '$needle'"
             printf '%s\n' "$out" | sed 's/^/    /'
             st_fail=1
@@ -1422,7 +1435,7 @@ EOF
     audit_stream "selftest:two-invocations-one-block" > "$st_out" < "$st_joined"
     out=$(cat "$st_out")
     if [ "$EXAMINED" -ne 2 ] || [ "$VIOLATIONS" -ne 1 ] \
-       || ! printf '%s\n' "$out" | grep -qF 'src/jit.c'; then
+       || ! grep -qF 'src/jit.c' <<<"$out"; then
         echo "SELFTEST FAILED: two invocations one block — expected examined=2 violations=1 naming src/jit.c, got examined=$EXAMINED violations=$VIOLATIONS"
         printf '%s\n' "$out" | sed 's/^/    /'
         st_fail=1
@@ -1444,8 +1457,8 @@ EOF
     else
         out=$(cat "$st_out")
         if [ "$EXAMINED" -ne 2 ] || [ "$VIOLATIONS" -ne 1 ] \
-           || ! printf '%s\n' "$out" | grep -qF 'selftest-target-b' \
-           || ! printf '%s\n' "$out" | grep -qF 'src/jit.c'; then
+           || ! grep -qF 'selftest-target-b' <<<"$out" \
+           || ! grep -qF 'src/jit.c' <<<"$out"; then
             echo "SELFTEST FAILED: merged-stream fault was not attributed to target B (examined=$EXAMINED violations=$VIOLATIONS)"
             printf '%s\n' "$out" | sed 's/^/    /'
             st_fail=1

From 5e1a2139535719fe44455e480c589d2f69d7ef5e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 05:26:40 +0000
Subject: [PATCH 36/39] ext_gfx: the drawing and audio surface answers a wrong
 argument loudly (#1007)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`src/ext_gfx.c` had no raise path at all: `grep -c rt_error src/ext_gfx.c`
was 0. ~89 `items[N]->data.num` reads happened with no type check — and
`Value`'s union overlaps `double num` with `char *str`, so a string where a
number belonged reinterpreted a pointer as a double — and ~52 `make_null()`
returns stood in for a rejected argument, indistinguishable from the same
builtin's ordinary "nothing to do" answer.

    $ cat repro.eigs
    o is gfx_open of [64, 64, "r"]
    ignore is gfx_clear of [0, 0, 0]
    ignore is gfx_rect of [0, 0, 32, 32, "255", 0, 0]
    print of f"wrong-typed red: {gfx_read of [4, 4]}"

    before (both modes):  wrong-typed red: [0, 0, 0]     rc=0
    after,  EIGS_STRICT=1: Error line 3: gfx_rect: expected [number x,
                           number y, number w, number h, number r, number g,
                           number b] and an optional number alpha   rc=1
    after,  flag off:      wrong-typed red: [0, 0, 0]     rc=0  (byte-identical)

WHAT CHANGED

- 60 ARG_GUARD / STRICT_REQUIRE sites across the whole extension: the
  drawing calls, the text calls, `gfx_fb`, `ppu_render_frame`, the audio
  generators, the mixer and the three device openers. Every guard sits above
  the `load_sdl2()` call and above any device check, so it is reachable on a
  machine with no libSDL2 and with no device — which is where CI runs; a
  guard behind an environment check is a guard that does not exist in the
  environment that lacks it. `gfx_read` and `audio_capture_open` are
  trace-recorded, so their guards also sit above the tape seam: a rejected
  argument is deterministic and must neither consume nor write a record.
- The union pun is gone in BOTH modes. An unchecked read is not behaviour
  anything can depend on; what a rejected call *draws* therefore changes
  (the parent painted at coordinate 0, in colour 0, at scale 1 — the punned
  subnormal), while every returned value stays byte-identical.
- Three rounds of blind review found the same axis three times, always on a
  different builtin: the argument CONTAINER (its arity and type) rather than
  its elements. The generators answered a short list with an empty sample
  list; the three audio *_open builtins answered a short or non-list argument
  by opening at the 44100/1 defaults and handing back a REAL DEVICE ID
  (`audio_stream_open of [48000]` -> 2, so the caller that asked for 48000
  was told it got 48000); `audio_play` / `audio_stream_push` /
  `audio_play_loop` answered a non-list `samples` with the documented
  "nothing to play" 0 while a wrong-typed ELEMENT of a list already raised.
  All three are closed, and the last of them is why the fourth item below
  exists: a hand-written probe row per bug fixes the instance, not the
  pattern.

GATES

- `tools/gfx_strict_sweep.sh` (new, suite section [139]) derives the guarded
  names AND their required arity from `ext_gfx.c`'s own `want` strings and
  crosses each with the wrong-container shapes, requiring every pair to raise
  from its own guard or to carry a reason in a staleness-checked allowlist.
  35 names, 140 rows, 129 raises, 11 allowlisted. Validated by execution:
  against a build of the parent it reports raised=0 and trips its own floor;
  against the previous round of this same change it names 18 silent rows —
  the three openers a blind review found by hand, plus two builtins it did
  not reach.

  Four things this gate had to learn before it was worth having, each bought
  by a red run rather than by reasoning, and each the same mistake: treating
  "the check did not run" as "the check says no".
  * A probe that exits nonzero having printed no runtime error is UNRUN, not
    a guard verdict. Its first suite run reported `MISATTRIBUTED audio_open`
    for a child the loaded box had killed. Retried three times, then failed
    under its own name (#988's rule).
  * The verdict is decided by shell case-globs, not `grep -q`. Two greps per
    row is 280 forks; a grep that cannot fork exits nonzero, which read as
    "that line is not there" and turned RAISED-OWN into MISATTRIBUTED about
    one run in eight (measured). Same for the pinned-name and allowlist
    lookups.
  * The guarded-name set is PINNED. Deleting audio_play's guard took the
    population from 35 names to 34 and the sweep still printed OK — a
    derived population cannot notice its own subject leaving.
  * An allowlist entry no probe ever asks is dead, and the raises-now
    staleness check cannot see it. Six such entries shipped in the first
    draft; all six are gone and the check now fails on a seventh.
- `tools/strict_differential.sh`: 117 probes / 18 pins / 122 valid-input rows
  against a `make gfx` build of the parent — identical-when-off 117,
  differing 0, raises-under-strict 117, silent 0, misattributed 0.
- `tools/gfx_pixel_differential.sh` (new in the previous round, section
  [138]): the readback oracle, because every drawing builtin returns null on
  every path, so a returned-value differential measured that surface in the
  one state where it could not fail. 37 rows, 23 raises, 0 silent.
- `tools/failsoft_classify_check.sh`: `NULL_SCOPE='src/ext_gfx.c'`, floor
  136 -> 174, every `make_null()` in the file classified, four new selftest
  rows proving the widened matcher fires in scope, discriminates in scope,
  stays out of scope, and rejects a misspelled tag.
- `make asan-gfx` becomes a gate: `tests/test_asan_gfx.sh` + section [137],
  which builds its own instrumented binary rather than running `make` under
  the suite. Its triage found one leak and it was ours (`gfx_poll`'s event
  dict, 584 bytes / 6 allocations on the two decode-nothing paths), so no
  LSan suppression file ships — a suppression with no leak behind it is a
  waiver for a claim nobody checked.
- `tests/test_gfx_argtypes.eigs` (section [133]) runs twice, plain and
  strict, with pinned counts; the load-bearing non-strict row is the pixel
  proof, the only row that can see the defect on real pixels.

RESIDUALS

- A builtin that takes NO argument (`gfx_poll`, `gfx_present`, `gfx_ticks`,
  `gfx_close`, `audio_close`, `audio_clear`, `audio_capture_close`,
  `audio_capture_read`, `audio_stream_close`, `audio_stream_clear`,
  `audio_stream_queued`, `audio_queue_size`, `audio_music_stop`) still
  ignores one, and a surplus TRAILING argument to a fixed-arity builtin is
  still dropped. Both are the general over-arity question (#989), not this
  extension's, and both are stated in docs/BUILTINS.md rather than left for
  a reader to discover.
- `gfx_clear`'s wrong-SHAPE branch stays a coercion (it cleared to black
  before and still does with the flag off), pinned as such in [133].
- The sweep probes the TOP-LEVEL container, not a nested slot;
  `audio_play_loop of [42, 2]` is pinned by hand for that reason.
- NOT this change, but seen while validating it and worth a look:
  `tools/werror_switch_check.sh` intermittently fails under load with a
  GATE ERROR naming a random tracked `.sh` that contains no compiler token
  at all (`tools/obs_reader_sync_check.sh`, `tests/test_state_at_order.sh`,
  `tools/obs_marker_check.sh` on three different runs; measured 1 failure
  in 5 consecutive standalone runs on a 4-core box shared with eight other
  agents, and 2 of 5 suite runs). Its `recognizer_waived` decides with
  `printf | grep -q ... && return 0` and `$(... | sed ...)`, so a helper
  that cannot fork becomes a verdict — the same class this change had to
  fix twice inside its own new gate. Reproducible with
  `for i in $(seq 1 6); do bash tools/werror_switch_check.sh >/dev/null ||
  echo FLAKE; done` under load.

RECONCILIATION ONTO THE INTEGRATION BRANCH

This lands on an integration branch that is 10 commits past the v0.43.0 base
this change was written on, and three of those commits rewrote files it also
rewrites. What was done with each, so a later reader does not have to diff
four trees to find out:

- `tools/strict_differential.sh` — three-way. #1120 replaced every `grep -q`
  verdict with fork-free matchers (`str_has` / `str_has_line` /
  `str_has_word`) because `printf | grep -q` under `pipefail` reports a failed
  match when grep matched and the writer took SIGPIPE, and added `--selftest`,
  an evidence recorder, a binary fingerprint and a DID NOT RUN bucket. #971
  round 2 deleted the divergence-waiver mechanism. This change added probe
  rows, VALID rows, the SDL dummy-driver exports, and a per-file presence
  probe with a sentinel, and it also carried its own (weaker) fix for the
  same pipefail race, spelled as herestrings.
  Resolution: #1120's file is the base. Every row this change adds is kept
  (139 probes now, up from 99). No verdict here goes through a pipeline: the
  herestring conversions are dropped in favour of the matcher of the right
  shape at each site, and the presence probe's `case` globs became `str_has`.
  The waiver mechanism stays deleted — this change added no waiver entry
  (`EXPECTED_DIVERGE_UNSTABLE` and `_FIXED` were both empty on its branch), so
  there was nothing to re-argue. Its awk that derived guarded names from
  ARG_GUARD+STRICT_REQUIRE is dropped for #1120's `extract_guard_names`, which
  is a superset (it also reads STRICT_DOMAIN and num_guard_named), so the
  "STRICT_REQUIRE guards were structurally unprobed" fix this change made
  survives by being subsumed rather than by being applied twice.
  The presence probe is the one place both sides did real work on the same
  lines, so it is spelled out: it is now per-FILE (this change's reduction of
  34 interpreter launches to 1, since a builtin's presence is a property of
  its translation unit), and a file's classification is believed only if BOTH
  tests pass — #1120's exit-status test (`run_did_not_measure`, which sees
  126/127 and signals) and this change's sentinel (the probe's own first
  `print` must appear in the capture, which sees a child that produced no
  output at all). Either one failing puts the file in #1120's DID NOT RUN
  bucket, which is red, names the environment rather than a guard, and
  records evidence — instead of this change's separate `probe_failed` flag,
  which said the same thing in a second vocabulary.

- `tools/werror_switch_check.sh` — union. #971 round 2 fixed the enrollment
  fallback (it chose `git ls-files` vs `find` by whether git produced output,
  so a fork that lost a race under load swapped in untracked files and
  reported them as unenrolled — the root cause of the `[99i]`/`[99p]` flake).
  #744 enrolled `tools/core_ext_boundary_check.sh`. Both are kept, and this
  change's `tests/test_asan_gfx.sh` (floor 4) sits alongside them in
  SCRIPT_AUDITS and in the per-script floors.
  That makes the last RESIDUAL above STALE: the werror flake it reports is
  #971 round 2's, and it is fixed here. Re-measured on the merged tree, 3
  consecutive standalone runs, all green (540 compile invocations across 29
  dry-run targets + 9 scripts).

- `tools/failsoft_classify_check.sh` — no conflict; both sides' changes are
  in. #744 made the split-return planter indentation-agnostic (its seven
  8-space sites had moved to `src/builtins_buf.c`, so the plant became a
  silent no-op and the control failed for the wrong reason); this change added
  NULL_SCOPE, fs:VOID and the floor move to 174. One comment is corrected:
  the header's make_null() census was measured before #744 split
  builtins_buf.c out, so it no longer matches `--residuals`; the census is
  now labelled as the pre-#744 measurement it is, and `--residuals` named as
  the live number. Selftest 17/17.

- `tests/run_all_tests.sh` — the conflict was positional. This change inserts
  three sections immediately above `[132]`, whose comment #859 had meanwhile
  rewritten (dropdown/combobox overlay rows). #859's comment is kept.

SECTION LABELS. The integration branch already uses `[100]`-`[136]`, and its
`[136]` is #1112's replay-diff crash gate. This change's `[136]`/`[137]`/`[138]`
are therefore renumbered to `[137]`/`[138]`/`[139]`, in the headers, the
`echo` lines and the one cross-reference in `[133]`'s comment ("leaks on those
paths"). No other file cites them. `tools/suite_label_check.sh`: 258 labelled
echo lines, no two sections share a label.

REBASED ONTO #1122, AND ITS GATE FOUND A REAL DEFECT HERE. The integration
branch advanced under this work to carry #1122 ("no pipeline decides a verdict
under pipefail"). Neither of that change's regions collided with this one, but
its new gate, `tools/pipefail_verdict_check.sh`, immediately flagged a site in
THIS change's own new tool: `tools/gfx_strict_sweep.sh` decided a selftest
branch with `printf | grep -qx`, the exact construct #1120 established is a
race rather than a test. Worse than the race, the selftest was proving a
matcher the tool does not use in production. Fixed by factoring the real
case-glob into `name_in_population()` and calling it from BOTH the pin loop and
the selftest row, so the selftest now exercises the matcher that ships. The
gate reports 21 scripts and 6400 logical lines clean with 11 matcher copies
pinned, and its own selftest passes 34 checks.

VALIDATION, all post-rebase on the integrated tree:

  release suite                     5059/5059 passed, 0 failed
  gfx-binary full suite             5142/5142 passed, 0 failed
  ASan+UBSan, detect_leaks=1        5060/5060 passed, 0 failed, no leak-tally NOTE
  tools/jit_diff.sh                 OK, 238 programs x {jit, osr}, 0 ledgered
  tools/replay_diff.sh              OK, 238 programs, 0 nondeterministic, 0 ledgered
  tools/suite_label_check.sh        258 labelled sections, no collisions
  tools/doc_drift_check.sh          clean

Zero FAIL lines in any suite and no binary-fingerprint error in either full run.

RE-ASSERTED AFTER THE MERGE, by running each rather than grepping for it, since
a clean auto-merge is where a one-line fix gets silently undone: the three
strict scan guards are leak-clean under the sanitizer (#971 round 2);
`strict_differential.sh --selftest` passes 11 checks (#1120); and
`tests/test_lint.sh` reports its own ledger check green (#1121).

Closes #1007

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 docs/BUILTINS.md                             |  82 ++-
 docs/SPEC.md                                 |  14 +-
 docs/TRACE.md                                |  15 +
 src/ext_gfx.c                                | 534 +++++++++++++++----
 tests/gfx_asan_corpus/01_draw.eigs           |  27 +
 tests/gfx_asan_corpus/02_poll.eigs           |  14 +
 tests/gfx_asan_corpus/03_fb_ppu.eigs         |  19 +
 tests/gfx_asan_corpus/04_audio.eigs          |  23 +
 tests/gfx_asan_corpus/05_capture_stream.eigs |  18 +
 tests/gfx_asan_corpus/06_rejected.eigs       |  56 ++
 tests/run_all_tests.sh                       | 199 ++++++-
 tests/test_asan_gfx.sh                       | 235 ++++++++
 tests/test_gfx_argtypes.eigs                 | 220 +++++++-
 tools/failsoft_classify_check.sh             | 132 ++++-
 tools/gfx_pixel_differential.sh              | 400 ++++++++++++++
 tools/gfx_strict_sweep.sh                    | 422 +++++++++++++++
 tools/strict_differential.sh                 | 157 +++++-
 tools/werror_switch_check.sh                 |   7 +-
 18 files changed, 2405 insertions(+), 169 deletions(-)
 create mode 100644 tests/gfx_asan_corpus/01_draw.eigs
 create mode 100644 tests/gfx_asan_corpus/02_poll.eigs
 create mode 100644 tests/gfx_asan_corpus/03_fb_ppu.eigs
 create mode 100644 tests/gfx_asan_corpus/04_audio.eigs
 create mode 100644 tests/gfx_asan_corpus/05_capture_stream.eigs
 create mode 100644 tests/gfx_asan_corpus/06_rejected.eigs
 create mode 100755 tests/test_asan_gfx.sh
 create mode 100755 tools/gfx_pixel_differential.sh
 create mode 100755 tools/gfx_strict_sweep.sh

diff --git a/docs/BUILTINS.md b/docs/BUILTINS.md
index 8b3ff231..597c8ca5 100644
--- a/docs/BUILTINS.md
+++ b/docs/BUILTINS.md
@@ -717,7 +717,7 @@ libSDL2 at runtime — no SDL2 headers needed at build time.
 |------|-----------|-------------|
 | `gfx_open` | `gfx_open of [width, height, title]` | Open window and renderer. Returns `1` on success, `0` when libSDL2 is unavailable or `width`/`height` are not numbers (#1007 — they used to be read without a type check, so a string opened a `0x0` window and still answered `1`). Under `EIGS_STRICT=1` a non-numeric size raises. |
 | `gfx_close` | `gfx_close of null` | Destroy window and quit SDL |
-| `gfx_clear` | `gfx_clear of [r, g, b]` | Clear backbuffer to color |
+| `gfx_clear` | `gfx_clear of [r, g, b]` / `gfx_clear of null` | Clear backbuffer to color; `null` clears to black |
 | `gfx_rect` | `gfx_rect of [x, y, w, h, r, g, b]` or `[..., a]` | Filled rectangle |
 | `gfx_line` | `gfx_line of [x1, y1, x2, y2, r, g, b]` | Line segment |
 | `gfx_point` | `gfx_point of [x, y, r, g, b]` | Single pixel |
@@ -736,6 +736,70 @@ libSDL2 at runtime — no SDL2 headers needed at build time.
 | `gfx_fb` | `gfx_fb of [buf, w, h, x, y, scale]` | Blit buffer (palette indices 0-3) as scaled texture |
 | `ppu_render_frame` | `ppu_render_frame of [mem_buf, fb_buf]` | Full Game Boy PPU render (BG/window/sprites) into framebuffer |
 
+**Wrong-typed and wrong-arity arguments (#1007).** Every builtin in this
+extension that takes an argument at all — the drawing calls, the text calls,
+the framebuffer blit, the PPU renderer, and the whole audio surface below —
+type-checks its arguments *before* reading them, and under `EIGS_STRICT=1` a
+wrong type, a short argument list, a wrong-shaped argument *container* (a
+number or a string where a list belonged) or an out-of-domain value raises a
+catchable `type` error naming the builtin and the shape it wanted. With the
+flag off the answer is byte-identical to before: the drawing calls still
+answer `null`, the generators still answer an empty list, the device calls
+still answer `0` or the device id they already answered.
+
+Two shapes are deliberately **not** covered, so the claim above is not read
+wider than it is. A builtin that takes **no** argument (`gfx_poll`,
+`gfx_present`, `gfx_ticks`, `gfx_close`, `audio_close`, `audio_clear`,
+`audio_capture_close`, `audio_capture_read`, `audio_stream_close`,
+`audio_stream_clear`, `audio_stream_queued`, `audio_queue_size`,
+`audio_music_stop`) ignores one entirely, and a **surplus trailing** argument
+to a fixed-arity builtin is dropped — both are the general over-arity
+question, which is #989's, not this extension's. `tools/gfx_strict_sweep.sh`
+crosses every guarded builtin in the extension with the wrong-container
+shapes and requires each pair to raise or to carry a reason in its allowlist,
+so this paragraph is checked against the binary rather than asserted.
+What changed with the flag OFF is the *read*, not the answer. `Value`'s union
+overlaps `double num` with `char *str`, so `gfx_rect of [0, 0, 32, 32, "255",
+0, 0]` used to reinterpret a `char *` as a `double`, `(int)`-cast it, and
+draw a **black** rectangle where red was asked for — silently, in both modes.
+That read is gone in both modes; an unchecked union pun is not behaviour
+anything can depend on.
+
+So be precise about what "byte-identical" covers: the **returned value** is
+unchanged in every case, and so is anything the call *reports*. What a
+rejected call **draws** is not, and cannot be — a 48-bit pointer read as a
+double is a subnormal that truncates to 0, so the parent painted a shape at
+coordinate 0, in colour 0, or at scale 1, and this build paints nothing at
+all. The same applies to the one drawing-surface builtin that answers with
+data: with a window open, `gfx_read of ["1", 1]` used to hand back the pixel
+at (0, 1) — the punned 0 — and now answers `null`.
+`tools/gfx_pixel_differential.sh` measures exactly that surface (it opens a
+window under the dummy driver and diffs a readback digest against a build of
+the parent commit) and requires every such divergence to carry an executed
+proof that the parent's answer was the punned zero and that this build's
+rejected call draws nothing else instead.
+
+**A wrong-typed OPTIONAL argument follows the same rule, which makes the three
+text builtins differ on purpose.** `gfx_text_width` and `gfx_text_height`
+type-checked their scale slot before this change, so a wrong-typed scale there
+is a *coercion*: with the flag off they still measure at scale 1.
+`gfx_text` did not — its scale slot was one of the unchecked reads — so a
+wrong-typed scale refuses the call and draws nothing. Under `EIGS_STRICT=1`
+all three raise. Layout code that sizes a box with `gfx_text_width` and then
+draws with `gfx_text` therefore sees a box with no text in it if it passes a
+stringy scale, which is the loudest signal available with the flag off; run
+strict to get the error.
+
+A few values are deliberately left quiet because they are the *answer*, not a
+rejected argument: a drawing call with no window open answers `null` (that is
+its answer on every path), `gfx_poll` answers `null` for "no event",
+`gfx_rrect`/`gfx_fb` answer `null` for a zero or negative width/height/scale
+(degenerate geometry covers no pixels), and every device builtin answers `0`
+when libSDL2 or the device is unavailable — environment state, not a caller
+mistake. The distinction is recorded per site in `src/ext_gfx.c` and enforced
+by `tools/failsoft_classify_check.sh`, whose `make_null()` population is
+scoped to that file (see its header for why it is not repo-wide).
+
 **Text rendering and fonts (#593).** `gfx_text` lazily loads
 `libSDL2_ttf-2.0.so.0` on first use and renders proportional antialiased
 text (`TTF_RenderUTF8_Blended`) when both the library and a font file are
@@ -884,17 +948,17 @@ receiver.
 
 | Name | Signature | Description |
 |------|-----------|-------------|
-| `audio_open` | `audio_open of [freq, channels]` or `of null` | Open the mixer playback device. Defaults `[44100, 1]`. Returns the device id (`>= 2`), or `0` when SDL/audio is unavailable. Non-numeric `freq`/`channels` answer `0` and raise under `EIGS_STRICT=1` (#1007 — they used to be read without a type check, so a string opened the device against a garbage spec and still answered a real id, taking the device with it). |
+| `audio_open` | `audio_open of [freq, channels]` or `of null` | Open the mixer playback device. Defaults `[44100, 1]`. Returns the device id (`>= 2`), or `0` when SDL/audio is unavailable. Non-numeric `freq`/`channels` answer `0` and raise under `EIGS_STRICT=1` (#1007 — they used to be read without a type check, so a string opened the device against a garbage spec and still answered a real id, taking the device with it). A **short or non-list** argument also raises under strict (#1007 — it used to skip the check entirely, open at the defaults and hand back a real device id, so `audio_open of [44100]` was indistinguishable from a well-formed call). `of null` is still the defaults. |
 | `audio_sweep` | `audio_sweep of [freq_start, freq_end, duration, amplitude, waveform]` | Generate a frequency sweep with continuous phase. `waveform`: 0=sine, 1=sawtooth. Returns sample list. |
-| `audio_play` | `audio_play of samples` | Play a clip once on a free mixer channel (oldest finite channel recycled when all 16 are busy). Returns the channel id, or `0` on bad args / closed device. A non-numeric element in `samples` raises a `type_mismatch` error (#1007 — it used to be coerced to 0, so a wrong-typed list played silence on a real channel id). |
-| `audio_play_loop` | `audio_play_loop of [samples, loops]` | Play `samples` `loops` times on one mixer channel; `loops == -1` loops forever (the mixer rewinds — no memory multiplication). Returns the channel id, or `0` on bad args / closed device. |
-| `audio_volume` | `audio_volume of [channel, vol]` | Live per-channel volume, `0.0`–`4.0`. Returns `1`, or `0` on a bad/inactive channel. |
-| `audio_stop` | `audio_stop of channel` | Stop one mixer channel. Returns `1`, or `0` on a bad/inactive channel. |
-| `audio_capture_open` | `audio_capture_open of [freq, channels]` | Open the recording (microphone) device and start capturing (#579). Defaults `[44100, 1]`; SDL converts to exactly the requested format. Returns the device id, or `0` when SDL/capture is unavailable. Non-numeric `freq`/`channels` answer `0` and raise under `EIGS_STRICT=1` (#1007). Re-opening closes the previous capture device. Trace-recorded — under `EIGS_REPLAY` no real device is opened. |
+| `audio_play` | `audio_play of samples` | Play a clip once on a free mixer channel (oldest finite channel recycled when all 16 are busy). Returns the channel id, or `0` on bad args / closed device. A non-numeric element in `samples` raises a `type_mismatch` error (#1007 — it used to be coerced to 0, so a wrong-typed list played silence on a real channel id), and so does a `samples` that is not a list or buffer at all (#1007 — `audio_play of 42` answered the documented "nothing to play" `0`, indistinguishable from an empty clip). `of null` still plays nothing. |
+| `audio_play_loop` | `audio_play_loop of [samples, loops]` | Play `samples` `loops` times on one mixer channel; `loops == -1` loops forever (the mixer rewinds — no memory multiplication). Returns the channel id, or `0` on bad args / closed device. `loops` must be a number equal to `-1` or in `1..10000`; anything else answers `0` and raises under `EIGS_STRICT=1` (#1007), and so does a `samples` slot that is not a list or buffer. |
+| `audio_volume` | `audio_volume of [channel, vol]` | Live per-channel volume, `0.0`–`4.0`. Returns `1`, or `0` on a bad/inactive channel. A non-numeric `channel` or `vol` answers `0` and raises under `EIGS_STRICT=1` (#1007); an out-of-range channel is simply inactive and stays quiet. |
+| `audio_stop` | `audio_stop of channel` | Stop one mixer channel. Returns `1`, or `0` on a bad/inactive channel. A non-numeric `channel` answers `0` and raises under `EIGS_STRICT=1` (#1007). |
+| `audio_capture_open` | `audio_capture_open of [freq, channels]` | Open the recording (microphone) device and start capturing (#579). Defaults `[44100, 1]`; SDL converts to exactly the requested format. Returns the device id, or `0` when SDL/capture is unavailable. Non-numeric `freq`/`channels` answer `0` and raise under `EIGS_STRICT=1` (#1007), and so does a **short or non-list** argument, which used to open at the defaults and answer a real device id. `of null` is still the defaults. Re-opening closes the previous capture device. Trace-recorded — under `EIGS_REPLAY` no real device is opened. |
 | `audio_capture_read` | `audio_capture_read of null` | Drain samples accumulated since the last read as a **buffer** of floats in `[-1, 1]` (interleaved when `channels > 1`). At most 2048 samples per call — loop until the returned buffer is empty to drain fully (keeps each trace record replayable). Empty buffer = nothing new yet; `null` = no capture device open. Trace-recorded — replay serves the recorded samples, never a live microphone. |
 | `audio_capture_close` | `audio_capture_close of null` | Stop and close the recording device, dropping undrained samples. Safe to call twice or with no device open. |
-| `audio_stream_open` | `audio_stream_open of [freq, channels]` | Open the live streaming playback device (queue mode, F-DS-17 — for on-the-fly synthesis like musical typing). Coexists with the `audio_open` mixer device. Defaults `[44100, 1]`. Returns the device id (`>= 2`), or `0` when SDL/audio is unavailable. Re-opening closes the previous stream device. |
-| `audio_stream_push` | `audio_stream_push of samples` | Queue a block of float samples `[-1, 1]` (**list** or **buffer**) onto the live stream. Same size cap / clamp as `audio_play`. Pure output sink (not trace-recorded). Returns `1` on success, `0` on a closed device or bad shape. |
+| `audio_stream_open` | `audio_stream_open of [freq, channels]` | Open the live streaming playback device (queue mode, F-DS-17 — for on-the-fly synthesis like musical typing). Coexists with the `audio_open` mixer device. Defaults `[44100, 1]`. Returns the device id (`>= 2`), or `0` when SDL/audio is unavailable. Non-numeric `freq`/`channels` answer `0` and raise under `EIGS_STRICT=1` (#1007 — they used to skip the override, open at 44100/1 and answer a real id, so a caller that asked for 48000 was told it got it). A **short or non-list** argument raises for the same reason: `audio_stream_open of [48000]` answered device id 2 opened at 44100/1. `of null` is still the defaults. Re-opening closes the previous stream device. |
+| `audio_stream_push` | `audio_stream_push of samples` | Queue a block of float samples `[-1, 1]` (**list** or **buffer**) onto the live stream. Same size cap / clamp as `audio_play`. Pure output sink (not trace-recorded). Returns `1` on success, `0` on a closed device or bad shape; a `samples` that is not a list or buffer raises under `EIGS_STRICT=1` (#1007). |
 | `audio_stream_queued` | `audio_stream_queued of null` | Samples still buffered (not yet played) on the live stream — the refill pump pushes another block only while this stays under its latency target. Returns `0` when no stream is open. Trace-recorded (a live, timing-dependent value) — replay serves the recorded depth, keeping the session deterministic. |
 | `audio_stream_clear` | `audio_stream_clear of null` | Drop any buffered audio on the live stream (flush for a panic / all-notes-off). Safe with no device. |
 | `audio_stream_close` | `audio_stream_close of null` | Stop and close the live stream device, dropping buffered audio. Safe to call twice or with no device open. |
diff --git a/docs/SPEC.md b/docs/SPEC.md
index 535824a1..cc253cfe 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -246,8 +246,18 @@ consequences are contracts you can rely on:
   wrong-typed argument with a stand-in, so `cos of "hello"` was `0` and
   `str_upper of 42` was `""` — a type mistake became a plausible value. Under
   strict those raise a catchable `type` error naming the builtin, across the
-  whole builtin surface (`builtins.c`, the host builtins, the tensor ops and
-  the embedded store). A `0` or `""` that is a genuine *answer* is untouched
+  whole builtin surface (`builtins.c`, the host builtins, the tensor ops, the
+  embedded store, and — since #1007 — the graphics/audio extension, where the
+  stand-in is usually `null` rather than `0`/`""`: `gfx_rect of [x, y, w, h,
+  "255", 0, 0]` drew a BLACK rectangle where red was asked for, in silence).
+  A guard covers the argument's **container** as well as its elements — a
+  short argument list, or a scalar where a list belonged, is a caller mistake
+  and raises. That half is the one an element-typed probe cannot see, and in
+  the extension it was the difference between "drew nothing" and a silent
+  *success*: `audio_stream_open of [48000]` opened the device at the 44100/1
+  defaults and answered a real device id, so the caller that asked for 48000
+  was told it got 48000.
+  A `0`, `""` or `null` that is a genuine *answer* is untouched
   in both modes: `try_parse` of invalid syntax still returns `0`, `task_alive`
   of an unknown id still returns `0`, `char_at` past the end is still `""`,
   and `num` still *coerces* (`num of ([1, 2])` is `0` — that is its documented
diff --git a/docs/TRACE.md b/docs/TRACE.md
index a99057be..cdb6a87c 100644
--- a/docs/TRACE.md
+++ b/docs/TRACE.md
@@ -122,6 +122,21 @@ perspective lands on the tape as an `N` record:
   included, so a program that hits one cannot desync the stream. Greedy
   (`temperature < 0.01`) calls ride the same path: the tape cannot show
   which branch ran, and replay may not load a model to re-derive it.
+- **Rendered pixels (gfx extension, #823):** `gfx_read`. Renderer output
+  depends on the font rasteriser, the driver and the backend, so the pixel
+  a render-decode oracle reads back is a device input and takes the
+  TAKE/RECORD pair.
+- **A REJECTED argument consumes no record** (#1007). `audio_capture_open`,
+  `audio_capture_read`'s siblings and `gfx_read` all place their
+  argument-type guard *above* `TRACE_NONDET_TAKE`, because an argument's
+  type is deterministic and so a rejected call is not a nondeterministic
+  input. Placed below the TAKE, the capture run returns before
+  `TRACE_NONDET_RECORD` and writes nothing while the replay run's TAKE still
+  consumes one — every later record for that name shifts by one and the
+  rejected call replays as a real device id or a real pixel, silently, even
+  under `EIGS_STRICT=1`. Measured on `audio_capture_open` before the guard
+  was hoisted: capture printed `0 2 null`, replay of that same tape printed
+  `2 2 null`. Suite section `[133]` pins it.
 - **Audio capture (gfx extension, #579):** `audio_capture_open`,
   `audio_capture_read`. Captured audio is a device input, so the whole
   capture chain is TAKE/RECORD-wrapped: under `EIGS_REPLAY` the tape is
diff --git a/src/ext_gfx.c b/src/ext_gfx.c
index 5ae36bb4..6bd4acc5 100644
--- a/src/ext_gfx.c
+++ b/src/ext_gfx.c
@@ -389,9 +389,65 @@ static const char* scancode_name(int sc) {
 
 /* ---- Builtins ---- */
 
+/* #1007: the drawing surface reads RUNS of list elements as `.data.num`
+ * with no type check. `Value`'s union overlaps `double num` with
+ * `char *str`, so an unchecked read reinterprets a pointer as a double
+ * and then `(int)`-casts it — the read itself is the defect, which is why
+ * every guard built on these helpers sits BEFORE it in BOTH modes:
+ * ARG_GUARD's soft half returns the same stand-in the function already
+ * answered, without performing the pun.
+ *
+ * `to` is clamped to the list count so an OPTIONAL trailing argument
+ * (gfx_rect's alpha, gfx_text's scale) can be named unconditionally.
+ * Caller must have established that `arg` is a VAL_LIST. */
+static int gfx_nums(Value *arg, int from, int to) {
+    int cnt = arg->data.list.count;
+    if (to > cnt) to = cnt;
+    for (int i = from; i < to; i++) {
+        Value *v = arg->data.list.items[i];
+        if (!v || v->type != VAL_NUM) return 0;
+    }
+    return 1;
+}
+
+/* Every element of a sample list is a number. Used by the audio helpers
+ * whose per-element read COERCES a non-number to 0.0 (audio_mix,
+ * audio_gain, audio_envelope): there is no single stand-in to name, so
+ * those sites use STRICT_REQUIRE and this predicate, checked BEFORE the
+ * output list is built so a strict raise leaks nothing. */
+static int gfx_list_all_num(Value *l) {
+    if (!l || l->type != VAL_LIST) return 0;
+    for (int i = 0; i < l->data.list.count; i++) {
+        Value *v = l->data.list.items[i];
+        if (!v || v->type != VAL_NUM) return 0;
+    }
+    return 1;
+}
+
+/* #1007 round 3: the CONTAINER half of the sample-list check. Round 1 made a
+ * wrong-typed sample ELEMENT loud (inside audio_convert_samples), and left the
+ * container itself silent one line above it: `samples->type != VAL_LIST` just
+ * `return NULL`, and every caller reads that NULL as the documented "nothing
+ * to play" and answers 0. So `audio_play of ["a"]` raised while
+ * `audio_play of 42` did not, which is the same asymmetry the three audio
+ * *_open builtins had between their element and arity halves.
+ *
+ * `null` stays quiet: audio_convert_samples answers NULL for a NULL argument
+ * too, and "play nothing" is a legitimate call. So only a PRESENT, non-null
+ * argument that is neither a list nor a buffer is a caller mistake. */
+static int gfx_bad_samples(Value *v) {
+    return v && v->type != VAL_NULL
+             && v->type != VAL_LIST && v->type != VAL_BUFFER;
+}
+
 /* gfx_open of [width, height, title] */
 Value* builtin_gfx_open(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) return make_num(0);  /* fs:TODO #971 guards the [w, h, title] arg-list shape; deferred: gfx is a variant-only build (make gfx) no session test can exercise */
+    /* #1007: the arg-list SHAPE, converted out of its #971 deferral marker. A wrong
+     * arity used to answer the same 0 the missing-libSDL2 path answers,
+     * so "you called it wrong" and "this machine has no SDL" were the
+     * same value. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 3,
+              "gfx_open", "[number width, number height, title]", make_num(0));
     /* #1007: width and height were read as `.data.num` with no type check
      * while the title on the very next line WAS checked. Value's union
      * overlaps `double num` with `char *str`, so gfx_open of ["800","600",t]
@@ -445,26 +501,48 @@ Value* builtin_gfx_close(Value *arg) {
         dlclose(g_sdl_lib);
         g_sdl_lib = NULL;
     }
-    return make_null();
+    return make_null(); /* fs:VOID gfx_close answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* gfx_clear of [r, g, b] */
 Value* builtin_gfx_clear(Value *arg) {
-    if (!g_renderer) return make_null();
+    /* #1007: argument shape BEFORE the renderer check, the [135] rule. The
+     * stand-in is the same null the no-window path answers, so a guard
+     * placed after it would be unreachable in exactly the environment
+     * (headless CI, no window opened) where the suite runs. */
+    int shaped = (arg && arg->type == VAL_LIST && arg->data.list.count >= 3);
+    /* A wrong SHAPE is the COERCION shape here, not a stand-in one: an
+     * unusable argument fell through to r = g = b = 0 and the buffer WAS
+     * cleared, to black. Refusing to clear at all would be a default-path
+     * behaviour change, which this reform does not make -- so STRICT_REQUIRE,
+     * which raises under the flag and does nothing otherwise. */
+    STRICT_REQUIRE(!shaped && arg && arg->type != VAL_NULL,
+                   "gfx_clear", "[number r, number g, number b] or null");
+    /* A wrong ELEMENT TYPE is different: the read itself is the union pun,
+     * so it is removed in both modes and the stand-in is the same null every
+     * path of this builtin answers. */
+    ARG_GUARD(shaped && !gfx_nums(arg, 0, 3),
+              "gfx_clear", "[number r, number g, number b]", make_null());
+    if (!g_renderer) return make_null();  /* fs:VOID no window open: gfx_clear answers null on every path -- this is the return value, not a stand-in for a rejected argument */
     int r = 0, g = 0, b = 0;
-    if (arg && arg->type == VAL_LIST && arg->data.list.count >= 3) {
+    if (shaped) {
         r = (int)arg->data.list.items[0]->data.num;
         g = (int)arg->data.list.items[1]->data.num;
         b = (int)arg->data.list.items[2]->data.num;
     }
     p_SDL_SetRenderDrawColor(g_renderer, r, g, b, 255);
     p_SDL_RenderClear(g_renderer);
-    return make_null();
+    return make_null(); /* fs:VOID gfx_clear answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* gfx_rect of [x, y, w, h, r, g, b] or [x, y, w, h, r, g, b, a] */
 Value* builtin_gfx_rect(Value *arg) {
-    if (!g_renderer || !arg || arg->type != VAL_LIST || arg->data.list.count < 7) return make_null();
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 7
+              || !gfx_nums(arg, 0, 8),
+              "gfx_rect",
+              "[number x, number y, number w, number h, number r, number g, number b] and an optional number alpha",
+              make_null());
+    if (!g_renderer) return make_null();  /* fs:VOID no window open: gfx_rect answers null on every path -- the return value, not a rejected-argument stand-in */
     SDL_Rect rect;
     rect.x = (int)arg->data.list.items[0]->data.num;
     rect.y = (int)arg->data.list.items[1]->data.num;
@@ -476,12 +554,17 @@ Value* builtin_gfx_rect(Value *arg) {
     int a = (arg->data.list.count >= 8) ? (int)arg->data.list.items[7]->data.num : 255;
     p_SDL_SetRenderDrawColor(g_renderer, r, g, b, a);
     p_SDL_RenderFillRect(g_renderer, &rect);
-    return make_null();
+    return make_null(); /* fs:VOID gfx_rect answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* gfx_line of [x1, y1, x2, y2, r, g, b] */
 Value* builtin_gfx_line(Value *arg) {
-    if (!g_renderer || !arg || arg->type != VAL_LIST || arg->data.list.count < 7) return make_null();
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 7
+              || !gfx_nums(arg, 0, 7),
+              "gfx_line",
+              "[number x1, number y1, number x2, number y2, number r, number g, number b]",
+              make_null());
+    if (!g_renderer) return make_null();  /* fs:VOID no window open: gfx_line answers null on every path -- the return value, not a rejected-argument stand-in */
     int x1 = (int)arg->data.list.items[0]->data.num;
     int y1 = (int)arg->data.list.items[1]->data.num;
     int x2 = (int)arg->data.list.items[2]->data.num;
@@ -491,12 +574,16 @@ Value* builtin_gfx_line(Value *arg) {
     int b = (int)arg->data.list.items[6]->data.num;
     p_SDL_SetRenderDrawColor(g_renderer, r, g, b, 255);
     p_SDL_RenderDrawLine(g_renderer, x1, y1, x2, y2);
-    return make_null();
+    return make_null(); /* fs:VOID gfx_line answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* gfx_point of [x, y, r, g, b] */
 Value* builtin_gfx_point(Value *arg) {
-    if (!g_renderer || !arg || arg->type != VAL_LIST || arg->data.list.count < 5) return make_null();
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 5
+              || !gfx_nums(arg, 0, 5),
+              "gfx_point", "[number x, number y, number r, number g, number b]",
+              make_null());
+    if (!g_renderer) return make_null();  /* fs:VOID no window open: gfx_point answers null on every path -- the return value, not a rejected-argument stand-in */
     int x = (int)arg->data.list.items[0]->data.num;
     int y = (int)arg->data.list.items[1]->data.num;
     int r = (int)arg->data.list.items[2]->data.num;
@@ -504,12 +591,17 @@ Value* builtin_gfx_point(Value *arg) {
     int b = (int)arg->data.list.items[4]->data.num;
     p_SDL_SetRenderDrawColor(g_renderer, r, g, b, 255);
     p_SDL_RenderDrawPoint(g_renderer, x, y);
-    return make_null();
+    return make_null(); /* fs:VOID gfx_point answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* gfx_circle of [cx, cy, radius, r, g, b] — filled circle via midpoint */
 Value* builtin_gfx_circle(Value *arg) {
-    if (!g_renderer || !arg || arg->type != VAL_LIST || arg->data.list.count < 6) return make_null();
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 6
+              || !gfx_nums(arg, 0, 7),
+              "gfx_circle",
+              "[number cx, number cy, number radius, number r, number g, number b] and an optional number alpha",
+              make_null());
+    if (!g_renderer) return make_null();  /* fs:VOID no window open: gfx_circle answers null on every path -- the return value, not a rejected-argument stand-in */
     int cx = (int)arg->data.list.items[0]->data.num;
     int cy = (int)arg->data.list.items[1]->data.num;
     int radius = (int)arg->data.list.items[2]->data.num;
@@ -524,13 +616,18 @@ Value* builtin_gfx_circle(Value *arg) {
         SDL_Rect row = { cx - dx, cy + dy, dx * 2 + 1, 1 };
         p_SDL_RenderFillRect(g_renderer, &row);
     }
-    return make_null();
+    return make_null(); /* fs:VOID gfx_circle answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* gfx_rrect of [x, y, w, h, radius, r, g, b] or [..., a]
  * Filled rounded rectangle. Draws corner arcs via scanlines + rects for body. */
 Value* builtin_gfx_rrect(Value *arg) {
-    if (!g_renderer || !arg || arg->type != VAL_LIST || arg->data.list.count < 8) return make_null();
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 8
+              || !gfx_nums(arg, 0, 9),
+              "gfx_rrect",
+              "[number x, number y, number w, number h, number radius, number r, number g, number b] and an optional number alpha",
+              make_null());
+    if (!g_renderer) return make_null();  /* fs:VOID no window open: gfx_rrect answers null on every path -- the return value, not a rejected-argument stand-in */
     int x = (int)arg->data.list.items[0]->data.num;
     int y = (int)arg->data.list.items[1]->data.num;
     int w = (int)arg->data.list.items[2]->data.num;
@@ -540,7 +637,7 @@ Value* builtin_gfx_rrect(Value *arg) {
     int g = (int)arg->data.list.items[6]->data.num;
     int b = (int)arg->data.list.items[7]->data.num;
     int a = (arg->data.list.count >= 9) ? (int)arg->data.list.items[8]->data.num : 255;
-    if (w <= 0 || h <= 0) return make_null();
+    if (w <= 0 || h <= 0) return make_null(); /* fs:EMPTY a rectangle with no width or height covers no pixels, so drawing nothing IS the answer -- the degenerate-geometry identity, not a laundered argument (lib/ui layout produces zero-size rects routinely) */
     /* Clamp radius to half the smaller dimension */
     if (rad > w / 2) rad = w / 2;
     if (rad > h / 2) rad = h / 2;
@@ -549,7 +646,7 @@ Value* builtin_gfx_rrect(Value *arg) {
     if (rad == 0) {
         SDL_Rect rect = { x, y, w, h };
         p_SDL_RenderFillRect(g_renderer, &rect);
-        return make_null();
+        return make_null(); /* fs:VOID radius 0 took the plain-rect path and drew it; gfx_rrect answers null on every path -- this is the return value, not a stand-in for a rejected argument */
     }
     /* Center body (between top and bottom rounded bands) */
     SDL_Rect center = { x, y + rad, w, h - 2 * rad };
@@ -564,25 +661,32 @@ Value* builtin_gfx_rrect(Value *arg) {
         SDL_Rect bot_row = { x + rad - dx, y + h - 1 - dy, w - 2 * (rad - dx), 1 };
         p_SDL_RenderFillRect(g_renderer, &bot_row);
     }
-    return make_null();
+    return make_null(); /* fs:VOID gfx_rrect answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* gfx_clip of [x, y, w, h] — set render clip rectangle.
  * gfx_clip of null — clear clip rectangle. */
 Value* builtin_gfx_clip(Value *arg) {
-    if (!g_renderer || !p_SDL_RenderSetClipRect) return make_null();
-    if (!arg || arg->type == VAL_NULL) {
+    /* `gfx_clip of null` CLEARS the clip and is the documented second call
+     * shape, so only a non-null argument is required to be a 4-number
+     * rectangle. */
+    int clearing = (!arg || arg->type == VAL_NULL);
+    ARG_GUARD(!clearing && (arg->type != VAL_LIST || arg->data.list.count < 4
+                            || !gfx_nums(arg, 0, 4)),
+              "gfx_clip", "[number x, number y, number w, number h] or null",
+              make_null());
+    if (!g_renderer || !p_SDL_RenderSetClipRect) return make_null();  /* fs:VOID no window / no SDL symbol: gfx_clip answers null on every path -- the return value, not a rejected-argument stand-in */
+    if (clearing) {
         p_SDL_RenderSetClipRect(g_renderer, NULL);
-        return make_null();
+        return make_null();  /* fs:VOID the clip was cleared -- gfx_clip's normal successful answer */
     }
-    if (arg->type != VAL_LIST || arg->data.list.count < 4) return make_null();
     SDL_Rect clip;
     clip.x = (int)arg->data.list.items[0]->data.num;
     clip.y = (int)arg->data.list.items[1]->data.num;
     clip.w = (int)arg->data.list.items[2]->data.num;
     clip.h = (int)arg->data.list.items[3]->data.num;
     p_SDL_RenderSetClipRect(g_renderer, &clip);
-    return make_null();
+    return make_null(); /* fs:VOID gfx_clip answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* gfx_read of [x, y] — read back one rendered pixel as [r, g, b].
@@ -595,9 +699,17 @@ Value* builtin_gfx_clip(Value *arg) {
  * this takes the TAKE/RECORD tape pair like audio_stream_queued.
  * Returns null with no window, no SDL symbol, or a failed read. */
 Value* builtin_gfx_read(Value *arg) {
+    /* ABOVE the tape seam, exactly as audio_capture_open's guard is (#1018).
+     * An argument's TYPE is deterministic, so a rejected call is not a
+     * nondeterministic input and must not touch the tape: placed below
+     * TRACE_NONDET_TAKE it would return without recording while replay's
+     * TAKE still consumed a record, shifting every later gfx_read and
+     * replaying a rejected call as a real pixel. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 2
+              || !gfx_nums(arg, 0, 2),
+              "gfx_read", "[number x, number y]", make_null());
     TRACE_NONDET_TAKE("gfx_read");
-    if (!g_renderer || !p_SDL_RenderReadPixels || !arg ||
-        arg->type != VAL_LIST || arg->data.list.count < 2)
+    if (!g_renderer || !p_SDL_RenderReadPixels)
         TRACE_NONDET_RECORD("gfx_read", make_null());
     SDL_Rect r;
     r.x = (int)arg->data.list.items[0]->data.num;
@@ -619,7 +731,7 @@ Value* builtin_gfx_read(Value *arg) {
 Value* builtin_gfx_present(Value *arg) {
     (void)arg;
     if (g_renderer) p_SDL_RenderPresent(g_renderer);
-    return make_null();
+    return make_null(); /* fs:VOID gfx_present answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* Attach keyboard modifier state as shift/ctrl/alt (0/1) dict fields.
@@ -642,9 +754,9 @@ static int poll_mod_state(void) {
  * Key, mouse, and wheel events all carry shift/ctrl/alt (0/1). */
 Value* builtin_gfx_poll(Value *arg) {
     (void)arg;
-    if (!g_window) return make_null();
+    if (!g_window) return make_null(); /* fs:ANSWER no window open means no event queue, which is the same "no event" null this builtin answers for an empty queue */
     SDL_Event ev;
-    if (!p_SDL_PollEvent(&ev)) return make_null();
+    if (!p_SDL_PollEvent(&ev)) return make_null(); /* fs:ANSWER SDL_PollEvent found nothing: "no event pending" is gfx_poll's documented answer */
 
     Value *d = make_dict(4);
     switch (ev.type) {
@@ -708,11 +820,17 @@ Value* builtin_gfx_poll(Value *arg) {
                 dict_set_owned(d, "w", make_num(ev.window.data1));
                 dict_set_owned(d, "h", make_num(ev.window.data2));
             } else {
-                return make_null();
+                /* #1007: `d` is already allocated. Returning without
+                 * releasing it leaked 584 bytes / 6 allocations per
+                 * uninteresting window event — the only leak `make asan-gfx`
+                 * surfaced over the gfx corpus, and it is ours, not SDL's. */
+                val_decref(d);
+                return make_null();  /* fs:ANSWER an uninteresting window event is "no event", the same null this builtin answers when the queue is empty */
             }
             break;
         default:
-            return make_null();
+            val_decref(d);
+            return make_null();  /* fs:ANSWER an event type this builtin does not decode is "no event", the same null it answers for an empty queue */
     }
     return d;
 }
@@ -725,16 +843,21 @@ Value* builtin_gfx_ticks(Value *arg) {
 
 /* gfx_delay of ms */
 Value* builtin_gfx_delay(Value *arg) {
-    if (!arg || arg->type != VAL_NUM) return make_null();
+    ARG_GUARD(!arg || arg->type != VAL_NUM, "gfx_delay", "number milliseconds",
+              make_null());
     if (g_sdl_lib) p_SDL_Delay((Uint32)arg->data.num);
-    return make_null();
+    return make_null(); /* fs:VOID gfx_delay answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* gfx_title of "new title" */
 Value* builtin_gfx_title(Value *arg) {
-    if (!g_window || !arg || arg->type != VAL_STR) return make_null();
+    /* Split: the STRING requirement is an argument guard, `!g_window` is
+     * environment state and stays soft. */
+    ARG_GUARD(!arg || arg->type != VAL_STR, "gfx_title", "string title",
+              make_null());
+    if (!g_window) return make_null();  /* fs:VOID no window open: gfx_title answers null on every path -- the return value, not a rejected-argument stand-in */
     p_SDL_SetWindowTitle(g_window, arg->data.str);
-    return make_null();
+    return make_null(); /* fs:VOID gfx_title answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* 5x7 bitmap font — printable ASCII 32..126 */
@@ -841,10 +964,37 @@ static const unsigned char font5x7[95][7] = {
  * (#593); the 5x7 bitmap path below is the exact pre-#593 behavior and
  * runs whenever any part of the TTF path is missing or fails. */
 Value* builtin_gfx_text(Value *arg) {
-    if (!g_renderer || !arg || arg->type != VAL_LIST || arg->data.list.count < 6) return make_null();
+    /* The text element was ALREADY type-checked here — and coerced to ""
+     * when it failed, so a number label drew nothing and said nothing —
+     * while the five numbers beside it were read unchecked. Same next-line
+     * asymmetry as gfx_open's.
+     *
+     * THE OPTIONAL SCALE (slot 6) IS IN THIS GUARD ON PURPOSE, and that is
+     * why gfx_text and gfx_text_width answer a wrong-typed scale
+     * DIFFERENTLY. gfx_text_width's slot carried `items[1]->type == VAL_NUM`
+     * before #1007, so its wrong-typed scale is a COERCION and keeps
+     * measuring at scale 1 (STRICT_REQUIRE there, byte-identical off the
+     * flag). This one did not:
+     *     int scale = (count >= 7) ? (int)items[6]->data.num : 1;
+     * reads the union unchecked, so a string scale drew the glyph from a
+     * reinterpreted `char *` — a subnormal that truncates to 0 and is then
+     * clamped to 1, which is why it LOOKED like scale 1 while being a pun.
+     * Unchecked reads are refused; checked coercions are preserved. A blind
+     * review read gfx_text_width's checked line as this one's and called the
+     * refusal a regression: tests/test_gfx_argtypes.eigs pins both shapes in
+     * pixels, and tools/gfx_pixel_differential.sh proves the parent's answer
+     * here was the punned zero. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 6
+              || !gfx_nums(arg, 0, 2)
+              || arg->data.list.items[2]->type != VAL_STR
+              || !gfx_nums(arg, 3, 7),
+              "gfx_text",
+              "[number x, number y, string text, number r, number g, number b] and an optional number scale",
+              make_null());
+    if (!g_renderer) return make_null();  /* fs:VOID no window open: gfx_text answers null on every path -- the return value, not a rejected-argument stand-in */
     int x = (int)arg->data.list.items[0]->data.num;
     int y = (int)arg->data.list.items[1]->data.num;
-    const char *text = arg->data.list.items[2]->type == VAL_STR ? arg->data.list.items[2]->data.str : "";
+    const char *text = arg->data.list.items[2]->data.str;
     int r = (int)arg->data.list.items[3]->data.num;
     int g = (int)arg->data.list.items[4]->data.num;
     int b = (int)arg->data.list.items[5]->data.num;
@@ -867,7 +1017,7 @@ Value* builtin_gfx_text(Value *arg) {
                     SDL_Rect dst = { x, y, tw, th };
                     p_SDL_RenderCopy(g_renderer, tex, NULL, &dst);
                     p_SDL_DestroyTexture(tex);
-                    return make_null();
+                    return make_null(); /* fs:VOID the TTF path rendered the string; gfx_text answers null on every path -- this is the return value, not a stand-in for a rejected argument */
                 }
             }
         }
@@ -895,7 +1045,7 @@ Value* builtin_gfx_text(Value *arg) {
         }
         cx += (5 + 1) * scale; /* 5 pixel width + 1 pixel gap */
     }
-    return make_null();
+    return make_null(); /* fs:VOID gfx_text answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* gfx_text_width of [text, scale?] (or of "text") — pixel width of `text`
@@ -906,15 +1056,27 @@ Value* builtin_gfx_text(Value *arg) {
 Value* builtin_gfx_text_width(Value *arg) {
     const char *text = NULL;
     int scale = 1;
+    int bad_scale = 0;
     if (arg && arg->type == VAL_STR) {
         text = arg->data.str;
     } else if (arg && arg->type == VAL_LIST && arg->data.list.count >= 1
                && arg->data.list.items[0]->type == VAL_STR) {
         text = arg->data.list.items[0]->data.str;
-        if (arg->data.list.count >= 2 && arg->data.list.items[1]->type == VAL_NUM)
-            scale = (int)arg->data.list.items[1]->data.num;
+        if (arg->data.list.count >= 2) {
+            if (arg->data.list.items[1]->type == VAL_NUM)
+                scale = (int)arg->data.list.items[1]->data.num;
+            else
+                bad_scale = 1;
+        }
     }
-    if (!text) return make_num(0);  /* fs:TODO #971 guards a non-string / non-[string, ...] argument (text is still NULL here); deferred: variant-only build */
+    /* #1007: converted out of its #971 deferral marker. The 0 stays the non-strict
+     * stand-in — tests/test_gfx_text.eigs pins `gfx_text_width of 5` at 0. */
+    ARG_GUARD(!text, "gfx_text_width",
+              "string text or [string text, number scale]", make_num(0));
+    /* A wrong-typed SCALE is the COERCION shape, not a stand-in one: the
+     * width for scale 1 is still computed and returned. STRICT_REQUIRE
+     * leaves the default path byte-identical by construction. */
+    STRICT_REQUIRE(bad_scale, "gfx_text_width", "[string text, number scale]");
     if (scale < 1) scale = 1;
     if (*text && ttf_available()) {
         void *font = ttf_font_for_scale(scale);
@@ -930,6 +1092,14 @@ Value* builtin_gfx_text_width(Value *arg) {
  * the bitmap glyph height (7 * scale) otherwise. */
 Value* builtin_gfx_text_height(Value *arg) {
     int scale = 1;
+    /* #1007, the COERCION shape: a wrong-typed scale silently fell back to
+     * 1 and the caller was told the height it did not ask for. There is no
+     * stand-in to name (the height for scale 1 is still returned), so this
+     * raises under strict and does nothing otherwise. */
+    STRICT_REQUIRE(arg && arg->type != VAL_NULL && arg->type != VAL_NUM
+                   && !(arg->type == VAL_LIST && arg->data.list.count >= 1
+                        && arg->data.list.items[0]->type == VAL_NUM),
+                   "gfx_text_height", "number scale, [number scale] or null");
     if (arg && arg->type == VAL_NUM) {
         scale = (int)arg->data.num;
     } else if (arg && arg->type == VAL_LIST && arg->data.list.count >= 1
@@ -1105,6 +1275,26 @@ Value* builtin_audio_open(Value *arg) {
      * none, so a guard placed after the load would never be exercised there.
      * Non-strict is unaffected: the stand-in is the same 0 the missing-SDL
      * path already answers. */
+    /* #1007, the SHORT/NON-LIST half of the same defect, found by a blind
+     * review against this binary: the element guard below is NESTED inside
+     * `count >= 2`, so an argument that never reaches two elements skips it
+     * entirely, falls through to the 44100/1 defaults and answers a REAL
+     * device id. `audio_open of [48000]` was indistinguishable from a
+     * well-formed call -- the caller who asked for 48000 was told it got
+     * it, silently, in BOTH modes. That is the same silent success the
+     * element check closes, reached by arity instead of by type, and it is
+     * the shape the generators (audio_sine et al) already reject.
+     *
+     * COERCION shape, so STRICT_REQUIRE: there is no single stand-in to
+     * name -- non-strict still opens at the defaults and answers whatever
+     * device SDL gives, byte-identical to before BY CONSTRUCTION. `null`
+     * stays the documented "use the defaults" form (BUILTINS.md spells
+     * `audio_open of null` out), so only a PRESENT, non-null argument
+     * that is not a >= 2-element list is refused. Above the element guard, and
+     * so above the SDL load -- the [135] rule. */
+    STRICT_REQUIRE(arg && arg->type != VAL_NULL
+                   && !(arg->type == VAL_LIST && arg->data.list.count >= 2),
+                   "audio_open", "[number freq, number channels] or null");
     if (arg && arg->type == VAL_LIST && arg->data.list.count >= 2) {
         /* The same unchecked `.data.num` type-pun as gfx_open. That it is an
          * oversight rather than a convention is settled 180 lines down:
@@ -1150,15 +1340,20 @@ Value* builtin_audio_close(Value *arg) {
         g_audio_device = 0;
         audio_free_channels(0);
     }
-    return make_null();
+    return make_null(); /* fs:VOID audio_close answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* audio_pause of flag — 1=pause, 0=unpause */
 Value* builtin_audio_pause(Value *arg) {
-    if (!g_audio_device) return make_null();
+    /* #1007, COERCION shape: a wrong-typed flag fell back to 1 (pause), so
+     * `audio_pause of "off"` PAUSED the device and said nothing. Above the
+     * device check, the [135] rule. */
+    STRICT_REQUIRE(arg && arg->type != VAL_NULL && arg->type != VAL_NUM,
+                   "audio_pause", "number flag (1 = pause, 0 = unpause) or null");
+    if (!g_audio_device) return make_null();  /* fs:VOID no device open: audio_pause answers null on every path -- the return value, not a rejected-argument stand-in */
     int pause = (arg && arg->type == VAL_NUM) ? (int)arg->data.num : 1;
     p_SDL_PauseAudioDevice(g_audio_device, pause);
-    return make_null();
+    return make_null(); /* fs:VOID audio_pause answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* ================================================================
@@ -1224,6 +1419,28 @@ Value* builtin_audio_capture_open(Value *arg) {
      * one and the rejected call replayed as a real device id. Executed:
      * capture printed `0 2 null` with 1 record on the tape, replay of that
      * same tape printed `2 2 null`, silently, even under EIGS_STRICT=1. */
+    /* #1007, the SHORT/NON-LIST half of the same defect, found by a blind
+     * review against this binary: the element guard below is NESTED inside
+     * `count >= 2`, so an argument that never reaches two elements skips it
+     * entirely, falls through to the 44100/1 defaults and answers a REAL
+     * device id. `audio_capture_open of [48000]` was indistinguishable from a
+     * well-formed call -- the caller who asked for 48000 was told it got
+     * it, silently, in BOTH modes. That is the same silent success the
+     * element check closes, reached by arity instead of by type, and it is
+     * the shape the generators (audio_sine et al) already reject.
+     *
+     * COERCION shape, so STRICT_REQUIRE: there is no single stand-in to
+     * name -- non-strict still opens at the defaults and answers whatever
+     * device SDL gives, byte-identical to before BY CONSTRUCTION. `null`
+     * stays the documented "use the defaults" form (tests/test_audio.eigs
+     * calls `audio_capture_open of null`), so only a PRESENT,
+     * non-null argument that is not a >= 2-element list is refused. Above the element guard, and
+     * so above the SDL load and above the tape seam (a rejected argument
+     * is deterministic: it must neither consume nor write a record) --
+     * the [135] rule. */
+    STRICT_REQUIRE(arg && arg->type != VAL_NULL
+                   && !(arg->type == VAL_LIST && arg->data.list.count >= 2),
+                   "audio_capture_open", "[number freq, number channels] or null");
     if (arg && arg->type == VAL_LIST && arg->data.list.count >= 2) {
         ARG_GUARD(arg->data.list.items[0]->type != VAL_NUM ||
                   arg->data.list.items[1]->type != VAL_NUM,
@@ -1290,7 +1507,7 @@ Value* builtin_audio_capture_close(Value *arg) {
         p_SDL_CloseAudioDevice(g_capture_device);
         g_capture_device = 0;
     }
-    return make_null();
+    return make_null(); /* fs:VOID audio_capture_close answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* ================================================================
@@ -1332,6 +1549,26 @@ Value* builtin_audio_stream_open(Value *arg) {
      * "expected type_mismatch, got none" there and only there. A guard behind
      * an environment check is a guard that does not exist in the environment
      * that lacks it. */
+    /* #1007, the SHORT/NON-LIST half of the same defect, found by a blind
+     * review against this binary: the element guard below is NESTED inside
+     * `count >= 2`, so an argument that never reaches two elements skips it
+     * entirely, falls through to the 44100/1 defaults and answers a REAL
+     * device id. `audio_stream_open of [48000]` was indistinguishable from a
+     * well-formed call -- the caller who asked for 48000 was told it got
+     * it, silently, in BOTH modes. That is the same silent success the
+     * element check closes, reached by arity instead of by type, and it is
+     * the shape the generators (audio_sine et al) already reject.
+     *
+     * COERCION shape, so STRICT_REQUIRE: there is no single stand-in to
+     * name -- non-strict still opens at the defaults and answers whatever
+     * device SDL gives, byte-identical to before BY CONSTRUCTION. `null`
+     * stays the documented "use the defaults" form (tests/test_audio.eigs
+     * calls `audio_stream_open of null`), so only a PRESENT,
+     * non-null argument that is not a >= 2-element list is refused. Above the element guard, and
+     * so above the SDL load -- the [135] rule. */
+    STRICT_REQUIRE(arg && arg->type != VAL_NULL
+                   && !(arg->type == VAL_LIST && arg->data.list.count >= 2),
+                   "audio_stream_open", "[number freq, number channels] or null");
     if (arg && arg->type == VAL_LIST && arg->data.list.count >= 2) {
         ARG_GUARD(arg->data.list.items[0]->type != VAL_NUM ||
                   arg->data.list.items[1]->type != VAL_NUM,
@@ -1377,6 +1614,9 @@ Value* builtin_audio_stream_open(Value *arg) {
  * freed immediately. Pure sink, not traced. Returns 1 on success, 0 on a
  * closed device, bad shape, or an SDL queue error. */
 Value* builtin_audio_stream_push(Value *arg) {
+    /* #1007 round 3: above the device check, for the reason audio_play's is. */
+    STRICT_REQUIRE(gfx_bad_samples(arg), "audio_stream_push",
+                   "a list or buffer of samples, or null");
     if (!g_stream_device) return make_num(0);  /* fs:ANSWER BUILTINS.md audio_stream_push: "0 on a closed device"; g_stream_device == 0 is device state, not an argument */
     int n = 0;
     int16_t *buf = audio_convert_samples(arg, &n);
@@ -1420,7 +1660,7 @@ Value* builtin_audio_stream_clear(Value *arg) {
     (void)arg;
     if (g_stream_device && p_SDL_ClearQueuedAudio)
         p_SDL_ClearQueuedAudio(g_stream_device);
-    return make_null();
+    return make_null(); /* fs:VOID audio_stream_clear answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* audio_stream_close of null — stop and close the live stream device.
@@ -1431,7 +1671,7 @@ Value* builtin_audio_stream_close(Value *arg) {
         p_SDL_CloseAudioDevice(g_stream_device);
         g_stream_device = 0;
     }
-    return make_null();
+    return make_null(); /* fs:VOID audio_stream_close answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* audio_music_play of [path, loops] — stream a music file (mp3/ogg/wav) via
@@ -1439,10 +1679,16 @@ Value* builtin_audio_stream_close(Value *arg) {
  * any current track. Returns 1 on success, 0 on failure (missing mixer lib,
  * unreadable/undecodable file, no audio device). */
 Value* builtin_audio_music_play(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 1) return make_num(0);  /* fs:TODO #971 guards the [path, loops] arg-list shape; deferred: variant-only build */
-    Value *pv = arg->data.list.items[0];
-    if (pv->type != VAL_STR) return make_num(0);  /* fs:TODO #971 guards a non-string path; deferred: variant-only build */
-    const char *path = pv->data.str;
+    /* #1007: both #971 deferral markers converted. Above load_sdl2(), the [135] rule. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 1
+              || arg->data.list.items[0]->type != VAL_STR,
+              "audio_music_play", "[string path, number loops]", make_num(0));
+    /* A wrong-typed `loops` is the COERCION shape: it fell back to -1
+     * (forever), so a typo made the track loop rather than play once. */
+    STRICT_REQUIRE(arg->data.list.count >= 2
+                   && arg->data.list.items[1]->type != VAL_NUM,
+                   "audio_music_play", "[string path, number loops]");
+    const char *path = arg->data.list.items[0]->data.str;
     int loops = (arg->data.list.count >= 2 && arg->data.list.items[1]->type == VAL_NUM)
                 ? (int)arg->data.list.items[1]->data.num : -1;
     if (!load_sdl2()) return make_num(0);  /* fs:ANSWER the header's documented "0 on failure (missing mixer lib ...)" -- libSDL2 absent is environment state, not an argument */
@@ -1476,7 +1722,13 @@ Value* builtin_audio_music_play(Value *arg) {
 
 /* audio_music_volume of v — music volume 0..128 */
 Value* builtin_audio_music_volume(Value *arg) {
-    if (!g_mixer_open || !p_Mix_VolumeMusic) return make_null();
+    /* #1007, COERCION shape: a wrong-typed volume fell through to v = 0 and
+     * MUTED the music. Above the mixer-state check, the [135] rule. */
+    STRICT_REQUIRE(!(arg && arg->type == VAL_NUM)
+                   && !(arg && arg->type == VAL_LIST && arg->data.list.count >= 1
+                        && arg->data.list.items[0]->type == VAL_NUM),
+                   "audio_music_volume", "number volume 0..128 or [number volume]");
+    if (!g_mixer_open || !p_Mix_VolumeMusic) return make_null();  /* fs:VOID no mixer open: audio_music_volume answers null on every path -- the return value, not a rejected-argument stand-in */
     int v = 0;
     if (arg && arg->type == VAL_NUM) v = (int)arg->data.num;
     else if (arg && arg->type == VAL_LIST && arg->data.list.count >= 1
@@ -1485,7 +1737,7 @@ Value* builtin_audio_music_volume(Value *arg) {
     if (v < 0) v = 0;
     if (v > MY_MIX_MAX_VOLUME) v = MY_MIX_MAX_VOLUME;
     p_Mix_VolumeMusic(v);
-    return make_null();
+    return make_null(); /* fs:VOID audio_music_volume answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* audio_music_stop of null — halt and free the current track. */
@@ -1493,11 +1745,17 @@ Value* builtin_audio_music_stop(Value *arg) {
     (void)arg;
     if (g_mixer_open && p_Mix_HaltMusic) p_Mix_HaltMusic();
     if (g_music && p_Mix_FreeMusic) { p_Mix_FreeMusic(g_music); g_music = NULL; }
-    return make_null();
+    return make_null(); /* fs:VOID audio_music_stop answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* audio_play of samples — convert float list [-1,1] to int16, queue */
 Value* builtin_audio_play(Value *arg) {
+    /* #1007 round 3: ABOVE the device check, the [135] rule applied to device
+     * state rather than to the SDL load. Below it, `audio_play of 42` is
+     * silent on any machine with no device open -- which is every CI runner
+     * -- so the guard would exist only where nothing runs it. */
+    STRICT_REQUIRE(gfx_bad_samples(arg), "audio_play",
+                   "a list or buffer of samples, or null");
     if (!g_audio_device) return make_num(0);  /* fs:ANSWER BUILTINS.md audio_play: "0 on ... closed device"; channel ids are slot+1 >= 1 (line 1057), so 0 is not a channel */
     int n = 0;
     int16_t *buf = audio_convert_samples(arg, &n);
@@ -1515,17 +1773,31 @@ Value* builtin_audio_play(Value *arg) {
  * no memory multiplication — Tidepool GAP-002). Returns the channel id,
  * or 0 on a bad arg / closed device. */
 Value* builtin_audio_play_loop(Value *arg) {
-    if (!g_audio_device || !arg || arg->type != VAL_LIST || arg->data.list.count < 2)
-        return make_num(0);  /* fs:TODO #971 mixed condition: !g_audio_device is device state (must stay soft) but the VAL_LIST/count checks are a real arg guard -- splitting them is the conversion; deferred: variant-only build */
-    Value *samples = arg->data.list.items[0];
-    Value *loops_v = arg->data.list.items[1];
-    if (!loops_v || loops_v->type != VAL_NUM) return make_num(0);  /* fs:TODO #971 guards a non-number loops argument; deferred: variant-only build */
+    /* #1007: the mixed condition split, exactly as its #971 deferral marker asked. The
+     * arg-shape half is loud; `!g_audio_device` is device state and stays
+     * soft, and it moves BELOW the guard so the guard is reachable on a
+     * machine with no audio device (the [135] rule). */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 2
+              || !arg->data.list.items[1]
+              || arg->data.list.items[1]->type != VAL_NUM,
+              "audio_play_loop", "[samples, number loops]", make_num(0));
     /* #152: NaN/huge casts are UB; -1 is the one negative with meaning. */
-    double loops_d = loops_v->data.num;
+    double loops_d = arg->data.list.items[1]->data.num;
     int loops;
     if (loops_d == -1.0) loops = -1;
-    else if (isnan(loops_d) || loops_d < 1.0 || loops_d > 10000.0) return make_num(0);  /* fs:TODO #971 value-domain guard (NaN / <1 / >10000 loops, the #152 UB-cast bound), not a device or answer path; deferred: variant-only build */
-    else loops = (int)loops_d;
+    else {
+        ARG_GUARD(isnan(loops_d) || loops_d < 1.0 || loops_d > 10000.0,
+                  "audio_play_loop",
+                  "[samples, number loops] with loops == -1 or 1..10000",
+                  make_num(0));
+        loops = (int)loops_d;
+    }
+    /* #1007 round 3: the samples slot, beside the loops slot and above the
+     * device check for the same reachability reason. */
+    STRICT_REQUIRE(gfx_bad_samples(arg->data.list.items[0]), "audio_play_loop",
+                   "[list or buffer of samples, number loops]");
+    if (!g_audio_device) return make_num(0);  /* fs:ANSWER BUILTINS.md audio_play_loop: "0 on ... closed device"; channel ids are slot+1 >= 1, so 0 is not a channel */
+    Value *samples = arg->data.list.items[0];
     int n = 0;
     int16_t *buf = audio_convert_samples(samples, &n);
     if (!buf) {
@@ -1540,12 +1812,14 @@ Value* builtin_audio_play_loop(Value *arg) {
 /* audio_volume of [channel, vol] — live per-channel volume, 0.0..4.0
  * (Tidepool GAP-003). Returns 1, or 0 on a bad channel/arg. */
 Value* builtin_audio_volume(Value *arg) {
-    if (!g_audio_device || !arg || arg->type != VAL_LIST || arg->data.list.count < 2)
-        return make_num(0);  /* fs:TODO #971 mixed condition: !g_audio_device is device state (must stay soft) but the VAL_LIST/count checks are a real arg guard; deferred: variant-only build */
+    /* #1007: the mixed condition split, as its #971 deferral marker asked. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 2
+              || !arg->data.list.items[0] || arg->data.list.items[0]->type != VAL_NUM
+              || !arg->data.list.items[1] || arg->data.list.items[1]->type != VAL_NUM,
+              "audio_volume", "[number channel, number volume]", make_num(0));
+    if (!g_audio_device) return make_num(0);  /* fs:ANSWER 0 means "that channel is not playing", and with no device open no channel is */
     Value *ch_v = arg->data.list.items[0];
     Value *vol_v = arg->data.list.items[1];
-    if (!ch_v || ch_v->type != VAL_NUM || !vol_v || vol_v->type != VAL_NUM)
-        return make_num(0);  /* fs:TODO #971 guards non-number channel/volume arguments; deferred: variant-only build */
     int c = (int)ch_v->data.num - 1;
     if (c < 0 || c >= AUDIO_MAX_CHANNELS) return make_num(0);  /* fs:ANSWER 0 means "that channel is not playing" -- the same value line 1452 returns for an inactive in-range channel; an out-of-range id is definitionally inactive */
     double vol = vol_v->data.num;
@@ -1561,7 +1835,10 @@ Value* builtin_audio_volume(Value *arg) {
 /* audio_stop of channel — stop one mixer channel. Returns 1, or 0 on a
  * bad/inactive channel. */
 Value* builtin_audio_stop(Value *arg) {
-    if (!g_audio_device || !arg || arg->type != VAL_NUM) return make_num(0);  /* fs:TODO #971 mixed condition: !g_audio_device is device state (must stay soft) but arg->type != VAL_NUM is a real arg guard; deferred: variant-only build */
+    /* #1007: the mixed condition split, as its #971 deferral marker asked. */
+    ARG_GUARD(!arg || arg->type != VAL_NUM, "audio_stop", "number channel",
+              make_num(0));
+    if (!g_audio_device) return make_num(0);  /* fs:ANSWER 0 means "the channel was not active", and with no device open none is */
     int c = (int)arg->data.num - 1;
     if (c < 0 || c >= AUDIO_MAX_CHANNELS) return make_num(0);  /* fs:ANSWER 0 means "the channel was not active" -- the same value line 1465 returns for an inactive in-range channel */
     p_SDL_LockAudioDevice(g_audio_device);
@@ -1595,12 +1872,21 @@ Value* builtin_audio_queue_size(Value *arg) {
 Value* builtin_audio_clear(Value *arg) {
     (void)arg;
     if (g_audio_device) audio_free_channels(1);
-    return make_null();
+    return make_null(); /* fs:VOID audio_clear answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* audio_sine of [freq, duration, amplitude] — generate sine wave samples */
 Value* builtin_audio_sine(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) return make_list(0);
+    /* #1007 round 2. The ARITY/SHAPE half of the same laundering: a short or
+     * non-list argument was answered with an empty sample list, which is
+     * indistinguishable from a legitimately empty generation (`n <= 0`
+     * returns the same list four lines down). Under EIGS_STRICT=1 it now
+     * raises; the empty list stays the non-strict stand-in, so the default
+     * path is byte-identical. Found by a blind review measuring the docs'
+     * "a wrong type, a short argument list or an out-of-domain value raises"
+     * claim against the binary: eight sites answered 0 quietly. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 3,
+              "audio_sine", "[number freq, number duration, number amplitude]", make_list(0));
     /* #1007, pointer-disclosure half. The generators BUILD their returned
      * samples out of these reads, so a type-pun here does not merely make a
      * wrong drawing call — it copies a reinterpreted `char *` into a list the
@@ -1633,7 +1919,9 @@ Value* builtin_audio_sine(Value *arg) {
 
 /* audio_saw of [freq, duration, amplitude] — sawtooth wave */
 Value* builtin_audio_saw(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) return make_list(0);
+    /* #1007 round 2, the arity/shape half — see builtin_audio_sine. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 3,
+              "audio_saw", "[number freq, number duration, number amplitude]", make_list(0));
     /* #1007, pointer-disclosure half. The generators BUILD their returned
      * samples out of these reads, so a type-pun here does not merely make a
      * wrong drawing call — it copies a reinterpreted `char *` into a list the
@@ -1665,7 +1953,9 @@ Value* builtin_audio_saw(Value *arg) {
 
 /* audio_square of [freq, duration, amplitude] — square wave */
 Value* builtin_audio_square(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 3) return make_list(0);
+    /* #1007 round 2, the arity/shape half — see builtin_audio_sine. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 3,
+              "audio_square", "[number freq, number duration, number amplitude]", make_list(0));
     /* #1007, pointer-disclosure half. The generators BUILD their returned
      * samples out of these reads, so a type-pun here does not merely make a
      * wrong drawing call — it copies a reinterpreted `char *` into a list the
@@ -1698,7 +1988,9 @@ Value* builtin_audio_square(Value *arg) {
 /* audio_sweep of [freq_start, freq_end, duration, amplitude, waveform]
    waveform: 0=sine, 1=sawtooth.  Continuous phase sweep. */
 Value* builtin_audio_sweep(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 5) return make_list(0);
+    /* #1007 round 2, the arity/shape half — see builtin_audio_sine. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 5,
+              "audio_sweep", "[number freq_start, number freq_end, number duration, number amplitude, number waveform]", make_list(0));
     /* #1007, pointer-disclosure half. The generators BUILD their returned
      * samples out of these reads, so a type-pun here does not merely make a
      * wrong drawing call — it copies a reinterpreted `char *` into a list the
@@ -1742,7 +2034,9 @@ Value* builtin_audio_sweep(Value *arg) {
 
 /* audio_noise of [duration, amplitude] — white noise */
 Value* builtin_audio_noise(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2) return make_list(0);
+    /* #1007 round 2, the arity/shape half — see builtin_audio_sine. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 2,
+              "audio_noise", "[number duration, number amplitude]", make_list(0));
     /* #1007, pointer-disclosure half. The generators BUILD their returned
      * samples out of these reads, so a type-pun here does not merely make a
      * wrong drawing call — it copies a reinterpreted `char *` into a list the
@@ -1771,10 +2065,20 @@ Value* builtin_audio_noise(Value *arg) {
 
 /* audio_mix of [samples_a, samples_b] — add and clamp */
 Value* builtin_audio_mix(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2) return make_list(0);
+    /* #1007 round 2, the arity/shape half — see builtin_audio_sine. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 2,
+              "audio_mix", "[list samples_a, list samples_b]", make_list(0));
     Value *a = arg->data.list.items[0];
     Value *b = arg->data.list.items[1];
-    if (a->type != VAL_LIST || b->type != VAL_LIST) return make_list(0);
+    ARG_GUARD(a->type != VAL_LIST || b->type != VAL_LIST,
+              "audio_mix", "[list samples_a, list samples_b]", make_list(0));
+    /* #1007, COERCION shape: a non-number ELEMENT was substituted with 0.0,
+     * so a wrong-typed sample list mixed to silence and answered a valid
+     * list. Checked BEFORE the output list is built so a strict raise leaks
+     * nothing. The `i < count` padding of the shorter list is a documented
+     * answer and is deliberately not part of this condition. */
+    STRICT_REQUIRE(!gfx_list_all_num(a) || !gfx_list_all_num(b),
+                   "audio_mix", "[list of numbers, list of numbers]");
     int n = a->data.list.count > b->data.list.count ? a->data.list.count : b->data.list.count;
 
     Value *out = make_list(n);
@@ -1791,9 +2095,17 @@ Value* builtin_audio_mix(Value *arg) {
 
 /* audio_gain of [samples, volume] — scale and clamp */
 Value* builtin_audio_gain(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2) return make_list(0);
+    /* #1007 round 2, the arity/shape half — see builtin_audio_sine. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 2,
+              "audio_gain", "[list samples, number volume]", make_list(0));
     Value *samples = arg->data.list.items[0];
-    if (samples->type != VAL_LIST) return make_list(0);
+    ARG_GUARD(samples->type != VAL_LIST, "audio_gain",
+              "[list samples, number volume]", make_list(0));
+    /* #1007, COERCION shape: a non-number ELEMENT was substituted with 0.0.
+     * Checked before the output list is built so a strict raise leaks
+     * nothing. */
+    STRICT_REQUIRE(!gfx_list_all_num(samples), "audio_gain",
+                   "[list of numbers, number volume]");
     /* #1007: the SEVENTH member of the disclosure family, and the one that
      * survived the first pass because the fix was written from the six
      * generators rather than from a sweep. `vol` multiplies every sample and
@@ -1819,7 +2131,9 @@ Value* builtin_audio_gain(Value *arg) {
 
 /* audio_envelope of [samples, attack, decay, sustain_level, release] — ADSR */
 Value* builtin_audio_envelope(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 5) return make_list(0);
+    /* #1007 round 2, the arity/shape half — see builtin_audio_sine. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 5,
+              "audio_envelope", "[list samples, number attack, number decay, number sustain, number release]", make_list(0));
     /* #1007, pointer-disclosure half. The generators BUILD their returned
      * samples out of these reads, so a type-pun here does not merely make a
      * wrong drawing call — it copies a reinterpreted `char *` into a list the
@@ -1835,7 +2149,14 @@ Value* builtin_audio_envelope(Value *arg) {
               arg->data.list.items[4]->type != VAL_NUM,
               "audio_envelope", "[samples, number attack, number decay, number sustain, number release]", make_list(0));
     Value *samples = arg->data.list.items[0];
-    if (samples->type != VAL_LIST) return make_list(0);
+    ARG_GUARD(samples->type != VAL_LIST, "audio_envelope",
+              "[list samples, number attack, number decay, number sustain, number release]",
+              make_list(0));
+    /* #1007, COERCION shape: a non-number ELEMENT was substituted with 0.0.
+     * Checked before the output list is built so a strict raise leaks
+     * nothing. */
+    STRICT_REQUIRE(!gfx_list_all_num(samples), "audio_envelope",
+                   "[list of numbers, number attack, number decay, number sustain, number release]");
     double attack = arg->data.list.items[1]->data.num;
     double decay = arg->data.list.items[2]->data.num;
     double sustain = arg->data.list.items[3]->data.num;
@@ -1880,27 +2201,41 @@ Value* builtin_audio_envelope(Value *arg) {
  * renderer as a scaled texture.  One C call replaces width*height draw calls.
  * Palette: 0 → white (0xFF), 1 → light (0xAA), 2 → dark (0x55), 3 → black (0x00). */
 Value* builtin_gfx_fb(Value *arg) {
-    if (!g_renderer || !p_SDL_CreateTexture || !p_SDL_UpdateTexture || !p_SDL_RenderCopy)
-        return make_null();
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 6)
-        return make_null();
+    /* Argument shape BEFORE the renderer/symbol check, the [135] rule: the
+     * five geometry elements were read unchecked while the buffer beside
+     * them was type-checked one line down. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 6
+              || !arg->data.list.items[0]
+              || arg->data.list.items[0]->type != VAL_BUFFER
+              || !gfx_nums(arg, 1, 6),
+              "gfx_fb",
+              "[buffer fb, number w, number h, number x, number y, number scale]",
+              make_null());
     Value *buf  = arg->data.list.items[0];
     int    w    = (int)arg->data.list.items[1]->data.num;
     int    h    = (int)arg->data.list.items[2]->data.num;
     int    dx   = (int)arg->data.list.items[3]->data.num;
     int    dy   = (int)arg->data.list.items[4]->data.num;
     int    sc   = (int)arg->data.list.items[5]->data.num;
-    if (!buf || buf->type != VAL_BUFFER || w <= 0 || h <= 0 || sc <= 0)
-        return make_null();
-    if (buf->data.buffer.count < w * h)
-        return make_null();
+    /* A non-positive dimension is DEGENERATE geometry (nothing to blit),
+     * the same verdict gfx_rrect gives a zero-size rectangle. A buffer
+     * SHORTER than w * h is an argument mismatch and is loud -- still above
+     * the SDL check so it is reachable without libSDL2 (the [135] rule);
+     * the reads it needs are type-checked by the guard above. */
+    if (w <= 0 || h <= 0 || sc <= 0) return make_null();  /* fs:EMPTY a zero or negative width/height/scale covers no pixels, so drawing nothing IS the answer -- the same degenerate-geometry identity gfx_rrect gives */
+    ARG_GUARD(buf->data.buffer.count < w * h,
+              "gfx_fb",
+              "[buffer fb, number w, number h, number x, number y, number scale] with len of fb >= w * h",
+              make_null());
+    if (!g_renderer || !p_SDL_CreateTexture || !p_SDL_UpdateTexture || !p_SDL_RenderCopy)
+        return make_null();  /* fs:VOID no window / no SDL texture symbols: gfx_fb answers null on every path -- the return value, not a rejected-argument stand-in */
 
     /* Recreate texture if size changed */
     if (!g_fb_texture || g_fb_w != w || g_fb_h != h) {
         if (g_fb_texture) p_SDL_DestroyTexture(g_fb_texture);
         g_fb_texture = p_SDL_CreateTexture(g_renderer,
             MY_SDL_PIXELFORMAT_ARGB8888, MY_SDL_TEXTUREACCESS_STREAMING, w, h);
-        if (!g_fb_texture) return make_null();
+        if (!g_fb_texture) return make_null(); /* fs:ANSWER SDL_CreateTexture failed -- environment/driver state, not an argument; nothing can be blitted so null is the result */
         g_fb_w = w;
         g_fb_h = h;
     }
@@ -1927,7 +2262,7 @@ Value* builtin_gfx_fb(Value *arg) {
 
     SDL_Rect dst = { dx, dy, w * sc, h * sc };
     p_SDL_RenderCopy(g_renderer, g_fb_texture, NULL, &dst);
-    return make_null();
+    return make_null(); /* fs:VOID gfx_fb answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 /* ================================================================
@@ -1938,14 +2273,21 @@ Value* builtin_gfx_fb(Value *arg) {
  * Reads LCDC, scroll, palette, VRAM, OAM registers directly from mem_buf.
  * ================================================================ */
 Value* builtin_ppu_render_frame(Value *arg) {
-    if (!arg || arg->type != VAL_LIST || arg->data.list.count < 2)
-        return make_null();
+    /* #1007: a wrong-typed or undersized buffer used to answer null and
+     * render nothing, which in an emulator presents as a black screen with
+     * no diagnostic anywhere. */
+    ARG_GUARD(!arg || arg->type != VAL_LIST || arg->data.list.count < 2,
+              "ppu_render_frame", "[buffer mem, buffer fb]", make_null());
     Value *mem_v = arg->data.list.items[0];
     Value *fb_v  = arg->data.list.items[1];
-    if (!mem_v || mem_v->type != VAL_BUFFER || mem_v->data.buffer.count < 65536)
-        return make_null();
-    if (!fb_v || fb_v->type != VAL_BUFFER || fb_v->data.buffer.count < 23040)
-        return make_null();
+    ARG_GUARD(!mem_v || mem_v->type != VAL_BUFFER
+              || mem_v->data.buffer.count < 65536,
+              "ppu_render_frame", "[buffer mem of at least 65536, buffer fb]",
+              make_null());
+    ARG_GUARD(!fb_v || fb_v->type != VAL_BUFFER
+              || fb_v->data.buffer.count < 23040,
+              "ppu_render_frame", "[buffer mem, buffer fb of at least 23040]",
+              make_null());
 
     double *mem = mem_v->data.buffer.data;
     double *fb  = fb_v->data.buffer.data;
@@ -1954,7 +2296,7 @@ Value* builtin_ppu_render_frame(Value *arg) {
     if (!(lcdc & 0x80)) {
         /* LCD off — blank */
         for (int i = 0; i < 23040; i++) fb[i] = 0;
-        return make_null();
+        return make_null(); /* fs:VOID the LCD is off, so the frame was blanked; ppu_render_frame answers null on every path -- this is the return value, not a stand-in for a rejected argument */
     }
 
     int scy = (int)mem[0xFF42];
@@ -2129,7 +2471,7 @@ Value* builtin_ppu_render_frame(Value *arg) {
             }
         }
     }
-    return make_null();
+    return make_null(); /* fs:VOID ppu_render_frame answers null on every path -- this is the return value, not a stand-in for a rejected argument */
 }
 
 void register_gfx_builtins(Env *env) {
diff --git a/tests/gfx_asan_corpus/01_draw.eigs b/tests/gfx_asan_corpus/01_draw.eigs
new file mode 100644
index 00000000..ef5e2bab
--- /dev/null
+++ b/tests/gfx_asan_corpus/01_draw.eigs
@@ -0,0 +1,27 @@
+# Every drawing builtin, valid arguments, with a window open. The point is
+# the ALLOCATION paths inside ext_gfx.c, so each call is made and its answer
+# read back rather than discarded.
+o is gfx_open of [64, 48, "asan-gfx corpus"]
+print of f"open: {o}"
+ignore is gfx_clear of [10, 20, 30]
+ignore is gfx_rect of [0, 0, 8, 8, 255, 0, 0]
+ignore is gfx_rect of [8, 0, 8, 8, 255, 0, 0, 128]
+ignore is gfx_line of [0, 0, 63, 47, 0, 255, 0]
+ignore is gfx_point of [1, 1, 0, 0, 255]
+ignore is gfx_circle of [32, 24, 5, 9, 9, 9]
+ignore is gfx_circle of [32, 24, 5, 9, 9, 9, 200]
+ignore is gfx_rrect of [4, 4, 20, 12, 3, 1, 2, 3]
+ignore is gfx_rrect of [4, 20, 20, 12, 0, 1, 2, 3, 64]
+ignore is gfx_clip of [0, 0, 32, 24]
+ignore is gfx_text of [2, 2, "hello", 255, 255, 255]
+ignore is gfx_text of [2, 12, "hello", 255, 255, 255, 2]
+ignore is gfx_clip of null
+tw is gfx_text_width of ["hello", 2]
+th is gfx_text_height of 2
+print of f"w: {tw} h: {th}"
+print of f"pixel: {gfx_read of [1, 1]}"
+ignore is gfx_title of "renamed"
+ignore is gfx_present of null
+ignore is gfx_delay of 1
+ignore is gfx_close of null
+print of "01 done"
diff --git a/tests/gfx_asan_corpus/02_poll.eigs b/tests/gfx_asan_corpus/02_poll.eigs
new file mode 100644
index 00000000..cf71320e
--- /dev/null
+++ b/tests/gfx_asan_corpus/02_poll.eigs
@@ -0,0 +1,14 @@
+# The event pump. gfx_poll allocates a dict per event and used to leak it on
+# the two paths that decode nothing (a non-resize SDL_WINDOWEVENT and any
+# event type it has no case for) -- 584 bytes / 6 allocations, the only leak
+# `make asan-gfx` surfaced over this corpus (#1007).
+o is gfx_open of [32, 32, "poll"]
+n is 0
+for i in range of 200:
+    e is gfx_poll of null
+    if e != null:
+        n is n + 1
+    ignore is gfx_present of null
+print of f"events seen: {n >= 0}"
+ignore is gfx_close of null
+print of "02 done"
diff --git a/tests/gfx_asan_corpus/03_fb_ppu.eigs b/tests/gfx_asan_corpus/03_fb_ppu.eigs
new file mode 100644
index 00000000..50f62593
--- /dev/null
+++ b/tests/gfx_asan_corpus/03_fb_ppu.eigs
@@ -0,0 +1,19 @@
+# The two buffer-consuming builtins: the framebuffer blit (allocates an ARGB
+# pixel array per call and caches an SDL texture across calls) and the whole
+# Game Boy PPU frame renderer.
+o is gfx_open of [160, 144, "fb"]
+fb is buffer of (160 * 144)
+for i in range of 100:
+    fb[i] is i % 4
+ignore is gfx_fb of [fb, 160, 144, 0, 0, 1]
+ignore is gfx_fb of [fb, 160, 144, 0, 0, 2]
+ignore is gfx_fb of [fb, 80, 72, 0, 0, 1]
+mem is buffer of 65536
+mem[0xFF40] is 0x91
+mem[0xFF47] is 0xE4
+ignore is ppu_render_frame of [mem, fb]
+mem[0xFF40] is 0x00
+ignore is ppu_render_frame of [mem, fb]
+print of f"fb[0]: {fb[0]}"
+ignore is gfx_close of null
+print of "03 done"
diff --git a/tests/gfx_asan_corpus/04_audio.eigs b/tests/gfx_asan_corpus/04_audio.eigs
new file mode 100644
index 00000000..22723532
--- /dev/null
+++ b/tests/gfx_asan_corpus/04_audio.eigs
@@ -0,0 +1,23 @@
+# The audio surface: device, generators (which allocate a sample list per
+# call), the transforms, the mixer channels, and the capture/stream devices.
+d is audio_open of [44100, 1]
+print of f"device: {d > 0}"
+s is audio_sine of [440, 0.01, 0.5]
+w is audio_saw of [220, 0.01, 0.4]
+q is audio_square of [330, 0.01, 0.3]
+p is audio_sweep of [100, 200, 0.01, 0.5, 0]
+z is audio_noise of [0.01, 0.2]
+m is audio_mix of [s, w]
+g is audio_gain of [m, 0.5]
+e is audio_envelope of [g, 0.002, 0.002, 0.5, 0.002]
+print of f"lens: {len of s} {len of q} {len of p} {len of z} {len of e}"
+c is audio_play of e
+c2 is audio_play_loop of [e, 2]
+ignore is audio_volume of [c, 0.5]
+ignore is audio_queue_size of null
+ignore is audio_stop of c
+ignore is audio_pause of 1
+ignore is audio_pause of 0
+ignore is audio_clear of null
+ignore is audio_close of null
+print of "04 done"
diff --git a/tests/gfx_asan_corpus/05_capture_stream.eigs b/tests/gfx_asan_corpus/05_capture_stream.eigs
new file mode 100644
index 00000000..2dc65275
--- /dev/null
+++ b/tests/gfx_asan_corpus/05_capture_stream.eigs
@@ -0,0 +1,18 @@
+# Capture and live-stream devices: both allocate buffers per read/push, and
+# both are trace-recorded, so this also walks the TAKE/RECORD seam.
+cd is audio_capture_open of [44100, 1]
+for i in range of 5:
+    b is audio_capture_read of null
+ignore is audio_capture_close of null
+sd is audio_stream_open of [44100, 1]
+blk is audio_sine of [440, 0.01, 0.3]
+ignore is audio_stream_push of blk
+ignore is audio_stream_queued of null
+ignore is audio_stream_clear of null
+ignore is audio_stream_close of null
+# The music path with no loadable file: exercises the SDL_mixer load-failure
+# branch, which frees on the way out.
+ignore is audio_music_play of ["/nonexistent/eigs-no-such-track.ogg", 0]
+ignore is audio_music_volume of 64
+ignore is audio_music_stop of null
+print of "05 done"
diff --git a/tests/gfx_asan_corpus/06_rejected.eigs b/tests/gfx_asan_corpus/06_rejected.eigs
new file mode 100644
index 00000000..ad965ba2
--- /dev/null
+++ b/tests/gfx_asan_corpus/06_rejected.eigs
@@ -0,0 +1,56 @@
+# The REJECTED-argument paths, which is where #1007's guards live. A guard
+# that raises must not leak what it had already built (audio_mix / audio_gain
+# / audio_envelope allocate an output list, which is why their element checks
+# sit before the build). Non-strict here; the strict pass runs the same file
+# under EIGS_STRICT=1 with the raise caught by the harness.
+o is gfx_open of [32, 32, "rejected"]
+ignore is gfx_rect of ["10", 10, 50, 50, 255, 0, 0]
+ignore is gfx_line of ["0", 0, 10, 10, 1, 2, 3]
+ignore is gfx_point of ["1", 2, 3, 4, 5]
+ignore is gfx_circle of ["1", 2, 3, 4, 5, 6]
+ignore is gfx_rrect of ["1", 2, 3, 4, 5, 6, 7, 8]
+ignore is gfx_clip of ["1", 2, 3, 4]
+ignore is gfx_clear of ["1", 2, 3]
+ignore is gfx_text of [1, 2, "hi", "255", 0, 0]
+ignore is gfx_fb of [42, 4, 4, 0, 0, 1]
+ignore is gfx_read of ["1", 1]
+ignore is gfx_delay of "5"
+ignore is gfx_title of 42
+ignore is gfx_text_width of 5
+ignore is gfx_text_height of "2"
+ignore is ppu_render_frame of [1, 2]
+ignore is audio_mix of [["a"], [0.1]]
+ignore is audio_gain of [["a"], 2.0]
+ignore is audio_envelope of [["a"], 0.01, 0.01, 0.5, 0.01]
+ignore is audio_sine of ["440", 0.01, 0.5]
+ignore is audio_play_loop of [[0.1], "2"]
+ignore is audio_volume of ["1", 1]
+ignore is audio_stop of "x"
+ignore is audio_pause of "x"
+ignore is audio_music_play of [42]
+ignore is audio_music_volume of "loud"
+ignore is audio_open of ["44100", "1"]
+ignore is audio_capture_open of ["44100", "1"]
+ignore is audio_stream_open of ["44100", "1"]
+# #1007 round 3: the CONTAINER axis. A short or non-list argument to the three
+# openers used to walk past the element guard and open the device at the
+# defaults; a non-list `samples` used to answer the documented "nothing to
+# play" 0. Both take a new early-return path, so both are walked here — a
+# guard whose return is never executed under ASan is a guard nobody has
+# checked for a leak.
+ignore is audio_open of [44100]
+ignore is audio_capture_open of [44100]
+ignore is audio_stream_open of [48000]
+ignore is audio_open of 44100
+ignore is audio_play of 42
+ignore is audio_stream_push of "zzz"
+ignore is audio_play_loop of [42, 2]
+# Non-strict, the three short-list opens above really DO open a device (that
+# is the unchanged answer this change preserves), so close them again --
+# an SDL device left open at exit is a leak this gate would report as ours.
+ignore is audio_close of null
+ignore is audio_capture_close of null
+ignore is audio_stream_close of null
+ignore is gfx_open of ["800", "600", "t"]
+ignore is gfx_close of null
+print of "06 done"
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 89db79f2..54ff100f 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -3173,12 +3173,25 @@ fi
 # audio device came up, which the file reports, so the pin is exact in both
 # environments rather than a floor.
 #
-# WHAT THIS SECTION DOES NOT COVER, so a green line is not misread: only the
-# three *_open type-pun guards and the sample-element coercion. The other
-# ~85 fail-soft returns #1007 enumerates are untouched — in particular the 52
-# `make_null()` sites where gfx_rect/gfx_line/gfx_text answer a wrong-typed
-# argument by silently drawing nothing, which no gate in this repo sees
-# (tools/failsoft_classify_check.sh enumerates only the 0/"" population).
+# WHAT THIS SECTION COVERS, since the answer changed: the whole ext_gfx.c
+# argument surface, not just the three *_open type-pun guards it started as.
+# The drawing half — the ~52 `make_null()` sites where gfx_rect/gfx_line/
+# gfx_text answered a wrong-typed argument by silently drawing nothing — is
+# in it since #1007's second pass, and so are the COERCION shapes
+# (gfx_text_width's scale, audio_pause's flag, audio_mix's sample elements),
+# which have no stand-in return and are invisible to
+# tools/failsoft_classify_check.sh by construction.
+#
+# The load-bearing row is the PIXEL PROOF in the non-strict pass, gated on a
+# real renderer: pre-fix, a wrong-typed colour painted BLACK over the cleared
+# pixel — a wrong drawing, not a missing one — and gfx_read reads it back.
+# That is the only row here that can see the defect on real pixels; every
+# other non-strict row asserts the answer is UNCHANGED, which is the
+# byte-identity half of the claim. The strict pass discriminates without SDL.
+#
+# Still NOT covered: whether the classifications recorded in ext_gfx.c are
+# RIGHT ([99r]'s population plus this section's pins together), and leaks on
+# those paths ([137]).
 GA_PROBE_FILE=$(mktemp /tmp/eigs_ga_probe_XXXXXX.eigs)
 cat > "$GA_PROBE_FILE" <<'PROBE'
 print of (gfx_text_width of ["m", 1])
@@ -3216,12 +3229,38 @@ TAPEPROG
     # `|| echo 0` appends a SECOND line and the diagnostic reads "0\n0".
     GA_TAPE_N=$(grep -c '^N ' "$GA_TDIR/r.tape" 2>/dev/null); GA_TAPE_N=${GA_TAPE_N:-0}
     rm -rf "$GA_TDIR"
-    # An audio device adds two rows to each pass. Both counts are derived from
-    # the file's own marker so neither branch is a floor.
+
+    # FOURTH PASS: the same tape contract for gfx_read, whose #1007 guard had
+    # to be placed above TRACE_NONDET_TAKE for the identical reason. Its own
+    # program, because the record count is pinned BY NAME (`N gfx_read=`) and
+    # a shared program would let one builtin's record satisfy the other's pin.
+    # Environment-independent: with no renderer the well-typed read still
+    # records (a null), so the count is 1 either way — while the pre-guard
+    # binary records 2 (measured), which is what makes the row discriminate.
+    GA_RDIR=$(mktemp -d /tmp/eigs_ga_read_XXXXXX)
+    cat > "$GA_RDIR/tape.eigs" <<'READPROG'
+o is gfx_open of [32, 32, "eigs #1007 gfx_read tape"]
+ignore is gfx_clear of [1, 2, 3]
+print of (gfx_read of ["1", 1])
+print of (gfx_read of [1, 1])
+ignore is gfx_close of null
+READPROG
+    SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy EIGS_TRACE="$GA_RDIR/r.tape" ./eigenscript "$GA_RDIR/tape.eigs" > "$GA_RDIR/first.out" 2>&1
+    SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy EIGS_REPLAY="$GA_RDIR/r.tape" ./eigenscript "$GA_RDIR/tape.eigs" > "$GA_RDIR/second.out" 2>&1
+    if cmp -s "$GA_RDIR/first.out" "$GA_RDIR/second.out"; then GA_READ_OK=1; else GA_READ_OK=0; fi
+    GA_READ_N=$(grep -c '^N gfx_read=' "$GA_RDIR/r.tape" 2>/dev/null); GA_READ_N=${GA_READ_N:-0}
+    rm -rf "$GA_RDIR"
+    # TWO environment axes now, each derived from the file's own marker so
+    # neither branch is a floor: an audio device adds 3 rows to the plain pass
+    # and 2 to the strict one, and a real renderer adds the 6 pixel-proof rows
+    # (plain only — the strict pass raises before it can draw). Counting only
+    # the audio axis, which is what this did while the pixel proof was being
+    # added, made the plain pin wrong by exactly 3 on a machine WITH libSDL2
+    # and right on one without.
+    GA_WANT_PLAIN=30; GA_WANT_STRICT=84
+    echo "$GA_PLAIN"  | grep -q "pixel-proof: 1"  && GA_WANT_PLAIN=$((GA_WANT_PLAIN + 6))
     if echo "$GA_STRICT" | grep -q "audio-device: 1"; then
-        GA_WANT_PLAIN=18; GA_WANT_STRICT=18
-    else
-        GA_WANT_PLAIN=15; GA_WANT_STRICT=16
+        GA_WANT_PLAIN=$((GA_WANT_PLAIN + 3)); GA_WANT_STRICT=$((GA_WANT_STRICT + 2))
     fi
     GA_GOT_PLAIN=$(echo "$GA_PLAIN"   | sed -n 's/^Tests: \([0-9]*\) .*/\1/p' | tail -1)
     GA_GOT_STRICT=$(echo "$GA_STRICT" | sed -n 's/^Tests: \([0-9]*\) .*/\1/p' | tail -1)
@@ -3233,23 +3272,26 @@ TAPEPROG
        && rc_ok "$GA_STRICT_RC" "$GA_STRICT" && echo "$GA_STRICT" | grep -q "All tests passed" \
        && echo "$GA_STRICT" | grep -q "strict-pass: 1" \
        && [ "$GA_GOT_PLAIN" = "$GA_WANT_PLAIN" ] && [ "$GA_GOT_STRICT" = "$GA_WANT_STRICT" ] \
-       && [ "$GA_TAPE_OK" = "1" ] && [ "$GA_TAPE_N" = "1" ]; then
-        TOTAL=$((TOTAL + 3))
-        PASS=$((PASS + 3))
+       && [ "$GA_TAPE_OK" = "1" ] && [ "$GA_TAPE_N" = "1" ] \
+       && [ "$GA_READ_OK" = "1" ] && [ "$GA_READ_N" = "1" ]; then
+        TOTAL=$((TOTAL + 4))
+        PASS=$((PASS + 4))
         echo "  PASS: wrong-typed w/h and freq/channels are refused in both modes ($GA_GOT_PLAIN + $GA_GOT_STRICT checks)"
         echo "  PASS: a rejected audio_capture_open consumes no tape record; capture == replay"
+        echo "  PASS: a rejected gfx_read consumes no tape record; capture == replay"
         # Say out loud what this environment could NOT exercise, rather than
         # letting a green line imply full coverage.
-        echo "$GA_PLAIN" | grep -q "sdl-present: 1" \
-            || echo "  NOTE: libSDL2 absent — the non-strict rows are not discriminating here; the strict pass is."
+        echo "$GA_PLAIN" | grep -q "pixel-proof: 1" \
+            || echo "  NOTE: libSDL2 absent — the pixel proof did not run, so the non-strict rows are not discriminating here; the strict pass is."
         echo "$GA_STRICT" | grep -q "audio-device: 1" \
             || echo "  NOTE: no audio device — the sample-element coercion rows did not run."
     else
-        TOTAL=$((TOTAL + 3))
-        FAIL=$((FAIL + 3))
+        TOTAL=$((TOTAL + 4))
+        FAIL=$((FAIL + 4))
         echo "  FAIL: gfx argument-type guards"
         echo "    counts: plain $GA_GOT_PLAIN/$GA_WANT_PLAIN, strict $GA_GOT_STRICT/$GA_WANT_STRICT"
         echo "    tape: capture==replay $GA_TAPE_OK (want 1), N records $GA_TAPE_N (want 1)"
+        echo "    gfx_read tape: capture==replay $GA_READ_OK (want 1), N gfx_read records $GA_READ_N (want 1)"
         echo "$GA_PLAIN"  | grep -iE "assert|error|FAIL" | head -3
         echo "$GA_STRICT" | grep -iE "assert|error|FAIL" | head -3
     fi
@@ -3380,6 +3422,127 @@ else
 fi
 echo ""
 
+# [137] ext_gfx.c under ASan+UBSan+LSan over the gfx corpus (#1007).
+#
+# `make asan-gfx` shipped in #1018 as a TOOL: no suite section and no
+# workflow ran it, so the file every app in the fleet and all 18 lib/ui
+# modules draw through was still the least instrumented in the repo. This is
+# the gate half. Its triage found one leak and it was OURS — gfx_poll's event
+# dict, 584 bytes / 6 allocations, leaked on the two paths that decode
+# nothing — so no LeakSanitizer suppression file is shipped: after the fix
+# the corpus has nothing to suppress, and a suppression with no leak behind
+# it is a waiver for a claim nobody checked.
+#
+# NOT probe-gated on THIS binary: the child finds or builds its own
+# asan-gfx binary (deliberately never by running `make`, which would
+# re-point src/eigenscript under the suite and trip the #681 fingerprint
+# guard), so the section is live in a release run too. It skips cleanly with
+# no ASan toolchain, and needs no libSDL2 — SDL is dlopen'd, so the corpus
+# walks every argument and allocation path either way and says so when the
+# renderer was absent. Its own positive/negative leak controls run BEFORE any
+# corpus verdict is believed.
+echo "[137] ext_gfx ASan/LSan corpus (#1007)"
+AG_OUTPUT=$(bash "$TESTS_DIR/test_asan_gfx.sh" 2>&1); AG_RC=$?
+AG_PASSED=$(echo "$AG_OUTPUT" | sed -n 's/^ASan gfx: \([0-9]*\) passed.*/\1/p' | tail -1)
+AG_FAILED=$(echo "$AG_OUTPUT" | sed -n 's/^ASan gfx: [0-9]* passed, \([0-9]*\) failed.*/\1/p' | tail -1)
+TOTAL=$((TOTAL + 1))
+if [ "$AG_RC" = "0" ] && [ "${AG_FAILED:-1}" = "0" ]; then
+    PASS=$((PASS + 1))
+    if echo "$AG_OUTPUT" | grep -q "(skipped)"; then
+        echo "  PASS: $(echo "$AG_OUTPUT" | grep -m1 'SKIP:' | sed 's/^ *//')"
+    else
+        echo "  PASS: ext_gfx.c is leak- and UB-clean over the gfx corpus" \
+             "(${AG_PASSED:-?} checks, controls included)"
+        echo "$AG_OUTPUT" | grep -m1 "NOTE:" || true
+    fi
+else
+    FAIL=$((FAIL + 1))
+    echo "  FAIL: a leak or sanitizer error in the gfx corpus, or the gate's own"
+    echo "        leak controls did not fire"
+    echo "$AG_OUTPUT" | grep -E "FAIL:|SUMMARY|runtime error:" | head -8 | sed 's/^/    /'
+fi
+echo ""
+
+# [138] gfx PIXEL differential (#1007 round 2), --no-baseline half.
+# [99s] compares the RETURNED VALUE of a probe. Every drawing builtin returns
+# null on every path and every gfx probe there runs with no window open, so for
+# the whole drawing surface its "identical-when-off" line was measured in the
+# one state where it could not fail. A blind review found the consequence by
+# hand: a wrong-typed OPTIONAL scale changed what gfx_text painted, and nothing
+# in the change could see it. This section runs the readback oracle that can.
+# The two-binary identity half is a pre-landing step (it needs a `make gfx`
+# build of the parent); what runs here is the rest — every wrong-typed slot
+# still raises from its own guard, every VALID call is untouched by strict, no
+# valid row has decayed into drawing nothing, and the row set still covers
+# every guarded renderer builtin and every gfx_nums slot boundary derived from
+# src/ext_gfx.c.
+echo "[138] gfx pixel differential (#1007, no-baseline half)"
+GPD_OUTPUT=$(bash "$TESTS_DIR/../tools/gfx_pixel_differential.sh" --no-baseline 2>&1); GPD_RC=$?
+if echo "$GPD_OUTPUT" | grep -q "^SKIP:"; then
+    echo "  $(echo "$GPD_OUTPUT" | grep '^SKIP:' | head -1)"
+else
+    TOTAL=$((TOTAL + 1))
+    if [ "$GPD_RC" = 0 ]; then
+        PASS=$((PASS + 1))
+        echo "  PASS: $(echo "$GPD_OUTPUT" | grep -E '^  rows=' | head -1)"
+        echo "        $(echo "$GPD_OUTPUT" | grep -E '^  raises-under-strict' | head -1 | sed 's/^ *//')"
+    else
+        FAIL=$((FAIL + 1))
+        echo "  FAIL: a wrong-typed slot went silent, a valid call changed under"
+        echo "        strict, a row stopped drawing, or a guarded slot has no row"
+        echo "$GPD_OUTPUT" | sed -n '1,16p'
+    fi
+fi
+echo ""
+
+# [139] ext_gfx container-shape sweep (#1007 round 3). The gate that replaces
+# a hand-written probe row per bug. #1007 landed three times, and each time a
+# blind review found one more builtin silent under strict on the SAME axis --
+# the argument CONTAINER (its arity and type) rather than its elements: the
+# generators' short list, then the three audio *_open builtins' short/non-list
+# argument (which answered a REAL DEVICE ID at the 44100/1 defaults), then
+# audio_play/audio_stream_push's non-list samples. [133] and [99s] were green
+# through all three, because every row in them held the arity right and varied
+# only the element type -- the question was asked in the one state where it
+# could not fail. This section derives the guarded names AND their required
+# arity from src/ext_gfx.c and crosses each with the container shapes, so the
+# population grows with the file instead of with the bug reports. Its
+# allowlist of deliberately-quiet pairs is staleness-checked: a pair that
+# starts raising fails the section. Not probe-gated on the binary here -- the
+# tool skips cleanly by itself when the build has no EXT_GFX.
+echo "[139] ext_gfx container-shape sweep (#1007)"
+GSS_SELF=$(bash "$TESTS_DIR/../tools/gfx_strict_sweep.sh" --selftest 2>&1); GSS_SELF_RC=$?
+GSS_OUTPUT=$(bash "$TESTS_DIR/../tools/gfx_strict_sweep.sh" 2>&1); GSS_RC=$?
+# BOTH halves must have skipped, not just the sweep: --selftest returns before
+# the sweep's own probe, so a lane with no gfx builtins has to be recognised
+# twice or the section reports a red selftest for a surface that is not there.
+if echo "$GSS_OUTPUT" | grep -q "^  SKIP:" && echo "$GSS_SELF" | grep -q "^  SKIP:"; then
+    echo "  $(echo "$GSS_OUTPUT" | grep '^  SKIP:' | head -1 | sed 's/^ *//')"
+else
+    TOTAL=$((TOTAL + 2))
+    GSS_SELF_FAILED=$(echo "$GSS_SELF" | sed -n 's/^selftest: [0-9]* passed, \([0-9]*\) failed.*/\1/p' | tail -1)
+    if [ "$GSS_SELF_RC" = 0 ] && [ "${GSS_SELF_FAILED:-1}" = "0" ]; then
+        PASS=$((PASS + 1))
+        echo "  PASS: $(echo "$GSS_SELF" | grep '^selftest:' | head -1) (arity parser, short-list builder, population, verdict classifier)"
+    else
+        FAIL=$((FAIL + 1))
+        echo "  FAIL: the sweep's own selftest is red — its verdicts mean nothing"
+        echo "$GSS_SELF" | grep '  FAIL' | head -4 | sed 's/^/    /'
+    fi
+    if [ "$GSS_RC" = 0 ]; then
+        PASS=$((PASS + 1))
+        echo "  PASS: $(echo "$GSS_OUTPUT" | grep -E '^  guarded names=' | head -1 | sed 's/^ *//')"
+        echo "        $(echo "$GSS_OUTPUT" | grep -E '^  raises-under-strict' | head -1 | sed 's/^ *//')"
+    else
+        FAIL=$((FAIL + 1))
+        echo "  FAIL: a guarded builtin is silent under strict for a wrong-shaped"
+        echo "        argument container, an allowlist entry has gone stale, or a"
+        echo "        probe never ran (did-not-run is not a guard verdict — #988)"
+        echo "$GSS_OUTPUT" | sed -n '1,16p'
+    fi
+fi
+echo ""
+
 # [132] UI containment render-decode oracle (#823/#859 — probe-gated:
 # needs a gfx build). The stubbed [63] suite proves containment and the
 # overlay z-order on RECORDED clip/draw state; this section proves them on
diff --git a/tests/test_asan_gfx.sh b/tests/test_asan_gfx.sh
new file mode 100755
index 00000000..ea197fe1
--- /dev/null
+++ b/tests/test_asan_gfx.sh
@@ -0,0 +1,235 @@
+#!/bin/bash
+# ext_gfx.c under AddressSanitizer + LeakSanitizer, over a gfx corpus (#1007).
+#
+# WHY THIS EXISTS. `make asan` compiles ext_gfx.c out entirely, so until
+# `make asan-gfx` landed (#1018) NO sanitizer build anywhere -- local or CI --
+# ever instrumented the file that every app in the fleet (DMG, dynamics, eddy,
+# eigen-edit, eigen-sheet, DeslanStudio) and all 18 lib/ui modules run on.
+# #1018 shipped the TARGET; it was not wired into any suite section or
+# workflow, so it was a tool nobody ran. This is the gate half.
+#
+# WHAT THE TRIAGE FOUND, recorded here rather than in a commit message
+# nobody re-reads: the corpus surfaced ONE leak, 584 bytes in 6 allocations,
+# and it was OURS, not SDL's -- builtin_gfx_poll allocates its event dict
+# before the switch and returned without releasing it on the two paths that
+# decode nothing (a non-resize SDL_WINDOWEVENT, and any event type it has no
+# case for). Fixed in ext_gfx.c. NO LeakSanitizer suppression file is
+# shipped, because after that fix the corpus reports nothing to suppress --
+# a suppression added "for SDL" with no leak behind it is a waiver for a
+# claim nobody checked.
+#
+# THE POSITIVE CONTROL IS THE POINT. "No leaks reported" is also what a
+# binary built WITHOUT the sanitizer says, and what a harness that greps the
+# wrong stream says. So a deliberately-leaking C program is compiled with the
+# same flags and judged by THE SAME predicate the corpus is judged by
+# (leak_reported), and it must come back REPORTED; a matching non-leaking one
+# must come back CLEAN. If either control is wrong the section fails without
+# looking at the corpus at all, because a corpus verdict from a blind
+# instrument is not evidence.
+#
+# SKIPS CLEANLY when the toolchain has no ASan, when the source list cannot
+# be derived, or when the binary it ends up with has no gfx builtins. libSDL2
+# is NOT required: it is dlopen'd, so the corpus runs either way -- gfx_open
+# answers 0 and the drawing calls no-op, which still walks every allocation
+# path on the argument side. Whether SDL was present is reported, so a green
+# line is not read as more coverage than the environment gave.
+#
+# Run by hand:  cd src && bash ../tests/test_asan_gfx.sh
+set -u
+TESTS_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$TESTS_DIR/.." && pwd)"
+CORPUS="$TESTS_DIR/gfx_asan_corpus"
+
+PASS=0; FAIL=0
+ok()   { echo "  PASS: $1"; PASS=$((PASS+1)); }
+bad()  { echo "  FAIL: $1"; FAIL=$((FAIL+1)); }
+skip() { echo "  SKIP: $1"; echo "ASan gfx: 0 passed, 0 failed (skipped)"; exit 0; }
+
+# A bound in pure shell. Coreutils' `timeout` is absent on the macOS runners,
+# and a child that calls it bare dies rc 127 there (test-suite rule).
+TMO=""
+if command -v timeout >/dev/null 2>&1; then TMO="timeout 120"
+elif command -v gtimeout >/dev/null 2>&1; then TMO="gtimeout 120"; fi
+
+# The -Werror trio is spelled out on every gcc line below rather than folded
+# into a variable: tools/werror_switch_check.sh reads the line, not the
+# expansion, and this script is enrolled in its SCRIPT_AUDITS with a floor of
+# four compile invocations.
+ASAN_CFLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer -g -O1"
+if ! echo 'int main(void){return 0;}' | gcc -Werror=switch -Werror=comment -Werror=misleading-indentation $ASAN_CFLAGS -x c - -o /tmp/eigs_asan_gfx_probe 2>/dev/null; then
+    rm -f /tmp/eigs_asan_gfx_probe
+    skip "AddressSanitizer not available in this toolchain"
+fi
+rm -f /tmp/eigs_asan_gfx_probe
+
+export ASAN_OPTIONS="detect_leaks=1:abort_on_error=0"
+export SDL_VIDEODRIVER="${SDL_VIDEODRIVER:-dummy}"
+export SDL_AUDIODRIVER="${SDL_AUDIODRIVER:-dummy}"
+
+# ---------------------------------------------------------------- the binary
+# Prefer an artifact `make asan-gfx` already produced, but ONLY when it is
+# newer than every source it was built from. A stale prebuilt is the vacuity
+# hazard here: the section would report on code that is no longer in the tree
+# and read exactly like a pass.
+BIN=""
+if [ -n "${EIGS_ASAN_GFX:-}" ] && [ -x "${EIGS_ASAN_GFX}" ]; then
+    BIN="$EIGS_ASAN_GFX"
+    echo "  using EIGS_ASAN_GFX=$BIN"
+elif [ -x "$ROOT/build/asan-gfx/eigenscript" ] \
+     && [ -z "$(find "$ROOT/src" -name '*.c' -newer "$ROOT/build/asan-gfx/eigenscript" -print -quit 2>/dev/null)" ] \
+     && [ -z "$(find "$ROOT/src" -name '*.h' -newer "$ROOT/build/asan-gfx/eigenscript" -print -quit 2>/dev/null)" ]; then
+    BIN="$ROOT/build/asan-gfx/eigenscript"
+    echo "  using build/asan-gfx/eigenscript (newer than every src/*.c and src/*.h)"
+else
+    # Build our own, into /tmp. Deliberately NOT `make asan-gfx`: the runner
+    # re-points src/eigenscript per variant and its #681 fingerprint guard
+    # fails the suite when the alias moves mid-run. Sources come from the
+    # Makefile's own variable so a hand-copied list cannot drift (#223).
+    SRCS=$(make -C "$ROOT" -s print-SRC_V_asan-gfx 2>/dev/null)
+    [ -n "$SRCS" ] || skip "could not read SRC_V_asan-gfx from the Makefile"
+    ( cd "$ROOT" && gcc -Werror=switch -Werror=comment -Werror=misleading-indentation $ASAN_CFLAGS \
+        -DEIGENSCRIPT_EXT_HTTP=0 -DEIGENSCRIPT_EXT_MODEL=0 -DEIGENSCRIPT_EXT_DB=0 \
+        -DEIGENSCRIPT_EXT_GFX=1 '-DEIGENSCRIPT_VERSION="asan_gfx_gate"' \
+        $SRCS -o /tmp/eigs_asan_gfx -lm -lpthread -ldl ) 2>/tmp/eigs_asan_gfx.log \
+        || skip "asan-gfx build failed (see /tmp/eigs_asan_gfx.log)"
+    BIN=/tmp/eigs_asan_gfx
+    echo "  built /tmp/eigs_asan_gfx from SRC_V_asan-gfx"
+fi
+
+# ---------------------------------------------------------------- predicate
+# ONE predicate, used by the corpus rows AND by the controls. Two copies of
+# this decision is how a guard goes green while the production path regresses.
+LAST_OUT=""
+leak_reported() {   # <cmd...> -> 0 when a leak WAS reported
+    LAST_OUT="$($TMO "$@" 2>&1)"
+    printf '%s' "$LAST_OUT" | grep -q "LeakSanitizer: detected memory leaks"
+}
+
+# ------------------------------------------------------------- the controls
+# The instrument is validated BEFORE any corpus verdict is believed.
+CTRL_OK=1
+
+# (0) The BINARY under test is an AddressSanitizer build. Decisive about
+#     $BIN specifically, which the two program controls below are not: they
+#     prove the toolchain and the predicate, not which binary was picked.
+if command -v nm >/dev/null 2>&1 && nm -D "$BIN" 2>/dev/null | grep -q __asan; then
+    ok "the binary under test links AddressSanitizer (__asan* present)"
+elif strings "$BIN" 2>/dev/null | grep -q "AddressSanitizer"; then
+    ok "the binary under test links AddressSanitizer (banner string present)"
+else
+    bad "the binary at $BIN carries no AddressSanitizer symbols — a clean corpus below would mean nothing"
+    CTRL_OK=0
+fi
+
+cat > /tmp/eigs_asan_gfx_leak.c <<'CEOF'
+#include <stdlib.h>
+/* Hidden inside a heap cell that is then freed, so the inner block is
+ * unreachable from every root LeakSanitizer scans. -O0 on purpose: at -O1
+ * the pointer survives in a register, LSan is reachability-based, and the
+ * "leak" is not reported — measured, and it made the control read as
+ * "LeakSanitizer is not armed" on a toolchain where it plainly was. */
+int main(void) {
+    void **cell = (void **)malloc(sizeof(void *));
+    if (!cell) return 1;
+    *cell = malloc(1234);
+    free(cell);
+    return 0;
+}
+CEOF
+cat > /tmp/eigs_asan_gfx_clean.c <<'CEOF'
+#include <stdlib.h>
+int main(void) {
+    void **cell = (void **)malloc(sizeof(void *));
+    if (!cell) return 1;
+    *cell = malloc(1234);
+    free(*cell);
+    free(cell);
+    return 0;
+}
+CEOF
+CTRL_CFLAGS="-fsanitize=address -fno-omit-frame-pointer -g -O0"
+if gcc -Werror=switch -Werror=comment -Werror=misleading-indentation $CTRL_CFLAGS /tmp/eigs_asan_gfx_leak.c  -o /tmp/eigs_asan_gfx_leak  2>/dev/null \
+&& gcc -Werror=switch -Werror=comment -Werror=misleading-indentation $CTRL_CFLAGS /tmp/eigs_asan_gfx_clean.c -o /tmp/eigs_asan_gfx_clean 2>/dev/null; then
+    if leak_reported /tmp/eigs_asan_gfx_leak; then
+        ok "positive control: a deliberate 1234-byte leak IS reported"
+    else
+        bad "positive control: a deliberate leak was NOT reported — LeakSanitizer is not armed, so every corpus row below is a blind instrument"
+        CTRL_OK=0
+    fi
+    if leak_reported /tmp/eigs_asan_gfx_clean; then
+        bad "negative control: a leak-free program was reported as leaking — the predicate is always-red and proves nothing"
+        CTRL_OK=0
+    else
+        ok "negative control: a leak-free program is clean"
+    fi
+else
+    bad "could not compile the leak controls; the corpus verdict would be unvalidated"
+    CTRL_OK=0
+fi
+rm -f /tmp/eigs_asan_gfx_leak.c /tmp/eigs_asan_gfx_clean.c \
+      /tmp/eigs_asan_gfx_leak /tmp/eigs_asan_gfx_clean
+
+if [ "$CTRL_OK" != 1 ]; then
+    echo "ASan gfx: $PASS passed, $FAIL failed"
+    exit 1
+fi
+
+# --------------------------------------------------------------- vacuity
+# The binary must actually CONTAIN the surface under test. A default build
+# answers "undefined variable" for every gfx name, and a corpus that never
+# enters ext_gfx.c reports leak-free for the uninteresting reason.
+echo 'print of (gfx_text_width of ["m", 1])' > /tmp/eigs_asan_gfx_probe.eigs
+PROBE_OUT="$($TMO "$BIN" /tmp/eigs_asan_gfx_probe.eigs 2>&1)"
+rm -f /tmp/eigs_asan_gfx_probe.eigs
+case "$PROBE_OUT" in
+    *"undefined variable"*) skip "the binary at $BIN has no gfx builtins (not an EIGENSCRIPT_EXT_GFX build)" ;;
+esac
+
+N_FILES=0
+for f in "$CORPUS"/*.eigs; do [ -f "$f" ] && N_FILES=$((N_FILES + 1)); done
+if [ "$N_FILES" -lt 5 ]; then
+    bad "corpus has $N_FILES programs (floor 5) — tests/gfx_asan_corpus/ lost ground"
+    echo "ASan gfx: $PASS passed, $FAIL failed"
+    exit 1
+fi
+
+# ---------------------------------------------------------------- the corpus
+# Each program runs in BOTH modes. The strict pass is not decoration: it is
+# the only one that walks the RAISE path of every #1007 guard, and a guard
+# that raises after allocating its answer leaks exactly there.
+for f in "$CORPUS"/*.eigs; do
+    [ -f "$f" ] || continue
+    base="$(basename "$f")"
+    for mode in plain strict; do
+        if [ "$mode" = strict ]; then
+            if EIGS_STRICT=1 leak_reported "$BIN" "$f"; then LEAK=1; else LEAK=0; fi
+        else
+            if leak_reported "$BIN" "$f"; then LEAK=1; else LEAK=0; fi
+        fi
+        # UBSan findings ride the same stream and are just as much a defect.
+        UB=0
+        printf '%s' "$LAST_OUT" | grep -q "runtime error:" && UB=1
+        printf '%s' "$LAST_OUT" | grep -q "AddressSanitizer: \(heap\|stack\|global\|attempting\)" && UB=1
+        if [ "$LEAK" = 0 ] && [ "$UB" = 0 ]; then
+            ok "$base [$mode] clean under ASan+UBSan+LSan"
+        else
+            bad "$base [$mode] leak=$LEAK sanitizer-error=$UB"
+            printf '%s\n' "$LAST_OUT" | grep -E "SUMMARY|runtime error:|ERROR: " | head -4 | sed 's/^/        /'
+        fi
+    done
+done
+
+# Say what the environment could not exercise rather than letting a green
+# line imply it did.
+echo 'o is gfx_open of [8, 8, "probe"]
+print of f"sdl-present: {o}"
+ignore is gfx_close of null' > /tmp/eigs_asan_gfx_sdl.eigs
+SDL_OUT="$($TMO "$BIN" /tmp/eigs_asan_gfx_sdl.eigs 2>&1)"
+rm -f /tmp/eigs_asan_gfx_sdl.eigs
+printf '%s' "$SDL_OUT" | grep -q "sdl-present: 1" \
+    || echo "  NOTE: libSDL2 absent — the corpus exercised the argument and"\
+            "allocation paths but no real renderer or audio device."
+
+echo "ASan gfx: $PASS passed, $FAIL failed"
+[ "$FAIL" = 0 ] || exit 1
+exit 0
diff --git a/tests/test_gfx_argtypes.eigs b/tests/test_gfx_argtypes.eigs
index 86fc13c1..cb3ab4b2 100644
--- a/tests/test_gfx_argtypes.eigs
+++ b/tests/test_gfx_argtypes.eigs
@@ -70,6 +70,127 @@ if env_get of "EIGS_STRICT" == "1":
     assert_eq of [strict_kind of ((_) => audio_sine of [440, 0.01, 0.5]), "none", "#1007 strict: a well-typed audio_sine does not raise"]
     assert_eq of [strict_kind of ((_) => audio_sweep of [100, 200, 0.01, 0.5, 0]), "none", "#1007 strict: a well-typed audio_sweep does not raise"]
     assert_eq of [strict_kind of ((_) => audio_gain of [[1.0], 0.5]), "none", "#1007 strict: a well-typed audio_gain does not raise"]
+
+    # ---- the DRAWING surface (#1007's second half) ----
+    # These are the ~52 make_null() sites: a wrong-typed or short argument
+    # was answered by silently drawing nothing (or, worse, drawing the
+    # WRONG thing off a punned pointer). None of them touch SDL before the
+    # guard, so every row below discriminates with or without libSDL2.
+    assert_eq of [strict_kind of ((_) => gfx_rect of ["10", 10, 50, 50, 255, 0, 0]), "type_mismatch", "#1007 strict: gfx_rect raises on a string x"]
+    assert_eq of [strict_kind of ((_) => gfx_rect of [0, 0, 1, 1, 255, 0, 0, "128"]), "type_mismatch", "#1007 strict: gfx_rect raises on a string OPTIONAL alpha"]
+    assert_eq of [strict_kind of ((_) => gfx_rect of [0, 0, 1, 1]), "type_mismatch", "#1007 strict: gfx_rect raises on a short argument list"]
+    assert_eq of [strict_kind of ((_) => gfx_line of ["0", 0, 10, 10, 1, 2, 3]), "type_mismatch", "#1007 strict: gfx_line raises on a string x1"]
+    assert_eq of [strict_kind of ((_) => gfx_point of ["1", 2, 3, 4, 5]), "type_mismatch", "#1007 strict: gfx_point raises on a string x"]
+    assert_eq of [strict_kind of ((_) => gfx_circle of ["1", 2, 3, 4, 5, 6]), "type_mismatch", "#1007 strict: gfx_circle raises on a string cx"]
+    assert_eq of [strict_kind of ((_) => gfx_rrect of ["1", 2, 3, 4, 5, 6, 7, 8]), "type_mismatch", "#1007 strict: gfx_rrect raises on a string x"]
+    assert_eq of [strict_kind of ((_) => gfx_clip of ["1", 2, 3, 4]), "type_mismatch", "#1007 strict: gfx_clip raises on a string x"]
+    assert_eq of [strict_kind of ((_) => gfx_clear of ["1", 2, 3]), "type_mismatch", "#1007 strict: gfx_clear raises on a string r"]
+    assert_eq of [strict_kind of ((_) => gfx_clear of "not a colour"), "type_mismatch", "#1007 strict: gfx_clear raises on an unusable shape (soft with the flag off -- it still clears to black)"]
+    assert_eq of [strict_kind of ((_) => gfx_text of [1, 2, "hi", "255", 0, 0]), "type_mismatch", "#1007 strict: gfx_text raises on a string r"]
+    assert_eq of [strict_kind of ((_) => gfx_text of [1, 2, 42, 255, 0, 0]), "type_mismatch", "#1007 strict: gfx_text raises on a non-string text (it used to draw \"\")"]
+    assert_eq of [strict_kind of ((_) => gfx_read of ["1", 1]), "type_mismatch", "#1007 strict: gfx_read raises on a string x"]
+    assert_eq of [strict_kind of ((_) => gfx_fb of [42, 4, 4, 0, 0, 1]), "type_mismatch", "#1007 strict: gfx_fb raises on a non-buffer"]
+    assert_eq of [strict_kind of ((_) => gfx_delay of "5"), "type_mismatch", "#1007 strict: gfx_delay raises on a string ms"]
+    assert_eq of [strict_kind of ((_) => gfx_title of 42), "type_mismatch", "#1007 strict: gfx_title raises on a non-string title"]
+    assert_eq of [strict_kind of ((_) => ppu_render_frame of [1, 2]), "type_mismatch", "#1007 strict: ppu_render_frame raises on non-buffers"]
+    # The COERCION shapes: no stand-in to name, so they raise under strict
+    # and do nothing otherwise.
+    assert_eq of [strict_kind of ((_) => gfx_text_width of 5), "type_mismatch", "#1007 strict: gfx_text_width raises on a non-string"]
+    assert_eq of [strict_kind of ((_) => gfx_text_width of ["hi", "2"]), "type_mismatch", "#1007 strict: gfx_text_width raises on a string scale"]
+    assert_eq of [strict_kind of ((_) => gfx_text_height of "2"), "type_mismatch", "#1007 strict: gfx_text_height raises on a string scale"]
+    assert_eq of [strict_kind of ((_) => audio_pause of "x"), "type_mismatch", "#1007 strict: audio_pause raises on a string flag"]
+    assert_eq of [strict_kind of ((_) => audio_music_volume of "loud"), "type_mismatch", "#1007 strict: audio_music_volume raises on a string volume"]
+    assert_eq of [strict_kind of ((_) => audio_mix of [["a"], [0.1]]), "type_mismatch", "#1007 strict: audio_mix raises on a non-number sample element"]
+    assert_eq of [strict_kind of ((_) => audio_gain of [["a"], 2.0]), "type_mismatch", "#1007 strict: audio_gain raises on a non-number sample element"]
+    assert_eq of [strict_kind of ((_) => audio_stop of "x"), "type_mismatch", "#1007 strict: audio_stop raises on a string channel"]
+    assert_eq of [strict_kind of ((_) => audio_volume of ["1", 1]), "type_mismatch", "#1007 strict: audio_volume raises on a string channel"]
+    assert_eq of [strict_kind of ((_) => audio_play_loop of [[0.1], "2"]), "type_mismatch", "#1007 strict: audio_play_loop raises on a string loops"]
+    assert_eq of [strict_kind of ((_) => audio_play_loop of [[0.1], 0]), "type_mismatch", "#1007 strict: audio_play_loop raises on an out-of-domain loops"]
+    assert_eq of [strict_kind of ((_) => audio_music_play of [42]), "type_mismatch", "#1007 strict: audio_music_play raises on a non-string path"]
+    # CONTROLS. Without these an over-broad guard — ARG_GUARD(1, ...), which
+    # would break the whole drawing surface — passes every row above.
+    assert_eq of [strict_kind of ((_) => gfx_rect of [0, 0, 1, 1, 255, 0, 0]), "none", "#1007 strict: a well-typed gfx_rect does not raise"]
+    assert_eq of [strict_kind of ((_) => gfx_rect of [0, 0, 1, 1, 255, 0, 0, 128]), "none", "#1007 strict: a well-typed gfx_rect with alpha does not raise"]
+    assert_eq of [strict_kind of ((_) => gfx_clear of [1, 2, 3]), "none", "#1007 strict: a well-typed gfx_clear does not raise"]
+    assert_eq of [strict_kind of ((_) => gfx_clip of null), "none", "#1007 strict: gfx_clip of null still clears the clip"]
+    assert_eq of [strict_kind of ((_) => gfx_text of [1, 2, "hi", 255, 0, 0]), "none", "#1007 strict: a well-typed gfx_text does not raise"]
+    assert_eq of [strict_kind of ((_) => gfx_text_width of ["hi", 2]), "none", "#1007 strict: a well-typed gfx_text_width does not raise"]
+    assert_eq of [strict_kind of ((_) => gfx_text_height of null), "none", "#1007 strict: gfx_text_height of null still defaults to scale 1"]
+    assert_eq of [strict_kind of ((_) => gfx_poll of null), "none", "#1007 strict: gfx_poll of null does not raise"]
+    assert_eq of [strict_kind of ((_) => audio_pause of null), "none", "#1007 strict: audio_pause of null still means pause"]
+    assert_eq of [strict_kind of ((_) => audio_mix of [[0.1], [0.2]]), "none", "#1007 strict: a well-typed audio_mix does not raise"]
+    assert_eq of [strict_kind of ((_) => audio_stop of 1), "none", "#1007 strict: a well-typed audio_stop does not raise"]
+    assert_eq of [strict_kind of ((_) => audio_play_loop of [[0.1], -1]), "none", "#1007 strict: loops == -1 is in domain"]
+    # #1007 round 2 — the ARITY/SHAPE half of the audio surface. Eight sites
+    # answered a short or non-list argument with an empty sample list, which
+    # is what a legitimately empty generation also answers, and stayed quiet
+    # under strict while docs/BUILTINS.md claimed "a short argument list ...
+    # raises". Measured against the binary by a blind review; these rows are
+    # the pin so the claim and the code cannot drift apart again.
+    assert_eq of [strict_kind of ((_) => audio_sine of [100, 0.01]), "type_mismatch", "#1007 strict: audio_sine raises on a short argument list"]
+    assert_eq of [strict_kind of ((_) => audio_saw of [100, 0.01]), "type_mismatch", "#1007 strict: audio_saw raises on a short argument list"]
+    assert_eq of [strict_kind of ((_) => audio_square of [100, 0.01]), "type_mismatch", "#1007 strict: audio_square raises on a short argument list"]
+    assert_eq of [strict_kind of ((_) => audio_sweep of [1, 2, 3]), "type_mismatch", "#1007 strict: audio_sweep raises on a short argument list"]
+    assert_eq of [strict_kind of ((_) => audio_noise of ([0.01])), "type_mismatch", "#1007 strict: audio_noise raises on a short argument list"]
+    assert_eq of [strict_kind of ((_) => audio_envelope of [([0.1]), 1, 2, 3]), "type_mismatch", "#1007 strict: audio_envelope raises on a short argument list"]
+    assert_eq of [strict_kind of ((_) => audio_mix of (["a"])), "type_mismatch", "#1007 strict: audio_mix raises on a short argument list"]
+    assert_eq of [strict_kind of ((_) => audio_gain of (["a"])), "type_mismatch", "#1007 strict: audio_gain raises on a short argument list"]
+    assert_eq of [strict_kind of ((_) => audio_mix of 42), "type_mismatch", "#1007 strict: audio_mix raises on a non-list argument"]
+    # #1007 round 3 — the SAME arity half on the three audio *_open builtins,
+    # the one place the round-2 sweep did not reach. Their element guard sits
+    # NESTED inside `if (count >= 2)`, so a SHORT or non-list argument walked
+    # past it, opened the device at the 44100/1 defaults and answered a REAL
+    # DEVICE ID: `audio_stream_open of [48000]` -> 2, silently, in both modes.
+    # That is a silent SUCCESS, not a silent no-op — the caller who asked for
+    # 48000 was told it got 48000 — and it is the sharpest shape in the issue.
+    # Found by a blind review against the binary, exactly as the generators'
+    # short-list case was; the rows below are why the same hole cannot be dug
+    # a third time.
+    assert_eq of [strict_kind of ((_) => audio_open of [44100]), "type_mismatch", "#1007 strict: audio_open raises on a short argument list"]
+    assert_eq of [strict_kind of ((_) => audio_capture_open of [44100]), "type_mismatch", "#1007 strict: audio_capture_open raises on a short argument list"]
+    assert_eq of [strict_kind of ((_) => audio_stream_open of [48000]), "type_mismatch", "#1007 strict: audio_stream_open raises on a short argument list"]
+    assert_eq of [strict_kind of ((_) => audio_open of 44100), "type_mismatch", "#1007 strict: audio_open raises on a non-list argument"]
+    assert_eq of [strict_kind of ((_) => audio_stream_open of "48000"), "type_mismatch", "#1007 strict: audio_stream_open raises on a non-list argument"]
+    # CONTROLS for those three. `of null` is the documented "use the defaults"
+    # form (BUILTINS.md), so a guard that refused it would break every caller
+    # that omits the spec while passing all five rows above. Each control opens
+    # a REAL device under the dummy driver, so each closes it again — the same
+    # discipline the audio_stream_open control above needed, for the same
+    # reason (a held device makes the later device-gated block silently skip).
+    assert_eq of [strict_kind of ((_) => audio_capture_open of null), "none", "#1007 strict: audio_capture_open of null still means the defaults"]
+    audio_capture_close of null
+    assert_eq of [strict_kind of ((_) => audio_stream_open of null), "none", "#1007 strict: audio_stream_open of null still means the defaults"]
+    audio_stream_close of null
+    assert_eq of [strict_kind of ((_) => audio_open of [44100, 1]), "none", "#1007 strict: a well-typed audio_open does not raise"]
+    audio_close of null
+    # #1007 round 3, the third instance of the same axis: the sample-list
+    # CONTAINER. A wrong-typed ELEMENT already raised inside
+    # audio_convert_samples; the line above it — `samples->type != VAL_LIST`
+    # — just returned NULL, which every caller reads as the documented
+    # "nothing to play" and answers 0. So `audio_play of ["a"]` was loud and
+    # `audio_play of 42` was silent. All three sit ABOVE the device check, so
+    # these rows discriminate with no audio device (which is where CI runs);
+    # a guard below it would exist only where nothing exercises it.
+    assert_eq of [strict_kind of ((_) => audio_play of 42), "type_mismatch", "#1007 strict: audio_play raises on a non-list samples argument"]
+    assert_eq of [strict_kind of ((_) => audio_play of "zzz"), "type_mismatch", "#1007 strict: audio_play raises on a string samples argument"]
+    assert_eq of [strict_kind of ((_) => audio_stream_push of 42), "type_mismatch", "#1007 strict: audio_stream_push raises on a non-list samples argument"]
+    # The NESTED slot, which the container sweep in tools/gfx_strict_sweep.sh
+    # deliberately does not reach: the top-level argument here is a well-formed
+    # two-element list and only slot 0 is wrong. Pinned by hand for that reason.
+    assert_eq of [strict_kind of ((_) => audio_play_loop of [42, 2]), "type_mismatch", "#1007 strict: audio_play_loop raises on a non-list samples SLOT"]
+    # CONTROLS: `of null` is "play nothing", a legitimate call, and a real
+    # sample list must stay quiet. Without them a guard that refused every
+    # argument would pass all four rows above.
+    assert_eq of [strict_kind of ((_) => audio_play of null), "none", "#1007 strict: audio_play of null still plays nothing"]
+    assert_eq of [strict_kind of ((_) => audio_stream_push of null), "none", "#1007 strict: audio_stream_push of null still pushes nothing"]
+    assert_eq of [strict_kind of ((_) => audio_play of [0.1, 0.2]), "none", "#1007 strict: a well-typed audio_play does not raise"]
+    assert_eq of [strict_kind of ((_) => audio_play_loop of [([0.1, 0.2]), 2]), "none", "#1007 strict: a well-typed audio_play_loop does not raise"]
+    # The optional trailing slot of gfx_text. Its wrong-typed scale was an
+    # unchecked `items[6]->data.num` read on the parent, so it is refused —
+    # and the refusal is loud here. The plain-mode half of the same rule is
+    # the pixel row below.
+    assert_eq of [strict_kind of ((_) => gfx_text of [0, 0, "H", 255, 255, 255, "2"]), "type_mismatch", "#1007 strict: gfx_text raises on a wrong-typed optional scale"]
+    assert_eq of [strict_kind of ((_) => gfx_text of [0, 0, "H", 255, 255, 255, 2]), "none", "#1007 strict: a well-typed gfx_text scale does not raise"]
     print of "strict-pass: 1"
 else:
     assert_eq of [gfx_open of ["800", "600", "t"], 0, "#1007: string w/h no longer opens a window"]
@@ -80,6 +201,18 @@ else:
     # 44100/1 defaults, answering a real device id to a caller that asked for
     # something else.
     assert_eq of [audio_stream_open of ["44100", "1"], 0, "#1007: string freq/channels no longer opens a stream device at defaults"]
+    # #1007 round 3, the plain half of the openers' ARITY axis. STRICT_REQUIRE
+    # cannot change non-strict behaviour BY CONSTRUCTION — it is a no-op when
+    # the flag is off — so the pin here is a RELATIVE one, and it is what
+    # would notice if someone "upgraded" that guard to an ARG_GUARD and
+    # started answering 0 to a short list. A short list must keep behaving
+    # exactly like the documented `of null` defaults form. Each open takes the
+    # single dummy device, so each is closed before the next.
+    short_dev is audio_stream_open of [48000]
+    audio_stream_close of null
+    null_dev is audio_stream_open of null
+    audio_stream_close of null
+    assert_eq of [short_dev, null_dev, "#1007: flag off, a short audio_stream_open still opens at the defaults exactly as `of null` does"]
     # CONTROL. Those three answer 0 for a wrong-typed argument — and 0 is also
     # the no-SDL answer, so on a machine without libSDL2 they pass on the
     # UNFIXED binary too. This row records which of the two worlds the run is
@@ -103,13 +236,98 @@ else:
     # names. Its sample elements were already type-checked; the volume beside
     # them was not.
     assert_eq of [len of (audio_gain of [[1.0], "2.0"]), 0, "#1007: audio_gain refuses a string volume"]
+    # #1007 round 2, the arity/shape half with the flag OFF: the empty list is
+    # still the stand-in, so the default path is byte-identical to before the
+    # guards. Only the flag makes these loud (rows in the strict pass above).
+    assert_eq of [len of (audio_sine of [100, 0.01]), 0, "#1007: a short audio_sine argument list still answers an empty list"]
+    assert_eq of [len of (audio_saw of [100, 0.01]), 0, "#1007: a short audio_saw argument list still answers an empty list"]
+    assert_eq of [len of (audio_square of [100, 0.01]), 0, "#1007: a short audio_square argument list still answers an empty list"]
+    assert_eq of [len of (audio_sweep of [1, 2, 3]), 0, "#1007: a short audio_sweep argument list still answers an empty list"]
+    assert_eq of [len of (audio_noise of ([0.01])), 0, "#1007: a short audio_noise argument list still answers an empty list"]
+    assert_eq of [len of (audio_envelope of [([0.1]), 1, 2, 3]), 0, "#1007: a short audio_envelope argument list still answers an empty list"]
+    assert_eq of [len of (audio_mix of (["a"])), 0, "#1007: a short audio_mix argument list still answers an empty list"]
+    assert_eq of [len of (audio_gain of (["a"])), 0, "#1007: a short audio_gain argument list still answers an empty list"]
+    assert_eq of [len of (audio_mix of 42), 0, "#1007: a non-list audio_mix argument still answers an empty list"]
     # Controls: a well-typed call must still produce samples, or the guards
     # above are over-broad and every row in this block passes for free.
     assert_true of [(len of (audio_sine of [440, 0.01, 0.5])) > 0, "#1007: a well-typed audio_sine still generates"]
     assert_true of [(len of (audio_sweep of [100, 200, 0.01, 0.5, 0])) > 0, "#1007: a well-typed audio_sweep still generates"]
     assert_true of [(len of (audio_envelope of [[0.1, 0.2], 0.01, 0.01, 0.5, 0.01])) > 0, "#1007: a well-typed audio_envelope still generates"]
     assert_eq of [(audio_gain of [[1.0], 0.5])[0], 0.5, "#1007: a well-typed audio_gain still scales"]
-    print of ("sdl-present: " + (str of (gfx_open of [80, 60, "eigs #1007 control"])))
+    # The drawing surface with the flag OFF: the ANSWER is unchanged (null
+    # on every path, exactly as before), which is what makes the default
+    # path byte-identical. What changed is that the punned read is gone.
+    assert_eq of [gfx_rect of ["10", 10, 50, 50, 255, 0, 0], null, "#1007: a rejected gfx_rect still answers null"]
+    assert_eq of [gfx_text_width of 5, 0, "#1007: gfx_text_width of a non-string still answers 0"]
+    assert_eq of [gfx_text_width of ["hi", "2"], (gfx_text_width of ["hi", 1]), "#1007: a wrong-typed scale still measures at scale 1 (coercion, not a stand-in)"]
+    assert_eq of [gfx_text_height of "2", (gfx_text_height of 1), "#1007: a wrong-typed height scale still answers scale 1"]
+    assert_eq of [len of (audio_mix of [["a"], [0.1]]), 1, "#1007: audio_mix still coerces the element with the flag off"]
+
+    sdl_open is gfx_open of [80, 60, "eigs #1007 control"]
+    print of ("sdl-present: " + (str of sdl_open))
+    # THE PIXEL PROOF, and the only row here that can see the defect the
+    # issue is about. Pre-fix, `gfx_rect of [..., "255", 0, 0]` reinterpreted
+    # the string's `char *` as a double, `(int)`-cast it to 0, and painted a
+    # BLACK rectangle over the cleared colour — a wrong drawing, not a
+    # missing one, and silent in both modes. Post-fix the call is refused
+    # before the read, so the cleared colour survives. Needs a real renderer,
+    # so it is gated and says when it did not run.
+    if sdl_open == 1:
+        ignore is gfx_clear of [7, 8, 9]
+        ignore is gfx_rect of [0, 0, 32, 32, "255", 0, 0]
+        px is gfx_read of [4, 4]
+        assert_eq of [px[0], 7, "#1007: a wrong-typed colour no longer paints black over the cleared pixel"]
+        assert_eq of [px[1], 8, "#1007: ...green channel unchanged too"]
+        # CONTROL: a well-typed rect at the same spot MUST still paint, or
+        # the row above passes because nothing draws at all any more.
+        ignore is gfx_rect of [0, 0, 32, 32, 255, 0, 0]
+        px2 is gfx_read of [4, 4]
+        assert_eq of [px2[0], 255, "#1007 control: a well-typed gfx_rect still paints"]
+        # THE EXEMPTION, pinned. gfx_clear's wrong-SHAPE branch is deliberately
+        # a coercion, not a refusal: an unusable argument fell through to
+        # r = g = b = 0 and the buffer WAS cleared, to black. Refusing to clear
+        # would be a default-path behaviour change, so it stays soft and only
+        # the flag makes it loud. Without this row the exemption is a sentence
+        # in a comment that nothing executes.
+        ignore is gfx_clear of "not a colour"
+        px3 is gfx_read of [4, 4]
+        assert_eq of [px3[0], 0, "#1007: a wrong-shaped gfx_clear still clears to black with the flag off"]
+        # #1007 round 2 — THE ASYMMETRY BETWEEN THE THREE TEXT BUILTINS,
+        # pinned so it reads as a decision and not an accident.
+        # gfx_text_width / gfx_text_height type-checked their scale slot
+        # BEFORE this issue, so a wrong-typed scale there is a COERCION and
+        # still measures at scale 1 (asserted above). gfx_text did NOT:
+        # on the parent commit its read is
+        #     int scale = (count >= 7) ? (int)items[6]->data.num : 1;
+        # with no type test, so a string scale reinterpreted a `char *` as a
+        # double — which truncates to 0 and is then clamped to 1, making the
+        # glyph LOOK correct while being drawn from a pointer. That is the
+        # unchecked-read class, so the call is refused rather than defaulted.
+        # A blind review read the CHECKED shape (gfx_text_width's items[1])
+        # as gfx_text's and called the refusal a plain-mode regression; this
+        # row records which shape each builtin actually had, in pixels.
+        ignore is gfx_clear of [0, 0, 0]
+        ignore is gfx_text of [0, 0, "H", 255, 255, 255, "2"]
+        lit_bad is 0
+        for ty in range of 16:
+            for tx in range of 16:
+                cb is gfx_read of [tx, ty]
+                if cb[0] > 100:
+                    lit_bad is lit_bad + 1
+        assert_eq of [lit_bad, 0, "#1007: a wrong-typed gfx_text scale is refused (an unchecked read, not a coercion)"]
+        # CONTROL: the same call with a well-typed scale must still draw, or
+        # the row above passes because gfx_text draws nothing at all any more.
+        ignore is gfx_text of [0, 0, "H", 255, 255, 255, 2]
+        lit_ok is 0
+        for ty in range of 16:
+            for tx in range of 16:
+                cg is gfx_read of [tx, ty]
+                if cg[0] > 100:
+                    lit_ok is lit_ok + 1
+        assert_true of [lit_ok > 0, "#1007 control: a well-typed gfx_text scale still draws"]
+        print of "pixel-proof: 1"
+    else:
+        print of "pixel-proof: 0"
     print of "strict-pass: 0"
 
 # ---- the sample-element coercion, when a device is actually available ----
diff --git a/tools/failsoft_classify_check.sh b/tools/failsoft_classify_check.sh
index 6d73b59b..bbf8203f 100755
--- a/tools/failsoft_classify_check.sh
+++ b/tools/failsoft_classify_check.sh
@@ -35,6 +35,36 @@
 # the documented answer; what is missing is any way to distinguish it from a
 # rejected argument. That needs a decision on this issue, not a wider matcher.
 #
+# THE make_null() POPULATION IS SCOPED TO ONE FILE, ON PURPOSE (#1007).
+# `return make_null()` is a soft stand-in too — the drawing half of
+# ext_gfx.c answered a wrong-typed argument by silently drawing nothing —
+# but it is ALSO the correct answer almost everywhere else: a store_get
+# miss, a dict_get miss, an absent optional. Measured across the surface
+# before deciding:
+#
+#   src/builtins.c         247      src/ext_gfx.c    52
+#   src/builtins_tensor.c   51      src/ext_http.c   26
+#   src/builtins_host.c     42      src/ext_store.c  25
+#   src/ext_net.c           12      src/ext_db.c      1     TOTAL 456
+#
+# (Measured on the pre-#744 tree. #744 later split builtins_buf.c out of
+# builtins.c and #973/#1093 grew the tensor file, so `--residuals` now
+# reports the same population under different file names and a larger
+# total. The decision is about SCOPE, not about the exact count, and
+# `--residuals` is the live number.)
+#
+# Widening to all 456 would demand hundreds of hand annotations on code
+# that is already right — the cry-wolf failure, after which a gate gets
+# routed around and protects nothing. So the widening is SCOPED BY FILE to
+# the one surface where "a wrong-typed argument silently draws nothing" is
+# a coherent defect class with a single verdict, and the other 404 sites
+# are left out with this written reason rather than by omission. The scope
+# is one list, NULL_SCOPE below; adding a file to it is a review event and
+# means committing to classify every make_null() in it.
+#
+#   fs:VOID     the builtin ANSWERS null by contract (a drawing or other
+#               side-effect call whose every path returns null); this is
+#               the return value, not a stand-in for a rejected argument
 #   fs:ANSWER   the 0/"" is the documented result; strict must NOT raise
 #   fs:CHANNEL  failure is signalled out-of-band (a flag, an out-param)
 #   fs:LITERAL  not a guard — this IS the value being constructed
@@ -48,11 +78,16 @@
 # WHAT THIS GATE DOES NOT COVER (every exemption is a waiver, so it is
 # written here rather than left to be rediscovered):
 #
-#   - Soft stand-ins that are not zero/empty/-1: `return make_null()`,
-#     `return make_list()`. Those are a different population and are NOT
-#     enumerated here. Counted and reported as a residual by --residuals so
-#     the number is visible rather than implied. (The `-1` sentinel WAS in
-#     this list until #1008 moved it into the population; see below.)
+#   - `return make_null()` OUTSIDE the NULL_SCOPE file list, and
+#     `return make_list(0)` everywhere. Those are a different population and
+#     are NOT enumerated here. Both are counted by --residuals so the number
+#     is visible rather than implied — and a NULL_SCOPE file is printed there
+#     as IN the population, never as a residual, because listing a gated file
+#     as residual is how the two halves came to contradict each other. (The `-1`
+#     sentinel WAS in this list until #1008 moved it into the population,
+#     and `make_null()` in ext_gfx.c until #1007 scoped it in; both are
+#     instances of the header's own rule that WIDENING THE POPULATION CAN
+#     FALSIFY AN EXEMPTION WRITTEN FOR THE NARROWER ONE.)
 #   - A soft return reached through a HELPER (`return zero_value();`) or
 #     built by an expression (`return make_num(ok ? n : -1);`). This gate is
 #     a text matcher, not a call graph, so it is blind to both by
@@ -99,7 +134,14 @@ set -uo pipefail
 
 SELF_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 
-VALID_TAGS='ANSWER|CHANNEL|LITERAL|EMPTY|STRICT|TODO'
+VALID_TAGS='ANSWER|CHANNEL|LITERAL|EMPTY|STRICT|TODO|VOID'
+
+# Files whose `return make_null()` sites are IN the population (#1007). See
+# the scope paragraph in the header: this is a decision, not an oversight,
+# and the reason is recorded there rather than here so it cannot be edited
+# away without reading it. Paths are repo-relative, exactly as the file
+# derivation emits them.
+NULL_SCOPE='src/ext_gfx.c'
 
 # The population floor. Sites leave this population legitimately (a guard
 # converted to ARG_GUARD, a builtin deleted), so this is not pinned upward
@@ -120,7 +162,17 @@ VALID_TAGS='ANSWER|CHANNEL|LITERAL|EMPTY|STRICT|TODO'
 # population for the first time (sha256/md5/hmac_sha256 all have one), with
 # 8 sites that had never been classified. A floor rising because the
 # derivation got wider is the good direction; note it either way.
-FLOOR_SITES=136
+#
+# 136 -> 174 on 2026-09-07 (#1007), and again because the derivation got
+# wider, not because sites were added: `return make_null()` entered the
+# population for src/ext_gfx.c only (see NULL_SCOPE and the scope paragraph
+# in the header). 38 previously invisible sites appeared there, every one of
+# them read and classified, and all 136 previously-classified sites were
+# still found — the monotonicity check this header demands of any widening.
+# ext_gfx.c's four fs:TODO #971 deferrals were converted to ARG_GUARD in the
+# same change and left the population entirely, which is why the net is +38
+# rather than +42.
+FLOOR_SITES=174
 
 usage_mode="${1:-}"
 
@@ -185,8 +237,8 @@ builtin_files() {
 # statement is split, which is reported separately: it is matched correctly
 # here, but it must be reformatted so the MARKER-context window (the return
 # line and the two above it) is meaningful.
-norm_hits() {   # <file> -> "startline\tnlines\tctxstart"
-    awk '
+norm_hits() {   # <file> <wide-null:0|1> -> "startline\tnlines\tctxstart"
+    awk -v wide_null="${2:-0}" '
     # Comments are stripped with real block-comment state AND real STRING
     # state. Two failures bought each half:
     #
@@ -244,7 +296,8 @@ norm_hits() {   # <file> -> "startline\tnlines\tctxstart"
         if (sn ~ /^return/ && index(sn, ";") == 0) { pending = 1; next }
         pending = 0
         if (sn == "") next
-        if (sn ~ /returnmake_num\(0(\.0*)?\);/ || sn ~ /returnmake_str\(""\);/ || sn ~ /returnmake_num\(-1(\.0*)?\);/) {
+        if (sn ~ /returnmake_num\(0(\.0*)?\);/ || sn ~ /returnmake_str\(""\);/ || sn ~ /returnmake_num\(-1(\.0*)?\);/ ||
+            (wide_null == 1 && sn ~ /returnmake_null\(\);/)) {
             ctx = (crun_end == start - 1) ? crun_start : start
             printf "%d\t%d\t%d\n", start, NR - start + 1, ctx
         }
@@ -263,7 +316,7 @@ run_check() {   # <root>  -> 0 clean / 1 finding ; prints a summary
     # ships bash 3.2, where `declare -A` is a syntax error and `tally[$tag]`
     # with a string key is parsed as arithmetic on an unbound name (release
     # build failed here — the [99p] child-exit ledger surfaced it).
-    local t_ANSWER=0 t_CHANNEL=0 t_LITERAL=0 t_EMPTY=0 t_STRICT=0 t_TODO=0
+    local t_ANSWER=0 t_CHANNEL=0 t_LITERAL=0 t_EMPTY=0 t_STRICT=0 t_TODO=0 t_VOID=0
     local c
     for c in $covered; do
         if ! grep -qxF "$c" <<<"$compiled"; then
@@ -275,6 +328,10 @@ run_check() {   # <root>  -> 0 clean / 1 finding ; prints a summary
     for f in $covered; do
         n_files=$((n_files + 1))
         local ln nl ctx tag
+        # #1007: `return make_null()` is in the population only for the files
+        # named in NULL_SCOPE. See the scope paragraph in the header.
+        local wide=0
+        case " $NULL_SCOPE " in *" $f "*) wide=1 ;; esac
         while read -r ln nl ctxstart; do
             [ -z "$ln" ] && continue
             n_hits=$((n_hits + 1))
@@ -313,9 +370,10 @@ run_check() {   # <root>  -> 0 clean / 1 finding ; prints a summary
                 EMPTY)   t_EMPTY=$((t_EMPTY + 1)) ;;
                 STRICT)  t_STRICT=$((t_STRICT + 1)) ;;
                 TODO)    t_TODO=$((t_TODO + 1)) ;;
+                VOID)    t_VOID=$((t_VOID + 1)) ;;
             esac
             [ "$usage_mode" = "--verbose" ] && printf '  %-8s %s:%s\n' "$tag" "$f" "$ln"
-        done < <(norm_hits "$root/$f")
+        done < <(norm_hits "$root/$f" "$wide")
     done
 
     # Vacuity. A gate that examined nothing prints OK — the single most
@@ -336,7 +394,7 @@ run_check() {   # <root>  -> 0 clean / 1 finding ; prints a summary
     printf '  files=%d sites=%d classified=%d unclassified=%d floor=%d\n' \
         "$n_files" "$n_hits" "$n_tagged" "$n_bad" "$FLOOR_SITES"
     local t c out=""
-    for t in ANSWER CHANNEL LITERAL EMPTY STRICT TODO; do
+    for t in ANSWER CHANNEL LITERAL EMPTY STRICT TODO VOID; do
         case "$t" in
             ANSWER)  c=$t_ANSWER ;;
             CHANNEL) c=$t_CHANNEL ;;
@@ -344,6 +402,7 @@ run_check() {   # <root>  -> 0 clean / 1 finding ; prints a summary
             EMPTY)   c=$t_EMPTY ;;
             STRICT)  c=$t_STRICT ;;
             TODO)    c=$t_TODO ;;
+            VOID)    c=$t_VOID ;;
         esac
         out="$out $t=$c"
     done
@@ -356,10 +415,30 @@ run_check() {   # <root>  -> 0 clean / 1 finding ; prints a summary
 # --------------------------------------------------------------- residuals
 if [ "$usage_mode" = "--residuals" ]; then
     echo "== fail-soft residual population (NOT gated) =="
+    # RESIDUAL MEANS OUTSIDE THE POPULATION, and the population MOVES. #1007
+    # scoped ext_gfx.c's `make_null()` sites IN (they are classified, tagged
+    # and gated), so listing them here as residual double-counted them and
+    # told a reader the opposite of what the gate does — reported by a blind
+    # review as "self-contradictory". The scope list is the single source of
+    # truth for both halves: a file named in NULL_SCOPE is gated, never
+    # residual. (Same for `make_list()`: it was named as residual in the
+    # header while nothing counted it, so the header promised a number that
+    # did not exist. Both halves are printed now.)
     for f in $(builtin_files "$SELF_ROOT"); do
+        gated=0
+        case " $NULL_SCOPE " in *" $f "*) gated=1 ;; esac
+        if [ "$gated" = 1 ]; then
+            n=$(awk '{s=$0; gsub(/[ \t]+/,"",s); if (s ~ /returnmake_null\(\);/) c++} END{print c+0}' "$SELF_ROOT/$f")
+            [ "$n" != 0 ] && printf '  %-26s return make_null(): %s  IN THE POPULATION (NULL_SCOPE) — gated, not residual\n' "$f" "$n"
+            continue
+        fi
         n=$(awk '{s=$0; gsub(/[ \t]+/,"",s); if (s ~ /returnmake_null\(\);/) c++} END{print c+0}' "$SELF_ROOT/$f")
         [ "$n" != 0 ] && printf '  %-26s return make_null(): %s\n' "$f" "$n"
     done
+    for f in $(builtin_files "$SELF_ROOT"); do
+        n=$(awk '{s=$0; gsub(/[ \t]+/,"",s); if (s ~ /returnmake_list\(0\);/) c++} END{print c+0}' "$SELF_ROOT/$f")
+        [ "$n" != 0 ] && printf '  %-26s return make_list(0): %s\n' "$f" "$n"
+    done
     echo "  (a different soft stand-in; see this script's header)"
     exit 0
 fi
@@ -391,7 +470,9 @@ if [ "$usage_mode" = "--selftest" ]; then
             echo "  FAIL  $label (rc=$rc want=$want)"; sed 's/^/        /' "$tmp/out"; bad=$((bad+1))
         fi
     }
-    restore() { cp "$SELF_ROOT/src/builtins.c" "$root/src/builtins.c"; rm -f "$root/src/builtins_planted.c"; }
+    restore() { cp "$SELF_ROOT/src/builtins.c" "$root/src/builtins.c"
+                cp "$SELF_ROOT/src/ext_gfx.c" "$root/src/ext_gfx.c"
+                rm -f "$root/src/builtins_planted.c" "$root/src/builtins_digits.c"; }
 
     # 0. Control, BOTH halves. A control with only the must-flag half is
     #    satisfied by a check that always fails; and an unstartable mutant
@@ -505,6 +586,29 @@ Value* builtin_planted_e(Value *arg) { (void)arg; return make_num(0); /* fs:ANSW
 EOF
     expect 1 "builtin file outside every make variant is an orphan"; restore
 
+    # 10. THE SCOPED make_null() POPULATION (#1007), all three directions.
+    #     The widening is scoped by FILE, so it needs three fixtures, not
+    #     one: it must FIRE inside the scope, DISCRIMINATE inside the scope
+    #     (a classified site is clean, so it is not simply flagging every
+    #     make_null it sees), and STAY OUT of it elsewhere. Without the third
+    #     row a global widening — the cry-wolf outcome the header rejects —
+    #     would pass this selftest.
+    printf '\nValue* builtin_planted_null(Value *arg) { (void)arg; return make_null(); }\n' >> "$root/src/ext_gfx.c"
+    expect 1 "planted unmarked make_null() IN the null scope is caught"; restore
+
+    printf '\nValue* builtin_planted_null_ok(Value *arg) { (void)arg; return make_null(); /* fs:VOID a planted void answer */ }\n' >> "$root/src/ext_gfx.c"
+    expect 0 "a CLASSIFIED make_null() in the null scope is clean"; restore
+
+    printf '\nValue* builtin_planted_null_out(Value *arg) { (void)arg; return make_null(); }\n' >> "$root/src/builtins.c"
+    expect 0 "an unmarked make_null() OUTSIDE the null scope is NOT in the population"; restore
+
+    # 11. the new fs:VOID tag must be a real tag, not silently unrecognised.
+    #     A tag added to VALID_TAGS but forgotten in the tally would count as
+    #     classified while reporting VOID=0 — classified-but-uncounted is the
+    #     interception blind spot this gate's own header names.
+    printf '\nValue* builtin_planted_void_typo(Value *arg) { (void)arg; return make_null(); /* fs:VIOD typo */ }\n' >> "$root/src/ext_gfx.c"
+    expect 1 "a misspelled fs:VOID in the null scope is caught"; restore
+
     # 7. the leavings. A gate that corrupts the thing it checks manufactures
     #    exactly the defect it exists to detect.
     after="$(cd "$SELF_ROOT" && cat src/*.c | md5sum)"
diff --git a/tools/gfx_pixel_differential.sh b/tools/gfx_pixel_differential.sh
new file mode 100755
index 00000000..02b625ee
--- /dev/null
+++ b/tools/gfx_pixel_differential.sh
@@ -0,0 +1,400 @@
+#!/usr/bin/env bash
+# #1007 round 2: the PIXEL differential — the half tools/strict_differential.sh
+# structurally cannot measure.
+#
+# WHY THIS EXISTS. strict_differential.sh compares the RETURNED VALUE of a
+# probe on two binaries. Every drawing builtin in ext_gfx.c returns null on
+# every path, and every gfx probe there runs with NO WINDOW OPEN — the guards
+# all sit above the SDL load, which is the point of [135]. So its
+# `identical-when-off: N differing: 0` line was, for the whole drawing
+# surface, measured in the one state where it could not fail: nothing was
+# drawn on either side, and null == null.
+#
+# A blind review found that hole by hand, with a readback oracle, and it was
+# right to: `gfx_text of [0, 0, "H", 255, 255, 255, "2"]` draws 17 lit pixels
+# on the parent build and 0 on this one, and NOTHING in the change could see
+# it. This tool is that oracle, mechanised.
+#
+# WHAT IT DOES. Each row opens a 32x32 window under the dummy video driver,
+# clears it, makes ONE call, and prints a digest of the whole back buffer read
+# back through gfx_read. The digest — not the return value — is the observable
+# compared between the baseline (a build of the parent commit) and this build.
+#
+#   valid-*   rows: a CORRECT call. Must be byte-identical on both binaries in
+#             BOTH modes. This is the half that catches an over-broad guard:
+#             a guard that rejects a legitimate call shows up as a blank
+#             canvas here and as nothing at all in a return-value differential.
+#   wrong-*   rows: one argument slot given the wrong type. Flag-off must be
+#             byte-identical UNLESS the row carries a waiver proof (below),
+#             and EIGS_STRICT=1 must raise naming that builtin.
+#
+# THE WAIVER PROOF, and exactly what it does and does not establish.
+#   #1007 type-checks ~89 `items[N]->data.num` reads that had none. Reading a
+#   `Value*` union's `.num` when the value is a string is UB, and what the
+#   parent DREW came from reinterpreting a pointer — so those rows legitimately
+#   change with the flag off, and the issue says so ("an unchecked read is not
+#   a behaviour anyone depends on"). A waiver may not be taken on trust, so
+#   each waived row carries a ZERO VARIANT: the same program with the
+#   wrong-typed value replaced by the number 0. The proof executed here is
+#
+#       baseline(wrong-typed program) == baseline(zero program)
+#
+#   i.e. the parent's answer to the wrong-typed argument was not an answer at
+#   all — it was, indistinguishably, its answer to 0, which is what a
+#   reinterpreted 48-bit pointer truncates to as a double. Plus: the baseline
+#   must be stable across two runs (otherwise "the old answer was X" is not a
+#   statement about anything), and the NEW binary must raise under strict.
+#
+#   A proven waiver licenses REJECTING the call and nothing else: the second
+#   half requires the new binary's canvas to equal the canvas of the same
+#   program with the offending call DELETED. Without it a waiver would excuse
+#   any new behaviour at all, including a "helpful" coercion that draws
+#   something different from what the program asked for.
+#
+#   What it does NOT establish: that no COERCION site could ever pass it. A
+#   coercion whose default happens to equal its zero-behaviour (a scale
+#   clamped `if (scale < 1) scale = 1`) satisfies the equality too. It DOES
+#   discriminate every coercion whose default differs from zero — an alpha
+#   defaulting to 255, a colour defaulting to white — and it makes the claim
+#   being waived explicit and executable instead of asserted. Read the site
+#   before adding a waiver; this proves the claim, it does not choose it.
+#
+# COVERAGE IS DERIVED FROM THE SOURCE, not from this file's own row list.
+#   1. Every builtin in ext_gfx.c that carries a guard AND touches g_renderer
+#      must have at least one row.
+#   2. Every `gfx_nums(arg, A, B)` range in ext_gfx.c must have a wrong-typed
+#      row at slot A and at slot B-1 — the FIRST and LAST slot the guard
+#      covers. B-1 is normally an OPTIONAL trailing argument (gfx_rect's
+#      alpha, gfx_text's scale), which is precisely the slot the hand-written
+#      probe table missed. A widened guard with no row for its new boundary
+#      fails this script rather than passing quietly.
+#
+# Usage: bash tools/gfx_pixel_differential.sh <baseline-gfx-binary>
+#        bash tools/gfx_pixel_differential.sh --no-baseline
+#   The baseline is a `make gfx` build of the PARENT commit:
+#     git worktree add --detach DIR <parent-sha> && make -C DIR gfx
+#   --no-baseline keeps the halves that need one binary (strict raises,
+#   coverage, non-vacuity) and says the identity half was skipped. As with
+#   strict_differential.sh, a differential with no reference is not a pass.
+set -uo pipefail
+cd "$(cd "$(dirname "$0")/.." && pwd)"
+
+export SDL_VIDEODRIVER="${SDL_VIDEODRIVER:-dummy}"
+export SDL_AUDIODRIVER="${SDL_AUDIODRIVER:-dummy}"
+
+# THE BINARY UNDER TEST IS src/eigenscript — the hard link to the last `make`
+# target — not build/gfx/eigenscript. Defaulting to the gfx objdir would test a
+# stale gfx build during a release suite run, i.e. a binary nobody asked about,
+# and would report PASS for it. Under `make` the link has no gfx builtins and
+# this script SKIPs; under `make gfx` it is the gfx build and the rows run. Same
+# probe-gate shape as [132]/[133]. EIGS_GFX_NEW overrides for a two-binary run.
+NEW="${EIGS_GFX_NEW:-./src/eigenscript}"
+BASE="${1:-}"
+NO_BASELINE=0
+[ "$BASE" = "--no-baseline" ] && { NO_BASELINE=1; BASE=""; }
+
+[ -x "$NEW" ] || { echo "FAIL: no built binary at $NEW"; exit 1; }
+if [ -z "$BASE" ] && [ "$NO_BASELINE" = 0 ]; then
+    echo "FAIL: no baseline binary given. Pass a 'make gfx' build of the parent"
+    echo "      commit, or --no-baseline to skip the identity half deliberately."
+    exit 1
+fi
+
+# The gfx builtins must EXIST in this build. A release binary has no gfx_open
+# at all, and every row would then 'fail' for a reason that has nothing to do
+# with a guard — so this is a clean SKIP, the same shape [132]/[133] use.
+probe=$(mktemp); printf 'print of (gfx_text_width of ["m", 1])\n' > "$probe"
+probe_out="$("$NEW" "$probe" 2>&1 || true)"; rm -f "$probe"
+case "$probe_out" in
+    *"undefined variable"*)
+        echo "SKIP: $NEW was built without EIGENSCRIPT_EXT_GFX (no gfx builtins)"
+        exit 0 ;;
+esac
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+# A RENDERER must actually open. libSDL2 is dlopen'd, so the gfx binary builds
+# and runs without it — and then every row draws nothing, the valid rows look
+# vacuous and this tool would report a defect that is really an absent library.
+# Probed by opening a window, because that is the thing the rows need.
+# The PIXEL halves need it; the strict-raise and coverage halves do not (every
+# guard sits above the SDL load, which is [135]'s rule), so a missing library
+# degrades this tool to those instead of switching it off. A whole gate that
+# skips is a gate CI never runs.
+printf 'print of (gfx_open of [8, 8, "pixdiff-probe"])\n' > "$TMP/open.eigs"
+NO_RENDERER=0
+if [ "$("$NEW" "$TMP/open.eigs" 2>&1 | tail -1)" != "1" ]; then
+    NO_RENDERER=1
+    BASE=""   # nothing to compare: neither binary can draw
+    echo "  NOTE: no renderer (libSDL2 absent, or no video device for"
+    echo "        SDL_VIDEODRIVER=$SDL_VIDEODRIVER) — the pixel halves are OFF."
+    echo "        The strict-raise and coverage halves still run: every guard sits"
+    echo "        above the SDL load, so they are reachable without a window."
+fi
+
+# ------------------------------------------------------------------ fixture
+# 32x32 so a scale-2 glyph fits with headroom; the digest is position-weighted
+# so a shape drawn in the wrong PLACE is a different number, not just a
+# different pixel count.
+read -r -d '' HEAD <<'EOF' || true
+ignore is gfx_open of [32, 32, "pixdiff"]
+ignore is gfx_clear of [0, 0, 0]
+EOF
+read -r -d '' TAIL <<'EOF' || true
+total is 0
+lit is 0
+for py in range of 32:
+    for px in range of 32:
+        c is gfx_read of [px, py]
+        if c != null:
+            total is total + (c[0] * 7 + c[1] * 13 + c[2] * 17) * (px + py * 32 + 1)
+            if c[0] + c[1] + c[2] > 0:
+                lit is lit + 1
+print of f"digest={total} lit={lit}"
+EOF
+
+# --------------------------------------------------------------------- rows
+# label|builtin|slot|program|zero-variant
+#   slot   the argument index given the wrong type ('-' for a valid row)
+#   zero   present => this row's default-path divergence is WAIVED, and this
+#          is the program that proves it (see the header)
+ROWS=$(cat <<'EOF'
+valid-rect|gfx_rect|-|ignore is gfx_rect of [4, 4, 10, 10, 255, 0, 0]|
+valid-rect-alpha|gfx_rect|-|ignore is gfx_rect of [4, 4, 10, 10, 255, 0, 0, 128]|
+valid-rrect|gfx_rrect|-|ignore is gfx_rrect of [4, 4, 12, 12, 3, 0, 255, 0]|
+valid-circle|gfx_circle|-|ignore is gfx_circle of [16, 16, 7, 0, 0, 255]|
+valid-line|gfx_line|-|ignore is gfx_line of [0, 0, 30, 30, 255, 255, 0]|
+valid-point|gfx_point|-|ignore is gfx_point of [5, 5, 255, 0, 255]|
+valid-clear|gfx_clear|-|ignore is gfx_clear of [10, 20, 30]|
+valid-clip|gfx_clip|-|ignore is gfx_clip of [2, 2, 8, 8]\nignore is gfx_rect of [0, 0, 32, 32, 255, 0, 0]|
+valid-clip-null|gfx_clip|-|ignore is gfx_clip of null\nignore is gfx_rect of [0, 0, 8, 8, 255, 0, 0]|
+valid-text|gfx_text|-|ignore is gfx_text of [0, 0, "H", 255, 255, 255]|
+valid-text-scale|gfx_text|-|ignore is gfx_text of [0, 0, "H", 255, 255, 255, 2]|
+valid-fb|gfx_fb|-|fb is buffer of 16\nignore is buf_fill of [fb, 0, 16, 0]\nignore is gfx_fb of [fb, 4, 4, 0, 0, 2]|
+valid-read|gfx_read|-|ignore is gfx_rect of [0, 0, 4, 4, 200, 100, 50]\nprint of (gfx_read of [1, 1])|
+valid-open-title|gfx_open|-|ignore is gfx_title of "pixdiff2"\nignore is gfx_rect of [1, 1, 3, 3, 9, 9, 9]|
+wrong-rect-slot0|gfx_rect|0|ignore is gfx_rect of ["4", 4, 10, 10, 255, 0, 0]|ignore is gfx_rect of [0, 4, 10, 10, 255, 0, 0]
+wrong-rect-slot7|gfx_rect|7|ignore is gfx_rect of [4, 4, 10, 10, 255, 0, 0, "128"]|
+wrong-rrect-slot0|gfx_rrect|0|ignore is gfx_rrect of ["4", 4, 12, 12, 3, 0, 255, 0]|ignore is gfx_rrect of [0, 4, 12, 12, 3, 0, 255, 0]
+wrong-rrect-slot8|gfx_rrect|8|ignore is gfx_rrect of [4, 4, 12, 12, 3, 0, 255, 0, "128"]|
+wrong-circle-slot0|gfx_circle|0|ignore is gfx_circle of ["16", 16, 7, 0, 0, 255]|ignore is gfx_circle of [0, 16, 7, 0, 0, 255]
+wrong-circle-slot6|gfx_circle|6|ignore is gfx_circle of [16, 16, 7, 0, 0, 255, "128"]|
+wrong-line-slot0|gfx_line|0|ignore is gfx_line of ["0", 0, 30, 30, 255, 255, 0]|ignore is gfx_line of [0, 0, 30, 30, 255, 255, 0]
+wrong-line-slot6|gfx_line|6|ignore is gfx_line of [0, 0, 30, 30, 255, 255, "0"]|ignore is gfx_line of [0, 0, 30, 30, 255, 255, 0]
+wrong-point-slot0|gfx_point|0|ignore is gfx_point of ["5", 5, 255, 0, 255]|ignore is gfx_point of [0, 5, 255, 0, 255]
+wrong-point-slot4|gfx_point|4|ignore is gfx_point of [5, 5, 255, 0, "255"]|ignore is gfx_point of [5, 5, 255, 0, 0]
+wrong-clear-slot0|gfx_clear|0|ignore is gfx_clear of ["10", 20, 30]|ignore is gfx_clear of [0, 20, 30]
+wrong-clear-slot2|gfx_clear|2|ignore is gfx_clear of [10, 20, "30"]|ignore is gfx_clear of [10, 20, 0]
+wrong-clip-slot0|gfx_clip|0|ignore is gfx_clip of ["2", 2, 8, 8]\nignore is gfx_rect of [0, 0, 32, 32, 255, 0, 0]|ignore is gfx_clip of [0, 2, 8, 8]\nignore is gfx_rect of [0, 0, 32, 32, 255, 0, 0]
+wrong-clip-slot3|gfx_clip|3|ignore is gfx_clip of [2, 2, 8, "8"]\nignore is gfx_rect of [0, 0, 32, 32, 255, 0, 0]|ignore is gfx_clip of [2, 2, 8, 0]\nignore is gfx_rect of [0, 0, 32, 32, 255, 0, 0]
+wrong-text-slot0|gfx_text|0|ignore is gfx_text of ["0", 0, "H", 255, 255, 255]|ignore is gfx_text of [0, 0, "H", 255, 255, 255]
+wrong-text-slot1|gfx_text|1|ignore is gfx_text of [0, "0", "H", 255, 255, 255]|ignore is gfx_text of [0, 0, "H", 255, 255, 255]
+wrong-text-slot3|gfx_text|3|ignore is gfx_text of [0, 0, "H", "255", 255, 255]|ignore is gfx_text of [0, 0, "H", 0, 255, 255]
+wrong-text-slot6|gfx_text|6|ignore is gfx_text of [0, 0, "H", 255, 255, 255, "2"]|ignore is gfx_text of [0, 0, "H", 255, 255, 255, 0]
+wrong-read-slot0|gfx_read|0|ignore is gfx_rect of [0, 0, 4, 4, 200, 100, 50]\nprint of (gfx_read of ["1", 1])|ignore is gfx_rect of [0, 0, 4, 4, 200, 100, 50]\nprint of (gfx_read of [0, 1])
+wrong-read-slot1|gfx_read|1|ignore is gfx_rect of [0, 0, 4, 4, 200, 100, 50]\nprint of (gfx_read of [1, "1"])|ignore is gfx_rect of [0, 0, 4, 4, 200, 100, 50]\nprint of (gfx_read of [1, 0])
+wrong-fb-slot1|gfx_fb|1|fb is buffer of 16\nignore is buf_fill of [fb, 0, 16, 0]\nignore is gfx_fb of [fb, "4", 4, 0, 0, 2]|
+wrong-fb-slot5|gfx_fb|5|fb is buffer of 16\nignore is buf_fill of [fb, 0, 16, 0]\nignore is gfx_fb of [fb, 4, 4, 0, 0, "2"]|
+wrong-open-slot0|gfx_open|0|ignore is gfx_open of ["16", 16, "reopen"]\nignore is gfx_rect of [0, 0, 8, 8, 255, 0, 0]|
+EOF
+)
+
+mkprog() { printf '%s\n' "$HEAD" > "$1"; printf '%b\n' "$2" >> "$1"; printf '%s\n' "$TAIL" >> "$1"; }
+run()    { local bin="$1" strict="$2" f="$3" out rc
+           if [ "$strict" = "1" ]; then out="$(EIGS_STRICT=1 "$bin" "$f" 2>&1)"; rc=$?
+           else out="$("$bin" "$f" 2>&1)"; rc=$?; fi
+           printf '%s\n%s' "$rc" "$out"; }
+
+rc=0
+n_row=0 n_valid=0 n_wrong=0 n_ident=0 n_differ=0 n_waived=0 n_raise=0 n_silent=0 n_misattr=0
+differ_list="" silent_list="" waiver_list="" misattr_list="" vacuous_list=""
+covered_names="" covered_slots=""
+
+# The empty canvas, for the non-vacuity check below.
+mkprog "$TMP/blank.eigs" "ignore is gfx_delay of 0"
+blank="$(run "$NEW" - "$TMP/blank.eigs")"
+blank_digest="${blank#*$'\n'}"
+
+while IFS='|' read -r label who slot prog zero; do
+    [ -z "${label:-}" ] && continue
+    n_row=$((n_row + 1))
+    covered_names="$covered_names $who"
+    [ "$slot" != "-" ] && covered_slots="$covered_slots $who:$slot"
+    mkprog "$TMP/p.eigs" "$prog"
+    b="$(run "$NEW" - "$TMP/p.eigs")"
+
+    if [ "$slot" = "-" ]; then
+        n_valid=$((n_valid + 1))
+        # A VALID row that draws nothing measures nothing. gfx_read's row
+        # prints a colour instead of lighting pixels, so it is exempt by name.
+        if [ "$NO_RENDERER" = 0 ] && [ "$who" != "gfx_read" ] && [ "${b#*$'\n'}" = "$blank_digest" ]; then
+            vacuous_list="$vacuous_list
+    $label — draws nothing: identical to the blank canvas ($blank_digest)"
+        fi
+        # Strict must leave a correct call completely alone.
+        s="$(run "$NEW" 1 "$TMP/p.eigs")"
+        if [ "$s" != "$b" ]; then
+            differ_list="$differ_list
+    $label [strict vs plain, same binary] — a guard rejects a LEGITIMATE call
+      plain : $(printf '%s' "$b" | tr '\n' ' ' | cut -c1-80)
+      strict: $(printf '%s' "$s" | tr '\n' ' ' | cut -c1-80)"
+            rc=1
+        fi
+    else
+        n_wrong=$((n_wrong + 1))
+        s="$(run "$NEW" 1 "$TMP/p.eigs")"
+        if [ "${s%%$'\n'*}" = "0" ]; then
+            n_silent=$((n_silent + 1))
+            silent_list="$silent_list
+    $label — still silent under EIGS_STRICT=1: $(printf '%s' "$s" | tr '\n' ' ' | cut -c1-70)"
+        elif grep -qF "$who: expected" <<<"$s"; then
+            n_raise=$((n_raise + 1))
+        else
+            n_misattr=$((n_misattr + 1))
+            misattr_list="$misattr_list
+    $label — raised, but not by $who's own guard: $(printf '%s' "$s" | tr '\n' ' ' | cut -c1-70)"
+        fi
+    fi
+
+    [ -z "$BASE" ] && continue
+
+    a="$(run "$BASE" - "$TMP/p.eigs")"
+    if [ "$a" = "$b" ]; then
+        n_ident=$((n_ident + 1))
+        # A waiver that no longer diverges is spent paperwork — the same
+        # failure mode strict_differential.sh's SPENT WAIVER check exists for.
+        if [ -n "${zero:-}" ]; then
+            waiver_list="$waiver_list
+    SPENT: $label carries a zero-variant waiver but does not diverge. Remove it."
+            rc=1
+        fi
+        continue
+    fi
+    if [ -z "${zero:-}" ]; then
+        n_differ=$((n_differ + 1))
+        differ_list="$differ_list
+    $label — the default path was NOT preserved, and no waiver claims it
+      baseline: $(printf '%s' "$a" | tr '\n' ' ' | cut -c1-80)
+      new     : $(printf '%s' "$b" | tr '\n' ' ' | cut -c1-80)"
+        rc=1
+        continue
+    fi
+    # ---- the waiver's proof, executed
+    a2="$(run "$BASE" - "$TMP/p.eigs")"
+    mkprog "$TMP/z.eigs" "$zero"
+    z="$(run "$BASE" - "$TMP/z.eigs")"
+    if [ "$a" != "$a2" ]; then
+        waiver_list="$waiver_list
+    UNPROVEN: $label — the baseline is not stable across two runs, so
+              'the parent answered X' is not a statement about anything."
+        rc=1
+    elif [ "$a" != "$z" ]; then
+        waiver_list="$waiver_list
+    UNPROVEN: $label — the baseline's answer to the WRONG-TYPED argument is
+              NOT its answer to 0, so this is not an unchecked union read.
+              Treat it as a real behaviour change, not a pun.
+      wrong-typed: $(printf '%s' "$a" | tr '\n' ' ' | cut -c1-70)
+      literal 0  : $(printf '%s' "$z" | tr '\n' ' ' | cut -c1-70)"
+        rc=1
+    else
+        # SECOND HALF: a proven-laundered baseline licenses REJECTING the call.
+        # It licenses nothing else. Without this, a waiver would excuse any new
+        # behaviour at all — including the "helpful" coercion that would make a
+        # wrong-typed argument draw something DIFFERENT but still not what the
+        # program asked for. So the new binary's canvas must equal the canvas of
+        # the same program with the offending call DELETED (mechanically: the
+        # first line naming this builtin). gfx_read draws nothing and is judged
+        # on its documented rejection stand-in instead, named here rather than
+        # implied.
+        noeffect="$(printf '%b\n' "$prog" | awk -v w="$who of" 'index($0, w) && !done { done = 1; next } { print }')"
+        mkprog "$TMP/n.eigs" "$noeffect"
+        ne="$(run "$NEW" - "$TMP/n.eigs")"
+        if [ "$who" = "gfx_read" ]; then
+            if ! grep -q "null" <<<"$b"; then
+                waiver_list="$waiver_list
+    UNPROVEN: $label — the parent's answer was laundered, but the new answer is
+              not gfx_read's documented rejection stand-in (null):
+              $(printf '%s' "$b" | tr '\n' ' ' | cut -c1-70)"
+                rc=1
+                continue
+            fi
+        elif [ "$b" != "$ne" ]; then
+            waiver_list="$waiver_list
+    UNPROVEN: $label — the rejected call did not draw NOTHING. A waiver licenses
+              rejecting the argument, never drawing something else instead.
+      with the call   : $(printf '%s' "$b" | tr '\n' ' ' | cut -c1-70)
+      call deleted    : $(printf '%s' "$ne" | tr '\n' ' ' | cut -c1-70)"
+            rc=1
+            continue
+        fi
+        n_waived=$((n_waived + 1))
+        waiver_list="$waiver_list
+    proven: $label — parent answered $(printf '%s' "$a" | tr '\n' ' ' | cut -c1-46)
+            for the wrong-typed value AND for a literal 0 (an unchecked
+            \`items[$slot]->data.num\` read: the drawing came from the
+            reinterpreted pointer, not from the argument), and this build
+            draws exactly what deleting the call draws"
+    fi
+done <<<"$ROWS"
+
+# ------------------------------------------------- coverage, from the source
+guarded_renderer="$(awk '
+    /^Value\* builtin_/ { name = $0; sub(/.*builtin_/, "", name); sub(/\(.*/, "", name); has = 0; g = 0 }
+    /g_renderer/        { if (name != "") has = 1 }
+    /(ARG_GUARD|STRICT_REQUIRE)\(/ { if (name != "") g = 1 }
+    /^}/                { if (name != "" && has && g) print name; name = "" }
+' src/ext_gfx.c | sort -u)"
+missing_names=""
+for nm in $guarded_renderer; do
+    case " $covered_names " in *" $nm "*) ;; *) missing_names="$missing_names $nm" ;; esac
+done
+missing_slots=""
+while read -r nm a b; do
+    [ -z "${nm:-}" ] && continue
+    last=$((b - 1))
+    for want in "$a" "$last"; do
+        case " $covered_slots " in *" $nm:$want "*) ;; *) missing_slots="$missing_slots $nm:$want" ;; esac
+    done
+done < <(awk '
+    /^Value\* builtin_/ { name = $0; sub(/.*builtin_/, "", name); sub(/\(.*/, "", name) }
+    match($0, /gfx_nums\(arg, [0-9]+, [0-9]+\)/) {
+        s = substr($0, RSTART, RLENGTH); gsub(/[^0-9 ]/, " ", s)
+        n = split(s, f, " "); lo = ""; hi = ""
+        for (i = 1; i <= n; i++) if (f[i] != "") { if (lo == "") lo = f[i]; else hi = f[i] }
+        if (name != "" && lo != "" && hi != "") print name, lo, hi
+    }
+' src/ext_gfx.c | sort -u)
+
+echo "== #1007 gfx pixel differential =="
+echo "  rows=$n_row (valid=$n_valid wrong=$n_wrong)"
+if [ -n "$BASE" ]; then
+    echo "  identical-when-off: $n_ident   differing: $n_differ   waived (proven): $n_waived"
+elif [ "$NO_RENDERER" = 1 ]; then
+    echo "  identical-when-off: SKIPPED (no renderer — nothing to draw on either side)"
+else
+    echo "  identical-when-off: SKIPPED (--no-baseline)"
+fi
+echo "  raises-under-strict: $n_raise   silent: $n_silent   misattributed: $n_misattr"
+[ "$NO_RENDERER" = 0 ] && echo "  blank canvas: $blank_digest"
+
+[ -n "$waiver_list" ]  && echo "  WAIVERS:$waiver_list"
+[ -n "$differ_list" ]  && { echo "  DIFFERING:$differ_list"; rc=1; }
+[ -n "$silent_list" ]  && { echo "  SILENT UNDER STRICT:$silent_list"; rc=1; }
+[ -n "$misattr_list" ] && { echo "  RAISED BY THE WRONG GUARD:$misattr_list"; rc=1; }
+[ -n "$vacuous_list" ] && { echo "  VACUOUS ROW (a valid call that draws nothing proves nothing):$vacuous_list"; rc=1; }
+[ -n "$missing_names" ] && {
+    echo "  GUARDED, TOUCHES THE RENDERER, NO PIXEL ROW:"
+    printf '    %s\n' $missing_names
+    echo "    (population derived from src/ext_gfx.c, not from this file's rows)"
+    rc=1; }
+[ -n "$missing_slots" ] && {
+    echo "  GUARDED SLOT WITH NO WRONG-TYPED ROW (first/last of a gfx_nums range):"
+    printf '    %s\n' $missing_slots
+    echo "    The LAST slot of a range is normally the OPTIONAL trailing argument"
+    echo "    — the slot a hand-written probe table forgets, and the one that hid"
+    echo "    gfx_text's wrong-typed scale from #1007's first pass."
+    rc=1; }
+
+[ "$rc" = 0 ] && echo "  OK" || echo "  FAIL"
+exit $rc
diff --git a/tools/gfx_strict_sweep.sh b/tools/gfx_strict_sweep.sh
new file mode 100755
index 00000000..1ac02cc9
--- /dev/null
+++ b/tools/gfx_strict_sweep.sh
@@ -0,0 +1,422 @@
+#!/usr/bin/env bash
+# #1007 round 3: the CONTAINER-SHAPE sweep over ext_gfx.c's guarded surface.
+#
+# WHY THIS EXISTS, and it is a process finding rather than a code one.
+# #1007 landed three times and a blind review found one more silent builtin
+# each time, always the SAME axis and never the same builtin:
+#
+#   round 1 -> 2  the eight audio GENERATORS answered a short argument list
+#                 with an empty sample list -- indistinguishable from a
+#                 legitimately empty generation.
+#   round 2 -> 3  the three audio *_open builtins answered a SHORT or non-list
+#                 argument by opening the device at the 44100/1 defaults and
+#                 handing back a REAL DEVICE ID, so a caller that asked for
+#                 48000 was told it got 48000.
+#   round 3       audio_play / audio_stream_push / audio_play_loop answered a
+#                 non-list `samples` with the documented "nothing to play" 0,
+#                 while a wrong-typed ELEMENT of a list already raised.
+#
+# Each time the hand-written probe table in tools/strict_differential.sh was
+# green, because every row in it held the ARITY right and varied only the
+# element TYPE. The table asked the question in the one state where it could
+# not fail. Adding a fourth hand-written row would fix the last instance and
+# not the pattern, so this asks the question mechanically instead: it derives
+# the guarded names AND their required arity from src/ext_gfx.c itself, and
+# crosses each with the container shapes a caller actually gets wrong.
+#
+# THE POPULATION IS DERIVED, NOT LISTED. Every ARG_GUARD / STRICT_REQUIRE in
+# the file names a builtin and spells the shape it wanted; the bracketed group
+# in that `want` string is the arity. So a builtin added tomorrow with a guard
+# is swept tomorrow, and one whose guard is deleted leaves the population and
+# trips the floor. What is hand-written is only the ALLOWLIST of pairs that
+# are quiet ON PURPOSE, and each entry carries its reason and is checked for
+# staleness: an allowlisted pair that starts raising fails this script, so the
+# list cannot rot into a blanket waiver.
+#
+# WHAT THIS DOES NOT COVER, stated so the next reader does not assume it:
+#   - It sweeps builtins that HAVE a guard. A builtin with no guard at all has
+#     no `want` string, so it is not in the population; that gap is covered by
+#     the guarded-name cross-check in tools/strict_differential.sh, which goes
+#     red for a guarded name with no probe, and by [135] for guard ORDER.
+#   - It probes the TOP-LEVEL argument container (arity and type), not element
+#     values and not a NESTED container. `audio_play_loop of [42, 2]` -- a
+#     non-list in the samples SLOT -- is the third round's third bug and this
+#     sweep does not see it: the top-level argument is a well-formed 2-element
+#     list. That row is pinned by hand in tests/test_gfx_argtypes.eigs; a
+#     nested-slot sweep would need per-slot types, which the `want` strings do
+#     not carry uniformly. Out-of-domain numbers (a negative width, loops == 0)
+#     are the differential table's axis and stay there.
+#
+# VALIDATED BY EXECUTION, not by argument. Pointed at a build of the parent
+# commit (no guards at all) it reports raised=0 and trips its own floor;
+# pointed at the SECOND round of this same change -- the artifact a blind
+# review failed -- it names 18 rows across audio_open, audio_capture_open,
+# audio_stream_open, audio_play and audio_stream_push, which is the finding
+# that review made by hand plus two builtins it did not reach.
+#   - It runs under EIGS_STRICT=1 only. The "byte-identical with the flag off"
+#     half is tools/strict_differential.sh's, which needs two binaries.
+#
+# Usage: bash tools/gfx_strict_sweep.sh [--selftest]
+#   EIGS_SWEEP_BIN overrides the binary (default ./src/eigenscript). Pointing
+#   it at a build that PREDATES a guard is how this harness is validated: the
+#   rows that guard covers go silent and the script fails.
+set -uo pipefail
+cd "$(cd "$(dirname "$0")/.." && pwd)"
+
+BIN="${EIGS_SWEEP_BIN:-./src/eigenscript}"
+SRC=src/ext_gfx.c
+export SDL_VIDEODRIVER="${SDL_VIDEODRIVER:-dummy}"
+export SDL_AUDIODRIVER="${SDL_AUDIODRIVER:-dummy}"
+
+# ---------------------------------------------------------------- allowlist
+# name|shape-id|reason. A pair here is quiet ON PURPOSE. Staleness is checked:
+# if the pair RAISES, this script fails and the entry must go.
+ALLOW=$(cat <<'EOF'
+gfx_text_height|scalar|the scale slot is documented as `gfx_text_height of 2`, a bare number
+gfx_text_height|list2|[scale] with a numeric first slot is the documented list form; the surplus slot is #989
+gfx_text_width|string|`gfx_text_width of "hello"` is the documented one-argument form
+audio_pause|scalar|`audio_pause of 1` is the documented flag form
+audio_stop|scalar|`audio_stop of 1` is the documented channel form
+audio_music_volume|scalar|`audio_music_volume of 96` is the documented form
+audio_music_volume|list2|[volume] with a numeric first slot is the documented list form; the surplus slot is #989
+gfx_delay|scalar|`gfx_delay of 16` is the documented one-argument form
+gfx_title|string|`gfx_title of "name"` is the documented one-argument form
+audio_play|list2|a 2-element numeric list IS a sample list -- the valid call
+audio_stream_push|list2|a 2-element numeric list IS a sample list -- the valid call
+EOF
+)
+
+# ------------------------------------------------------------ required names
+# The population is DERIVED, which means a deleted guard does not fail a
+# derived check -- it leaves the population, and coverage vanishes with it.
+# Bought by this tool's own planted fault: removing audio_play's guard took
+# the sweep from 35 names to 34 and it still printed OK, which is the exact
+# vacuity this file exists to prevent, one level up. So the names that had a
+# guard when this landed are PINNED. A new guarded builtin grows the
+# population on its own and needs no edit here; a name that disappears fails,
+# and removing it from this list is the review event that says so out loud.
+REQUIRED_NAMES="audio_capture_open audio_envelope audio_gain audio_mix audio_music_play
+audio_music_volume audio_noise audio_open audio_pause audio_play
+audio_play_loop audio_saw audio_sine audio_square audio_stop
+audio_stream_open audio_stream_push audio_sweep audio_volume gfx_circle
+gfx_clear gfx_clip gfx_delay gfx_fb gfx_line
+gfx_open gfx_point gfx_read gfx_rect gfx_rrect
+gfx_text gfx_text_height gfx_text_width gfx_title ppu_render_frame"
+
+# ------------------------------------------------------------- the population
+# Join the file into one stream first: ARG_GUARD/STRICT_REQUIRE invocations
+# span lines, so a per-line grep loses the `want` string of every multi-line
+# call -- which is most of the drawing surface.
+POP="$(tr '\n' ' ' < "$SRC" \
+  | grep -oE '(ARG_GUARD|ARG_GUARD_TAPED|ARG_GUARD_PRETAKE|STRICT_REQUIRE)\([^;]*;' \
+  | grep -oE '"(gfx|audio|ppu)_[a-z_]+", *"[^"]*"' \
+  | sed 's/", *"/|/; s/^"//; s/"$//')"
+
+# One row per name: the SMALLEST bracketed slot count any of its guards asks
+# for is its required arity (a guard that wants more slots is describing an
+# optional tail). Names whose `want` has no bracketed group are scalar-argument
+# builtins and get the scalar-shaped probes instead.
+NAMES="$(printf '%s\n' "$POP" | cut -d'|' -f1 | sort -u)"
+n_names=$(printf '%s\n' "$NAMES" | sed '/^$/d' | wc -l)
+# Pure shell, no subprocess, and that is load-bearing rather than tidy: the
+# first version ran `grep -qx` 35 times and, on this shared box, occasionally
+# reported `audio_sweep` missing when it was plainly there. A grep that cannot
+# be forked exits nonzero, and `|| MISSING=...` reads that as "absent" -- the
+# SAME conflation of "the check did not run" with "the check says no" that the
+# UNRUN verdict exists for, one level up. A case-glob cannot fail to run.
+# ONE matcher, used by the pin loop below and by --selftest's row for it.
+# The selftest used to re-implement this as `printf | grep -qx`, which is the
+# #1122-banned shape and, worse, meant the row proved a matcher this file does
+# not use.
+name_in_population() {   # <name> -> 0 when $NAMES carries it as a whole line
+    case "
+$NAMES
+" in *"
+$1
+"*) return 0 ;; esac
+    return 1
+}
+
+MISSING=""
+for req in $REQUIRED_NAMES; do
+    name_in_population "$req" || MISSING="$MISSING $req"
+done
+
+arity_of() {  # $1 = name -> smallest bracketed slot count, or 0 for none
+    printf '%s\n' "$POP" | awk -F'|' -v n="$1" '
+        $1 == n {
+            w = $2
+            if (match(w, /\[[^]]*\]/)) {
+                g = substr(w, RSTART + 1, RLENGTH - 2)
+                k = 1
+                for (i = 1; i <= length(g); i++) if (substr(g, i, 1) == ",") k++
+                if (best == 0 || k < best) best = k
+            }
+        }
+        END { print best + 0 }'
+}
+
+# ------------------------------------------------------------------- shapes
+# shape-id -> the EigenScript argument text. `short` is filled per name.
+#
+# `([1])` is parenthesised deliberately: a bare 1-element list is an ARGUMENT
+# LIST at every count, so `f of [1]` passes the element 1, not the list. The
+# parenthesised form is how a 1-element list is passed whole (#355/#405).
+shape_text() {  # $1 = shape-id, $2 = arity
+    case "$1" in
+        scalar) echo '42' ;;
+        string) echo '"zzz"' ;;
+        dict)   echo '{"k": 1}' ;;
+        list2)  echo '[1, 2]' ;;
+        short)  k=$(( $2 - 1 ))
+                if [ "$k" -le 0 ]; then echo ''
+                elif [ "$k" -eq 1 ]; then echo '([1])'
+                else printf '['; for i in $(seq 1 "$k"); do
+                         [ "$i" -gt 1 ] && printf ', '; printf '%d' "$i"; done; printf ']\n'
+                fi ;;
+    esac
+}
+
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+
+# $1 = name, $2 = argument text -> SILENT | RAISED-OWN | RAISED-OTHER | UNRUN
+#
+# FOUR verdicts, not three, and the fourth is why: the first version of this
+# function had `else echo RAISED-OTHER`, which folded "raised from somebody
+# else's guard" together with "did not run at all". On a 4-core box shared
+# with eight other agents' suites the second happens: the child is killed and
+# exits nonzero having printed no runtime error, and the section reported
+# MISATTRIBUTED audio_open — a guard verdict, for a probe that never reached
+# a guard. Caught by this tool's own first suite run, and it is #988's rule
+# exactly: a child that did not complete must not produce a section verdict.
+# So a nonzero exit with NO `Error line` is UNRUN, retried, and if it never
+# runs it fails the gate under its own name rather than impersonating a
+# finding. The last output is left in $TMP/last.out for the diagnostic.
+verdict() {
+    printf 'ignore is %s of %s\n' "$1" "$2" > "$TMP/p.eigs"
+    tries=0
+    while [ "$tries" -lt 3 ]; do
+        tries=$((tries + 1))
+        out="$(EIGS_STRICT=1 "$BIN" "$TMP/p.eigs" 2>&1)"; rc=$?
+        printf '%s\n' "$out" > "$TMP/last.out"
+        if [ "$rc" -eq 0 ]; then echo SILENT; return; fi
+        # case-globs, not `grep -q`. Two greps per row x 140 rows is 280 forks
+        # on a box shared with eight other suites, and a grep that cannot fork
+        # exits nonzero -- which read as "this line is not there" and turned
+        # RAISED-OWN into MISATTRIBUTED at about one run in eight (measured).
+        # A verdict must not depend on whether a helper process started.
+        case "$out" in
+            "Error line 1: $1:"*|*"
+Error line 1: $1:"*) echo RAISED-OWN; return ;;
+        esac
+        case "$out" in
+            "Error line "*|*"
+Error line "*) echo RAISED-OTHER; return ;;
+        esac
+        echo "retry: $1 of $2 (exit $rc, no runtime error printed)" >> "$TMP/retries"
+    done
+    echo UNRUN
+}
+
+# ----------------------------------------------------------------- selftest
+if [ "${1:-}" = "--selftest" ]; then
+    # The classifier rows below RUN the binary, so they need the gfx builtins
+    # for the same reason the sweep does. Checked here as well as in the sweep
+    # because --selftest returns before the sweep's own probe: without this the
+    # release lane reported "the sweep's own selftest is red" on a binary that
+    # simply has no gfx surface to classify.
+    printf 'ignore is gfx_text_height of null\n' > "$TMP/probe.eigs"
+    sf_probe="$("$BIN" "$TMP/probe.eigs" 2>&1)" || true
+    case "$sf_probe" in
+        *"undefined variable"*)
+            echo "== gfx_strict_sweep selftest =="
+            echo "  SKIP: $BIN was built without EIGENSCRIPT_EXT_GFX"
+            exit 0 ;;
+    esac
+    sf_pass=0; sf_fail=0
+    sf() { if [ "$2" = "$3" ]; then echo "  PASS $1"; sf_pass=$((sf_pass+1));
+           else echo "  FAIL $1 (got '$2', want '$3')"; sf_fail=$((sf_fail+1)); fi }
+    echo "== gfx_strict_sweep selftest =="
+    # The arity parser, on shapes taken verbatim from the file.
+    p_arity() { printf '%s\n' "$1" | awk '
+        { w = $0
+          if (match(w, /\[[^]]*\]/)) {
+              g = substr(w, RSTART + 1, RLENGTH - 2); k = 1
+              for (i = 1; i <= length(g); i++) if (substr(g, i, 1) == ",") k++
+              print k } else print 0 }'; }
+    sf "arity of a 7-slot want" \
+       "$(p_arity '[number x, number y, number w, number h, number r, number g, number b] and an optional number alpha')" 7
+    sf "arity of a 2-slot want" "$(p_arity '[number freq, number channels] or null')" 2
+    sf "arity of a scalar want" "$(p_arity 'number milliseconds')" 0
+    # The short-list builder, including the 1-element spread trap.
+    sf "short list at arity 3" "$(shape_text short 3)" '[1, 2]'
+    sf "short list at arity 2 is parenthesised" "$(shape_text short 2)" '([1])'
+    sf "short list at arity 1 is empty (nothing shorter)" "$(shape_text short 1)" ''
+    # The pinned-name check, proven by asking it about a name that is not in
+    # the population. Without this row the check could be an empty loop.
+    _sweep_miss=""
+    for req in $REQUIRED_NAMES eigs_no_such_builtin_1007; do
+        name_in_population "$req" || _sweep_miss="$_sweep_miss $req"
+    done
+    sf "pinned-name check notices a name absent from the population" \
+       "$_sweep_miss" " eigs_no_such_builtin_1007"
+    sf "every pinned name IS in the population right now" "$MISSING" ""
+    # The population must be non-vacuous and must contain the three names each
+    # round missed, which is the only reason this file exists.
+    for n in audio_sine audio_stream_open audio_play; do
+        case "$NAMES" in *"$n"*) sf "population contains $n" yes yes ;;
+                         *)      sf "population contains $n" no yes ;; esac
+    done
+    # The verdict classifier, exercised against the live binary on a call that
+    # must raise and one that must not. A classifier that always says RAISED
+    # would pass every row in the sweep.
+    sf "classifier scores a well-formed gfx_text_height quiet" "$(verdict gfx_text_height 'null')" SILENT
+    sf "classifier scores a dict to gfx_rect as its own raise"  "$(verdict gfx_rect '{"k": 1}')" RAISED-OWN
+    # The other two branches, both proven rather than assumed. A raise that is
+    # not this builtin's must not read as its guard firing; and a child that
+    # exits nonzero having printed nothing must not read as a verdict at all
+    # -- that conflation is what this tool's own first suite run produced
+    # (MISATTRIBUTED audio_open, from a probe killed on a loaded box).
+    sf "classifier scores somebody else's raise misattributed" \
+       "$(verdict eigs_no_such_builtin_1007 '42')" RAISED-OTHER
+    _sweep_savebin="$BIN"; BIN=/bin/false
+    sf "classifier scores a killed child UNRUN, not a guard verdict" \
+       "$(verdict gfx_rect '42')" UNRUN
+    BIN="$_sweep_savebin"
+    echo "selftest: $sf_pass passed, $sf_fail failed"
+    [ "$sf_fail" -eq 0 ] || exit 1
+    exit 0
+fi
+
+# --------------------------------------------------------------------- sweep
+echo "== #1007 container-shape sweep =="
+[ -x "$BIN" ] || { echo "FAIL: no built binary at $BIN"; exit 1; }
+# NOT `"$BIN" ... | grep -q`: this script runs under `set -o pipefail`, and the
+# probe program EXITS NONZERO on the very build the probe is looking for (the
+# undefined-variable error is the signal), so the pipeline's status was 1 even
+# when grep matched and the skip never fired. Measured: the release lane ran the
+# whole sweep against a binary with no gfx builtins and reported 140
+# MISATTRIBUTED rows. Capture, then match with a case-glob -- no pipeline, and
+# no subprocess whose failure could decide the answer.
+printf 'ignore is gfx_text_height of null\n' > "$TMP/probe.eigs"
+probe_out="$("$BIN" "$TMP/probe.eigs" 2>&1)" || true
+case "$probe_out" in
+    *"undefined variable"*)
+        echo "  SKIP: $BIN was built without EIGENSCRIPT_EXT_GFX"
+        exit 0 ;;
+esac
+
+# One leading newline so the first allowlist row matches the same glob as the
+# rest, and so `${ALLOW_NL#*...}` can find it.
+ALLOW_NL="
+$ALLOW"
+PROBED=""
+rc=0; n_rows=0; n_raised=0; n_silent=0; n_other=0; n_allowed=0; n_unrun=0
+silent_list=""; other_list=""; used_allow=""
+for name in $NAMES; do
+    ar=$(arity_of "$name")
+    case "$ar" in
+        ''|*[!0-9]*) echo "  FAIL: could not derive an arity for $name (the awk"
+                     echo "        pass produced '$ar'); a missing arity would"
+                     echo "        silently pick the wrong probe shapes."
+                     rc=1; continue ;;
+    esac
+    if [ "$ar" -ge 2 ]; then shapes="short scalar string dict"
+    else                     shapes="scalar string dict list2"; fi
+    for sh in $shapes; do
+        txt="$(shape_text "$sh" "$ar")"
+        [ -z "$txt" ] && continue
+        n_rows=$((n_rows + 1))
+        PROBED="$PROBED
+$name|$sh"
+        v="$(verdict "$name" "$txt")"
+        # Same rule as the pinned-name check above: no subprocess, so a fork
+        # that fails cannot masquerade as "not allowlisted".
+        allowed=""
+        case "$ALLOW_NL" in
+            *"
+$name|$sh|"*) rest="${ALLOW_NL#*"
+$name|$sh|"}"; allowed="${rest%%
+*}" ;;
+        esac
+        case "$v" in
+            RAISED-OWN)
+                n_raised=$((n_raised + 1))
+                if [ -n "$allowed" ]; then
+                    other_list="$other_list
+    STALE ALLOWLIST $name|$sh — it raises now; delete the entry"
+                    rc=1
+                fi ;;
+            RAISED-OTHER)
+                n_other=$((n_other + 1))
+                other_list="$other_list
+    MISATTRIBUTED $name of $txt — raised, but not from $name's own guard"
+                rc=1 ;;
+            UNRUN)
+                n_unrun=$((n_unrun + 1))
+                other_list="$other_list
+    DID NOT RUN $name of $txt — nonzero exit, no runtime error, 3 attempts; last output:
+$(sed -n '1,3p' "$TMP/last.out" | sed 's/^/      /')"
+                rc=1 ;;
+            SILENT)
+                if [ -n "$allowed" ]; then
+                    n_allowed=$((n_allowed + 1))
+                    used_allow="$used_allow
+    allowed $name of $txt — $allowed"
+                else
+                    n_silent=$((n_silent + 1))
+                    silent_list="$silent_list
+    SILENT UNDER STRICT: $name of $txt"
+                    rc=1
+                fi ;;
+        esac
+    done
+done
+
+echo "  guarded names=$n_names  rows=$n_rows"
+echo "  raises-under-strict: $n_raised   silent: $n_silent   misattributed: $n_other   did-not-run: $n_unrun"
+echo "  quiet on purpose (allowlisted): $n_allowed"
+# Retries are not failures, but a box that needed them is a box whose numbers
+# deserve a caveat, so they are printed rather than swallowed.
+[ -s "$TMP/retries" ] && { echo "  probes retried after a killed child: $(wc -l < "$TMP/retries")"; sed 's/^/    /' "$TMP/retries"; }
+[ -n "${SWEEP_VERBOSE:-}" ] && [ -n "$used_allow" ] && echo "$used_allow"
+[ -n "$silent_list" ] && echo "$silent_list"
+[ -n "$other_list" ]  && echo "$other_list"
+
+# An allowlist entry that nothing PROBES is stale in the other direction, and
+# the raises-now check above cannot see it: six such entries shipped in the
+# first draft of this file (`audio_open|list2` and friends, for a shape that
+# is only probed on arity-1 builtins), each quietly waiving nothing. A waiver
+# for a question never asked is the tidiest way to look covered.
+while IFS= read -r entry; do
+    [ -z "$entry" ] && continue
+    key="${entry%%|*}"; rest="${entry#*|}"; key="$key|${rest%%|*}"
+    case "$PROBED" in
+        *"
+$key"*) ;;
+        *) echo "  DEAD ALLOWLIST $key — no probe ever asks this pair; delete it"
+           rc=1 ;;
+    esac
+done <<EOF
+$ALLOW
+EOF
+
+# A pinned name that has left the population means its guard is gone, and a
+# derived population cannot notice that on its own.
+if [ -n "$MISSING" ]; then
+    echo "  GUARD REMOVED — pinned builtins no longer carry any guard in $SRC:$MISSING"
+    echo "  They are therefore unswept. Restore the guard, or delete the name from"
+    echo "  REQUIRED_NAMES in this file and say why in the commit."
+    rc=1
+fi
+
+# Non-vacuity floors. Without them a broken extractor sweeps nothing and
+# reports OK -- the exact failure mode this tool was written to replace.
+if [ "$n_names" -lt 25 ] || [ "$n_rows" -lt 90 ] || [ "$n_raised" -lt 70 ]; then
+    echo "  VACUOUS: names=$n_names rows=$n_rows raised=$n_raised — below the floor;"
+    echo "  the extractor or the binary is wrong, not the guards."
+    rc=1
+fi
+
+[ "$rc" -eq 0 ] && echo "OK" || echo "FAIL"
+exit $rc
diff --git a/tools/strict_differential.sh b/tools/strict_differential.sh
index 8dfc7d2a..b24d7ccd 100755
--- a/tools/strict_differential.sh
+++ b/tools/strict_differential.sh
@@ -81,6 +81,14 @@ cd "$(cd "$(dirname "$0")/.." && pwd)"
 NEW="${EIGS_DIFF_NEW:-./src/eigenscript}"
 BASE="${1:-}"
 
+# #1007 put probes on the gfx/audio surface. They never open a window (the
+# guards all sit ABOVE the SDL load, which is the point of #1018's [135]
+# gate), but SDL is dlopen'd lazily and a probe that DID reach it must not
+# block on a real display or sound card. Only set when unset, so a caller
+# can still point the harness at a real driver.
+export SDL_VIDEODRIVER="${SDL_VIDEODRIVER:-dummy}"
+export SDL_AUDIODRIVER="${SDL_AUDIODRIVER:-dummy}"
+
 # --no-baseline runs every half EXCEPT identical-when-off, and passes on those.
 # It exists so CI has something: without it this tool only ever runs on a dev
 # box that happens to have built the parent commit, and a harness nobody runs
@@ -217,6 +225,18 @@ trap _sd_exit EXIT
 # ARG_GUARD reports, which is what the cross-check below matches on. The
 # optional third field is the message substring the raise must carry when
 # it is not ARG_GUARD's "<who>: expected" (the NaN and domain rows).
+#
+# A name may appear on MORE THAN ONE row, and for the three audio *_open
+# builtins it must. Holding arity right and varying only the element TYPE
+# measures exactly one axis, and #1007 shipped a first version whose guards
+# were NESTED inside a `count >= 2` shape test: every wrong-typed row went
+# loud while a SHORT list walked past the guard, opened the device at the
+# 44100/1 defaults and answered a real device id. `raises-under-strict: N,
+# silent: 0` was true and the surface was still silently succeeding, because
+# the table only ever asked the question in the state where it could not
+# fail. So the openers carry a short-list row (and audio_open a non-list
+# row) beside the wrong-typed one, and the well-formed `of null` /
+# `of [freq, channels]` forms sit in VALID below as the over-broad control.
 PROBES=$(cat <<'EOF'
 abs|print of (abs of "x")
 acos|print of (acos of "x")
@@ -301,6 +321,13 @@ gfx_open|print of (gfx_open of ["800", "600", "t"])
 audio_open|print of (audio_open of ["44100", "1"])
 audio_capture_open|print of (audio_capture_open of ["44100", "1"])
 audio_stream_open|print of (audio_stream_open of ["44100", "1"])
+audio_open|print of (audio_open of [44100])
+audio_capture_open|print of (audio_capture_open of [44100])
+audio_stream_open|print of (audio_stream_open of [48000])
+audio_open|print of (audio_open of 44100)
+audio_play|print of (audio_play of 42)
+audio_stream_push|print of (audio_stream_push of 42)
+audio_play_loop|print of (audio_play_loop of [42, 2])
 audio_sine|print of (len of (audio_sine of ["440", 0.01, 0.5]))
 audio_saw|print of (len of (audio_saw of ["440", 0.01, 0.5]))
 audio_square|print of (len of (audio_square of ["440", 0.01, 0.5]))
@@ -329,6 +356,28 @@ json_build|print of (json_build of ({"a": 1}))
 sort|print of (sort of ({"a": 1}))
 random_int|print of (random_int of ["a", 3])
 random_hex|print of (random_hex of "x")
+audio_mix|print of (len of (audio_mix of [42, ([0.1])]))
+audio_music_play|print of (audio_music_play of [42])
+audio_music_volume|print of (audio_music_volume of "loud")
+audio_pause|print of (audio_pause of "x")
+audio_play_loop|print of (audio_play_loop of [([0.1]), "2"])
+audio_stop|print of (audio_stop of "x")
+audio_volume|print of (audio_volume of ["1", 1])
+gfx_circle|print of (gfx_circle of ["1", 2, 3, 4, 5, 6])
+gfx_clear|print of (gfx_clear of ["1", 2, 3])
+gfx_clip|print of (gfx_clip of ["1", 2, 3, 4])
+gfx_delay|print of (gfx_delay of "5")
+gfx_fb|print of (gfx_fb of [42, 4, 4, 0, 0, 1])
+gfx_line|print of (gfx_line of ["0", 0, 10, 10, 1, 2, 3])
+gfx_point|print of (gfx_point of ["1", 2, 3, 4, 5])
+gfx_read|print of (gfx_read of ["1", 1])
+gfx_rect|print of (gfx_rect of ["10", 10, 50, 50, 255, 0, 0])
+gfx_rrect|print of (gfx_rrect of ["1", 2, 3, 4, 5, 6, 7, 8])
+gfx_text|print of (gfx_text of [1, 2, "hi", "255", 0, 0])
+gfx_text_height|print of (gfx_text_height of "2")
+gfx_text_width|print of (gfx_text_width of 5)
+gfx_title|print of (gfx_title of 42)
+ppu_render_frame|print of (ppu_render_frame of [1, 2])
 EOF
 )
 # A probe that needs a real resource must build it under this run's own $TMP,
@@ -449,6 +498,29 @@ print of (json_build of ["k", 1])
 print of (sort of [3, 1, 2])
 seed_random of 7\nprint of (random_int of [1, 1])
 print of (len of (random_hex of 4))
+print of (gfx_text_width of ["hello", 2])
+print of (gfx_text_width of "hello")
+print of (gfx_text_height of 3)
+print of (gfx_text_height of null)
+print of (gfx_rect of [0, 0, 1, 1, 1, 2, 3])
+print of (gfx_rect of [0, 0, 1, 1, 1, 2, 3, 128])
+print of (gfx_clear of [1, 2, 3])
+print of (gfx_clip of null)
+print of (gfx_poll of null)
+print of (gfx_read of [0, 0])
+print of (audio_mix of [[0.5], [0.25, 0.25]])
+print of (audio_gain of [[1.0], 0.5])
+print of (audio_stop of 1)
+print of (audio_volume of [1, 0.5])
+print of (audio_open of null)
+print of (audio_capture_open of null)
+print of (audio_stream_open of null)
+print of (audio_open of [44100, 1])
+print of (audio_capture_open of [44100, 1])
+print of (audio_stream_open of [44100, 1])
+print of (audio_play of null)
+print of (audio_stream_push of null)
+print of (audio_play of [0.1, 0.2])
 EOF
 )
 
@@ -748,11 +820,67 @@ extract_guard_names() {
 
 release_srcs="$(make print-SRC_V_release 2>/dev/null | tr ' ' '\n' | sed '/^$/d' | sort -u)"
 variant_only=""
+absent_here=""
+
+# PRESENCE IS PROBED ONCE PER FILE, NOT ONCE PER NAME, and the probe carries
+# a SENTINEL (#1007). Both halves were bought on the same run.
+#
+# Per file: every builtin in a translation unit is registered together (one
+# `register_*_builtins` seam behind one -D flag), so a name's presence is a
+# property of its FILE. #1007 took ext_gfx.c's guarded-name count from 3 to
+# 33, which turned this loop from 3 interpreter launches into 34 — on a
+# loaded box, under ASan, 34 chances for one launch to come back wrong.
+#
+# Sentinel: without it, "the output does not say 'undefined variable'" was
+# read as "the name is present", so a launch that produced NO output at all
+# — killed, out of memory, a sanitizer abort — silently classified every
+# name in the file as present, its probe then failed with "undefined
+# variable", and the tool reported `misattributed` for a reason that has
+# nothing to do with the code under test. Observed once in a full ASan suite
+# run (2026-09-07) and green on the diagnostic re-run, which is exactly the
+# shape of a flake nobody can act on. An exit status can miss that shape (a
+# child killed after its parent has already read a clean 0), so BOTH tests
+# run and either one puts the file in the DID NOT RUN bucket below, which is
+# red and names the environment rather than a guard.
 if [ -n "$release_srcs" ]; then
     for f in src/*.c; do
         str_has_line "$release_srcs" "$f" && continue
+        # The slash forms ("sqrt/exp/log/negative") are trimmed to the first
+        # component here, because that is the spelling a program can call and
+        # the spelling probe_builtin_present compares against.
+        f_names="$(extract_guard_names "$f" | sed 's,/.*,,' | sed '/^$/d' | sort -u)"
+        [ -z "$f_names" ] && continue
         variant_only="$variant_only
-$(extract_guard_names "$f")"
+$f_names"
+        rep="$(printf '%s\n' "$f_names" | head -1)"
+        printf 'print of "eigs-probe-ran"\nprint of %s\n' "$rep" > "$TMP/present.eigs"
+        # Capture, THEN match. Under `set -o pipefail` a pipeline reports the
+        # rightmost nonzero status, and the probe program exits 1 by design
+        # when the name is undefined — so `prog | grep -q` returned 1 on a
+        # successful match and every absent builtin read as present.
+        _present_out="$("$NEW" "$TMP/present.eigs" 2>&1)"; _present_rc=$?
+        # A presence check that did not RUN is not a "present" answer, and it
+        # is not an "absent" one either. Assuming present sends every probe in
+        # the file to a guard that is not there, where it dies "undefined
+        # variable" and is scored RAISED BY THE WRONG GUARD — an environment
+        # fact charged to a guard, which is the #1120 shape arriving by a
+        # second road. Same bucket as an unrun probe: named, red, and not a
+        # finding about the code.
+        _why="$(run_did_not_measure "$_present_rc")"
+        if [ -z "$_why" ] && ! str_has "$_present_out" "eigs-probe-ran"; then
+            _why="the probe printed no sentinel, so it never reached its first statement"
+        fi
+        if [ -n "$_why" ]; then
+            n_unrun=$((n_unrun + 1))
+            unrun_list="$unrun_list
+    presence check for $f (representative: $rep) — $_why"
+            record_evidence unrun "presence:$f" "" "$_present_rc
+$_present_out"
+            continue
+        fi
+        if str_has "$_present_out" "undefined variable"; then
+            absent_here="$absent_here $(printf '%s\n' "$f_names" | tr '\n' ' ')"
+        fi
     done
     variant_only="$(printf '%s\n' "$variant_only" | sed '/^$/d' | sort -u)"
 else
@@ -762,33 +890,6 @@ else
     echo "  NOTE: 'make print-SRC_V_release' gave nothing — variant-only detection off"
 fi
 
-absent_here=""
-for v in $variant_only; do
-    printf 'print of %s\n' "${v%%/*}" > "$TMP/present.eigs"
-    # Capture, THEN match. Under `set -o pipefail` a pipeline reports the
-    # rightmost nonzero status, and the probe program exits 1 by design when
-    # the name is undefined — so `prog | grep -q` returned 1 on a successful
-    # match and every absent builtin read as present.
-    _present_out="$("$NEW" "$TMP/present.eigs" 2>&1)"; _present_rc=$?
-    # A presence check that did not RUN is not a "present" answer. Assuming
-    # present sends the probe in, where it dies "undefined variable" and is
-    # scored RAISED BY THE WRONG GUARD — an environment fact charged to a
-    # guard, which is the #1120 shape arriving by a second road. Same bucket
-    # as an unrun probe: named, red, and not a finding about the code.
-    _why="$(run_did_not_measure "$_present_rc")"
-    if [ -n "$_why" ]; then
-        n_unrun=$((n_unrun + 1))
-        unrun_list="$unrun_list
-    presence check for ${v%%/*} — $_why"
-        record_evidence unrun "presence:${v%%/*}" "" "$_present_rc
-$_present_out"
-        continue
-    fi
-    case "$_present_out" in
-        *"undefined variable"*) absent_here="$absent_here ${v%%/*}" ;;
-    esac
-done
-
 # A probe is runnable unless its builtin is a variant-only one this build
 # does not contain.
 probe_builtin_present() {
diff --git a/tools/werror_switch_check.sh b/tools/werror_switch_check.sh
index d84d8b77..b5283ed2 100755
--- a/tools/werror_switch_check.sh
+++ b/tools/werror_switch_check.sh
@@ -236,7 +236,11 @@ SCRIPT_ENROLL_PINS="tools/amalgamate.sh:254253ab8bb08531 tests/test_lint_linkage
 # decision on record. test_leak_guard.sh:56 compiles the ENTIRE runtime
 # ($SRCS, the largest compile surface in the tree) and carried NEITHER
 # required flag until this change.
-SCRIPT_AUDITS="build.sh tools/freestanding_check.sh tools/freestanding_smoke.sh tools/embed_stack_soak.sh tools/core_ext_boundary_check.sh web/build.sh tests/test_leak_guard.sh tests/run_all_tests.sh"
+# tests/test_asan_gfx.sh joined in #1007: it builds its own asan-gfx
+# interpreter (deliberately not via `make`, which would re-point
+# src/eigenscript under the suite) plus two leak controls, so four real
+# compile invocations that no make target covers.
+SCRIPT_AUDITS="build.sh tools/freestanding_check.sh tools/freestanding_smoke.sh tools/embed_stack_soak.sh tools/core_ext_boundary_check.sh web/build.sh tests/test_leak_guard.sh tests/test_asan_gfx.sh tests/run_all_tests.sh"
 
 # Comment lines must not be examined: a script comment QUOTING a bare
 # compile line is not a compile.
@@ -310,6 +314,7 @@ script:tools/embed_stack_soak.sh 1
 script:tools/core_ext_boundary_check.sh 1
 script:web/build.sh 1
 script:tests/test_leak_guard.sh 2
+script:tests/test_asan_gfx.sh 4
 script:tests/run_all_tests.sh 1
 '
 

From a86e86c1ac832582ef0800b76887975bb7d30308 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 05:26:54 +0000
Subject: [PATCH 37/39] changelog: the #1007 ext_gfx entry

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A8rPrmr564H7yB2tQ6DwV9
---
 CHANGELOG.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f835acee..17fd394a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -106,6 +106,43 @@ All notable changes to EigenScript are documented here.
 
 ### Fixed
 
+- **`EIGS_STRICT=1` reaches the graphics and audio extension (#1007).**
+  `src/ext_gfx.c` had no raise path at all — `grep -c rt_error src/ext_gfx.c`
+  was 0 — while ~89 argument reads went straight through `items[N]->data.num`,
+  and `Value`'s union overlaps `double num` with `char *str`, so a string
+  where a number belonged reinterpreted a pointer as a double. `gfx_rect of
+  [10, 10, 50, 50, "255", 0, 0]` drew a BLACK rectangle where red was asked
+  for, and ~52 `make_null()` returns stood in for a rejected argument,
+  indistinguishable from the same builtin's ordinary "nothing to do" answer.
+  60 `ARG_GUARD`/`STRICT_REQUIRE` sites now cover the drawing calls, the text
+  calls, `gfx_fb`, `ppu_render_frame`, the generators, the mixer and the three
+  device openers; every one sits above the `load_sdl2()` call and above any
+  device check, so it is reachable where CI runs, and the two trace-recorded
+  builtins (`gfx_read`, `audio_capture_open`) guard above the tape seam so a
+  rejected argument neither consumes nor writes a record. The union pun is
+  gone in BOTH modes: what a rejected call *draws* changes, every returned
+  value stays byte-identical. A guard covers the argument's CONTAINER as well
+  as its elements — three rounds of blind review found the same axis three
+  times, most sharply in the openers, where `audio_stream_open of [48000]`
+  opened the device at the 44100/1 defaults and handed back a real device id,
+  telling a caller that asked for 48000 that it got 48000. Four gates carry
+  it: `tools/gfx_strict_sweep.sh` (section [139]) derives the guarded names
+  and their arity from the file's own `want` strings and crosses them with the
+  wrong-container shapes — 35 names, 140 rows, 129 raises, 11 in a
+  staleness-checked allowlist; `tools/gfx_pixel_differential.sh` (section
+  [138]) is the readback oracle, because every drawing builtin returns null on
+  every path and a returned-value differential measures that surface in the
+  one state where it cannot fail; `tests/test_asan_gfx.sh` (section [137])
+  makes `make asan-gfx` a gate over a six-program corpus, with its own
+  positive and negative leak controls — its triage found one leak and it was
+  ours (`gfx_poll`'s event dict, 584 bytes on the two decode-nothing paths),
+  so no LeakSanitizer suppression ships; and `tools/failsoft_classify_check.sh`
+  scopes `return make_null()` into the classified population for this one file
+  (`NULL_SCOPE`, floor 136 -> 174, new `fs:VOID` tag). A builtin that takes no
+  argument still ignores one and a surplus trailing argument is still dropped;
+  both are the general over-arity question (#989) and are stated in
+  `docs/BUILTINS.md` rather than left to be discovered.
+
 - **Three `EIGS_STRICT` guards leaked their own allocation on every raise
   (#971 round 2).** `STRICT_REQUIRE` returns, so it has to sit above anything
   the function already owns; in `scan_ints`, `scan_tokens` and

From a2fc74927a4bd1bbe9dd06aa9203dbcc57fa194b Mon Sep 17 00:00:00 2001
From: InauguralPhysicist <InauguralPhysicist@gmail.com>
Date: Tue, 8 Sep 2026 14:07:46 -0500
Subject: [PATCH 38/39] observer_gate_diff: corpus() falls back to find when
 git ls-files is empty (#1124 CI)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The #1115 self-test derives 3 corpus names from corpus() = git ls-files '*.eigs'.
In the CI devcontainer git returns nothing (dubious-ownership / detached checkout),
so the self-test found 0 corpus names and failed (rc=2) on both linux lanes,
cascading to the [99p] child-exit ledger. Locally git worked, so it passed —
the observer corpus is a CI-only surface. Fall back to a find walk of the same
tree (cd'd to $REPO) when git ls-files is empty, excluding .git/build/captures/
eigs_modules. Verified: selftest 9/9 with git, and 9/9 in a .git-less copy where
git ls-files returns 0.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Kpzyjv1SaLaqBf45FSFDhB
---
 tools/observer_gate_diff.sh | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/tools/observer_gate_diff.sh b/tools/observer_gate_diff.sh
index 8f755976..e9cb7dea 100755
--- a/tools/observer_gate_diff.sh
+++ b/tools/observer_gate_diff.sh
@@ -166,7 +166,25 @@ is_denied() {
     esac
 }
 
-corpus() { git ls-files '*.eigs' | sort; }
+corpus() {
+    # git ls-files is the source of truth for the TRACKED corpus, but it
+    # returns nothing when git refuses the checkout (dubious ownership / a
+    # detached devcontainer checkout — the selftest found 0 corpus names on
+    # the CI linux lanes, #1124). Fall back to a filesystem walk of the same
+    # tree (we are cd'd to $REPO), excluding non-corpus trees, so the selftest
+    # and the compare both have a corpus wherever git is unavailable.
+    local out
+    out=$(git ls-files '*.eigs' 2>/dev/null)
+    if [ -z "$out" ]; then
+        out=$(find . -name '*.eigs' -type f \
+                -not -path './.git/*' \
+                -not -path './build/*' \
+                -not -path './.observer_gate_captures/*' \
+                -not -path '*/eigs_modules/*' \
+                2>/dev/null | sed 's|^\./||')
+    fi
+    printf '%s\n' "$out" | sort
+}
 
 # Pure bash: this runs once per corpus entry per compare (520 x 9 in the
 # selftest); with a `tr` subprocess each time the selftest took 12.6s, pure

From 1773b18e86c5db208db5b2c581677eafcec2defe Mon Sep 17 00:00:00 2001
From: InauguralPhysicist <InauguralPhysicist@gmail.com>
Date: Tue, 8 Sep 2026 14:27:28 -0500
Subject: [PATCH 39/39] observer_corpus: regenerate 6 goldens for the
 #1044/#1045 verdict shift
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The configurable window depth and scale-free relative step (#1044/#1045) change
when the value-channel predicates fire — deliberately. #1045 fixed the
unit-dependent early convergence (rel=dv/(1+|v|) degenerating to an absolute
deadband below |v|~1), so a decaying-toward-zero signal now stays 'improving'
until it is RELATIVELY flat instead of converging at a fixed absolute
threshold: observer_predicates converges at step 201 (was 118), numerical/idioms
run more steps, physics/solve drop a converged flag on two trajectories. All six
programs run clean (0 errors, sensible output); only the observer VERDICTS
shifted. The observer corpus run (tests/observer_corpus/run.sh) is not wired into
the local suite (CI-only), so the goldens were not recaptured with the change.
Recaptured on the branch binary: 14 match, 0 diverge. The 8 unaffected goldens
are byte-identical.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Kpzyjv1SaLaqBf45FSFDhB
---
 .../golden/EigenScript__idioms.out            |  2 +-
 .../golden/EigenScript__numerical.out         | 18 +++++++----
 .../EigenScript__observer_predicates.out      | 30 +++++++++++++++----
 .../EigenScript__structural_observer.out      |  8 ++---
 .../golden/dynamics__physics.out              |  4 +--
 .../golden/dynamics__solve.out                |  6 ++--
 6 files changed, 47 insertions(+), 21 deletions(-)

diff --git a/tests/observer_corpus/golden/EigenScript__idioms.out b/tests/observer_corpus/golden/EigenScript__idioms.out
index 495a9d5a..b6598523 100644
--- a/tests/observer_corpus/golden/EigenScript__idioms.out
+++ b/tests/observer_corpus/golden/EigenScript__idioms.out
@@ -43,4 +43,4 @@ diana: index 3
 frank: index -1
 
 --- convergence with safety limit ---
-Converged at step 176 x=0.012004788991027214
+Converged at step 311 x=1.1804327357121166e-05
diff --git a/tests/observer_corpus/golden/EigenScript__numerical.out b/tests/observer_corpus/golden/EigenScript__numerical.out
index 465587cf..9d46132e 100644
--- a/tests/observer_corpus/golden/EigenScript__numerical.out
+++ b/tests/observer_corpus/golden/EigenScript__numerical.out
@@ -9,7 +9,7 @@ Root: 1.5213796943426132
 f(root) = -7.407122248892506e-08
 
 --- Fixed Point: cos(x) = x ---
-Fixed point: 0.7390713652989449
+Fixed point: 0.739078885994992
 Observer status: equilibrium
 
 --- Exponential Decay ---
@@ -26,10 +26,18 @@ Step 50: value=0.02957646637126989 status=improving
 Step 55: value=0.013123235253910044 status=improving
 Step 60: value=0.005822849199347172 status=improving
 Step 65: value=0.0025836291236367107 status=improving
-Step 70: value=0.0011463699676873278 status=converged
-Converged at step 70 with value 0.0011463699676873278
+Step 70: value=0.0011463699676873278 status=improving
+Step 75: value=0.0005086504447533207 status=improving
+Step 80: value=0.00022569090454253608 status=improving
+Step 85: value=0.00010014025332845363 status=improving
+Step 90: value=4.4432762396930686e-05 status=improving
+Step 95: value=1.971505272456838e-05 status=improving
+Step 100: value=8.747673630108587e-06 status=improving
+Step 105: value=3.881389261695339e-06 status=improving
+Step 110: value=1.7221930352946745e-06 status=improving
+Converged at step 112 with value 1.2442844680004022e-06
 
 --- Gradient Descent: minimize (x-3)^2 ---
-Minimum at x = 3.001817303900487
-f(x) = 3.302593466725101e-06
+Minimum at x = 3.0014538431203897
+f(x) = 2.1136598187043226e-06
 Status: converged
diff --git a/tests/observer_corpus/golden/EigenScript__observer_predicates.out b/tests/observer_corpus/golden/EigenScript__observer_predicates.out
index cabb5fff..15420197 100644
--- a/tests/observer_corpus/golden/EigenScript__observer_predicates.out
+++ b/tests/observer_corpus/golden/EigenScript__observer_predicates.out
@@ -14,10 +14,19 @@ sqrt(0.01) = 0.1
   step 90: improving signal=0.05506865395042193
   step 100: improving signal=0.023921187465699906
   step 110: improving signal=0.010391087646419113
-Converged at step 118 signal=0.005332902292568855
+  step 120: improving signal=0.004513768500430279
+  step 130: improving signal=0.0019607289216252324
+  step 140: improving signal=0.0008517180054163542
+  step 150: improving signal=0.0003699764678072454
+  step 160: improving signal=0.00016071350594990878
+  step 170: improving signal=6.981209142244144e-05
+  step 180: improving signal=3.0325566479113236e-05
+  step 190: improving signal=1.3173075946317996e-05
+  step 200: improving signal=5.722232097691588e-06
+Converged at step 201 signal=5.264453529876261e-06
 
 --- stable as early detection ---
-Converged at step 91 value=0.003427980662063994
+Converged at step 157 value=3.273738503506898e-06
 
 --- improving as progress monitor ---
   step 10: improving, value=15.749952347257809
@@ -32,14 +41,23 @@ Converged at step 91 value=0.003427980662063994
   step 55: improving, value=0.010498588203128042
   step 60: improving, value=0.0046582793594777405
   step 65: improving, value=0.00206690329890937
-Done at step 68 value=0.0012693369884427168 status=converged
+  step 70: improving, value=0.0009170959741498628
+  step 75: improving, value=0.00040692035580265683
+  step 80: improving, value=0.00018055272363402898
+  step 85: improving, value=8.011220266276296e-05
+  step 90: improving, value=3.5546209917544564e-05
+  step 95: improving, value=1.5772042179654708e-05
+  step 100: improving, value=6.998138904086872e-06
+  step 105: improving, value=3.105111409356272e-06
+  step 110: improving, value=1.37775442823574e-06
+Done at step 111 value=1.171091264000379e-06 status=converged
 
 --- regime detection ---
 Step 1: start -> moving
 Step 6: moving -> improving
-Step 78: improving -> converged
+Step 133: improving -> converged
 Total regime changes: 3
-Final loss: 0.002336783255831447
+Final loss: 2.066166902105908e-06
 
 --- oscillating as instability detector ---
   step 5: oscillating! lr halved to 0.6
@@ -52,4 +70,4 @@ Final loss: 0.002336783255831447
   step 12: oscillating! lr halved to 0.0046875
   step 13: oscillating! lr halved to 0.00234375
   step 14: oscillating! lr halved to 0.001171875
-Done at step 23 x=4.028419306289019 lr=0.001171875 adjustments=10
+Done at step 24 x=4.030696448539904 lr=0.001171875 adjustments=10
diff --git a/tests/observer_corpus/golden/EigenScript__structural_observer.out b/tests/observer_corpus/golden/EigenScript__structural_observer.out
index f8e3054a..0abb0d3c 100644
--- a/tests/observer_corpus/golden/EigenScript__structural_observer.out
+++ b/tests/observer_corpus/golden/EigenScript__structural_observer.out
@@ -1,9 +1,9 @@
 equilibrium
 moving
 ["moving", 0.7219280948873623, -0.19636773916712724, -0.08170416594551044]
-0.0032791850478503127
+3.479597728084419e-06
 4
 1
-0.0012918145618183554
-0.0032387012818274703
-3.001817303900487
+1.191829090169325e-06
+3.4366397314414046e-06
+3.0014538431203897
diff --git a/tests/observer_corpus/golden/dynamics__physics.out b/tests/observer_corpus/golden/dynamics__physics.out
index df0158b4..5521d2de 100644
--- a/tests/observer_corpus/golden/dynamics__physics.out
+++ b/tests/observer_corpus/golden/dynamics__physics.out
@@ -4,10 +4,10 @@ observe ENERGY (Lyapunov) vs DISPLACEMENT (oscillation); flags = regime visited
   zeta     | E:osc conv div grew | x:osc conv div | reading
   -0.05	| E:Y - - Y     | x:Y - -      | DIVERGES (energy grew)
   0	| E:Y - - -     | x:Y - -      | x OSCILLATES, energy settles
-  0.1	| E:- Y - -     | x:Y - -      | x OSCILLATES, energy settles
+  0.1	| E:- - - -     | x:Y - -      | x OSCILLATES, energy settles
   0.4	| E:- Y - -     | x:Y Y -      | x OSCILLATES, energy settles
   1	| E:- Y - -     | x:- Y -      | settles
-  2	| E:- Y - -     | x:- Y -      | settles
+  2	| E:- Y - -     | x:- - -      | settles
 
 the gem is the zeta=0 row: energy conserved -> never converges, while x
 oscillates. Same system, opposite verdict, set by what the observer watches.
diff --git a/tests/observer_corpus/golden/dynamics__solve.out b/tests/observer_corpus/golden/dynamics__solve.out
index 47715aa8..6124e492 100644
--- a/tests/observer_corpus/golden/dynamics__solve.out
+++ b/tests/observer_corpus/golden/dynamics__solve.out
@@ -3,12 +3,12 @@ every loop runs until `report of change` is settled and HOLDs — the observer,
 not a magnitude tolerance, decides when to stop. (iters include the hold)
 
 Jacobi        Ax=b -> <buffer:3>
-              19 iters
+              27 iters
 Gauss-Seidel  Ax=b -> <buffer:3>
-              17 iters  (fresh values -> fewer than Jacobi)
+              21 iters  (fresh values -> fewer than Jacobi)
 
 Power iteration dominant eigenvalue -> 2  (14 iters, expect ~2)
 
-PageRank stationary distribution -> <buffer:3>  (24 iters)
+PageRank stationary distribution -> <buffer:3>  (44 iters)
 
 DONE