rubyduino 0.1.3 → 0.2.1

data/vendor/spinel/docs/issue-646-plan.md

@@ -0,0 +1,159 @@
+# Issue #646 修正計画
+
+## 現象
+
+```ruby
+class App
+  def initialize
+    APP.something    # APP is being initialized RIGHT NOW
+  end
+end
+APP = App.new
+```
+
+MRI: `NameError: uninitialized constant App::APP` を init 中に raise。
+spinel: `cst_APP` は `NULL`。read は NULL を返し、`.something` で segfault。
+
+reporter の実例 (tep#13) は transitive ケース:
+```
+APP = App.new
+  → App#initialize
+    → PG::Connection.new(...)
+      → ... → Tep::Scheduler.scheduled_context?
+        → Tep::APP.sched_current   # APP is still NULL
+```
+
+dispatch が compile-time に static resolve した結果、`cst_Tep_APP->iv_sched_current` が直接 emit され、NULL deref で SEGV。
+
+## 現在の対応 (765b984)
+
+直接 shape (`Class#initialize` が `CONST` を直接 read、ただし `CONST = Class.new` 形式) を compile-time に detect して clearer warning を emit。Runtime crash の plug は無し。
+
+## ゴール
+
+issue の expected behaviour:
+1. **Best**: MRI 互換の `NameError` raise (option 1)
+2. **Acceptable**: `nil` を返して method dispatch で NoMethodError (option 2)
+3. **現状 / Worst**: silent partial-init pointer / SEGV (option 3)
+
+option 1 を目指す。
+
+## 修正案: per-const in-progress flag + read-side guard
+
+### Phase 1: 直接 shape (`<C>` init reads `<X>` where `<X> = <C>.new`)
+
+#### Analyzer 側 (spinel_analyze.rb)
+
+新しい table `@const_init_class`:
+- 要素: `@const_expr_ids[i]` が `<Class>.new(...)` shape なら `<Class>` の名前。そうでなければ `""`。
+- IR export: `SA @const_init_class N value;value;...`
+
+```ruby
+def detect_const_init_classes
+  @const_init_class = "".split(",")
+  i = 0
+  while i < @const_expr_ids.length
+    init_cls = ""
+    eid = @const_expr_ids[i]
+    if eid >= 0 && @nd_type[eid] == "CallNode" && @nd_name[eid] == "new"
+      recv = @nd_receiver[eid]
+      if recv >= 0 && @nd_type[recv] == "ConstantReadNode"
+        init_cls = @nd_name[recv]
+      end
+    end
+    @const_init_class.push(init_cls)
+    i = i + 1
+  end
+end
+```
+
+`generate_code` 内の早めのタイミング (precompute_all_scope_decls 後) で 1 回呼び出し。
+
+#### Runtime 側 (lib/sp_runtime.h)
+
+`sp_raise_cls("NameError", msg)` は既存。再利用する。新しいヘルパは不要。
+
+#### Codegen 側 (spinel_codegen.rb)
+
+1. **Per-const in-progress flag emit** (`emit_const_init` 周辺):
+   - `@const_init_class[i]` が空でない const に対し、`static int sp_init_in_progress_<X> = 0;` を const 宣言と一緒に emit。
+
+2. **Const init assignment を guard で包む** (`emit_const_init` 内):
+   ```c
+   sp_init_in_progress_X = 1;
+   cst_X = sp_C_new();
+   sp_init_in_progress_X = 0;
+   ```
+
+3. **Const read site で in-progress check** (`compile_expr` ConstantReadNode arm):
+   - resolve した const X の `@const_init_class[ci]` が空でない場合のみ、wrap で emit:
+   ```c
+   ((sp_init_in_progress_X) ? (sp_raise_cls("NameError", "uninitialized constant X"), (sp_C *)NULL) : cst_X)
+   ```
+   - sp_raise_cls 後の cast は dead code だが C compile を通すために必要。
+
+### Phase 2 (任意 - 最適化)
+
+- 完全に static に "init 経路外" と判明する read site (e.g., main の APP = App.new の後 emit される statements) では in-progress check を skip。
+- これにより hot path の overhead をゼロにできる (call graph 解析が必要)。
+- Phase 1 だけでも MRI 互換 + 性能影響は branch 1 つ per const read のみ。許容範囲。
+
+## 影響範囲
+
+| ファイル | 変更内容 | 行数概算 |
+|---|---|---|
+| spinel_analyze.rb | `detect_const_init_classes` 追加 + `generate_code` 呼び出し + IR export | ~30 |
+| spinel_codegen.rb | `@const_init_class` ロード + const decl で flag emit + assign を guard + read 側 wrap | ~50 |
+| lib/sp_runtime.h | 変更不要 (sp_raise_cls 再利用) | 0 |
+| test/ | 新規 regression test (NameError raise + rescue) | ~20 |
+
+## 検証
+
+```ruby
+# test/const_self_ref_raises_name_error.rb
+class App
+  def initialize
+    APP                    # ← raises NameError
+  rescue NameError => e
+    puts "caught: " + e.message
+  end
+end
+APP = App.new
+puts "after"
+```
+
+Expected:
+```
+caught: uninitialized constant APP
+after
+```
+
+## エッジケース
+
+1. **Transitive (`APP = build_app()` where build_app does `App.new`)**: Phase 1 では Catch しない。`@const_init_class[APP]` は `""` (build_app は CallNode `new` でも recv が ConstantReadNode でもない)。Phase 2 でも難しい (call graph + dispatch resolve が必要)。Reporter の workaround で対応可能。
+
+2. **Class hierarchy: `APP = SubApp.new` で SubApp < App**: `@const_init_class[APP] = "SubApp"`。SubApp#initialize 内 + 継承された App#initialize 内の APP read は guard 対象。inheritance walk を `@const_init_class` のチェックに加える必要あり。Phase 1 では SubApp の直接 init のみ catch、parent init は miss する可能性 — phase 1.5 で追加するか。
+
+3. **Module const (`APP = App.new` inside `module Tep`)**: const 名は `Tep_APP`。`@const_init_class` は qualified 名で record。標準パスで動く。
+
+4. **`||=` re-init**: `APP ||= App.new` (rare)。`@nd_type[eid]` が ConstantOrWriteNode と違う。最初の `=` パスでのみ guard、`||=` は skip。妥当。
+
+5. **Setter on partially-init recv (`APP.foo = bar`)**: const recv が NULL の attr_writer dispatch。setter は usually `cst_APP->iv_foo = ...` を emit → NULL deref で SEGV。Guard の wrap がここでも必要。compile_call_expr の `[]=` / attr_writer setter dispatch でも cst_X recv detect が要る。
+
+## 段階的な実装
+
+Phase 1 で issue #646 のメインケース (直接 shape) を MRI 互換に raise する。
+Phase 1.5 で inheritance walk と setter path を追加。
+Phase 2 (任意) で call graph による guard 削減。
+Transitive case (build_app 経由) は inherently 難しく、document する方が pragmatic。
+
+## 実装順序
+
+1. `detect_const_init_classes` 追加、IR export 動作確認
+2. Codegen で `@const_init_class` をロード、in-progress flag を decl
+3. Const assignment を guard で包む emit
+4. Const read site の wrap
+5. Regression test 追加
+6. setter path 追加 (Phase 1.5)
+7. inheritance walk (Phase 1.5)
+8. push + close #646

data/vendor/spinel/docs/promote-mode-plan.md

@@ -0,0 +1,227 @@
+# `--int-overflow=promote` 完全動作計画
+
+## ゴール
+
+`SPINEL_INT_OVERFLOW=promote` (`-DSP_INT_OVERFLOW_MODE_PROMOTE`) で:
+- `make test` 全 pass
+- `make bench` 全 pass
+- `make optcarrot` PASS + checksum 59662 (Makefile から `--int-overflow=wrap` pin 除去)
+
+## 現状 (master HEAD, commit `bc7e1a1`)
+
+| Target | promote 結果 | 主要 error |
+|---|---|---|
+| `make test` | 557 / 52 fail / 22 error | 23 errors の多くは bit-ops / typed-call-args poly→bigint |
+| `make bench` | 36 / 7 fail / 14 error | bit-ops, IntArray index with bigint, FFI float arg |
+| `make optcarrot` (--int-overflow=promote) | C compile failed | 72 errors、 80%以上が bit-op (`&`, `\|`, `^`, `<<`, `>>`, `~`) |
+
+## Error バケット分類
+
+### Bucket A: Bit operators on `sp_Bigint *` (LARGEST — optcarrot の 80%)
+
+```
+error: invalid operands to binary & (have 'sp_Bigint *' and 'long long int')
+error: wrong type argument to bit-complement
+```
+
+Ruby の `a & b`, `a | b`, `a ^ b`, `a << n`, `a >> n`, `~a` で operands が bigint の時 C 演算子が使えない。 optcarrot は CPU emulator なので bit-op が大量。
+
+**修正**: runtime helpers + codegen 分岐:
+- `sp_bigint_and(a, b)`, `_or`, `_xor`, `_shl`, `_shr`, `_not`, `_inv`
+- `compile_operator_expr` / `compile_bitop_expr` で bigint operands を検出 → helper call emit
+- 混在 (bigint + int_literal) → 一方を unbox / box して揃える
+
+### Bucket B: Builtin container helpers with bigint args
+
+```
+sp_IntArray_push(a, bigint_lv)   ← needs sp_bigint_to_int
+sp_IntArray_get(a, bigint_idx)
+sp_FloatArray_set(a, idx, bigint_val)  ← unbox + cast to mrb_float
+sp_IntStrHash_set(h, bigint_key, val)
+```
+
+memory に partial fix 言及あり。 残るのは `_push` / `_get` / `_set` の特定 site と FloatArray の bigint→float cast。
+
+### Bucket C: 反復 / index で bigint
+
+```
+range.each { |i| arr[i] = ... }   ← i bigint、 arr[i] で unbox 必要
+n.times { |i| ... }
+```
+
+block param が bigint で IntArray index 等に使われる shape。 既に部分対応済みだが取りこぼし。
+
+### Bucket D: FFI / typed user method call の poly → bigint coerce
+
+```
+sp_Counter_cls_double(poly_val)   ← param bigint、 arg poly
+sp_mandelbrot(bigint, bigint)     ← FFI param float、 arg bigint
+```
+
+`compile_typed_call_args` で poly arg → bigint param の coerce を追加 (mirror of #639 IVW unbox)。 FFI :float / :int arg は bigint で `sp_bigint_to_int` → cast。
+
+### Bucket E: Bigint slot init / return from poly
+
+```
+sp_Bigint * x = poly_expr          ← .v.p extract 必要
+return poly_expr                   (function return bigint)
+```
+
+`compile_expr_for_expected_type` の poly→bigint arm が無い / 不完全。
+
+### Bucket F: Bigint → string 変換漏れ
+
+```
+puts bigint_val
+"prefix" + bigint_val
+sp_int_to_s(bigint_val)            ← should be sp_bigint_to_s
+```
+
+memory に「文字列補間 / str_concat / str << の bigint→string 変換 (sp_bigint_to_s)」とあり partial fix 済み。 残りの emit site を探す。
+
+### Bucket G: Test/bench infrastructure issues
+
+promote と無関係に表面化する shape:
+- `int_eq_nil_strict` — int slot が bigint 化したので nil check の挙動が変わる
+- `pattern_pin` — pin pattern が int を期待してるが bigint で型不一致
+- `const_self_ref_init_warns` — 出力 format 変化 (`0` vs `0LL`?)
+
+これらは個別調査。
+
+## Phases (実装順)
+
+### Phase 1 — Bit-op support for bigint (大ブロッカー解消)
+
+最大の塊。 これで optcarrot の 80% errors が消える。
+
+1.1 `lib/sp_runtime.h`: 新 helpers
+- `sp_bigint_and(a, b)`, `_or(a, b)`, `_xor(a, b)` — 既存 GMP wrapper 経由
+- `sp_bigint_shl(a, n)`, `_shr(a, n)` — n は mrb_int
+- `sp_bigint_not(a)` — 1's complement (符号反転 + 1 で signed と同じ)
+
+1.2 `lib/sp_bigint.c`: GMP `mpz_and` / `mpz_ior` / `mpz_xor` / `mpz_mul_2exp` / `mpz_fdiv_q_2exp` / `mpz_com` ラップ
+
+1.3 `spinel_codegen.rb`:
+- `compile_operator_expr` で `op in {"&", "|", "^", "<<", ">>"}` && (lt == bigint || rt == bigint) → helper
+- `~` の単項 (`compile_call_expr` で recv bigint mname `~`) → `sp_bigint_not`
+- mixed (bigint + int literal): literal を `sp_bigint_new_int` で box して helper、 OR 両方 unbox して C 演算子 → re-box
+
+1.4 `optcarrot` で動作確認、 checksum 59662 維持確認
+
+期待: optcarrot promote PASS、 test promote +20〜30 cases
+
+### Phase 2 — Builtin container helpers の bigint unbox 取りこぼし
+
+2.1 `sp_IntArray_push` emit site: arg が bigint なら `sp_bigint_to_int` を wrap
+2.2 `sp_IntArray_get` / `_set` / `_index` 同様
+2.3 `sp_FloatArray_set` の val が bigint なら `(mrb_float)sp_bigint_to_int(...)` で cast
+2.4 `sp_*IntHash_*` で key/val bigint の unbox
+
+期待: bench bm_loops_times / bm_matmul / bm_fannkuch PASS。 test promote +10〜15 cases
+
+### Phase 3 — Typed user method call の poly→bigint coerce
+
+3.1 `compile_typed_call_args` (positional + kwarg):
+- 引数の static type が `poly` で param expected が `bigint` → `(arg).v.p` 経由
+- mirror of #639 の IVW unbox path
+
+3.2 FFI :float / :int arg with bigint:
+- `compile_ffi_func_call` で arg が bigint なら `sp_bigint_to_int` → cast
+
+期待: nullable_poly_hash_arg_unbox 等 +5 tests、 bm_mandel_term / bm_so_mandelbrot 系 PASS
+
+### Phase 4 — Bigint slot init / return from poly
+
+4.1 `compile_expr_for_expected_type`: at == "poly" && expected == "bigint" → `(... ).v.p`
+4.2 `compile_return_stmt`: rt == "poly" && method return == "bigint" → 同様 unbox
+
+期待: 残 test promote errors +5
+
+### Phase 5 — Bigint → string 変換取りこぼし
+
+5.1 `puts bigint`, string interpolation `"x=#{bigint}"`, `<<` chain の emit site で bigint operand → `sp_bigint_to_s` 経由
+
+期待: bench bm_csv_process / bm_jekyll_lite 系 PASS
+
+### Phase 6 — 個別 test failure 調査
+
+残 test failures を個別に潰す。 各々小さな shape:
+- `int_eq_nil_strict` — bigint slot で nil compare 挙動
+- `pattern_pin` — pattern matching の bigint scrutinee
+- `const_self_ref_init_warns` — output format 微差
+
+期待: test promote 100% pass
+
+### Phase 7 — Bench 残り + Makefile 整理
+
+7.1 残 bench failures 個別に潰す
+7.2 Makefile から `optcarrot` 用 `--int-overflow=wrap` pin 除去 (or `--int-overflow=$(SPINEL_INT_OVERFLOW)` defaulting to wrap だが promote でも通る)
+
+期待: bench promote 100% pass
+
+## 検証フロー (各 phase で)
+
+```bash
+# default mode は壊さない
+rm -rf build/test-results/
+make -j8 test 2>&1 | tail -2   # 631/0/0 維持
+make optcarrot 2>&1 | tail -3  # checksum 59662 維持
+
+# promote mode 進捗
+rm -rf build/test-results/
+SPINEL_INT_OVERFLOW=promote make \
+  CFLAGS="-O2 -Wno-all -Wno-unknown-warning-option -Wno-alloc-size-larger-than -DSP_INT_OVERFLOW_MODE_PROMOTE" \
+  -j8 test 2>&1 | tail -2
+
+SPINEL_INT_OVERFLOW=promote make \
+  CFLAGS="-O2 -Wno-all -Wno-unknown-warning-option -Wno-alloc-size-larger-than -DSP_INT_OVERFLOW_MODE_PROMOTE" \
+  -j8 bench 2>&1 | tail -2
+
+# optcarrot single
+SPINEL_INT_OVERFLOW=promote ./spinel --int-overflow=promote build/optcarrot-single.rb -o /tmp/op_p
+/tmp/op_p
+```
+
+## 効果量予想 (累積)
+
+| Phase | test | bench | optcarrot |
+|---|---|---|---|
+| 現状 | 557/52/22 | 36/7/14 | C compile fail |
+| 1完了 | ~580/45/15 | ~45/5/7 | **PASS** (checksum 59662) |
+| 2完了 | ~595/40/8 | ~52/3/2 | PASS |
+| 3完了 | ~610/15/4 | ~55/2/0 | PASS |
+| 4完了 | ~620/8/2 | ~56/1/0 | PASS |
+| 5完了 | ~625/5/0 | ~57/0/0 | PASS |
+| 6完了 | **631/0/0** | 57/0/0 | PASS |
+| 7完了 | 631/0/0 | **57/0/0** | PASS (Makefile clean) |
+
+## 工数概算
+
+- Phase 1 (bit-ops): 2-4 hours
+- Phase 2 (containers): 1-2 hours
+- Phase 3 (call args): 1-2 hours
+- Phase 4 (return/slot): 0.5-1 hour
+- Phase 5 (string conv): 0.5-1 hour
+- Phase 6 (個別 test): 2-4 hours (varies)
+- Phase 7 (bench + Makefile): 1-2 hours
+
+**合計**: 8-16 hours focused work
+
+## 進め方の注意
+
+- **default を壊さない**: 各 commit 直後に `make test` (default 631/0/0) + `make optcarrot` (wrap pin、 checksum 59662) を回す
+- **commit を小刻みに**: bucket 1 つ ≒ 1 commit (memory `feedback_commit_often`)
+- **inline 関数 vs macro**: `sp_int_*` は macro。 新規 helper も同じ pattern で (memory `feedback_promote_mode_inline_pitfall`)
+- **stale cache 注意**: promote_int_to_bigint_globally 後の cache invalidation 漏れに警戒
+- **記録**: 各 phase の commit 後、 残り errors / fails の数を memo して進捗トラック
+
+## Risks
+
+1. **optcarrot は --int-overflow=wrap が最速**: promote だと bigint helper call overhead で fps 低下が予想される。 Makefile のデフォルトは wrap のままにする (promote は opt-in mode という設計に沿う)
+2. **bigint memory pressure**: 全 int slot が heap-allocated bigint になる → GC 圧と allocator churn。 既存 GC で対応できるか測定要
+3. **既存 default test の non-determinism**: 不変なはずだが、 stale cache invalidation 経由で稀に regression が出る可能性あり。 毎 commit で default test 必須
+4. **新 helper の signedness**: GMP の `mpz_and` 等は arbitrary-precision で signed 自然サポート。 spinel 側で signedness 維持確認
+
+## 開始 phase
+
+**Phase 1 (bit-ops)** を最優先。 optcarrot を unblock し、 影響が最も大きい。 着手後、 各 helper を 1 つずつ追加 → optcarrot で動作確認 → commit。

data/vendor/spinel/docs/setbyte-semantic-plan.md

@@ -0,0 +1,203 @@
+# String#setbyte semantic-preserving plan (改訂版: frozen literal 採用)
+
+## 方針
+
+**spinel は `# frozen_string_literal: true` がグローバルに有効な Ruby として振る舞う。**
+
+- string literal は frozen (rodata に置く既存設計と整合)
+- 変更操作 (setbyte, <<, concat, replace, !-suffix mutators, …) を frozen literal に対して行うと `FrozenError` を raise
+- mutable string が必要なら `.dup` で heap allocate
+
+## 何故これが正しいか
+
+1. **spinel の既存設計と一致**: literal は既に rodata に dedup されている。 frozen として扱うのが本質的に正しい
+2. **Ruby の方向性**: 3.0+ で frozen-string-literal を推奨、 将来的にデフォルト化の議論あり
+3. **subset の identity と一致**: spinel は Ruby のサブセット → サブセット内では一貫した強い保証を提供する設計
+4. **silent failure を排除**: no-op は最悪。 raise なら user は問題を即座に発見し `.dup` で fix できる
+5. **aliasing 曖昧さの解消**: COW にあった `a = "ab"; b = a; a.setbyte(...)` の divergence 問題が起きない (mutation 試行で必ず raise)
+
+## 現在の問題
+
+`commit bbfc3b3` (sp_str_setbyte) の挙動:
+- heap (0xfe/0xfc/0xfd) → mutate ✓
+- literal (0xff) → **silent no-op** ✗
+- FFI / unknown → silent no-op ✗
+
+silent no-op は受け入れられない。 frozen literal semantics で raise に切り替える。
+
+## Phase 1: setbyte の frozen literal raise
+
+### Runtime 変更
+
+`lib/sp_runtime.h` の `sp_str_setbyte`:
+
+```c
+static inline mrb_int sp_str_setbyte(const char *s, mrb_int i, mrb_int v) {
+  if (!s) return v;
+  unsigned char m = ((const unsigned char *)s)[-1];
+  if (m == 0xfe || m == 0xfc || m == 0xfd) {
+    ((char *)s)[i] = (char)v;
+    return v;
+  }
+  /* literal (0xff) or FFI / unknown -> frozen, raise. spinel
+     treats all string literals as frozen-string-literal: true. */
+  sp_raise_cls("FrozenError", "can't modify frozen String");
+  return v;  /* unreachable; longjmp via sp_raise_cls */
+}
+```
+
+### Codegen 変更
+
+なし。 既存の `sp_str_setbyte(rc, idx, val)` emit がそのまま runtime check を経由する。
+
+### Test 更新
+
+`test/str_method_nil_arg_no_segv.rb` の setbyte 部分が FrozenError raise するように:
+
+```ruby
+# 旧:
+(str = "a")
+str.setbyte(0, 98)
+puts str   # spinel: "a" (mutation dropped)
+
+# 新:
+(str = "a")
+begin
+  str.setbyte(0, 98)
+  puts "no raise: " + str
+rescue FrozenError => e
+  puts "frozen: " + e.message
+end
+```
+
+期待値 `"frozen: can't modify frozen String"`。
+
+### 新 regression test (`test/str_setbyte_frozen_literal.rb`)
+
+```ruby
+# Spinel adopts `# frozen_string_literal: true` semantics globally:
+# string literals are immutable; setbyte on a literal raises
+# FrozenError. To mutate, use .dup or a fresh heap-allocated
+# string from .+/.concat etc.
+
+# Literal: raises
+begin
+  s = "abc"
+  s.setbyte(0, 67)
+  puts "no raise"
+rescue FrozenError => e
+  puts "literal: " + e.message
+end
+
+# Dup'd: mutates
+s2 = "abc".dup
+s2.setbyte(0, 67)
+puts s2   # Cbc
+
+# String#+: mutates (returns fresh heap)
+s3 = "x" + "y"
+s3.setbyte(0, 90)
+puts s3   # Zy
+
+# ivar on heap string: mutates
+class C
+  attr_reader :buf
+  def initialize; @buf = "abc".dup; end
+  def hit; @buf.setbyte(0, 67); end
+end
+c = C.new
+c.hit
+puts c.buf  # Cbc
+```
+
+期待値:
+```
+literal: can't modify frozen String
+Cbc
+Zy
+Cbc
+```
+
+## Phase 2: 他の mutator にも適用 (follow-up)
+
+Phase 1 が安定したら、 同じ frozen-check を以下にも適用:
+
+| Method | 現状 | 目標 |
+|---|---|---|
+| String#<< | (調査要) | literal recv で FrozenError |
+| String#concat | (調査要) | 同上 |
+| String#replace | (調査要) | 同上 |
+| String#chomp! | (調査要) | 同上 |
+| String#strip! | (調査要) | 同上 |
+| String#squeeze! | (調査要) | 同上 |
+| String#gsub!, sub! | (調査要) | 同上 |
+| String#upcase!, downcase! 等 | (調査要) | 同上 |
+
+各 method の codegen で marker check を runtime emit するか、 共通 helper を経由させる。 Phase 2 は別 issue で個別に対応。
+
+## Phase 3: ユーザー視点の error message 改善
+
+`FrozenError` の message を spinel-aware に:
+- `can't modify frozen String (literal "<content>")` のように literal 文字列の先頭 32 文字を含めると debug 容易
+- ただし stack trace が無いので line 情報は出ない (既存の sp_raise_cls 仕様)
+
+Phase 3 はオプション。
+
+## Aliasing semantics — frozen literal 採用で完全互換
+
+| Pattern | spinel (frozen literal) | MRI (frozen literal pragma) | 一致? |
+|---|---|---|---|
+| `a = "ab"; a.setbyte(0, 67)` | FrozenError raise | FrozenError raise | ✅ |
+| `a = "ab"; b = "ab"; a.setbyte(0, 67)` | FrozenError raise | FrozenError raise | ✅ |
+| `a = "ab".dup; b = a; a.setbyte(0, 67)` | mutate, b="Cb" (shared) | mutate, b="Cb" (shared) | ✅ |
+| `a = "ab".dup; a.setbyte(0, 67)` | mutate | mutate | ✅ |
+
+frozen literal pragma 有効な Ruby と完全一致。
+
+## bm_ruby_xor の挙動
+
+```ruby
+def xor_strings(a, b)
+  result = a.dup    # heap (0xfe)
+  result.setbyte(i, ...)  # heap path で mutate
+  result
+end
+```
+
+dup で heap 化されるので問題なし。 Phase 1 で PASS。
+
+## 影響範囲
+
+| File | 変更 | 行数 |
+|---|---|---|
+| lib/sp_runtime.h | `sp_str_setbyte` を frozen-raise 化 | ~5 |
+| test/str_method_nil_arg_no_segv.rb | literal setbyte を rescue で wrap | ~8 |
+| test/str_method_nil_arg_no_segv.rb.expected | "a" → "frozen: ..." | ~1 |
+| test/str_setbyte_frozen_literal.rb | 新 regression test | ~25 |
+| test/str_setbyte_frozen_literal.rb.expected | | ~4 |
+| docs/SPINEL-SEMANTICS.md (任意) | frozen-literal-default の document | ~30 |
+
+## 検証
+
+- `make test`: 628/0/0 → 629/0/0 (新 regression test 追加、 既存 test の expected 更新)
+- `make bench`: 57/0/0/0 維持 (bm_ruby_xor は dup → heap path)
+- `make optcarrot`: checksum 59662 維持
+
+## Risks
+
+1. **既存 user code の breakage**: spinel で動いていた `s = "abc"; s.setbyte(...)` が raise に変わる
+   - 緩和: error message が明確、 `.dup` で簡単に修正可能
+   - spinel は Ruby subset、 frozen literal pragma に依存することは subset 内では妥当
+2. **他の mutator が consistent でない**: Phase 1 では setbyte のみ。 String#<< 等は別挙動のまま
+   - 緩和: Phase 2 で順次対応、 個別 issue で track
+3. **FFI / unknown marker への扱い**: 現在は literal 同様 raise (defensive)
+   - FFI で返った文字列は通常 spinel-side で `sp_str_dup_external` 経由して heap 化されているので実害は少ない
+
+## 実装順
+
+1. `sp_str_setbyte` を frozen-raise 化
+2. `test/str_method_nil_arg_no_segv` 更新
+3. 新 regression test `str_setbyte_frozen_literal` 追加
+4. `make test` / `make bench` / `make optcarrot` 全通し
+5. commit + push
+6. Phase 2 (他の mutator) を別 issue として open

data/vendor/spinel/examples/ffi/sqlite/README.md

@@ -65,9 +65,10 @@ Comments on the FFI post:
 
 ## Notes
 
-The demo uses inline-quoted SQL with `Sql.q` for escaping, not bound
-parameters. The reason: `sqlite3_bind_text`'s last argument is a
-destructor callback (the `SQLITE_TRANSIENT` sentinel is `(void *)-1`),
-and the MVP FFI can't yet construct a `:ptr` from a sentinel integer.
-For real applications you'd write a tiny C helper that wraps `bind_text`
-with `SQLITE_TRANSIENT` baked in and link it alongside.
+The demo uses inline-quoted SQL with `Sql.q` for escaping, kept as the
+minimal path through `prepare_v2` / `step` / `finalize`. For bound
+parameters, `sqlite3_bind_text` is supported directly — pass `-1` as
+the destructor argument to get `SQLITE_TRANSIENT` (`(void *)-1`); the
+FFI accepts an integer literal in a `:ptr` arg slot and emits
+`((void *)-1LL)`. See `sqlite3_lib.rb` for the `ffi_func` declaration
+and `test/ffi_ptr_int_literal.rb` for the regression test.

data/vendor/spinel/examples/ffi/sqlite/sqlite3_lib.rb

@@ -5,10 +5,12 @@
 #   - exec for DDL + INSERT/UPDATE/DELETE
 #   - prepare_v2 / step / finalize + column accessors for SELECT
 #
-# Strings are passed inline into SQL; bind_text would also work but
-# requires the SQLITE_TRANSIENT destructor sentinel which the Spinel FFI
-# can't construct as a `:ptr` value yet. For string columns we escape
-# single quotes ourselves (`Sql.q`).
+# Strings are passed inline into SQL: `Sql.q` doubles single quotes
+# to handle the demo's well-known inputs. `bind_text` is also
+# supported — pass `-1` as the destructor argument for
+# `SQLITE_TRANSIENT` (`((sqlite3_destructor_type)-1)`), the same
+# wire-shape ruby-ffi exposes via `FFI::Pointer.new(-1)`. See
+# test/ffi_ptr_int_literal.rb for the underlying primitive.
 module SQL
   ffi_lib "sqlite3"
 
@@ -21,6 +23,7 @@ module SQL
   ffi_func :sqlite3_close,             [:ptr],                                :int
   ffi_func :sqlite3_exec,              [:ptr, :str, :ptr, :ptr, :ptr],        :int
   ffi_func :sqlite3_prepare_v2,        [:ptr, :str, :int, :ptr, :ptr],        :int
+  ffi_func :sqlite3_bind_text,         [:ptr, :int, :str, :int, :ptr],        :int
   ffi_func :sqlite3_step,              [:ptr],                                :int
   ffi_func :sqlite3_finalize,          [:ptr],                                :int
   ffi_func :sqlite3_column_int,        [:ptr, :int],                          :int

data/vendor/spinel/experiments/rbs/box.rb

@@ -0,0 +1,32 @@
+# Spike fixture: a class whose `relabel` method is never called from
+# main, so without RBS seeding spinel's analyzer has no call-site
+# evidence to infer `s`'s type. Default for unseen params is `int`,
+# which then disagrees with @label (a string ivar) when the method
+# body assigns `@label = s`. Without seeding, that disagreement
+# either widens @label to poly or forces a coercion in codegen.
+#
+# With RBS seeding (see box.seed -> `meth relabel string string`),
+# `s` starts as :string. The body assignment matches the ivar's
+# declared type and no widening / coercion happens.
+#
+# This file alone compiles and runs identically either way -- the
+# observable difference is in the analyzer's IR output for the
+# Box class. See harness.rb for the diff.
+
+class Box
+  def initialize
+    @label = "default"
+  end
+
+  def relabel(s)
+    @label = s
+    @label
+  end
+
+  def show
+    @label
+  end
+end
+
+b = Box.new
+puts b.show

data/vendor/spinel/experiments/rbs/box.seed

@@ -0,0 +1,18 @@
+# Hand-written seed file for box.rb. In the eventual --rbs flow, this
+# file is generated by scripts/spinel_rbs_extract.rb from a sig/box.rbs
+# declaring the same shapes. For the spike we author it directly so the
+# seeding mechanism can be tested without depending on the rbs gem.
+#
+# Format: see load_rbs_seeds / apply_rbs_seeds in spinel_analyze.rb.
+#   class <Name>             -- enter class scope
+#   meth <name> <ret> <ptypes>  -- ret/ptypes are `-` for "leave alone";
+#                                  ptypes is comma-separated
+#   ivar <name> <type>       -- seed ivar type
+# Any line whose first token isn't a keyword is ignored (so this comment
+# block costs nothing).
+
+class Box
+ivar label string
+meth relabel string string
+meth show string -
+meth initialize - -