rubyduino 0.1.3 → 0.2.1

data/vendor/spinel/Makefile

@@ -5,9 +5,19 @@
 #   make parse        Build C parser only
 #   make bootstrap    Bootstrap the compiler backend
 #   make test         Run feature tests (requires bootstrap first)
+#   make fast-test    Force feature tests with cheaper C optimization
 #   make bench        Run benchmarks (requires bootstrap first)
 #   make clean        Remove built binaries
 
+# Machine-local overrides (gitignored). Lets a developer point the
+# bootstrap at an alternative Ruby -- e.g. a YJIT-enabled miniruby --
+# and set OPT/CC/etc. without editing committed defaults. Included
+# before the `?=` defaults below so its values win; a command-line
+# `make VAR=...` still overrides everything. Example local.mk:
+#   BOOTSTRAP_RUBY = /path/to/ruby/miniruby
+#   YJIT = 1
+-include local.mk
+
 CC       ?= cc
 # Auto-wrap CC with sccache or ccache when present. Skip when CC is
 # already wrapped — the substring guard catches both "ccache" and
@@ -104,6 +114,28 @@ endif
 # which the bootstrap miniruby can't load.
 REF_RUBY ?= ruby
 
+# Ruby used to run the bootstrap compiler (spinel_analyze.rb /
+# spinel_codegen.rb interpret the compiler on its own source). These
+# are long-running, hot-loop-heavy processes — exactly where YJIT
+# amortizes its warmup — so `YJIT=1 make` adds `--yjit` here only.
+# Opt-in because it requires a Ruby built with YJIT (3.3+ default-on,
+# 3.1/3.2 need a YJIT-enabled build). The per-test REF_RUBY is left on
+# plain `ruby`: those spawn a fresh short-lived process per file, so
+# YJIT warmup never pays off before the process exits. YJIT does not
+# change semantics, so the emitted IR / C is identical either way.
+BOOTSTRAP_RUBY ?= ruby
+ifeq ($(YJIT),1)
+  BOOTSTRAP_RUBY := $(BOOTSTRAP_RUBY) --yjit
+endif
+
+# FAST_BOOTSTRAP: how `make all` rebuilds the compiler backend.
+#   auto (default) -- use the previous compiled binaries (stage0) via
+#                     tools/fast-bootstrap (~3.5x faster than the CRuby round);
+#                     falls back to CRuby when stage0 is missing/unusable.
+#   0              -- always use the CRuby authority round.
+# `make bootstrap` always forces the CRuby round regardless of this.
+FAST_BOOTSTRAP ?= auto
+
 # Prism library: prefer vendor/prism (fetched via `make deps`), then
 # fall back to the Prism gem if one is installed. Override by setting
 # PRISM_DIR=/path/to/prism on the command line.
@@ -119,17 +151,41 @@ PRISM_SRC    = $(wildcard $(PRISM_DIR)/src/*.c) $(wildcard $(PRISM_DIR)/src/util
 PRISM_OBJ    = $(patsubst $(PRISM_DIR)/src/%.c,build/prism/%.o,$(PRISM_SRC))
 PRISM_LIB    = build/libprism.a
 
+# rbs C parser. Fetched via `make deps` from rubygems.org (the rbs
+# gem bundles its standalone C parser under src/ + include/, the same
+# way prism does). Consumed by spinel_rbs_extract to produce a seed
+# file for spinel_analyze when --rbs is passed.
+RBS_VERSION ?= 4.0.1
+RBS_DIR      = vendor/rbs
+RBS_INC      = $(RBS_DIR)/include
+RBS_SRC      = $(wildcard $(RBS_DIR)/src/*.c) $(wildcard $(RBS_DIR)/src/util/*.c)
+RBS_OBJ      = $(patsubst $(RBS_DIR)/src/%.c,build/rbs/%.o,$(RBS_SRC))
+RBS_LIB      = build/librbs.a
+
 CODEGEN_STAMP := build/stamps/spinel_codegen.rb.stamp
+ANALYZE_STAMP := build/stamps/spinel_analyze.rb.stamp
+NODE_TABLE_LOADER_STAMP := build/stamps/node_table_loader.rb.stamp
+COMPILER_HELPERS_STAMP := build/stamps/compiler_helpers.rb.stamp
 PARSE_STAMP   := build/stamps/spinel_parse.c.stamp
 
-.PHONY: all parse bootstrap codegen test retest clean-test-results regen-expected bench optcarrot clean install uninstall deps
+.PHONY: all parse bootstrap bootstrap-fixpoint fast-bootstrap codegen rbs_extract rbs-test analyze-fail-test regen-rbs-expected test retest fast-test clean-test-results regen-expected bench optcarrot gate check gate-legs gate-test gate-bench gate-optcarrot clean install uninstall deps FORCE
+
+# `make all` includes spinel_rbs_extract when vendor/rbs has been
+# fetched (via `make deps`). Without vendor/rbs the extractor is
+# silently omitted -- spinel still works; `spinel --rbs DIR` then
+# becomes a no-op (warns and proceeds without seeds).
+ifneq ($(wildcard $(RBS_INC)/rbs/parser.h),)
+  RBS_EXTRACT_TARGET = spinel_rbs_extract$(EXE)
+else
+  RBS_EXTRACT_TARGET =
+endif
 
-all: parse regexp spinel_codegen$(EXE)
+all: parse regexp spinel_analyze$(EXE) spinel_codegen$(EXE) $(RBS_EXTRACT_TARGET)
 
 # ---- Dependencies ----
 # Clone Prism into vendor/prism at the pinned version. Run this once
 # after cloning Spinel if you don't have the Prism gem installed.
-deps: vendor/prism/include/prism/diagnostic.h
+deps: vendor/prism/include/prism/diagnostic.h vendor/rbs/include/rbs/parser.h
 
 # Download the pre-built Prism gem from rubygems.org and extract its C
 # sources. We use the .gem tarball instead of a git clone because it
@@ -145,6 +201,21 @@ vendor/prism/include/prism/diagnostic.h:
 	 rm -rf $$tmpdir /tmp/prism-$(PRISM_VERSION).gem
 	@test -f $@ && echo "prism v$(PRISM_VERSION) ready at vendor/prism"
 
+# Same shape as the prism fetch above: download the rbs gem from
+# rubygems.org and extract its bundled C parser into vendor/rbs.
+# The gem ships src/ + include/ (the same files used to build the
+# Rust ruby-rbs binding and the Ruby C-extension) which is exactly
+# what spinel_rbs_extract needs.
+vendor/rbs/include/rbs/parser.h:
+	@mkdir -p vendor/rbs
+	@echo "Fetching rbs v$(RBS_VERSION) from rubygems.org..."
+	curl -sL -o /tmp/rbs-$(RBS_VERSION).gem https://rubygems.org/gems/rbs-$(RBS_VERSION).gem
+	@tmpdir=$$(mktemp -d); \
+	 tar -xf /tmp/rbs-$(RBS_VERSION).gem -C $$tmpdir data.tar.gz; \
+	 tar -xzf $$tmpdir/data.tar.gz -C vendor/rbs; \
+	 rm -rf $$tmpdir /tmp/rbs-$(RBS_VERSION).gem
+	@test -f $@ && echo "rbs v$(RBS_VERSION) ready at vendor/rbs"
+
 # If PRISM_DIR ended up empty (no vendor/prism, no gem), halt with a
 # clear message before trying to build anything that needs it.
 ifeq ($(PRISM_DIR),)
@@ -167,16 +238,33 @@ build/prism/%.o: $(PRISM_DIR)/src/%.c
 	@mkdir -p $(dir $@)
 	$(CC) -c -O2 -I$(PRISM_INC) -I$(PRISM_DIR)/src $< -o $@
 
+# ---- rbs static library ----
+
+build/librbs.a: $(RBS_OBJ)
+	@mkdir -p build
+	ar rcs $@ $^
+
+build/rbs/%.o: $(RBS_DIR)/src/%.c
+	@mkdir -p $(dir $@)
+	$(CC) -c -O2 -Wno-all -I$(RBS_INC) -I$(RBS_DIR)/src $< -o $@
+
 # ---- Content stamps ----
-# Content stamps: rules depend on `build/stamps/foo.stamp` instead of
-# `foo` directly, so `touch foo` (or `git checkout` of an identical
-# version) doesn't invalidate downstream targets. cmp-or-replace
-# advances the stamp's mtime only on real content change.
+# Content stamps: downstream rules depend on `build/stamps/foo.stamp`
+# instead of `foo` directly, so `touch foo` (or `git checkout` of an
+# identical version) doesn't invalidate bootstrap/test targets.
+#
+# The stamp rule intentionally does not list `%` as a normal prerequisite:
+# if it did, a same-content but newer source would make GNU make consider
+# the stamp out-of-date on every run when cmp leaves the stamp untouched.
+# FORCE lets us cheaply re-check content each invocation, while downstream
+# targets only rebuild when cp actually advances the stamp's mtime.
 build/stamps:
 	@mkdir -p $@
 
-build/stamps/%.stamp: % | build/stamps
-	@cmp -s $< $@ 2>/dev/null || cp $< $@
+FORCE:
+
+build/stamps/%.stamp: FORCE | build/stamps
+	@cmp -s $* $@ 2>/dev/null || cp $* $@
 
 # Without .PRECIOUS make would delete these as pattern-rule
 # intermediates, recreating them with fresh mtimes next run.
@@ -189,6 +277,23 @@ parse: spinel_parse$(EXE)
 spinel_parse$(EXE): $(PARSE_STAMP) $(PRISM_LIB)
 	$(CC) $(CFLAGS) -I$(PRISM_INC) spinel_parse.c $(PRISM_LIB) -lm -o $@
 
+# ---- RBS extractor ----
+# Reads sig/**/*.rbs, emits the seed-file format spinel_analyze
+# consumes when invoked with `spinel --rbs DIR`.
+
+ifeq ($(wildcard $(RBS_INC)/rbs/parser.h),)
+rbs_extract: rbs-missing
+rbs-missing:
+	@echo "Error: rbs C parser not found at $(RBS_INC)/rbs/parser.h."; \
+	 echo "  Run 'make deps' to fetch it from rubygems.org into vendor/rbs."; \
+	 exit 1
+else
+rbs_extract: spinel_rbs_extract$(EXE)
+
+spinel_rbs_extract$(EXE): spinel_rbs_extract.c $(RBS_LIB)
+	$(CC) $(CFLAGS) -I$(RBS_INC) spinel_rbs_extract.c $(RBS_LIB) -o $@
+endif
+
 # ---- Runtime library (regexp + bigint) ----
 
 RE_SRC = lib/regexp/re_compile.c lib/regexp/re_exec.c lib/regexp/re_utf8.c
@@ -202,49 +307,201 @@ build/sp_bigint.o: lib/sp_bigint.c lib/sp_bigint.h lib/mruby_shim.h
 	@mkdir -p build
 	$(CC) -c -O2 -Wno-all $(SEC_FLAGS) -Ilib lib/sp_bigint.c -o build/sp_bigint.o
 
+build/sp_crypto.o: lib/sp_crypto.c lib/sp_crypto.h
+	@mkdir -p build
+	$(CC) -c -O2 -Wno-all $(SEC_FLAGS) -Ilib lib/sp_crypto.c -o build/sp_crypto.o
+
+build/sp_pack.o: lib/sp_pack.c lib/mruby_shim.h
+	@mkdir -p build
+	$(CC) -c -O2 -Wno-all $(SEC_FLAGS) -Ilib lib/sp_pack.c -o build/sp_pack.o
+
+build/sp_strscan.o: lib/sp_strscan.c lib/mruby_shim.h
+	@mkdir -p build
+	$(CC) -c -O2 -Wno-all $(SEC_FLAGS) -Ilib -Ilib/regexp lib/sp_strscan.c -o build/sp_strscan.o
+
+build/sp_time.o: lib/sp_time.c lib/sp_time.h
+	@mkdir -p build
+	$(CC) -c -O2 -Wno-all $(SEC_FLAGS) -Ilib lib/sp_time.c -o build/sp_time.o
+
+build/sp_core.o: lib/sp_core.c lib/sp_core.h
+	@mkdir -p build
+	$(CC) -c -O2 -Wno-all $(SEC_FLAGS) -Ilib lib/sp_core.c -o build/sp_core.o
+
+build/sp_system.o: lib/sp_system.c lib/sp_system.h
+	@mkdir -p build
+	$(CC) -c -O2 -Wno-all $(SEC_FLAGS) -Ilib lib/sp_system.c -o build/sp_system.o
+
+build/sp_gc.o: lib/sp_gc.c lib/sp_gc.h lib/sp_types.h
+	@mkdir -p build
+	$(CC) -c -O2 -Wno-all $(SEC_FLAGS) -Ilib lib/sp_gc.c -o build/sp_gc.o
+
+build/sp_fiber.o: lib/sp_fiber.c lib/sp_fiber.h lib/sp_gc.h lib/sp_types.h
+	@mkdir -p build
+	$(CC) -c -O2 -Wno-all $(SEC_FLAGS) -Ilib lib/sp_fiber.c -o build/sp_fiber.o
+
+build/sp_net.o: lib/sp_net.c lib/sp_net.h
+	@mkdir -p build
+	$(CC) -c -O2 -Wno-all $(SEC_FLAGS) -Ilib lib/sp_net.c -o build/sp_net.o
+
+build/sp_io.o: lib/sp_io.c lib/sp_io.h lib/sp_gc.h lib/sp_types.h
+	@mkdir -p build
+	$(CC) -c -O2 -Wno-all $(SEC_FLAGS) -Ilib lib/sp_io.c -o build/sp_io.o
+
 SP_RT_LIB = lib/libspinel_rt.a
 
-$(SP_RT_LIB): $(RE_OBJ) build/sp_bigint.o
+$(SP_RT_LIB): $(RE_OBJ) build/sp_bigint.o build/sp_crypto.o build/sp_pack.o build/sp_strscan.o build/sp_time.o build/sp_core.o build/sp_net.o build/sp_system.o build/sp_gc.o build/sp_fiber.o build/sp_io.o
 	ar rcs $@ $^
 
 regexp: $(SP_RT_LIB)
 
 # ---- Build the codegen binary (fast path) ----
-# `make spinel_codegen` (or the alias `make codegen`) compiles
-# spinel_codegen.rb once via CRuby and links the result. This is
-# enough to use the binary; for the full self-hosting fixed-point
-# check (gen2.c == gen3.c), use `make bootstrap`.
+# Build both binaries via CRuby (the bootstrap "round 1"). Each
+# spinel_<phase>.rb is its own ~20K-line source; we compile each
+# through the same parse → analyze → codegen → cc pipeline. Use
+# `make bootstrap` for the full self-hosting fixed-point check.
+
+codegen: spinel_analyze$(EXE) spinel_codegen$(EXE)
+
+# Round 1 pipeline split into per-stage rules. Previously the
+# `spinel_<phase>$(EXE)` recipe produced its AST/IR/C1 outputs as
+# side effects, which left those files without proper Make rules.
+# Under parallel make that races: `build/codegen2.ir` (declared to
+# depend on `build/codegen.ast`) could be scheduled before the
+# spinel_codegen recipe had refreshed the AST, so it read a stale
+# AST while later steps used the fresh one. The bid mismatch then
+# corrupted scope tables in the bootstrap fixpoint output. See #620.
+
+build/analyze.ast: $(ANALYZE_STAMP) $(NODE_TABLE_LOADER_STAMP) $(COMPILER_HELPERS_STAMP) spinel_parse$(EXE)
+	./spinel_parse$(EXE) spinel_analyze.rb build/analyze.ast
+
+build/codegen.ast: $(CODEGEN_STAMP) $(NODE_TABLE_LOADER_STAMP) $(COMPILER_HELPERS_STAMP) spinel_parse$(EXE)
+	./spinel_parse$(EXE) spinel_codegen.rb build/codegen.ast
 
-codegen: spinel_codegen$(EXE)
+build/analyze.ir: build/analyze.ast $(ANALYZE_STAMP) $(NODE_TABLE_LOADER_STAMP) $(COMPILER_HELPERS_STAMP)
+	$(BOOTSTRAP_RUBY) spinel_analyze.rb build/analyze.ast build/analyze.ir
 
-spinel_codegen$(EXE): $(CODEGEN_STAMP) spinel_parse$(EXE)
-	./spinel_parse$(EXE) spinel_codegen.rb build/codegen.ast
-	ruby spinel_codegen.rb build/codegen.ast build/gen1.c
-	$(CC) $(BOOTSTRAP_CFLAGS) -Ilib build/gen1.c $(LDFLAGS) -lm -o spinel_codegen$(EXE)
-
-# ---- Self-hosting verification (slow path) ----
-# Re-runs the binary on its own AST to produce gen2.c, compiles bin2,
-# re-runs bin2 to produce gen3.c, asserts gen2.c == gen3.c (the
-# self-hosting fixed point). On success, replaces spinel_codegen with
-# the verified bin2.
-
-bootstrap: spinel_codegen$(EXE)
-	@echo "=== Bootstrap: gen2 (via spinel_codegen) ==="
-	./spinel_codegen$(EXE) build/codegen.ast build/gen2.c
-	$(CC) $(BOOTSTRAP_CFLAGS) -Ilib build/gen2.c $(LDFLAGS) -lm -o build/bin2$(EXE)
-	@echo "=== Bootstrap: gen3 (via bin2) - verify ==="
-	./build/bin2$(EXE) build/codegen.ast build/gen3.c
-	@diff build/gen2.c build/gen3.c > /dev/null && echo "gen2.c == gen3.c (bootstrap OK)" || (echo "BOOTSTRAP FAILED: gen2.c != gen3.c" && exit 1)
-	cp build/bin2$(EXE) spinel_codegen$(EXE)
+build/codegen.ir: build/codegen.ast $(ANALYZE_STAMP) $(NODE_TABLE_LOADER_STAMP) $(COMPILER_HELPERS_STAMP)
+	$(BOOTSTRAP_RUBY) spinel_analyze.rb build/codegen.ast build/codegen.ir
+
+build/analyze1.c: build/analyze.ast build/analyze.ir $(CODEGEN_STAMP) $(NODE_TABLE_LOADER_STAMP) $(COMPILER_HELPERS_STAMP)
+	$(BOOTSTRAP_RUBY) spinel_codegen.rb build/analyze.ast build/analyze.ir build/analyze1.c
+
+build/codegen1.c: build/codegen.ast build/codegen.ir $(CODEGEN_STAMP) $(NODE_TABLE_LOADER_STAMP) $(COMPILER_HELPERS_STAMP)
+	$(BOOTSTRAP_RUBY) spinel_codegen.rb build/codegen.ast build/codegen.ir build/codegen1.c
+
+ifeq ($(FAST_BOOTSTRAP),auto)
+# Default: rebuild BOTH compiler binaries from the previous binaries (stage0)
+# via tools/fast-bootstrap, gated on the source stamps. Helper falls back to
+# the CRuby rules (FAST_BOOTSTRAP=0) when stage0 is missing or can't compile
+# the source.
+#
+# spinel_analyze carries the recipe and the helper produces BOTH binaries;
+# spinel_codegen just waits on it. We deliberately do NOT use a `&:` grouped
+# target: macOS's system Make (GNU Make 3.81) predates `&:` and runs the recipe
+# once PER target, spawning two concurrent helpers that race on the shared
+# build/*.ast / *.ir intermediates (a flaky macOS-only build break -- corrupt
+# IR -> "undeclared identifier" in codegen1.c). Listing both source stamps as
+# prereqs of spinel_analyze means any compiler-source edit re-runs the helper.
+spinel_analyze$(EXE): $(ANALYZE_STAMP) $(CODEGEN_STAMP) $(NODE_TABLE_LOADER_STAMP) $(COMPILER_HELPERS_STAMP) $(SP_RT_LIB) | spinel_parse$(EXE)
+	@CC='$(CC)' EXE='$(EXE)' BOOTSTRAP_CFLAGS='$(BOOTSTRAP_CFLAGS)' SP_RT_LIB='$(SP_RT_LIB)' LDFLAGS='$(LDFLAGS)' sh tools/fast-bootstrap
+spinel_codegen$(EXE): spinel_analyze$(EXE)
+	@:
+else
+spinel_analyze$(EXE): build/analyze1.c $(SP_RT_LIB)
+	$(CC) $(BOOTSTRAP_CFLAGS) -Ilib build/analyze1.c $(SP_RT_LIB) $(LDFLAGS) -lm -o spinel_analyze$(EXE)
+
+spinel_codegen$(EXE): build/codegen1.c $(SP_RT_LIB)
+	$(CC) $(BOOTSTRAP_CFLAGS) -Ilib build/codegen1.c $(SP_RT_LIB) $(LDFLAGS) -lm -o spinel_codegen$(EXE)
+endif
+
+# ---- Self-hosting verification ----
+# After CRuby builds spinel_{analyze,codegen}, run them on each
+# source file to produce a "round 2" pair of binaries. Then run
+# bin2_{analyze,codegen} on each source again to produce "round 3"
+# outputs and assert byte equality. The fixpoint covers both the
+# analysis IR and the emitted C, so any drift in either phase is
+# caught.
+
+# Round 2: gen1 binaries (spinel_{analyze,codegen}) compile each .rb
+# source into a fresh `bin2_*` binary. The analyze and codegen sources
+# are independent, so the two pipelines are split into per-binary
+# targets that `make -j` can run in parallel. Same for the round 3
+# verify step.
+
+build/analyze2.ir: build/analyze.ast spinel_analyze$(EXE)
+	./spinel_analyze$(EXE) build/analyze.ast build/analyze2.ir
+
+build/analyze2.c: build/analyze.ast build/analyze2.ir spinel_codegen$(EXE)
+	./spinel_codegen$(EXE) build/analyze.ast build/analyze2.ir build/analyze2.c
+
+build/bin2_analyze$(EXE): build/analyze2.c $(SP_RT_LIB)
+	$(CC) $(BOOTSTRAP_CFLAGS) -Ilib build/analyze2.c $(SP_RT_LIB) $(LDFLAGS) -lm -o build/bin2_analyze$(EXE)
+
+build/codegen2.ir: build/codegen.ast spinel_analyze$(EXE)
+	./spinel_analyze$(EXE) build/codegen.ast build/codegen2.ir
+
+build/codegen2.c: build/codegen.ast build/codegen2.ir spinel_codegen$(EXE)
+	./spinel_codegen$(EXE) build/codegen.ast build/codegen2.ir build/codegen2.c
+
+build/bin2_codegen$(EXE): build/codegen2.c $(SP_RT_LIB)
+	$(CC) $(BOOTSTRAP_CFLAGS) -Ilib build/codegen2.c $(SP_RT_LIB) $(LDFLAGS) -lm -o build/bin2_codegen$(EXE)
+
+build/analyze3.ir: build/analyze.ast build/bin2_analyze$(EXE)
+	./build/bin2_analyze$(EXE) build/analyze.ast build/analyze3.ir
+
+build/analyze3.c: build/analyze.ast build/analyze3.ir build/bin2_codegen$(EXE)
+	./build/bin2_codegen$(EXE) build/analyze.ast build/analyze3.ir build/analyze3.c
+
+build/codegen3.ir: build/codegen.ast build/bin2_analyze$(EXE)
+	./build/bin2_analyze$(EXE) build/codegen.ast build/codegen3.ir
+
+build/codegen3.c: build/codegen.ast build/codegen3.ir build/bin2_codegen$(EXE)
+	./build/bin2_codegen$(EXE) build/codegen.ast build/codegen3.ir build/codegen3.c
+
+# bootstrap: the CRuby-seeded self-host fixpoint AUTHORITY (CI/release). Always
+# rebuilds the compiler via the CRuby round (forces FAST_BOOTSTRAP=0, never the
+# fast path), then verifies round2 == round3 byte-for-byte.
+bootstrap:
+	@$(MAKE) --no-print-directory FAST_BOOTSTRAP=0 bootstrap-fixpoint
+
+bootstrap-fixpoint: build/analyze3.c build/codegen3.c
+	@diff build/analyze2.ir build/analyze3.ir > /dev/null && echo "analyze.rb: IR fixpoint OK" || (echo "BOOTSTRAP FAILED: analyze.rb IR diverged" && exit 1)
+	@diff build/analyze2.c  build/analyze3.c  > /dev/null && echo "analyze.rb: C fixpoint OK"  || (echo "BOOTSTRAP FAILED: analyze.rb C diverged"  && exit 1)
+	@diff build/codegen2.ir build/codegen3.ir > /dev/null && echo "codegen.rb: IR fixpoint OK" || (echo "BOOTSTRAP FAILED: codegen.rb IR diverged" && exit 1)
+	@diff build/codegen2.c  build/codegen3.c  > /dev/null && echo "codegen.rb: C fixpoint OK"  || (echo "BOOTSTRAP FAILED: codegen.rb C diverged"  && exit 1)
+	cp build/bin2_analyze$(EXE) spinel_analyze$(EXE)
+	cp build/bin2_codegen$(EXE) spinel_codegen$(EXE)
+
+# fast-bootstrap: rebuild the compiler from the PREVIOUS compiled binaries
+# (stage0) instead of the slow CRuby round, then atomically promote. Speed
+# path: no self-host fixpoint (that is `make bootstrap`). Falls back to the
+# CRuby authority path when stage0 is missing or can't compile the current
+# source. See tools/fast-bootstrap.
+fast-bootstrap: spinel_parse$(EXE) $(SP_RT_LIB)
+	@CC='$(CC)' EXE='$(EXE)' BOOTSTRAP_CFLAGS='$(BOOTSTRAP_CFLAGS)' SP_RT_LIB='$(SP_RT_LIB)' LDFLAGS='$(LDFLAGS)' sh tools/fast-bootstrap
 
 # ---- Test ----
 
 TESTS := $(wildcard test/*.rb)
+ANALYZE_FAIL_TESTS := $(sort $(wildcard test/analyze_fail/*.rb))
+# Mode-incompatible tests: int_overflow_raises pins raise-mode semantics
+# (RangeError on overflow); under --int-overflow=promote the same code
+# auto-promotes to bigint and the expected output diverges by design.
+ifeq ($(SPINEL_INT_OVERFLOW),promote)
+TESTS := $(filter-out test/int_overflow_raises.rb,$(TESTS))
+endif
+# sp_net is POSIX-only; on Windows the TU compiles to stubs, so the
+# sp_net smoke's output diverges. Skip it there (the POSIX surface is
+# exercised by consumer suites on POSIX targets).
+ifeq ($(OS),Windows_NT)
+TESTS := $(filter-out test/sp_net_basic.rb,$(TESTS))
+endif
 TEST_TARGETS := $(patsubst test/%.rb,build/test-results/%.ok,$(TESTS))
 
 # `make test` is incremental via mtime tracking on .ok files;
-# `make retest` wipes them for a forced rerun.
-test: $(TEST_TARGETS)
+# `make retest` wipes them for a forced rerun. The rbs-test prereq
+# golden-checks the RBS extractor (cheap, runs every invocation).
+test: rbs-test analyze-fail-test $(TEST_TARGETS)
 	@if [ -z "$(TIMEOUT_BIN)" ]; then echo "Note: no 'timeout' command found; running without time limits."; fi
 	@if [ -t 1 ]; then printf '\n'; fi
 	@pass=$$(grep -l '^PASS' build/test-results/*.ok 2>/dev/null | wc -l); \
@@ -266,34 +523,120 @@ test: $(TEST_TARGETS)
 retest: clean-test-results
 	@$(MAKE) --no-print-directory test
 
+fast-test: clean-test-results
+	@$(MAKE) --no-print-directory test OPT=-O0 LTO=0
+
+# ---- RBS extractor golden tests ----
+# spinel_rbs_extract is a pure text transform (*.rbs -> seed lines on
+# stdout), so it golden-tests cleanly without Ruby at test time. Each
+# test/rbs/<name>.rbs has a committed test/rbs/<name>.seed.expected;
+# `rbs-test` diffs live output against it. Regenerate after intentional
+# extractor changes with `make regen-rbs-expected` and commit the diff.
+# Skips (rather than fails) when vendor/rbs hasn't been fetched, so a
+# `make deps`-less checkout can still run the rest of `make test`.
+RBS_TEST_SRCS := $(sort $(wildcard test/rbs/*.rbs))
+
+ifeq ($(wildcard $(RBS_INC)/rbs/parser.h),)
+rbs-test:
+	@echo "rbs-test: skipped (vendor/rbs not fetched; run 'make deps')"
+regen-rbs-expected:
+	@echo "regen-rbs-expected: skipped (vendor/rbs not fetched; run 'make deps')"
+else
+rbs-test: spinel_rbs_extract$(EXE)
+	@fail=0; n=0; \
+	for f in $(RBS_TEST_SRCS); do \
+	  n=$$((n+1)); \
+	  exp="$${f%.rbs}.seed.expected"; \
+	  if [ ! -f "$$exp" ]; then echo "rbs-test: MISSING golden $$exp"; fail=1; continue; fi; \
+	  d=$$(./spinel_rbs_extract$(EXE) "$$f" 2>/dev/null | diff -u "$$exp" - 2>&1); \
+	  if [ -z "$$d" ]; then \
+	    if [ -t 1 ]; then printf .; fi; \
+	  else \
+	    echo; echo "rbs-test FAIL: $$f"; echo "$$d"; fail=1; \
+	  fi; \
+	done; \
+	if [ -t 1 ]; then printf '\n'; fi; \
+	if [ $$fail -ne 0 ]; then echo "RBS extractor tests: FAIL"; exit 1; fi; \
+	echo "RBS extractor tests: $$n pass"
+
+regen-rbs-expected: spinel_rbs_extract$(EXE)
+	@for f in $(RBS_TEST_SRCS); do \
+	  ./spinel_rbs_extract$(EXE) "$$f" > "$${f%.rbs}.seed.expected"; \
+	  echo "regen: $${f%.rbs}.seed.expected"; \
+	done
+endif
+
+# Analyze-fail fixtures are intentionally rejected during the
+# spinel_analyze phase. They cover semantic subset limits that should
+# produce a stable diagnostic, not a generated binary.
+analyze-fail-test: spinel_parse$(EXE) spinel_analyze$(EXE)
+	@mkdir -p build/analyze-fail-results
+	@fail=0; n=0; \
+	for f in $(ANALYZE_FAIL_TESTS); do \
+	  n=$$((n+1)); \
+	  bn=$$(basename "$$f" .rb); \
+	  tmpdir=$$(mktemp -d /tmp/spinel-analyze-fail.XXXXXX); \
+	  ast=$$tmpdir/test.ast; ir=$$tmpdir/test.ir; err=$$tmpdir/analyze.err; \
+	  exp="$${f%.rb}.stderr.expected"; \
+	  if ! ./spinel_parse$(EXE) "$$f" "$$ast" >/dev/null 2>"$$tmpdir/parse.err"; then \
+	    echo "analyze-fail ERR: $$bn (parse failed)"; \
+	    cat "$$tmpdir/parse.err"; \
+	    fail=1; rm -rf "$$tmpdir"; continue; \
+	  fi; \
+	  if ./spinel_analyze$(EXE) "$$ast" "$$ir" >/dev/null 2>"$$err"; then \
+	    echo "analyze-fail FAIL: $$bn (analyze succeeded)"; \
+	    fail=1; rm -rf "$$tmpdir"; continue; \
+	  fi; \
+	  if [ ! -f "$$exp" ]; then \
+	    echo "analyze-fail ERR: $$bn missing $$exp"; \
+	    fail=1; rm -rf "$$tmpdir"; continue; \
+	  fi; \
+	  LC_ALL=C sed 's/\r$$//' "$$exp" > "$$tmpdir/expected.n"; \
+	  LC_ALL=C sed 's/\r$$//' "$$err" > "$$tmpdir/actual.n"; \
+	  if cmp -s "$$tmpdir/expected.n" "$$tmpdir/actual.n"; then \
+	    echo PASS > "build/analyze-fail-results/$$bn.ok"; \
+	  else \
+	    echo "analyze-fail FAIL: $$bn"; \
+	    diff -u "$$tmpdir/expected.n" "$$tmpdir/actual.n" || true; \
+	    fail=1; \
+	  fi; \
+	  rm -rf "$$tmpdir"; \
+	done; \
+	echo "Analyze-fail tests: $$n pass"; \
+	if [ $$fail -ne 0 ]; then exit 1; fi
+
 # The .ok target is the test's stamp; mtime tracking gives per-test
-# caching for free. Order-only spinel_parse$(EXE) / spinel_codegen$(EXE)
-# stop a bootstrap relink from invalidating every test.
-build/test-results/%.ok: test/%.rb $(SP_RT_LIB) $(CODEGEN_STAMP) $(PARSE_STAMP) | spinel_parse$(EXE) spinel_codegen$(EXE)
+# caching for free. Order-only spinel_parse$(EXE) / spinel_analyze$(EXE)
+# / spinel_codegen$(EXE) stop a bootstrap relink from invalidating every test.
+build/test-results/%.ok: test/%.rb $(SP_RT_LIB) $(CODEGEN_STAMP) $(ANALYZE_STAMP) $(NODE_TABLE_LOADER_STAMP) $(COMPILER_HELPERS_STAMP) $(PARSE_STAMP) | spinel_parse$(EXE) spinel_analyze$(EXE) spinel_codegen$(EXE)
 	@mkdir -p build/test-results
 	@tmpdir=$$(mktemp -d /tmp/spinel-test.XXXXXX); \
 	ast=$$tmpdir/test.ast; \
+	ir=$$tmpdir/test.ir; \
 	cfile=$$tmpdir/test.c; \
 	bin=$$tmpdir/test_bin$(EXE); \
 	exp=$$tmpdir/expected; \
 	act=$$tmpdir/actual; \
+	args=""; \
+	if [ -f "$<.args" ]; then args=$$(cat "$<.args"); fi; \
 	rm -f "$@.diff"; \
 	./spinel_parse$(EXE) "$<" "$$ast" 2>/dev/null && \
-	./spinel_codegen$(EXE) "$$ast" "$$cfile" 2>/dev/null && \
+	./spinel_analyze$(EXE) "$$ast" "$$ir" 2>/dev/null && \
+	./spinel_codegen$(EXE) "$$ast" "$$ir" "$$cfile" 2>/dev/null && \
 	$(CC) $(CFLAGS) -Werror $(SEC_FLAGS) -Ilib -c "$$cfile" -o "$$cfile.o" 2>/dev/null && \
 	$(CC) $(CFLAGS) "$$cfile.o" $(SP_RT_LIB) $(LDFLAGS) -lm $(GC_FLAGS) -o "$$bin" 2>/dev/null; \
 	if [ $$? -eq 0 ]; then \
 	  if [ -f "$<.expected" ]; then \
 	    LC_ALL=C sed 's/\r$$//' "$<.expected" >"$$exp.n"; \
 	  else \
-	    $(TIMEOUT10) $(REF_RUBY) "$<" >"$$exp" 2>/dev/null; \
+	    $(TIMEOUT10) $(REF_RUBY) "$<" $$args >"$$exp" 2>/dev/null; \
 	    ruby_rc=$$?; \
 	    if [ $$ruby_rc -ne 0 ] && [ "$(REF_RUBY)" != "ruby" ]; then \
-	      $(TIMEOUT10) ruby "$<" >"$$exp" 2>/dev/null; \
+	      $(TIMEOUT10) ruby "$<" $$args >"$$exp" 2>/dev/null; \
 	    fi; \
 	    LC_ALL=C sed 's/\r$$//' "$$exp" >"$$exp.n"; \
 	  fi; \
-	  $(TIMEOUT10) "$$bin" >"$$act" 2>/dev/null; \
+	  $(TIMEOUT10) "$$bin" $$args >"$$act" 2>/dev/null; \
 	  LC_ALL=C sed 's/\r$$//' "$$act" >"$$act.n"; \
 	  if cmp -s "$$exp.n" "$$act.n"; then \
 	    echo PASS > "$@"; \
@@ -310,7 +653,7 @@ build/test-results/%.ok: test/%.rb $(SP_RT_LIB) $(CODEGEN_STAMP) $(PARSE_STAMP)
 	rm -rf "$$tmpdir"
 
 clean-test-results:
-	@rm -rf build/test-results
+	@rm -rf build/test-results build/analyze-fail-results
 
 # ---- Expected-output regeneration ----
 # Capture each test's reference Ruby output into test/<name>.rb.expected.
@@ -324,15 +667,23 @@ EXPECTED_FILES := $(patsubst test/%.rb,test/%.rb.expected,$(TESTS))
 regen-expected: $(EXPECTED_FILES)
 
 test/%.rb.expected: test/%.rb
-	@$(TIMEOUT10) $(REF_RUBY) $< >$@.tmp 2>/dev/null; \
+	@args=""; \
+	if [ -f "$<.args" ]; then args=$$(cat "$<.args"); fi; \
+	$(TIMEOUT10) $(REF_RUBY) $< $$args >$@.tmp 2>/dev/null; \
 	rc=$$?; \
 	if [ $$rc -ne 0 ] && [ "$(REF_RUBY)" != "ruby" ]; then \
-	  $(TIMEOUT10) ruby $< >$@.tmp 2>/dev/null; \
+	  $(TIMEOUT10) ruby $< $$args >$@.tmp 2>/dev/null; \
+	  rc=$$?; \
 	fi; \
-	LC_ALL=C sed 's/\r$$//' $@.tmp > $@; \
-	rm -f $@.tmp
+	if [ $$rc -ne 0 ]; then \
+	  echo "regen-expected: $< failed (rc=$$rc); skipping" >&2; \
+	  rm -f $@.tmp; \
+	else \
+	  LC_ALL=C sed 's/\r$$//' $@.tmp > $@; \
+	  rm -f $@.tmp; \
+	fi
 
-bench: spinel_parse$(EXE) $(SP_RT_LIB) spinel_codegen$(EXE)
+bench: spinel_parse$(EXE) $(SP_RT_LIB) spinel_analyze$(EXE) spinel_codegen$(EXE)
 	@if [ -z "$(TIMEOUT_BIN)" ]; then echo "Note: no 'timeout' command found; running without time limits."; fi
 	@total=$$(ls benchmark/*.rb | wc -l); \
 	if [ -t 1 ]; then tty=1; else tty=0; fi; \
@@ -342,7 +693,8 @@ bench: spinel_parse$(EXE) $(SP_RT_LIB) spinel_codegen$(EXE)
 	  bn=$$(basename "$$f" .rb); \
 	  if [ "$$tty" = 1 ]; then printf '\r\033[K  [%d/%d] %s' "$$i" "$$total" "$$bn"; fi; \
 	  $(TIMEOUT10) ./spinel_parse$(EXE) "$$f" /tmp/_sp_b.ast 2>/dev/null && \
-	  $(TIMEOUT10) ./spinel_codegen$(EXE) /tmp/_sp_b.ast /tmp/_sp_b.c 2>/dev/null && \
+	  $(TIMEOUT10) ./spinel_analyze$(EXE) /tmp/_sp_b.ast /tmp/_sp_b.ir 2>/dev/null && \
+	  $(TIMEOUT10) ./spinel_codegen$(EXE) /tmp/_sp_b.ast /tmp/_sp_b.ir /tmp/_sp_b.c 2>/dev/null && \
 	  $(CC) $(CFLAGS) -Werror $(SEC_FLAGS) -Ilib -c /tmp/_sp_b.c -o /tmp/_sp_b.c.o 2>/dev/null && \
 	  $(CC) $(CFLAGS) /tmp/_sp_b.c.o $(SP_RT_LIB) $(LDFLAGS) -lm $(GC_FLAGS) -o /tmp/_sp_b_bin$(EXE) 2>/dev/null; \
 	  if [ $$? -eq 0 ]; then \
@@ -374,7 +726,7 @@ bench: spinel_parse$(EXE) $(SP_RT_LIB) spinel_codegen$(EXE)
 	  fi; \
 	done; \
 	if [ "$$tty" = 1 ]; then printf '\r\033[K'; fi; \
-	rm -f /tmp/_sp_b.ast /tmp/_sp_b.c /tmp/_sp_b.c.o /tmp/_sp_b_bin$(EXE) /tmp/_sp_b_exp /tmp/_sp_b_act /tmp/_sp_b_exp.n /tmp/_sp_b_act.n; \
+	rm -f /tmp/_sp_b.ast /tmp/_sp_b.ir /tmp/_sp_b.c /tmp/_sp_b.c.o /tmp/_sp_b_bin$(EXE) /tmp/_sp_b_exp /tmp/_sp_b_act /tmp/_sp_b_exp.n /tmp/_sp_b_act.n; \
 	echo "Benchmarks: $$pass pass, $$fail fail, $$err error, $$skip skip"; \
 	if [ $$fail -ne 0 ] || [ $$err -ne 0 ]; then exit 1; fi
 
@@ -391,12 +743,12 @@ OPTCARROT_DIR  := build/optcarrot
 OPTCARROT_REPO := https://github.com/mame/optcarrot.git
 OPTCARROT_BRANCH := experiment/spinel
 
-optcarrot: spinel_parse$(EXE) $(SP_RT_LIB) spinel_codegen$(EXE)
+optcarrot: spinel_parse$(EXE) $(SP_RT_LIB) spinel_analyze$(EXE) spinel_codegen$(EXE)
 	@if [ ! -d $(OPTCARROT_DIR) ]; then \
 	  git clone --depth=1 --branch=$(OPTCARROT_BRANCH) $(OPTCARROT_REPO) $(OPTCARROT_DIR); \
 	fi
 	@ruby $(OPTCARROT_DIR)/tools/pack-for-spinel.rb > build/optcarrot-single.rb
-	@./spinel build/optcarrot-single.rb -o build/optcarrot-single
+	@./spinel --int-overflow=wrap build/optcarrot-single.rb -o build/optcarrot-single
 	@out=$$($(TIMEOUT60) ./build/optcarrot-single 2>&1); \
 	echo "$$out"; \
 	if echo "$$out" | grep -qE "^fps: [0-9.]+$$" && echo "$$out" | grep -q "^checksum: 59662$$"; then \
@@ -406,6 +758,52 @@ optcarrot: spinel_parse$(EXE) $(SP_RT_LIB) spinel_codegen$(EXE)
 	  exit 1; \
 	fi
 
+# ---- Developer gates ----
+#
+# Two composite targets to cut the edit/verify loop. The full gate is
+# dominated by the self-host bootstrap (~3x the rest); `test`, `bench`
+# and `optcarrot` only READ the compiler binaries and write to disjoint
+# build/ dirs, so they run concurrently as parallel prerequisites, while
+# `bootstrap` rewrites spinel_{analyze,codegen} (round-3 cp) and must run
+# alone afterward.
+#
+# These rely on make's own jobserver rather than a hand-rolled `-jN` +
+# `&` background loop: every recursive `$(MAKE)` is `+`-prefixed so the
+# jobserver fd is inherited (no "jobserver unavailable -> -j1" fallback),
+# and none pass an explicit `-j` (which would force a sub-make to reset
+# the jobserver and spawn its own full pool -> oversubscription). The
+# default-`-j` logic above gives the top-level invocation its pool.
+
+# Fast pre-commit check: rebuild the compiler and run the full test
+# suite with the optimizer off (type-checking still happens). Skips
+# bench/optcarrot/bootstrap — run `make gate` before pushing for those.
+# LTO=0 keeps the compiler rebuild fast (no -O3 -flto link of the ~80k
+# line generated C); it doesn't affect type-checking or test output.
+check:
+	+@$(MAKE) --no-print-directory LTO=0 all
+	+@$(MAKE) --no-print-directory clean-test-results
+	+@$(MAKE) --no-print-directory test OPT=-O0
+
+# Full pre-push gate: test || bench || optcarrot in parallel (via the
+# gate-legs prerequisites), then the self-host bootstrap. ~90s faster
+# than the four in sequence.
+gate:
+	+@$(MAKE) --no-print-directory LTO=0 all
+	+@$(MAKE) --no-print-directory clean-test-results
+	+@$(MAKE) --no-print-directory gate-legs
+	+@$(MAKE) --no-print-directory LTO=0 bootstrap
+	@echo "gate: ALL GREEN"
+
+# The three read-only legs as parallel prerequisites; make schedules
+# them across the jobserver pool.
+gate-legs: gate-test gate-bench gate-optcarrot
+gate-test:
+	+@$(MAKE) --no-print-directory test OPT=-O0
+gate-bench:
+	+@$(MAKE) --no-print-directory bench
+gate-optcarrot:
+	+@$(MAKE) --no-print-directory optcarrot
+
 # ---- Install ----
 
 PREFIX   ?= /usr/local
@@ -415,10 +813,21 @@ install: all
 	install -d $(SPNLDIR)/lib
 	install -m 755 spinel                $(SPNLDIR)/
 	install -m 755 spinel_parse$(EXE)    $(SPNLDIR)/
+	install -m 755 spinel_analyze$(EXE)  $(SPNLDIR)/
 	install -m 755 spinel_codegen$(EXE)  $(SPNLDIR)/
+	install -m 644 node_table_loader.rb  $(SPNLDIR)/
+	install -m 644 spinel_analyze.rb     $(SPNLDIR)/
 	install -m 644 spinel_codegen.rb     $(SPNLDIR)/
 	install -m 644 lib/libspinel_rt.a    $(SPNLDIR)/lib/
 	install -m 644 lib/sp_runtime.h      $(SPNLDIR)/lib/
+	install -m 644 lib/sp_types.h        $(SPNLDIR)/lib/
+	install -m 644 lib/sp_core.h         $(SPNLDIR)/lib/
+	install -m 644 lib/sp_system.h       $(SPNLDIR)/lib/
+	install -m 644 lib/sp_gc.h           $(SPNLDIR)/lib/
+	install -m 644 lib/sp_fiber.h         $(SPNLDIR)/lib/
+	install -m 644 lib/sp_io.h           $(SPNLDIR)/lib/
+	install -m 644 lib/sp_time.h         $(SPNLDIR)/lib/
+	install -m 644 lib/sp_net.h          $(SPNLDIR)/lib/
 	install -m 644 lib/*.rb              $(SPNLDIR)/lib/
 	install -d $(PREFIX)/bin
 	ln -sf $(SPNLDIR)/spinel $(PREFIX)/bin/spinel
@@ -431,4 +840,4 @@ uninstall:
 
 clean:
 	rm -rf build/
-	rm -f spinel_parse$(EXE) spinel_codegen$(EXE)
+	rm -f spinel_parse$(EXE) spinel_analyze$(EXE) spinel_codegen$(EXE)