rubyduino 0.1.1

data/vendor/spinel/Makefile

@@ -0,0 +1,406 @@
+# Spinel AOT Compiler - Makefile
+#
+# Usage:
+#   make              Build everything (parser + bootstrap compiler)
+#   make parse        Build C parser only
+#   make bootstrap    Bootstrap the compiler backend
+#   make test         Run feature tests (requires bootstrap first)
+#   make bench        Run benchmarks (requires bootstrap first)
+#   make clean        Remove built binaries
+
+CC       ?= cc
+# Auto-wrap CC with sccache or ccache when present. Skip when CC is
+# already wrapped — the substring guard catches both "ccache" and
+# "sccache" since "ccache" is a substring of "sccache", so CI's
+# `CC=sccache <cc>` env stays untouched. NO_CCACHE=1 opts out.
+# `override` is required so that `make CC=gcc` (command-line CC) is
+# also wrapped — without it, command-line CC takes precedence over
+# Makefile assignments and the wrap is silently ignored.
+ifeq (,$(findstring ccache,$(CC)))
+ifeq (,$(NO_CCACHE))
+  CCACHE_BIN := $(shell command -v sccache 2>/dev/null || command -v ccache 2>/dev/null)
+  ifneq (,$(CCACHE_BIN))
+    override CC := $(CCACHE_BIN) $(CC)
+  endif
+endif
+endif
+# `-Wno-alloc-size-larger-than` silences a gcc 13+ paranoia warning that
+# fires on the inlined `h->cap *= 2` in sp_*Hash_grow when the inliner
+# can't bound h->cap. The pattern is bounded in practice (cap doubles
+# from a small power of two until memory runs out, never approaches
+# 2^60), but gcc tracks signed-overflow UB conservatively. Clang
+# doesn't have that warning; without `-Wno-unknown-warning-option`
+# first, clang would turn the unknown -Wno- into a -Werror failure on
+# every cc invocation in `make test` / `make bench`.
+# Optimization level for the C compiles driven by the test/bench
+# harness (each .rb gets parsed → codegen → cc'd → run). CI overrides
+# this to -O0 to cut Windows cc time substantially; locally -O2 keeps
+# the test binaries reasonable-speed for quicker run-after-compile.
+OPT     ?= -O2
+CFLAGS   = $(OPT) -Wno-all -Wno-unknown-warning-option -Wno-alloc-size-larger-than
+# Bootstrap-only flags: spinel_codegen runs on the developer's machine
+# only, so we can use -O3 -flto for ~5-10% extra wall-clock without
+# constraining users (whose generated C is built with plain CFLAGS).
+# Override with LTO=0 on toolchains without LTO support.
+LTO     ?= 1
+ifeq ($(LTO),1)
+  BOOTSTRAP_CFLAGS = -O3 -flto=auto -Wno-all
+else
+  BOOTSTRAP_CFLAGS = $(CFLAGS)
+endif
+# Per-function sections allow the linker to strip unused bigint/regexp
+# functions from the final binary (supported since GCC 2.7 / binutils 2.17).
+SEC_FLAGS = -ffunction-sections -fdata-sections
+# Apple ld64 spells dead-code stripping --dead_strip; GNU ld uses --gc-sections.
+ifeq ($(shell uname -s),Darwin)
+  GC_FLAGS = -Wl,-dead_strip
+else
+  GC_FLAGS = -Wl,--gc-sections
+endif
+
+# MinGW gcc appends .exe to its output filename; reflect that in target
+# names so Make's dependency tracking and install/clean match reality.
+# Windows (MinGW) default stack is also only 1MB — far too small for the
+# deeply recursive bootstrap compile (~75k frames of AST traversal).
+ifeq ($(OS),Windows_NT)
+  EXE = .exe
+  LDFLAGS += -Wl,--stack,67108864
+endif
+
+# `timeout` is GNU coreutils — present by default on Linux but missing
+# on macOS unless `brew install coreutils` is run (where it's named
+# `gtimeout`). Without it test/bench would chain-fail at the very first
+# `timeout` call with exit 127, reporting 0 pass / 0 fail. Detect both
+# names; if neither is found, run without time limits (slow benches
+# won't be auto-killed, but otherwise everything works).
+TIMEOUT_BIN := $(shell command -v timeout 2>/dev/null || command -v gtimeout 2>/dev/null)
+TIMEOUT10 := $(if $(TIMEOUT_BIN),$(TIMEOUT_BIN) 10,)
+TIMEOUT60 := $(if $(TIMEOUT_BIN),$(TIMEOUT_BIN) 60,)
+
+# Default -j to logical CPU count when MAKEFLAGS doesn't already
+# carry a -j flag. The combined guard catches the three forms a user
+# can supply -j in (per the GNU Make manual): `-j N` / `-jN` via
+# filter, the short-flag-cluster form like `-kj` via findstring on
+# the first word (the leading `-` makes firstword non-empty when
+# MAKEFLAGS starts blank), and Make 4.x's `--jobserver-auth=…` long
+# form. Note: GNU Make 3.81 (macOS system make) reports MAKEFLAGS
+# as empty at parse time, so the guard always fires there; users on
+# 3.81 wanting to override should pass `MAKEFLAGS=-jN make …`.
+ifeq (,$(filter -j%,$(MAKEFLAGS))$(findstring j,$(firstword -$(MAKEFLAGS)))$(filter --jobserver%,$(MAKEFLAGS)))
+  MAKEFLAGS += -j$(shell getconf _NPROCESSORS_ONLN 2>/dev/null || echo 4)
+endif
+
+# Reference Ruby for `make test` / `make bench` output comparison.
+# Defaults to `ruby` (the system CRuby), matching the historical
+# behaviour. Override on the command line when a newer or differently-
+# built interpreter is needed, e.g.
+#
+#   REF_RUBY=miniruby make test
+#
+# to use a freshly-built bootstrap interpreter (Ruby's `miniruby`)
+# that supports newer features like the `it` block param. The
+# harness falls back to `ruby` per-file if `REF_RUBY` exits non-zero
+# — covers tests that `require` extension libraries (stringio, etc.)
+# which the bootstrap miniruby can't load.
+REF_RUBY ?= ruby
+
+# 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.
+PRISM_VERSION ?= 1.9.0
+ifneq ($(wildcard vendor/prism/include/prism.h),)
+  PRISM_DIR ?= vendor/prism
+else
+  PRISM_DIR ?= $(shell ruby -rprism -e 'puts $$LOADED_FEATURES.grep(/prism/).first.sub(%r{/lib/.*}, "")' 2>/dev/null)
+endif
+
+PRISM_INC    = $(PRISM_DIR)/include
+PRISM_SRC    = $(wildcard $(PRISM_DIR)/src/*.c) $(wildcard $(PRISM_DIR)/src/util/*.c)
+PRISM_OBJ    = $(patsubst $(PRISM_DIR)/src/%.c,build/prism/%.o,$(PRISM_SRC))
+PRISM_LIB    = build/libprism.a
+
+CODEGEN_STAMP := build/stamps/spinel_codegen.rb.stamp
+PARSE_STAMP   := build/stamps/spinel_parse.c.stamp
+
+.PHONY: all parse bootstrap codegen test retest clean-test-results regen-expected bench clean install uninstall deps
+
+all: parse regexp spinel_codegen$(EXE)
+
+# ---- 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
+
+# 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
+# ships with the generated headers (diagnostic.h, etc.) already in
+# place — no rake/bundler needed.
+vendor/prism/include/prism/diagnostic.h:
+	@mkdir -p vendor/prism
+	@echo "Fetching prism v$(PRISM_VERSION) from rubygems.org..."
+	curl -sL -o /tmp/prism-$(PRISM_VERSION).gem https://rubygems.org/gems/prism-$(PRISM_VERSION).gem
+	@tmpdir=$$(mktemp -d); \
+	 tar -xf /tmp/prism-$(PRISM_VERSION).gem -C $$tmpdir data.tar.gz; \
+	 tar -xzf $$tmpdir/data.tar.gz -C vendor/prism; \
+	 rm -rf $$tmpdir /tmp/prism-$(PRISM_VERSION).gem
+	@test -f $@ && echo "prism v$(PRISM_VERSION) ready at vendor/prism"
+
+# 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),)
+parse bootstrap codegen regexp all: prism-missing
+prism-missing:
+	@echo "Error: Prism not found."; \
+	 echo "  Run 'make deps' to fetch libprism into vendor/prism,"; \
+	 echo "  or install the prism gem (gem install prism),"; \
+	 echo "  or set PRISM_DIR=/path/to/prism manually."; \
+	 exit 1
+endif
+
+# ---- Prism static library ----
+
+build/libprism.a: $(PRISM_OBJ)
+	@mkdir -p build
+	ar rcs $@ $^
+
+build/prism/%.o: $(PRISM_DIR)/src/%.c
+	@mkdir -p $(dir $@)
+	$(CC) -c -O2 -I$(PRISM_INC) -I$(PRISM_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.
+build/stamps:
+	@mkdir -p $@
+
+build/stamps/%.stamp: % | 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.
+.PRECIOUS: build/stamps/%.stamp
+
+# ---- C Parser ----
+
+parse: spinel_parse$(EXE)
+
+spinel_parse$(EXE): $(PARSE_STAMP) $(PRISM_LIB)
+	$(CC) $(CFLAGS) -I$(PRISM_INC) spinel_parse.c $(PRISM_LIB) -lm -o $@
+
+# ---- Runtime library (regexp + bigint) ----
+
+RE_SRC = lib/regexp/re_compile.c lib/regexp/re_exec.c lib/regexp/re_utf8.c
+RE_OBJ = $(patsubst lib/regexp/%.c,build/regexp/%.o,$(RE_SRC))
+
+build/regexp/%.o: lib/regexp/%.c lib/regexp/re_internal.h
+	@mkdir -p build/regexp
+	$(CC) -c -O2 $(SEC_FLAGS) -Ilib/regexp $< -o $@
+
+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
+
+SP_RT_LIB = lib/libspinel_rt.a
+
+$(SP_RT_LIB): $(RE_OBJ) build/sp_bigint.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`.
+
+codegen: spinel_codegen$(EXE)
+
+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)
+
+# ---- Test ----
+
+TESTS := $(wildcard test/*.rb)
+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)
+	@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); \
+	fail=$$(grep -l '^FAIL' build/test-results/*.ok 2>/dev/null | wc -l); \
+	err=$$(grep -l '^ERR' build/test-results/*.ok 2>/dev/null | wc -l); \
+	for f in build/test-results/*.ok; do \
+	  bn=$$(basename "$$f" .ok); \
+	  status=$$(cat "$$f"); \
+	  if [ "$$status" = FAIL ]; then \
+	    echo "FAIL: $$bn"; \
+	    head -40 "$$f.diff"; \
+	  elif [ "$$status" = ERR ]; then \
+	    echo "ERR:  $$bn"; \
+	  fi; \
+	done; \
+	echo "Tests: $$pass pass, $$fail fail, $$err error"; \
+	if [ $$fail -ne 0 ] || [ $$err -ne 0 ]; then exit 1; fi
+
+retest: clean-test-results
+	@$(MAKE) --no-print-directory test
+
+# 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)
+	@mkdir -p build/test-results
+	@tmpdir=$$(mktemp -d /tmp/spinel-test.XXXXXX); \
+	ast=$$tmpdir/test.ast; \
+	cfile=$$tmpdir/test.c; \
+	bin=$$tmpdir/test_bin$(EXE); \
+	exp=$$tmpdir/expected; \
+	act=$$tmpdir/actual; \
+	rm -f "$@.diff"; \
+	./spinel_parse$(EXE) "$<" "$$ast" 2>/dev/null && \
+	./spinel_codegen$(EXE) "$$ast" "$$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; \
+	    ruby_rc=$$?; \
+	    if [ $$ruby_rc -ne 0 ] && [ "$(REF_RUBY)" != "ruby" ]; then \
+	      $(TIMEOUT10) ruby "$<" >"$$exp" 2>/dev/null; \
+	    fi; \
+	    LC_ALL=C sed 's/\r$$//' "$$exp" >"$$exp.n"; \
+	  fi; \
+	  $(TIMEOUT10) "$$bin" >"$$act" 2>/dev/null; \
+	  LC_ALL=C sed 's/\r$$//' "$$act" >"$$act.n"; \
+	  if cmp -s "$$exp.n" "$$act.n"; then \
+	    echo PASS > "$@"; \
+	    if [ -t 1 ]; then printf .; fi; \
+	  else \
+	    echo FAIL > "$@"; \
+	    diff -u "$$exp.n" "$$act.n" > "$@.diff" 2>&1 || true; \
+	    if [ -t 1 ]; then printf F; fi; \
+	  fi; \
+	else \
+	  echo ERR > "$@"; \
+	  if [ -t 1 ]; then printf E; fi; \
+	fi; \
+	rm -rf "$$tmpdir"
+
+clean-test-results:
+	@rm -rf build/test-results
+
+# ---- Expected-output regeneration ----
+# Capture each test's reference Ruby output into test/<name>.rb.expected.
+# Once committed, the test target uses the .expected file directly and
+# skips the per-test ruby invocation — useful in CI where ruby's startup
+# (especially mingw64 ruby on Windows) adds up across hundreds of tests.
+# Regenerate after adding or modifying tests; commit the result.
+
+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; \
+	rc=$$?; \
+	if [ $$rc -ne 0 ] && [ "$(REF_RUBY)" != "ruby" ]; then \
+	  $(TIMEOUT10) ruby $< >$@.tmp 2>/dev/null; \
+	fi; \
+	LC_ALL=C sed 's/\r$$//' $@.tmp > $@; \
+	rm -f $@.tmp
+
+bench: spinel_parse$(EXE) $(SP_RT_LIB) 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; \
+	pass=0; fail=0; err=0; skip=0; i=0; \
+	for f in benchmark/*.rb; do \
+	  i=$$((i+1)); \
+	  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 && \
+	  $(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 \
+	    $(TIMEOUT60) $(REF_RUBY) "$$f" >/tmp/_sp_b_exp 2>/dev/null; \
+	    ruby_rc=$$?; \
+	    if [ $$ruby_rc -ne 0 ] && [ "$(REF_RUBY)" != "ruby" ]; then \
+	      $(TIMEOUT60) ruby "$$f" >/tmp/_sp_b_exp 2>/dev/null; \
+	      ruby_rc=$$?; \
+	    fi; \
+	    if [ $$ruby_rc -eq 124 ]; then \
+	      if [ "$$tty" = 1 ]; then printf '\r\033[K'; fi; \
+	      echo "SKIP: $$bn (ruby timeout)"; skip=$$((skip+1)); \
+	    else \
+	      $(TIMEOUT60) /tmp/_sp_b_bin$(EXE) >/tmp/_sp_b_act 2>/dev/null; \
+	      LC_ALL=C sed 's/\r$$//' /tmp/_sp_b_exp >/tmp/_sp_b_exp.n; \
+	      LC_ALL=C sed 's/\r$$//' /tmp/_sp_b_act >/tmp/_sp_b_act.n; \
+	      if cmp -s /tmp/_sp_b_exp.n /tmp/_sp_b_act.n; then \
+	        pass=$$((pass+1)); \
+	      else \
+	        if [ "$$tty" = 1 ]; then printf '\r\033[K'; fi; \
+	        echo "FAIL: $$bn"; \
+	        diff -u /tmp/_sp_b_exp.n /tmp/_sp_b_act.n 2>&1 | head -40; \
+	        fail=$$((fail+1)); \
+	      fi; \
+	    fi; \
+	  else \
+	    if [ "$$tty" = 1 ]; then printf '\r\033[K'; fi; \
+	    echo "ERR:  $$bn"; err=$$((err+1)); \
+	  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; \
+	echo "Benchmarks: $$pass pass, $$fail fail, $$err error, $$skip skip"; \
+	if [ $$fail -ne 0 ] || [ $$err -ne 0 ]; then exit 1; fi
+
+# ---- Install ----
+
+PREFIX   ?= /usr/local
+SPNLDIR   = $(PREFIX)/lib/spinel
+
+install: all
+	install -d $(SPNLDIR)/lib
+	install -m 755 spinel                $(SPNLDIR)/
+	install -m 755 spinel_parse$(EXE)    $(SPNLDIR)/
+	install -m 755 spinel_codegen$(EXE)  $(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/*.rb              $(SPNLDIR)/lib/
+	install -d $(PREFIX)/bin
+	ln -sf $(SPNLDIR)/spinel $(PREFIX)/bin/spinel
+
+uninstall:
+	rm -f $(PREFIX)/bin/spinel
+	rm -rf $(SPNLDIR)
+
+# ---- Clean ----
+
+clean:
+	rm -rf build/
+	rm -f spinel_parse$(EXE) spinel_codegen$(EXE)

data/vendor/spinel/POLY-AS-SET.md

@@ -0,0 +1,217 @@
+# Stage 2 設計案: poly-as-set 型表現
+
+Stage 1 (`narrow_param_types_from_body_method_calls`、commit `0d10645`) の制約「呼ばれる全メソッドが**ただ1つ**のクラスにしかない」を外すための、内部型表現の拡張案。記録目的。実装は未着手。
+
+## 動機
+
+現状の "poly" は不透明な単一トークン。次の精度向上が手に入っていない:
+
+1. **set-intersection narrowing** — 候補集合を観測ごとに intersect して絞る
+   ```ruby
+   def render(model)
+     model.title  # Article のみ → {Article}
+     model.body   # Article + Comment → {Article, Comment}
+     # 交差 = {Article} → narrow できるはず
+   end
+   ```
+   Stage 1 では `model.body` の信号がぼやけて捨てられる。
+
+2. **else-arm 負の絞り込み** — `if x.is_a?(A); ... ; else; # x:NOT(A) ; end`
+   現在 scan_new_calls の comment にも明示:
+   > The else-arm walks unchanged (we don't currently model "type minus C")
+
+3. **emit サイズ削減** — `compile_poly_method_call` の per-class arm が `@cls_names` を全列挙。候補集合に絞れば未到達 arm を消せる。
+
+## 内部表現
+
+### 文字列エンコード案
+
+`"poly"` → `"poly{<sorted-class-name-list>}"` (集合を文字列でエンコード):
+
+```
+"poly"             → 既存の "全クラス" 意味、互換維持のため keep
+"poly{Article}"    → 単一クラス、`obj_Article` と等価扱いで折り畳み可能
+"poly{Article;Comment}"          → 二項
+"poly{Article;Comment;HWIA}"     → 三項
+"poly{Article;Comment;HWIA}?"    → nullable版 (既存の `?` サフィックス慣習継承)
+```
+
+セパレータは `;` (既存の `@cls_meth_params` のクラス区切り `|` や param 区切り `,` と衝突しない、`@cls_meth_names` の method 区切りと一致)。
+
+### 正規化ルール
+
+- ソートして決定的なエンコードに (`{B;A}` ではなく `{A;B}`)
+- 重複除去
+- サイズ 1 → `obj_<C>` に折り畳み (representation lift; 集合表現を消す)
+- 全クラスを含む → `"poly"` に折り畳み (degenerate case)
+
+### 影響を受ける関数 (主要)
+
+| 関数 | 既存ロジック | 必要な拡張 |
+|------|-------------|------------|
+| `base_type` | `"obj_C?"` → `"obj_C"` | `"poly{A;B}?"` → `"poly{A;B}"` |
+| `is_obj_type` | `"obj_"` プレフィックス判定 | (poly-set は obj_ ではない、独立)  |
+| `is_value_type_obj` | obj_C の class lookup | poly-set は value-type 不可 (各候補は struct 化 NG) |
+| `c_type` | `"poly"` → `"sp_RbVal"` | `"poly{...}"` も同じく `"sp_RbVal"` |
+| `c_default_val` | `"poly"` → `"sp_box_nil()"` | 同 |
+| `unify_call_types` | 二項 unify | set union (詳細下記) |
+| `box_value_to_poly` | obj_C / 各種 → sp_box_* | set 経由は対象外、各 candidate ごとに caller 側で box済を期待 |
+
+### unify_call_types の拡張
+
+```
+unify("poly{A;B}", "obj_A")        = "poly{A;B}"        (subset → 包含)
+unify("poly{A;B}", "obj_C")        = "poly{A;B;C}"      (union)
+unify("poly{A;B}", "poly{B;C}")    = "poly{A;B;C}"      (union)
+unify("poly{A;B}", "poly{A;B}")    = "poly{A;B}"        (idempotent)
+unify("poly{A;B}", "int")          = "poly"             (混合型は既存 poly に degrade)
+unify("obj_A", "obj_B")            = "poly{A;B}"        (新ロジック; 現状は "poly")
+unify("poly", any)                 = "poly"             (degenerate keep)
+```
+
+ポイント: **混合型 (obj+primitive) は既存の不透明 `"poly"` に落とす**。これにより既存コードの `"poly"` 判定 (受け取り側のすべての場所) と互換が取れる。`"poly{...}"` は **すべて user obj** な集合に限定。
+
+### intersection 演算 (Stage 1 を一般化)
+
+```
+intersect("poly{A;B;C}", "poly{B;C;D}") = "poly{B;C}"
+intersect("poly{A;B}", "poly{C;D}")     = ""             (空 → 信号矛盾)
+intersect("poly{A}", "obj_A")           = "obj_A"
+intersect("poly{A;B}", "obj_C")         = ""             (空)
+```
+
+Stage 1 の `unify_param_class_from_observations` を集合演算で書き直す:
+- 各観測 `param.<m>` で「`<m>` を定義する user class 集合 S(m)」を計算
+- 各観測の S(m) で intersection を取る
+- `is_primitive_shared_method(m)` は S に「全クラス + builtins」を意味するので intersection 中立 (skip)
+- 最終 intersection が空でなければ narrow
+
+### type minus 演算 (else-arm)
+
+```
+type_minus("poly{A;B;C}", "obj_A") = "poly{B;C}"
+type_minus("poly{A;B}", "obj_A")   = "obj_B"             (size 1 折り畳み)
+type_minus("poly{A}", "obj_A")     = ""                  (空; unreachable)
+type_minus("poly", "obj_A")        = "poly"              (不透明は触らない)
+```
+
+scan_new_calls の IfNode 処理に else-arm narrow を追加:
+```ruby
+# then-arm
+if narrow_var != ""
+  push_type_narrow(narrow_var, narrow_t)  # 既存
+end
+walk(then_body)
+pop
+
+# else-arm (新規)
+else_narrow_t = type_minus(原型, narrow_t)
+if else_narrow_t != ""
+  push_type_narrow(narrow_var, else_narrow_t)
+end
+walk(else_body)
+pop
+```
+
+## emit-side 変更
+
+### compile_poly_method_call
+
+```ruby
+# 現状:
+i = 0
+while i < @cls_names.length
+  midx = cls_find_method_direct(i, mname)
+  if midx >= 0
+    # arm 出力
+  end
+  i += 1
+end
+
+# Stage 2:
+candidates = poly_candidates(recv_type)   # "poly{A;B}" → ["A", "B"]
+# 候補が空 (= 不透明 "poly") なら現状通り全列挙
+# 候補があれば限定列挙
+candidates.each { |cn|
+  ci = find_class_idx(cn)
+  midx = cls_find_method_direct(ci, mname)
+  if midx >= 0
+    # arm 出力
+  end
+}
+```
+
+emit 量削減: Roundhouse 規模 (~20 user class、平均候補3クラス) で arm 17 個 ÷ poly call sites 50-100 個 ≈ 1000-2000 行の C 削減 (runtime 動作に影響なし、cc 時間 + emit サイズのみ)。
+
+### sp_RbVal タグの動作変化なし
+
+ランタイムの sp_RbVal/cls_id 機構は変更不要。集合は **静的判定** だけの情報。runtime は cls_id で正しく分岐。
+
+## 不動点の収束
+
+Stage 2 では union (拡大) と intersection (縮小) の両方を扱う:
+
+- caller→callee widening (scan_new_calls): union で拡大
+- callee→caller (戻り値伝播): union で拡大
+- body-side narrow (Stage 1 拡張): intersection で縮小
+
+各 round 内の順序を:
+1. union 系 (call-site 観測) を全部走らせて param ptype を膨らませる
+2. その後で intersection 系 (body 観測) を走らせて絞る
+
+→ "拡大→縮小" の順序が各 round で一定なら、実質単調に近づく。`inference_signature` で前回と等しくなったら stop。最大 round 数を上げる必要があるかもしれない (現状 4 → 6〜8 程度に)。
+
+## 互換性 / 移行ステップ
+
+Stage 2 を 1 PR で全部入れるのは bootstrap risk が高い。段階移行:
+
+### 2a. 表現拡張 (no-op)
+- `"poly{A;B}"` 文字列を内部で生成する経路を入れるが、すべて `"poly"` に折り畳んで返す
+- `unify_call_types` などはまだ既存挙動
+- すべての判定箇所が新表現を view できることを bootstrap で確認
+
+### 2b. set-intersection narrow
+- Stage 1 の単一クラス制約を外す
+- `unify_param_class_from_observations` を set intersection で書き直す
+- 既存の `"poly"` への混合型 degrade はそのまま
+
+### 2c. else-arm 負の絞り込み
+- IfNode の else-arm に type_minus 適用
+- recursive scan のスコープ管理を慎重に (then と else で違う narrow)
+
+### 2d. emit-side 列挙の限定
+- `compile_poly_method_call` で候補集合があればそれを使う
+- emit 出力差を 1 PR で分離 (review しやすさのため)
+
+## リスクと観察ポイント
+
+1. **bootstrap stability**: 型文字列処理の 1 箇所のミスで gen2 != gen3 → CI 全敗
+   - 各サブステップ後 `make bootstrap` 必須
+   - 表現変更前に既存 split/join ロジックの全数 grep し、新セパレータ衝突の有無を確認
+
+2. **テスト盲点**: 
+   - 集合サイズ 0 (空 = unreachable) のハンドリング
+   - サイズ 1 → obj_<C> 折り畳みの一貫性
+   - 全クラス集合と "poly" の等価扱い
+
+3. **ROI 計測**:
+   - Stage 2a 完了時点で既存テスト + Roundhouse archive で no-op 確認
+   - Stage 2b 後、stage 1 で narrow できなかった param が集合 narrow できる事例を 1 つ以上見つける (見つからないなら投資中止判断材料)
+   - Stage 2c, 2d は 2b の効果を見て継続判断
+
+## 着手判断条件
+
+Stage 2 に踏み込むべきタイミング:
+
+- `caller-side widening が届かない経路` 起源でない、**型精度**起源のバグが具体例で現れた時
+- Roundhouse 移行が runtime 段階に入って "static dispatch ミス" が顕在化した時
+- emit サイズ・cc 時間のボトルネックが計測で示された時 (現状は CI 11分問題は sccache miss 由来で、emit サイズではない)
+
+それまでは Stage 1 で観察を継続。
+
+---
+
+参考:
+- Stage 1: `narrow_param_types_from_body_method_calls` (`0d10645`)
+- 関連コメント: `spinel_codegen.rb` の `scan_new_calls` IfNode 処理 ("we don't currently model 'type minus C'")
+- 既存集合的ロジックの先例: `module_acc_resolved` のセミコロン区切りクラス候補リスト (#126)