From 780abed20a111cfedbc5833529557a574a18cf78 Mon Sep 17 00:00:00 2001
From: Estevao Fonseca <estevaopfon@gmail.com>
Date: Sat, 5 Sep 2026 17:59:19 -0400
Subject: [PATCH 1/2] chore(benchmarks): runners em bash para Linux/macOS e
 primeiro cross-runtime em Ubuntu
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Porta os três runners PowerShell para bash com o mesmo protocolo e a mesma
saída: `run_benchmarks.sh` (suíte por binário, mediana), `interleaved_compare.sh`
(dois binários intercalados, guard de CHECKSUM, benches sem equivalência
pulados e listados) e `cross_runtime/run_cross_runtime.sh` (Noxy × CPython ×
Lua × Go, mínimo de N, coluna `--noxy-baseline` na mesma janela, líquido e
razões). Números saem com ponto decimal fixo (`LC_NUMERIC=C`).

`run_benchmarks.sh` pula e lista bench sem linha CHECKSUM em vez de abortar,
como o intercalado já faz: hoje `bench_bst_owned`/`bench_bst_ref` não compilam
na v0.25.0 (construtor com `null` em campo não-anulável) e `bench_hash31_bytes`
nunca imprimiu CHECKSUM — o `.ps1` aborta no primeiro deles.

Adiciona `cross_runtime/results/2026-09-05-v0250-ubuntu.md`: primeira medição
em Linux (Ubuntu 26.04, CPython 3.14.4 do pacote, Go 1.27.1). As razões
noxy/python são piores que as do Windows (fib 1,16x → 1,80x) porque o build
gcc + PGO/LTO do CPython no Linux é mais rápido que o build MSVC; o Noxy
rende igual nos três binários disponíveis.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013tLpxkXEQZgrHZaQdAj1c7
---
 AGENTS.md                                     |   3 +-
 benchmarks/RESULTS.md                         |  11 ++
 benchmarks/cross_runtime/README.md            |  14 +-
 .../results/2026-09-05-v0250-ubuntu.md        |  83 ++++++++
 benchmarks/cross_runtime/run_cross_runtime.sh | 186 ++++++++++++++++++
 benchmarks/interleaved_compare.sh             |  66 +++++++
 benchmarks/run_benchmarks.sh                  |  62 ++++++
 7 files changed, 423 insertions(+), 2 deletions(-)
 create mode 100644 benchmarks/cross_runtime/results/2026-09-05-v0250-ubuntu.md
 create mode 100755 benchmarks/cross_runtime/run_cross_runtime.sh
 create mode 100755 benchmarks/interleaved_compare.sh
 create mode 100755 benchmarks/run_benchmarks.sh

diff --git a/AGENTS.md b/AGENTS.md
index 1ad4a91f..2b7d5dc2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -58,7 +58,8 @@ lugar errado foi tocado; não afrouxe o teste:
 
 Benchmarks em `benchmarks/`: `pwsh -NoProfile -File interleaved_compare.ps1`
 (dois binários intercalados — a única comparação que vale), máquina ociosa,
-delta só na mesma sessão; `compare_examples.ps1` captura a saída dos exemplos
+delta só na mesma sessão; em Linux/macOS os mesmos runners existem em bash
+(`interleaved_compare.sh`, `run_benchmarks.sh`, `cross_runtime/run_cross_runtime.sh`); `compare_examples.ps1` captura a saída dos exemplos
 antes/depois ao mexer no runtime. CI (`.github/workflows/network-deadlines.yml`):
 testes Go em ubuntu+windows, `-race` em `internal/vm`, o runner, cross-build
 com `CGO_ENABLED=0`.
diff --git a/benchmarks/RESULTS.md b/benchmarks/RESULTS.md
index 7e9e6ce9..7acec197 100644
--- a/benchmarks/RESULTS.md
+++ b/benchmarks/RESULTS.md
@@ -1495,6 +1495,17 @@ powershell -File benchmarks/cross_runtime/run_cross_runtime.ps1 -Noxy <exe> `
            -NoxyBaseline <exe-antigo> -BaselineLabel v060
 ```
 
+Em Linux/macOS, os mesmos três runners em bash (mesmo protocolo, mesma
+saída; `compare_examples` continua só em PowerShell):
+
+```bash
+benchmarks/run_benchmarks.sh --binary <bin> --label <label>
+benchmarks/interleaved_compare.sh --baseline <bin> --candidate <bin> \
+           --baseline-label v060 --candidate-label v0141 --runs 9
+benchmarks/cross_runtime/run_cross_runtime.sh --noxy <bin> \
+           --noxy-baseline <bin-antigo> --baseline-label v060
+```
+
 Os binários têm de estar em **disco local**: este repo vive em OneDrive e medir
 de lá infla os tempos em ~2x (filtro de sync + antivírus no read). Benches que
 não rodam nos dois binários são pulados e listados no relatório, não medidos.
diff --git a/benchmarks/cross_runtime/README.md b/benchmarks/cross_runtime/README.md
index 63ea83c6..1d2767d3 100644
--- a/benchmarks/cross_runtime/README.md
+++ b/benchmarks/cross_runtime/README.md
@@ -15,8 +15,20 @@ diferentes do VM, mais um piso de processo.
                         -NoxyBaseline C:\local\noxy_antigo.exe -BaselineLabel v060
 ```
 
+Em Linux/macOS, o mesmo protocolo em bash (mesma saída, mesmas colunas):
+
+```bash
+./run_cross_runtime.sh --noxy /caminho/local/noxy
+
+# comparando duas versões do próprio Noxy na mesma janela intercalada
+./run_cross_runtime.sh --noxy /local/noxy_novo \
+                       --noxy-baseline /local/noxy_antigo --baseline-label v060
+```
+
 Saída em `results/cross_runtime.md`. `lua` e `go` são opcionais — se não
-estiverem no `PATH`, viram `-` na tabela em vez de erro.
+estiverem no `PATH`, viram `-` na tabela em vez de erro. Os dois runners
+gravam números com ponto decimal fixo (`LC_NUMERIC=C` no bash), independente
+do locale da máquina.
 
 `-NoxyBaseline` adiciona uma segunda versão do Noxy como coluna extra,
 intercalada junto com os outros runtimes. É a **única forma válida de comparar
diff --git a/benchmarks/cross_runtime/results/2026-09-05-v0250-ubuntu.md b/benchmarks/cross_runtime/results/2026-09-05-v0250-ubuntu.md
new file mode 100644
index 00000000..f6215fad
--- /dev/null
+++ b/benchmarks/cross_runtime/results/2026-09-05-v0250-ubuntu.md
@@ -0,0 +1,83 @@
+# Cross-runtime: Noxy x CPython x Go — v0.25.0, Ubuntu 26.04 (2026-09-05)
+
+- noxy: build local de e4496f8 (Noxy v0.25.0), Go 1.27.1
+- python: Python 3.14.4
+- go: go version go1.27.1 linux/amd64
+- lua: ausente
+- Sistema: Ubuntu 26.04.1 LTS, Intel Core i7-1165G7 (8 threads), instalacao limpa, load ~0.5
+- python: pacote do Ubuntu (gcc, computed gotos, JIT compilado mas desligado, GIL ativo)
+- Runner: `run_cross_runtime.sh` (port bash, mesmo protocolo do `.ps1`)
+- Data: 2026-09-05T17:49
+- Runs por bench: 9, intercalados; **minimo** reportado
+
+## Tempo total (ms)
+
+| bench | noxy | python | go |
+|---|---|---|---|
+| `bubblesort` | 88.8 | 57.1 | - |
+| `fib` | 128.4 | 79.8 | 5.6 |
+| `loop_arith` | 180.8 | 149.1 | 10.8 |
+| `mandelbrot` | 122.8 | 68.2 | - |
+| `map_churn` | 126.0 | 61.7 | - |
+| `startup` | 3.0 | 10.1 | 1.8 |
+| `string_ops` | 81.3 | 35.6 | - |
+
+## Tempo de execucao, descontado o piso de `startup` (ms)
+
+| bench | noxy | python | go |
+|---|---|---|---|
+| `bubblesort` | 85.8 | 47.0 | - |
+| `fib` | 125.4 | 69.7 | ~0 |
+| `loop_arith` | 177.8 | 139.0 | 9.0 |
+| `mandelbrot` | 119.8 | 58.1 | - |
+| `map_churn` | 123.0 | 51.6 | - |
+| `string_ops` | 78.3 | 25.5 | - |
+
+`~0` = o trabalho cabe dentro do ruido do piso de processo do runtime.
+
+## Razoes sobre o tempo liquido (noxy / outro)
+
+| bench | / python | / go |
+|---|---|---|
+| `bubblesort` | 1.83x | - |
+| `fib` | 1.80x | - |
+| `loop_arith` | 1.28x | 19.76x |
+| `mandelbrot` | 2.06x | - |
+| `map_churn` | 2.38x | - |
+| `string_ops` | 3.07x | - |
+
+## Checksums
+
+- bubblesort: CHECKSUM:376520193
+- fib: CHECKSUM:832040
+- loop_arith: CHECKSUM:135
+- mandelbrot: CHECKSUM:692665
+- map_churn: CHECKSUM:764868
+- startup: CHECKSUM:0
+- string_ops: CHECKSUM:2200001
+
+## Segunda rodada (mesma sessao, confirmacao)
+
+| bench | noxy | python | go |
+|---|---|---|---|
+| `bubblesort` | 90.9 | 57.0 | - |
+| `fib` | 130.4 | 80.2 | 5.6 |
+| `loop_arith` | 185.3 | 150.7 | 10.6 |
+| `mandelbrot` | 125.0 | 68.4 | - |
+| `map_churn` | 126.8 | 62.7 | - |
+| `startup` | 3.0 | 10.3 | 1.8 |
+| `string_ops` | 82.7 | 37.2 | - |
+
+## Leitura
+
+- Primeira medicao do cross-runtime em Linux. As razoes noxy/python sao
+  piores que as publicadas no Windows (`fib` 1,16x -> 1,80x, `loop_arith`
+  1,06x -> 1,28x, `string_ops` 2,17x -> 3,07x). O que mudou de lado foi o
+  CPython: o build gcc + PGO/LTO do pacote Debian/Ubuntu e consistentemente
+  mais rapido que o build MSVC do Windows, enquanto o Go rende parecido nas
+  duas plataformas. Os tres binarios noxy disponiveis (build do HEAD, `./noxy`
+  do repo, `~/go/bin/noxy` via `go install`) deram o mesmo `fib`, entao nao e
+  regressao de build.
+- Piso de processo: noxy 3 ms, python 10 ms — o Noxy sobe 3x mais rapido.
+- Maquina diferente da dos resultados anteriores: os ms absolutos nao se
+  comparam com as rodadas do Windows, so as razoes dentro desta janela.
diff --git a/benchmarks/cross_runtime/run_cross_runtime.sh b/benchmarks/cross_runtime/run_cross_runtime.sh
new file mode 100755
index 00000000..9d740e08
--- /dev/null
+++ b/benchmarks/cross_runtime/run_cross_runtime.sh
@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+# Port bash de run_cross_runtime.ps1 — mesmo protocolo, mesma saida.
+#
+# Compara o VM do Noxy com outros runtimes na mesma carga. Noxy e CPython
+# cobrem os sete benches; Lua 5.4 e Go nativo cobrem tres (startup,
+# loop_arith, fib) como calibracao. Runtime ausente vira "-" na tabela.
+#
+# Metodologia (ver README.md): intercalado, MINIMO de N amostras, fontes
+# copiados para disco local, versao antiga medida na mesma janela
+# (--noxy-baseline). Cada implementacao imprime a mesma linha CHECKSUM: e o
+# script aborta se divergirem — nao seria a mesma carga.
+#
+# Uso:
+#   ./run_cross_runtime.sh --noxy <bin> [--noxy-baseline <bin> --baseline-label v060]
+#                          [--python python3] [--lua lua] [--runs 9]
+set -euo pipefail
+export LC_NUMERIC=C
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+NOXY="$HERE/../../noxy"
+NOXY_BASE=""
+BASE_LABEL="noxy_base"
+PYTHON="python3"
+LUA="lua"
+RUNS=9
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --noxy)           NOXY="$2"; shift 2 ;;
+        --noxy-baseline)  NOXY_BASE="$2"; shift 2 ;;
+        --baseline-label) BASE_LABEL="$2"; shift 2 ;;
+        --python)         PYTHON="$2"; shift 2 ;;
+        --lua)            LUA="$2"; shift 2 ;;
+        --runs)           RUNS="$2"; shift 2 ;;
+        -h|--help)        sed -n '2,15p' "$0"; exit 0 ;;
+        *) echo "argumento desconhecido: $1" >&2; exit 2 ;;
+    esac
+done
+
+have() { command -v "$1" >/dev/null 2>&1; }
+[ -x "$NOXY" ] || have "$NOXY" || { echo "noxy nao encontrado: $NOXY" >&2; exit 2; }
+have "$PYTHON" || { echo "python nao encontrado: $PYTHON" >&2; exit 2; }
+HAS_LUA=0; have "$LUA" && HAS_LUA=1
+HAS_GO=0;  have go && HAS_GO=1
+
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/noxy_cross_XXXXXXXX")"
+trap 'rm -rf "$WORK"' EXIT
+cp "$HERE"/*.nx "$HERE"/*.py "$WORK"/
+cp "$HERE"/*.lua "$WORK"/ 2>/dev/null || true
+
+# Go compila antes de medir: o benchmark e do binario, nao do compilador.
+if [ "$HAS_GO" = 1 ]; then
+    for d in "$HERE"/go/*/; do
+        b="$(basename "$d")"
+        go build -o "$WORK/go_$b" "$d/main.go" || { echo "go build falhou para $b" >&2; exit 1; }
+    done
+fi
+
+# Ordem fixa: define a ordem das colunas e a ordem do intercalamento.
+ORDER=(noxy)
+[ -n "$NOXY_BASE" ] && ORDER+=("$BASE_LABEL")
+ORDER+=(python lua go)
+
+now_ms() { awk -v t="$EPOCHREALTIME" 'BEGIN{printf "%.3f", t*1000}'; }
+
+run_one() { # $1=runtime $2=bench
+    case "$1" in
+        noxy)         "$NOXY" "$WORK/$2.nx" ;;
+        "$BASE_LABEL") "$NOXY_BASE" "$WORK/$2.nx" ;;
+        python)       "$PYTHON" "$WORK/$2.py" ;;
+        lua)          "$LUA" "$WORK/$2.lua" ;;
+        go)           "$WORK/go_$2" ;;
+    esac
+}
+
+declare -A MIN CHK
+BENCHES=()
+for f in "$WORK"/*.nx; do BENCHES+=("$(basename "$f" .nx)"); done
+IFS=$'\n' BENCHES=($(sort <<<"${BENCHES[*]}")); unset IFS
+
+for b in "${BENCHES[@]}"; do
+    # Monta so os runtimes que existem para este bench.
+    rts=(noxy)
+    [ -n "$NOXY_BASE" ] && rts+=("$BASE_LABEL")
+    [ -f "$WORK/$b.py" ] && rts+=(python)
+    [ "$HAS_LUA" = 1 ] && [ -f "$WORK/$b.lua" ] && rts+=(lua)
+    [ -x "$WORK/go_$b" ] && rts+=(go)
+
+    # Warmup (aquece o cache de arquivo) + equivalencia entre runtimes.
+    chk=""
+    for r in "${rts[@]}"; do
+        c="$(run_one "$r" "$b" 2>&1 | grep -m1 '^CHECKSUM:' || true)"
+        [ -n "$c" ] || { echo "$b/$r : sem linha CHECKSUM" >&2; exit 1; }
+        [ -n "$chk" ] || chk="$c"
+        [ "$c" = "$chk" ] || { echo "$b : checksum divergente ($r=$c, esperado $chk)" >&2; exit 1; }
+    done
+    CHK[$b]="$chk"
+
+    declare -A samples=()
+    for i in $(seq 1 "$RUNS"); do
+        for r in "${rts[@]}"; do
+            t0="$(now_ms)"; run_one "$r" "$b" >/dev/null 2>&1; t1="$(now_ms)"
+            samples[$r]+=" $(awk -v a="$t0" -v b="$t1" 'BEGIN{printf "%.1f", b-a}')"
+        done
+    done
+    shown=""
+    for r in "${rts[@]}"; do
+        m="$(tr ' ' '\n' <<<"${samples[$r]}" | sed '/^$/d' | sort -n | head -1)"
+        MIN[$b,$r]="$m"; shown+="  $r=${m}ms"
+    done
+    printf '%-12s%s\n' "$b" "$shown"
+    unset samples
+done
+
+# ---- relatorio ----
+PRESENT=()
+for r in "${ORDER[@]}"; do
+    for b in "${BENCHES[@]}"; do
+        if [ -n "${MIN[$b,$r]:-}" ]; then PRESENT+=("$r"); break; fi
+    done
+done
+
+cell()   { [ -n "${1:-}" ] && echo "$1" || echo "-"; }
+# Liquido: total menos o piso de processo do proprio runtime. Para runtimes
+# rapidos o trabalho cabe no ruido do piso e a subtracao vai a zero ou fica
+# negativa — reportamos "~0" em vez de fingir precisao.
+net()    { [ -n "${1:-}" ] && [ -n "${2:-}" ] || { echo "-"; return; }
+           awk -v v="$1" -v f="$2" 'BEGIN{n=v-f; if (n<=5) print "~0"; else printf "%.1f", n}'; }
+ratio()  { case "$1$2" in *~0*|*-*) echo "-"; return ;; esac
+           awk -v a="$1" -v b="$2" 'BEGIN{printf "%.2fx", a/b}'; }
+header() { local s="| bench |"; for r in "$@"; do s+=" $r |"; done; echo "$s"
+           s="|---|"; for r in "$@"; do s+="---|"; done; echo "$s"; }
+
+OUT="$HERE/results/cross_runtime.md"
+mkdir -p "$HERE/results"
+{
+    echo "# Cross-runtime: Noxy x CPython x Lua x Go"
+    echo
+    echo "- noxy: \`$NOXY\` ($("$NOXY" --version 2>&1 | tr -d '\n'))"
+    [ -n "$NOXY_BASE" ] && echo "- $BASE_LABEL: \`$NOXY_BASE\` ($("$NOXY_BASE" --version 2>&1 | tr -d '\n'))"
+    echo "- python: $("$PYTHON" --version 2>&1 | tr -d '\n')"
+    if [ "$HAS_LUA" = 1 ]; then echo "- lua: $("$LUA" -v 2>&1 | tr -d '\n')"; else echo "- lua: ausente"; fi
+    if [ "$HAS_GO" = 1 ]; then echo "- go: $(go version)"; else echo "- go: ausente"; fi
+    echo "- Sistema: $(uname -srm)"
+    echo "- Data: $(date +%Y-%m-%dT%H:%M:%S)"
+    echo "- Runs por bench: $RUNS, intercalados; **minimo** reportado"
+    echo
+    echo "## Tempo total (ms)"
+    echo
+    header "${PRESENT[@]}"
+    for b in "${BENCHES[@]}"; do
+        s="| \`$b\` |"; for r in "${PRESENT[@]}"; do s+=" $(cell "${MIN[$b,$r]:-}") |"; done; echo "$s"
+    done
+    echo
+    echo "## Tempo de execucao, descontado o piso de \`startup\` (ms)"
+    echo
+    header "${PRESENT[@]}"
+    for b in "${BENCHES[@]}"; do
+        [ "$b" = startup ] && continue
+        s="| \`$b\` |"; for r in "${PRESENT[@]}"; do s+=" $(net "${MIN[$b,$r]:-}" "${MIN[startup,$r]:-}") |"; done; echo "$s"
+    done
+    echo
+    echo "\`~0\` = o trabalho cabe dentro do ruido do piso de processo do runtime."
+    # Razoes sobre o liquido: os ms absolutos dependem da carga da maquina na
+    # hora; a razao contra um runtime medido na MESMA janela, sim, se compara.
+    OTHERS=(); for r in "${PRESENT[@]}"; do [ "$r" != noxy ] && OTHERS+=("$r"); done
+    if [ "${#OTHERS[@]}" -gt 0 ]; then
+        echo
+        echo "## Razoes sobre o tempo liquido (noxy / outro)"
+        echo
+        labels=(); for r in "${OTHERS[@]}"; do labels+=("/ $r"); done
+        header "${labels[@]}"
+        for b in "${BENCHES[@]}"; do
+            [ "$b" = startup ] && continue
+            n="$(net "${MIN[$b,noxy]:-}" "${MIN[startup,noxy]:-}")"
+            s="| \`$b\` |"
+            for r in "${OTHERS[@]}"; do s+=" $(ratio "$n" "$(net "${MIN[$b,$r]:-}" "${MIN[startup,$r]:-}")") |"; done
+            echo "$s"
+        done
+    fi
+    echo
+    echo "## Checksums"
+    echo
+    for b in "${BENCHES[@]}"; do echo "- \`$b\`: ${CHK[$b]}"; done
+} > "$OUT"
+echo "wrote results/cross_runtime.md"
diff --git a/benchmarks/interleaved_compare.sh b/benchmarks/interleaved_compare.sh
new file mode 100755
index 00000000..ac013d85
--- /dev/null
+++ b/benchmarks/interleaved_compare.sh
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Port bash de interleaved_compare.ps1 — medicao intercalada de dois binarios
+# na mesma janela de tempo, imune a drift termico/carga de background que
+# contamina rodadas sequenciais por rotulo. Grava results/interleaved.md.
+#
+# O warmup tambem e o guard de equivalencia: cada bench imprime uma linha
+# CHECKSUM: e os dois binarios tem de concordar. Bench que um dos binarios nem
+# compila sai do erro em ~30ms e entraria na tabela como regressao de 10x —
+# e pulado e listado, nao medido.
+#
+# Uso: ./interleaved_compare.sh --baseline <bin> --candidate <bin>
+#          [--baseline-label baseline] [--candidate-label candidate] [--runs 5]
+set -euo pipefail
+export LC_NUMERIC=C
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BASE=""; CAND=""; BLABEL="baseline"; CLABEL="candidate"; RUNS=5
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --baseline)        BASE="$2"; shift 2 ;;
+        --candidate)       CAND="$2"; shift 2 ;;
+        --baseline-label)  BLABEL="$2"; shift 2 ;;
+        --candidate-label) CLABEL="$2"; shift 2 ;;
+        --runs)            RUNS="$2"; shift 2 ;;
+        -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
+        *) echo "argumento desconhecido: $1" >&2; exit 2 ;;
+    esac
+done
+[ -n "$BASE" ] && [ -n "$CAND" ] || { echo "uso: $0 --baseline <bin> --candidate <bin> [...]" >&2; exit 2; }
+
+now_ms()   { awk -v t="$EPOCHREALTIME" 'BEGIN{printf "%.3f", t*1000}'; }
+median()   { sed '/^$/d' | sort -n | awk '{a[NR]=$1} END{print a[int((NR-1)/2)+1]}'; }
+checksum() { "$1" "$2" 2>&1 | grep -m1 '^CHECKSUM:' || true; }
+time_one() { local t0 t1; t0="$(now_ms)"; "$1" "$2" >/dev/null 2>&1 || true; t1="$(now_ms)"
+             awk -v a="$t0" -v b="$t1" 'BEGIN{printf "%.1f", b-a}'; }
+
+lines=("| bench | ${BLABEL}_ms | ${CLABEL}_ms | delta |" "|---|---|---|---|")
+skipped=()
+for p in $(ls "$HERE"/bench_*.nx | sort); do
+    name="$(basename "$p")"
+    cb="$(checksum "$BASE" "$p")"; cc="$(checksum "$CAND" "$p")"
+    if [ -z "$cb" ] || [ -z "$cc" ] || [ "$cb" != "$cc" ]; then
+        if   [ -z "$cb" ]; then why="sem CHECKSUM no $BLABEL"
+        elif [ -z "$cc" ]; then why="sem CHECKSUM no $CLABEL"
+        else why="checksum divergente ($BLABEL=$cb, $CLABEL=$cc)"; fi
+        skipped+=("$name — $why")
+        echo "$name: PULADO ($why)"
+        continue
+    fi
+    tb=""; tc=""
+    for i in $(seq 1 "$RUNS"); do
+        tb+="$(time_one "$BASE" "$p")"$'\n'
+        tc+="$(time_one "$CAND" "$p")"$'\n'
+    done
+    mb="$(median <<<"$tb")"; mc="$(median <<<"$tc")"
+    delta="$(awk -v a="$mb" -v b="$mc" 'BEGIN{printf "%.1f", 100*(b-a)/a}')"
+    lines+=("| $name | $mb | $mc | $delta% |")
+    echo "$name: $BLABEL=$mb $CLABEL=$mc delta=$delta%"
+done
+if [ "${#skipped[@]}" -gt 0 ]; then
+    lines+=("" "Pulados (sem equivalencia entre os dois binarios):" "")
+    for s in "${skipped[@]}"; do lines+=("- $s"); done
+fi
+mkdir -p "$HERE/results"
+printf '%s\n' "${lines[@]}" > "$HERE/results/interleaved.md"
+echo "wrote results/interleaved.md"
diff --git a/benchmarks/run_benchmarks.sh b/benchmarks/run_benchmarks.sh
new file mode 100755
index 00000000..1dca7f7a
--- /dev/null
+++ b/benchmarks/run_benchmarks.sh
@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# Port bash de run_benchmarks.ps1 — suite completa por binario, mediana de N,
+# grava results/<label>.md. Bench sem linha CHECKSUM (nao compila neste
+# binario, ou nunca teve) e pulado e listado no fim, nao medido. Para comparar
+# dois binarios prefira interleaved_compare.sh (a unica comparacao que vale).
+#
+# Uso: ./run_benchmarks.sh --binary <bin> --label <label> [--runs 5]
+set -euo pipefail
+export LC_NUMERIC=C
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BINARY=""; LABEL=""; RUNS=5
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --binary) BINARY="$2"; shift 2 ;;
+        --label)  LABEL="$2"; shift 2 ;;
+        --runs)   RUNS="$2"; shift 2 ;;
+        -h|--help) sed -n '2,6p' "$0"; exit 0 ;;
+        *) echo "argumento desconhecido: $1" >&2; exit 2 ;;
+    esac
+done
+[ -n "$BINARY" ] && [ -n "$LABEL" ] || { echo "uso: $0 --binary <bin> --label <label> [--runs N]" >&2; exit 2; }
+
+now_ms() { awk -v t="$EPOCHREALTIME" 'BEGIN{printf "%.3f", t*1000}'; }
+median() { sed '/^$/d' | sort -n | awk '{a[NR]=$1} END{print a[int((NR-1)/2)+1]}'; }
+
+OUT_DIR="$HERE/results"; mkdir -p "$OUT_DIR"
+OUT="$OUT_DIR/$LABEL.md"
+{
+    echo "# Benchmark results: $LABEL"
+    echo
+    echo "- Binary: \`$BINARY\`"
+    echo "- Date: $(date +%Y-%m-%dT%H:%M:%S)"
+    echo "- Runs per bench: $RUNS (median reported)"
+    echo
+    echo "| bench | median_ms | runs_ms | checksum |"
+    echo "|---|---|---|---|"
+} > "$OUT"
+
+skipped=()
+for p in $(ls "$HERE"/bench_*.nx | sort); do
+    name="$(basename "$p")"
+    chk="$("$BINARY" "$p" 2>&1 | grep '^CHECKSUM:' | paste -sd';' || true)"
+    if [ -z "$chk" ]; then
+        skipped+=("$name — $("$BINARY" "$p" 2>&1 | head -1 || true)")
+        echo "$name: PULADO (sem linha CHECKSUM)"
+        continue
+    fi
+    times=""
+    for i in $(seq 1 "$RUNS"); do
+        t0="$(now_ms)"; "$BINARY" "$p" >/dev/null 2>&1; t1="$(now_ms)"
+        times+="$(awk -v a="$t0" -v b="$t1" 'BEGIN{printf "%.1f", b-a}') "
+    done
+    times="${times% }"
+    med="$(tr ' ' '\n' <<<"$times" | median)"
+    echo "| $name | $med | $times | $chk |" >> "$OUT"
+    echo "$name: median=${med}ms checksum=$chk"
+done
+if [ "${#skipped[@]}" -gt 0 ]; then
+    { echo; echo "Pulados (sem linha CHECKSUM):"; echo; for s in "${skipped[@]}"; do echo "- $s"; done; } >> "$OUT"
+fi
+echo "wrote results/$LABEL.md"

From a785ffa720b4056d887544e32d4463ca8702153e Mon Sep 17 00:00:00 2001
From: Estevao Fonseca <estevaopfon@gmail.com>
Date: Sat, 5 Sep 2026 18:04:18 -0400
Subject: [PATCH 2/2] fix(benchmarks): bst_owned/bst_ref na sintaxe T? da spec;
 CHECKSUM no hash31
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Os dois benches BST ainda declaravam campo e parâmetro com `T` nu e passavam
`null`, o que a spec §2.4 rejeita desde a regra de nulabilidade ("expected
TreeNode, got null"). Seguem agora o idioma da spec §3 "Self-Reference":

- bst_owned: `esquerda/direita: TreeNode?`, `ref (TreeNode?)` ao slot em
  `insert`/`count`, `let raiz: TreeNode? = null`. Em `count`, o narrowing de
  `*node` não sobrevive à chamada recursiva com raiz `ref`, então o primeiro
  `count(ref node.esquerda)` é vinculado a um `let` e `*node` é testado de
  novo antes do segundo empréstimo — exatamente o hint do compilador.
- bst_ref: `esquerda/direita: ref TreeNode?`, `count(node: ref TreeNode?)`
  vincula `let n: ref TreeNode = node` uma vez, como em noxy_examples/bst.nx.

Tempos na mesma máquina (667 ms / 211 ms) ficam na ordem dos publicados no
RESULTS.md (565–780 / 217): o caminho medido é o mesmo.

bench_hash31_bytes nunca imprimiu CHECKSUM; ganha a linha para entrar nos
runners sem ser pulado.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013tLpxkXEQZgrHZaQdAj1c7
---
 benchmarks/bench_bst_owned.nx    | 18 ++++++++++++------
 benchmarks/bench_bst_ref.nx      |  9 +++++----
 benchmarks/bench_hash31_bytes.nx |  1 +
 3 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/benchmarks/bench_bst_owned.nx b/benchmarks/bench_bst_owned.nx
index dc303eb8..44d98f56 100644
--- a/benchmarks/bench_bst_owned.nx
+++ b/benchmarks/bench_bst_owned.nx
@@ -5,10 +5,10 @@
 // `ref TreeNode` nos filhos e nao passa por esse caminho.
 struct TreeNode
     valor: int
-    esquerda: TreeNode
-    direita: TreeNode
+    esquerda: TreeNode?     // posse; null onde a arvore termina (spec §2.4, §3)
+    direita: TreeNode?
 end
-func insert(node: ref TreeNode, v: int) -> void
+func insert(node: ref (TreeNode?), v: int) -> void
     if *node == null then
         *node = TreeNode(v, null, null)
         return
@@ -19,14 +19,20 @@ func insert(node: ref TreeNode, v: int) -> void
         insert(ref node.direita, v)
     end
 end
-func count(node: ref TreeNode) -> int
+func count(node: ref (TreeNode?)) -> int
     if *node == null then
         return 0
     end
-    return 1 + count(ref node.esquerda) + count(ref node.direita)
+    // O narrowing de `*node` nao sobrevive a uma chamada cuja raiz e `ref`
+    // (spec §3, "Self-Reference"): um emprestimo por chamada, testado de novo.
+    let e: int = count(ref node.esquerda)
+    if *node == null then
+        return 0
+    end
+    return 1 + e + count(ref node.direita)
 end
 func main() -> void
-    let raiz: TreeNode = null
+    let raiz: TreeNode? = null
     let seed: int = 12345
     let i: int = 0
     while i < 20000 do
diff --git a/benchmarks/bench_bst_ref.nx b/benchmarks/bench_bst_ref.nx
index 71595b56..23d405bc 100644
--- a/benchmarks/bench_bst_ref.nx
+++ b/benchmarks/bench_bst_ref.nx
@@ -2,8 +2,8 @@
 // promovida a heap, e o acesso nao caminha o caminho do emprestimo (issue #93).
 struct TreeNode
     valor: int
-    esquerda: ref TreeNode
-    direita: ref TreeNode
+    esquerda: ref TreeNode?     // compartilhado; null onde a arvore termina (spec §2.3 R8)
+    direita: ref TreeNode?
 end
 func insert(node: ref TreeNode, v: int) -> void
     if v < node.valor then
@@ -22,11 +22,12 @@ func insert(node: ref TreeNode, v: int) -> void
         end
     end
 end
-func count(node: ref TreeNode) -> int
+func count(node: ref TreeNode?) -> int
     if node == null then
         return 0
     end
-    return 1 + count(node.esquerda) + count(node.direita)
+    let n: ref TreeNode = node   // spec §2.4: o narrowing nao sobrevive a chamada; vincula uma vez
+    return 1 + count(n.esquerda) + count(n.direita)
 end
 func main() -> void
     let raiz: TreeNode = TreeNode(500000, null, null)
diff --git a/benchmarks/bench_hash31_bytes.nx b/benchmarks/bench_hash31_bytes.nx
index 41e20bcf..357b5a2f 100644
--- a/benchmarks/bench_hash31_bytes.nx
+++ b/benchmarks/bench_hash31_bytes.nx
@@ -22,3 +22,4 @@ while i < n do
 end
 let t1: int = time_now_ms()
 print("bytes=" + to_str(n) + " hash31=" + to_str(h) + " ms=" + to_str(t1 - t0))
+print(f"CHECKSUM:{h}")