rubyduino 0.1.3 → 0.2.1

data/vendor/spinel/docs/HASH-NULLABLE.md

@@ -0,0 +1,379 @@
+# Hash Nullable Semantics
+
+Phase 1 design doc for aligning all typed-hash variants' `[]` lookup
+with Ruby semantics (`h[missing_key] == nil`).
+
+## Problem
+
+Of 8 typed-hash variants, 5 violate Ruby semantics by returning a
+non-nil sentinel on missing-key lookup:
+
+| Variant | Value type | Missing-key returns | Ruby semantics |
+|---|---|---|---|
+| `StrIntHash` | `mrb_int` | `0` | nil |
+| `SymIntHash` | `mrb_int` | `0` | nil |
+| `StrStrHash` | `const char *` | `sp_str_empty` ("") | nil (NULL) |
+| `SymStrHash` | `const char *` | `sp_str_empty` ("") | nil (NULL) |
+| `IntStrHash` | `const char *` | `sp_str_empty` ("") | nil (NULL) |
+| `StrPolyHash` | `sp_RbVal` | `sp_box_nil()` | nil (correct) |
+| `SymPolyHash` | `sp_RbVal` | `sp_box_nil()` | nil (correct) |
+| `PolyPolyHash` | `sp_RbVal` | `sp_box_nil()` | nil (correct) |
+
+User-visible consequences:
+
+- `if h[:missing]; ... end` — current spinel sees "" / 0 as truthy
+  for the string/int variants, contrary to Ruby
+- `cached = h[k]; if cached.length > 0` — works around the bug at
+  caller-side but pollutes call sites
+- The codegen's own `has_key?+[]` fusion bug (uncovered during
+  measurement work) was triggered by `StrStrHash_get` returning ""
+  on miss instead of NULL
+
+## Sentinel Convention
+
+Reuse spinel's existing dual nullable encoding:
+
+- **Pointer-nullable** (`is_nullable_pointer_type`): `string`,
+  `<hash variants>`, `<array variants>`, `<obj_X>`, etc. — `NULL`
+  is the nil inhabitant
+- **Scalar-nullable** (`is_scalar_nullable_type`): `int?` — uses
+  `SP_INT_NIL = INT64_MIN` sentinel via the existing
+  `sp_int_is_nil(v)` predicate
+
+Mapping per variant:
+
+| Variant | New `_get` returns on miss | LV slot when `x = h[k]` |
+|---|---|---|
+| `StrIntHash` | `SP_INT_NIL` | `int?` (mrb_int with sentinel) |
+| `SymIntHash` | `SP_INT_NIL` | `int?` |
+| `StrStrHash` | `NULL` | `string` (const char *, already nullable) |
+| `SymStrHash` | `NULL` | `string` |
+| `IntStrHash` | `NULL` | `string` |
+| `*PolyHash` | (unchanged) | `poly` (already nullable via box_nil) |
+
+### Sym-valued hashes
+
+spinel currently has no dedicated `*SymHash` variant (no `sym_sym_hash`,
+`str_sym_hash`, or `int_sym_hash`). Hash literals with symbol values
+(e.g. `{a: :x}`) infer as `sym_poly_hash` / `str_poly_hash` etc. and
+box symbols into `sp_RbVal` (SP_TAG_SYM) -- so missing-key already
+returns `sp_box_nil()`, Ruby-compatible.
+
+If a future memory-optimization Phase introduces dedicated
+`*SymHash` variants (sp_sym = mrb_int storage, 8 bytes/entry vs
+sp_RbVal's 16 bytes), the natural nil sentinel is
+`((sp_sym)-1)` -- which already serves as `c_default_val("symbol")`
+in spinel_codegen.rb. The intern table's index 0 is reserved for
+the first symbol, so -1 is unambiguously "no symbol". A
+`sym?` scalar-nullable type would follow the same shape as
+`int?` (sentinel-based, not pointer-based), gated on
+`is_scalar_nullable_type`. Out of scope for the current rollout.
+
+## Call-site Audit
+
+### Internal-safe callers (no change needed)
+
+These iterate `h->order[i]` which holds **existing** keys, so they
+never trigger the missing-key path:
+
+- `*Hash_values()` — values list from order
+- `*Hash_dup()` — clone via order walk
+- `*Hash_merge()` — combine two hashes, key from order
+- `*Hash_eq()` — compare; checks `has_key?` first per-key
+- `*Hash_update()` — copy values from order
+- `*Hash_invert()` — swap k/v, key from order
+- `*Hash_inspect()` — render via order
+- `*Hash_to_<other_variant>()` — convert via order walk
+- `*Hash_from_<other_variant>()` — likewise
+
+### `fetch(k, default)` callers (already correct)
+
+The `Hash#fetch(k, default)` codegen path already wraps with
+`has_key?` and supplies the user's `default`:
+
+```c
+sp_StrIntHash_has_key(h, k) ? sp_StrIntHash_get(h, k) : <user_default>
+```
+
+When user passes `nil`, the codegen emits `SP_INT_NIL` for the int
+variants or `NULL` for the str variants (issues #671 / #682 wired
+these up). Phase A is orthogonal — `fetch` keeps working.
+
+### `h[k]` direct callers (THE TARGET)
+
+5 sites in `spinel_codegen.rb` emit raw `sp_<Hash>_get(...)`:
+
+| Line | Variant |
+|---|---|
+| 20579, 20628 | `SymIntHash` |
+| 20758, 20794 | `SymStrHash` |
+| 21131, 21190 | `StrIntHash` |
+| 21302, 21336 | `IntStrHash` |
+| 21379, 21436 | `StrStrHash` |
+
+Each currently lowers `h[k]` to:
+
+```c
+sp_<Hash>_get(rc, key)   // returns 0 / "" on miss — wrong
+```
+
+The Phase A change makes these return the correct sentinel without
+needing a wrapper `has_key? ? get : SENTINEL` (because `_get` itself
+is the wrapper now).
+
+### iter-with-key callers (no change needed)
+
+These read `h->order[i]` (existing keys) inside `each` / `keys` etc.
+walks — they don't hit miss:
+
+- 20650, 21241, 21253, 21292, 21350, 21416 — all `h->order[i]` reads
+
+### `_eq` callers (no change needed)
+
+`*Hash_eq` walks a's keys, checks `has_key?(b, k)` first, then
+compares values. The `_get` calls inside `_eq` are guarded — never
+miss.
+
+### `_inspect` callers (no change needed)
+
+Inspect walks `h->order[i]` — existing keys only.
+
+## Analyzer `[]` Return Type Table
+
+Located at `spinel_analyze.rb:5304-5328` (the `mname == "[]"` arm).
+Current mapping:
+
+| Recv type | `[]` returns |
+|---|---|
+| `str_int_hash` | `int` |
+| `str_str_hash` | `string` |
+| `int_str_hash` | `string` |
+| `sym_int_hash` | `int` |
+| `sym_str_hash` | `string` |
+| `sym_poly_hash` | `poly` |
+| `str_poly_hash` | `poly` |
+| `poly_poly_hash` | `poly` |
+
+Phase A change:
+
+| Recv type | New `[]` returns |
+|---|---|
+| `str_int_hash` | `int?` |
+| `str_str_hash` | `string` (already nullable via NULL) |
+| `int_str_hash` | `string` |
+| `sym_int_hash` | `int?` |
+| `sym_str_hash` | `string` |
+| `sym_poly_hash` | `poly` (unchanged) |
+| `str_poly_hash` | `poly` (unchanged) |
+| `poly_poly_hash` | `poly` (unchanged) |
+
+The `int` → `int?` widening is the main analyzer change. Strings
+keep their type label because the storage (`const char *`) is
+already nullable; only the runtime miss return changes.
+
+## Downstream Codegen — NULL / SP_INT_NIL Propagation
+
+Once `_get` returns NULL / SP_INT_NIL on miss, every downstream
+operation on the result needs nullable-aware handling.
+
+### String operations (mostly already NULL-safe)
+
+- `sp_str_length(NULL)` returns 0 (NULL-safe per lib/sp_runtime.h:475)
+- `sp_str_eq(NULL, NULL)` returns 1; `sp_str_eq(NULL, "x")` returns 0
+  (NULL-safe per lib/sp_runtime.h:494)
+- `sp_str_concat(NULL, "x")` falls back to `sp_str_empty` for NULL
+  (NULL-safe coalesce per lib/sp_runtime.h:1129)
+
+These produce silently-not-Ruby-but-safe behavior (Ruby's
+`nil.length` raises NoMethodError; spinel returns 0). Phase A keeps
+the silent-coalesce behavior — only the **truthy check** changes.
+
+`if h[:missing]; ... end`:
+- Before: `if (sp_str_empty)` — non-NULL pointer is truthy in C —
+  WRONG (Ruby says nil is falsy)
+- After: `if (NULL)` — falsy in C — CORRECT
+
+### Int operations on int?
+
+The codegen already has helpers for int? from prior work
+(`compile_expr_int_opt_*`, sp_int_is_nil, etc.). Need to extend the
+inference walk to mark `x = h[k]` as widening x's slot to `int?`
+when h is a typed int-valued hash.
+
+Truthy check on int? sentinel (already implemented for
+sp_str_index_opt etc., spinel_codegen.rb:12290+):
+
+```c
+if (sp_int_is_nil(lv_x)) /* falsy */
+```
+
+### Arithmetic on SP_INT_NIL
+
+Out of scope for Phase A — same constraint as the existing `int?`
+work: arithmetic on SP_INT_NIL silently produces garbage (the
+sentinel is a real `int64_t` value, so `SP_INT_NIL + 1` is just
+`INT64_MIN + 1` — surprising but not a crash). Documented in
+existing int? work (commit f6c3b6d era).
+
+## Phase 2 Scope — REVERTED (2026-05-25, #708)
+
+Phase 2 attempted to change `sp_StrStrHash_get` / `sp_IntStrHash_get` /
+`sp_SymStrHash_get` to return `NULL` on missing keys. Committed as
+0ec6b1d, then **reverted via 532ba3e** after #708 surfaced a
+real-world breakage:
+
+- Tep apps segfault at boot.
+- `lib/tep.rb`'s seeding chain (175-730) reads from hash slots
+  in patterns that the Phase 2 commit's "safe call paths" audit
+  missed -- the audit covered string-method dispatch
+  (`sp_str_length` / `sp_str_eq` / `sp_str_concat` are NULL-safe)
+  but didn't enumerate every downstream `const char *` use site
+  in user code or framework runtime.
+- Restoring `sp_str_empty` semantics is the conservative call
+  until a wider audit + codemod recipe is ready.
+
+### Re-planned Phase 2 (deferred)
+
+The Ruby semantic violation is real (`if h[:missing]` evaluates as
+truthy under the `""` fallback because `sp_str_empty` is a non-NULL
+pointer). Bringing it inline with Ruby without breaking tep / real-
+blog requires one of:
+
+1. **Opt-in via build flag** (`-DSP_STRHASH_MISS_NIL`). Apps that
+   audit their hash use can flip the flag; others stay on the
+   `""` fallback. Lowest-risk for downstream users.
+2. **Lazy null-coalescing pass** in codegen: detect `h[k]` followed
+   by a method-call that requires non-NULL (`.length`, `.bytes`,
+   `.split`, ...) and insert a NULL → `sp_str_empty` coalesce.
+   The `if h[:k]` truthy site dispatches to a separate truthy
+   helper that treats `sp_str_empty` as falsy when the value came
+   from a hash miss (requires tagging the miss in the runtime).
+3. **Surgical attack** on `compile_cond_expr` only: when the
+   condition is `h[k]` on a typed-string hash, emit
+   `sp_StrStrHash_has_key(h, k)` instead of the raw value-truthy
+   check. Doesn't change the runtime miss return at all; only
+   fixes the truthy check. Tep / real-blog can keep their
+   `s = h[k]; s.length` etc. patterns working.
+
+Option 3 is the smallest and most targeted; consider for a future
+Phase 2 attempt.
+
+Until that lands, `*StrHash[missing] == sp_str_empty` (current
+spinel behavior) -- documented Ruby-semantic violation, stable
+runtime.
+
+## Phase 4 Scope — DEFERRED (2026-05-25)
+
+Implementing `*IntHash` → SP_INT_NIL is significantly more invasive
+than initially scoped. First attempt (16:00-16:40 JST) hit three
+cascading issues, all reverted before commit:
+
+### Cascade 1: Self-host bootstrap breaks via inferred-LV typing
+
+Changing `analyze`'s `[]` return for `str_int_hash` from `"int"` to
+`"int?"` propagates "int?" through spinel_analyze.rb's OWN type
+inference. Specifically `unify_return_type` and `unify_call_types`
+treat `"int?"` as a distinct type from `"int"`, widening many
+internal calls (like `not_in(name, arr)`) to poly. Mitigations
+attempted:
+
+- `unify_hash_value_types`: treat `int?` as `int` (added)
+- `unify_return_type`: treat `int?` as `int` for fallback (added)
+
+These alone aren't enough — `unify_call_types`'s
+`base_type(old_pt) == base_type(at)` check at line 11568 still
+diverges for `("string", "int?")` pairs, which then fall through
+to the trailing "incompatible → poly" branch. The bootstrap fails
+with `lv_kt = sp_box_nil()` typing (poly) on locals that should
+be `const char *` (the result of `infer_type(...)`).
+
+### Cascade 2: `&&=` / `||=` codegen treats `SP_INT_NIL` as truthy
+
+The compound-assignment codegen lowers `counts[k] &&= v` to:
+
+```c
+if (sp_StrIntHash_get(counts, k)) {
+  sp_StrIntHash_set(counts, k, v);
+}
+```
+
+The `if (...)` is C-truthy on the raw mrb_int. After Phase 4,
+missing-key returns `SP_INT_NIL = INT64_MIN`, which is **non-zero**
+and therefore C-truthy. Ruby says nil is falsy. The fix requires
+the codegen to emit `if (!sp_int_is_nil(...))` for typed-int-hash
+sources — a parallel arm in `compile_index_and_assign` /
+`compile_index_or_assign`.
+
+### Cascade 3: Existing test assumptions
+
+`test/sym_int_hash_merge.rb` line 10 expects `puts h3[:q]` after
+`h3.delete(:q)` to output `0`. Updating to empty line (Ruby's
+`puts nil`) requires the int? puts arm AND propagation through
+the analyze type so the call site dispatches to it. Without all
+cascades fixed, the test produces the raw `-9223372036854775808`
+output.
+
+### Re-planned Phase 4 (alternative: poly wrapper)
+
+The cleaner approach, mirroring `Array#index` (commit e46ec54):
+
+1. Add `sp_StrIntHash_get_poly(h, k)` runtime helper that returns
+   `sp_RbVal` (sp_box_nil() for missing, sp_box_int(v) for present).
+2. Same for `sp_SymIntHash_get_poly`.
+3. Codegen `h[k]` direct dispatch for `str_int_hash` / `sym_int_hash`
+   routes to `_get_poly` (returns sp_RbVal).
+4. Analyze `[]` returns `"poly"` for these variants.
+5. Compound writes (`&&=`/`||=`) read via `_get_poly`, write via
+   `_set` after unboxing.
+
+The poly route reuses existing infrastructure (sp_poly_truthy,
+sp_poly_inspect, etc.) and avoids the int? cascade. Cost: boxing
+on every `[]` lookup. For frameworks heavy in typed-int hash use,
+profile before committing.
+
+### Status
+
+Phase 4 deferred until either:
+- A focused session implements the poly-wrapper route end-to-end, or
+- The int? cascade is fixed at all sites (3+ places in
+  spinel_analyze.rb plus the compound-assignment codegen)
+
+Until then, `*IntHash[missing]` returns the value-type zero (`0`)
+— a known Ruby semantic violation, but stable.
+
+## Phase 5 Scope
+
+- Add regression tests:
+  - `test/str_str_hash_missing_returns_nil.rb` — `if h["missing"]; ...; end` falsy path
+  - `test/str_int_hash_missing_returns_nil.rb` — `if h["missing"]; ...; end` falsy
+  - `test/sym_int_hash_missing_arithmetic.rb` — document SP_INT_NIL arith caveat
+- `make test` (all pass)
+- `make bootstrap` (gen2 == gen3)
+- `make optcarrot` (checksum 59662)
+
+## Risks
+
+1. **Bootstrap self-host**: spinel_analyze.rb + spinel_codegen.rb
+   use typed hashes extensively. Per-phase bootstrap convergence
+   required.
+2. **optcarrot regression**: prior body-driven-widening cascade
+   (memory: body_usage_widening_optcarrot) warns that even
+   post-fixpoint widening can cascade-break optcarrot. Phase 4's
+   `int?` widening is the highest-risk step.
+3. **Test-suite assumptions**: any existing test that asserts
+   `h[missing] == ""` or `h[missing] == 0` semantics needs update.
+   Survey via `grep -rE 'Hash.*\[".*"\].*== "?"' test/`.
+
+## Order of Operations
+
+```
+Phase 1 — survey + this doc                    [current]
+Phase 2 — *StrHash → NULL                      next
+Phase 3 — *StrHash codegen tightening          
+Phase 4 — *IntHash → SP_INT_NIL                bigger surgery
+Phase 5 — regression tests + final verify      
+```
+
+Each phase ends with a green CI before the next begins. If Phase 4
+regresses optcarrot, fall back to Phase 4a (per-variant rollout
+with feature flag).

data/vendor/spinel/docs/INCOMPATIBILITIES.md

@@ -0,0 +1,102 @@
+# Intentional incompatibilities with CRuby
+
+Spinel aims to be a subset of Ruby: programs it accepts should behave the same
+as on CRuby. In a few cases CRuby's behavior depends on a feature Spinel does
+not implement, and silently returning a wrong value would be worse than a
+visible error. Those deliberate divergences are listed here.
+
+## `Integer#**` with a negative exponent
+
+CRuby evaluates a negative integer exponent to a `Rational`:
+
+```ruby
+2 ** -1   # => (1/2)
+2 ** -2   # => (1/4)
+```
+
+Spinel has no `Rational` type. Rather than silently truncating the result to
+`0` (the previous behavior), a negative integer exponent raises:
+
+```ruby
+2 ** -1   # RangeError: negative exponent
+```
+
+This applies to `Integer#**` / `Integer#pow` across the int, bigint, and
+poly-dispatched paths. It is catchable as usual:
+
+```ruby
+begin
+  2 ** -1
+rescue RangeError => e
+  # e.message == "negative exponent"
+end
+```
+
+`Float#**` is unaffected and stays CRuby-compatible, because a float result is
+representable:
+
+```ruby
+2.0 ** -1   # => 0.5
+```
+
+## `String#grapheme_clusters`
+
+CRuby splits a string into Unicode extended grapheme clusters:
+
+```ruby
+"á".grapheme_clusters   # => ["á"]   (one cluster: a + combining accent)
+```
+
+Correct grapheme segmentation requires shipping and maintaining the Unicode
+grapheme-break property tables, which Spinel deliberately does not carry.
+`String#grapheme_clusters` and `String#each_grapheme_cluster` are therefore not
+supported. For codepoint- or byte-level iteration, use the supported
+`String#chars`, `#each_char`, `#codepoints`, or `#bytes`.
+
+## Aliasing the regexp match globals
+
+CRuby's `English` library aliases the punctuation match globals to readable
+names:
+
+```ruby
+require "English"   # alias $MATCH $&, alias $PREMATCH $`, ...
+"hello world" =~ /\w+/
+puts $MATCH         # => "hello"
+```
+
+In Spinel the match globals (`$&`, `` $` ``, `$'`, `$+`, `$~`) are not ordinary
+global-variable storage: a direct read lowers to a special regexp runtime
+accessor. Supporting `alias $name $&` would require a separate special-global
+alias mechanism plus broader `MatchData` compatibility, which is outside the
+intended AOT subset. Aliasing one of these globals is rejected at compile time
+rather than falling through to an undefined generated symbol:
+
+```
+$ spinel uses_english.rb
+Error: global aliasing of regexp special globals is not supported (alias $MATCH $&)
+```
+
+Direct reads of the match globals work as usual; only aliasing them is
+unsupported. `require "English"` therefore does not compile.
+
+## Flip-flop operator
+
+CRuby supports the flip-flop operator (a `Range` used as a condition, toggled
+between its two endpoints):
+
+```ruby
+(1..10).each { |i| puts i if (i == 3)..(i == 5) }   # prints 3, 4, 5
+```
+
+This is a rarely used feature with surprising hidden per-site state, and Spinel
+does not support it; a program using it fails to compile rather than running
+with wrong behavior. Use an explicit boolean state variable instead:
+
+```ruby
+active = false
+(1..10).each do |i|
+  active = true if i == 3
+  puts i if active
+  active = false if i == 5
+end
+```

data/vendor/spinel/docs/RBS-EXTRACT.md

@@ -0,0 +1,128 @@
+# spinel_rbs_extract — supported RBS subset
+
+`spinel_rbs_extract` reads `*.rbs` files and emits a line-oriented seed
+file that `spinel_analyze` consumes when invoked with `spinel --rbs DIR`.
+The seeded types are **advisory**: inference still runs on top, and the
+analyzer widens on observed contradiction, so the seed file is never
+load-bearing — a wrong or unrepresentable seed is at worst a no-op.
+
+Anything outside the subset below is silently dropped: the seed line
+isn't emitted, and the analyzer falls back to its normal inference for
+that method or ivar.
+
+## Supported
+
+### Type vocabulary
+
+| RBS                                    | Spinel tag                            |
+| -------------------------------------- | ------------------------------------- |
+| `Integer`                              | `int`                                 |
+| `Float`                                | `float`                               |
+| `String`                               | `string`                              |
+| `Symbol`                               | `symbol`                              |
+| `TrueClass`, `FalseClass`              | `bool`                                |
+| `NilClass`, `nil`                      | `nil`                                 |
+| `bool`                                 | `bool`                                |
+| `void` (return only)                   | `nil`                                 |
+| `Foo`, `Foo::Bar` (nominal)            | `obj_Foo`, `obj_Foo_Bar`              |
+| `Array[Integer]`                       | `int_array`                           |
+| `Array[Float]`                         | `float_array`                         |
+| `Array[String]`                        | `str_array`                           |
+| `Array[Symbol]`                        | `sym_array`                           |
+| `Array[Foo]`                           | `obj_Foo_ptr_array`                   |
+| `Array[<other>]`                       | `poly_array`                          |
+| `Hash[String, Integer]`                | `str_int_hash`                        |
+| `Hash[String, String]`                 | `str_str_hash`                        |
+| `Hash[String, <other>]`                | `str_poly_hash`                       |
+| `Hash[Symbol, Integer]`                | `sym_int_hash`                        |
+| `Hash[Symbol, String]`                 | `sym_str_hash`                        |
+| `Hash[Symbol, <other>]`                | `sym_poly_hash`                       |
+| `T?`                                   | `<T>?`  (recursive)                   |
+| `T \| nil` / `nil \| T`                | `<T>?`                                |
+
+### Members emitted
+
+- `def name: (...) -> R` — instance method (`meth`)
+- `def self.name: (...) -> R` — class method (`cmeth`)
+- `def self?.name: (...) -> R` — emits both `meth` and `cmeth`
+- `attr_accessor`, `attr_reader`, `attr_writer` — emits `ivar`
+
+### Unqualified type resolution
+
+Inside `module Foo; class Bar`, an unqualified reference like
+`def record: () -> Base` is resolved to `obj_Foo_Base` (single-level
+parent fallback). A wrong guess is a no-op because the analyzer
+silently drops seeds for unknown types — no symbol table is required.
+Covers the common sibling-in-module pattern; full lexical lookup is
+not implemented.
+
+## Dropped (silently skipped)
+
+### Method signature shapes
+
+- Multiple overloads — only the first overload is considered; if the
+  first is itself out-of-subset the whole method is skipped.
+- Optional positional params (`?String`)
+- Rest positional params (`*args`)
+- Trailing positional params
+- Required keyword params (`name: T`)
+- Optional keyword params (`?name: T`)
+- Rest keyword params (`**rest`)
+- Block params (`{ ... }`, `?{ ... }`)
+- Generic method params (`[X]`)
+- Proc / untyped function types
+
+A signature that touches any of the above is dropped wholesale rather
+than emitted partially.
+
+### Param-level — any one of these in any required positional kills the whole signature
+
+- A type that doesn't reduce to a supported tag.
+- A generic container that isn't `Array[T]` or `Hash[K, V]`.
+- A union that isn't `T | nil`.
+
+### Type-level
+
+- `self`, `instance`, `class`, `top`, `bot`, `untyped` / `any`
+- Interfaces (`_Foo`)
+- Intersections (`T & U`)
+- Literal types (`:foo`, `42`, `"x"`)
+- Type aliases
+- Type variables (generics with parameters)
+- Records (`{ name: T, ... }`)
+- Tuples (`[T, U]`)
+- Proc types (`^(T) -> U`)
+- `Hash[K, V]` where K is not `String` or `Symbol`
+
+### Members
+
+- `include`, `extend`, `prepend` — mixin ancestry not modeled
+- `public`, `private`
+- `alias`
+- `@ivar` / `@@cvar` declarations (use `attr_*` for ivars)
+
+## Seed file format
+
+Consumed by `load_rbs_seeds` / `apply_rbs_seeds` in
+`spinel_analyze.rb`:
+
+```
+class <QualifiedName>           # enter class scope; nested names use `_`
+meth <name> <ret> <ptypes>      # `-` means "leave alone"; ptypes is
+cmeth <name> <ret> <ptypes>     # comma-separated, or `-` for nullary
+ivar <name> <type>
+```
+
+Lines whose first token isn't a keyword are treated as comments.
+
+See `experiments/rbs/box.seed` for a worked example.
+
+## Follow-up
+
+Tracked as out-of-scope for the initial spike (see matz/spinel#7 +
+OriPekelman/tep#6):
+
+- Multi-overload resolution
+- Generics with type variables
+- Mixin ancestry from `include` / `extend`
+- Return-type pinning where the body would otherwise cascade-widen

data/vendor/spinel/docs/fast-bootstrap.md

@@ -0,0 +1,74 @@
+# Fast Bootstrap
+
+Spinel is self-hosting: the compiler backend (`spinel_analyze.rb` and
+`spinel_codegen.rb`) is itself compiled to native binaries. The reliable way to
+build those binaries from scratch is the CRuby round: run the two `.rb` sources
+under `miniruby` to emit C, then compile. That round is the trustworthy
+authority, but on a machine that already has working compiler binaries it is
+slow, because CRuby re-interprets the whole backend every time the sources
+change.
+
+Fast bootstrap rebuilds the compiler from the *previous* compiled binaries
+("stage0") instead of from CRuby. On this codebase a stage0 round is about 3.5x
+faster than the CRuby round (the type-inference pass dominates either way, but
+the compiled inferencer is far faster than the interpreted one).
+
+## Modes
+
+`make` reads one variable:
+
+- `FAST_BOOTSTRAP=auto` (default): `make all` rebuilds the compiler from stage0
+  via `tools/fast-bootstrap`. If stage0 is missing or cannot compile the current
+  source, the helper falls back to the CRuby round automatically.
+- `FAST_BOOTSTRAP=0`: always use the CRuby authority round. `make bootstrap`
+  forces this regardless of the default.
+
+## Targets
+
+- `make all` / `make spinel_analyze spinel_codegen`: fast path by default,
+  gated on the compiler-source content stamps. Unchanged source rebuilds
+  nothing.
+- `make fast-bootstrap`: run the stage0 path explicitly.
+- `make bootstrap`: the authority. Forces `FAST_BOOTSTRAP=0`, runs the
+  CRuby-seeded self-host fixpoint (round2 built by round1, round3 built by
+  round2), and requires round2 == round3 byte-for-byte for both sources before
+  promoting. Use this for releases, for CI, and whenever a byte-canonical
+  compiler is wanted.
+
+## What the helper does
+
+`tools/fast-bootstrap` is a small POSIX shell script (no CRuby in the policy
+layer, to keep the fast path self-hosting). On each run:
+
+1. **Eligibility.** Require executable `spinel_analyze`, `spinel_codegen`,
+   `spinel_parse` and the runtime library `lib/libspinel_rt.a`. If any is
+   missing, fall back to the CRuby Make rules.
+2. **Generate.** Parse both compiler sources with the current parser and run
+   stage0 to emit IR and C, all isolated under `build/fast-bootstrap/`.
+3. **Compile** the stage1 binaries there, leaving the top-level binaries
+   untouched.
+4. **Smoke check.** The fresh stage1 must analyze and code-generate the large
+   `codegen` AST and emit non-empty C. This catches a stage1 that links but
+   crashes or emits junk.
+5. **Promote.** Only on full success: publish the intermediates into the
+   canonical `build/` (so Make's dependency graph stays consistent) and
+   atomically `mv` the stage1 binaries over the top-level ones.
+
+Any failure at any step leaves the previous working binaries in place and
+delegates to the CRuby authority path, so a failed fast bootstrap never destroys
+the last good compiler.
+
+## Correctness model
+
+The fast path does **not** run a self-host fixpoint; that is `make bootstrap`.
+stage0 is the immediately-previous self-hosted compiler, and for ordinary edits
+it compiles the current source correctly. The residual risk, stage0 silently
+miscompiling the new source without erroring, is covered by `make test`,
+`make bootstrap`, and CI, which always exercise the authority path.
+
+Because the fixpoint is skipped, a fast-bootstrapped binary is functionally
+correct for the current source but not byte-canonical: its own machine code
+carries the compilation style of whatever stage0 produced it. This does not
+compound into incorrectness, since every stage0 is itself a correct compiler.
+To obtain a reproducible, byte-canonical compiler, run `make bootstrap`, which
+re-converges through the round2/round3 fixpoint.