spinel_kit 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a199ba3cb14b31a8bb59a0f05df22e0bb982a1c4862b315236feb05278e653c7
-  data.tar.gz: bad3e3859f7647ae5f80387a5b97a5abdfd34b3154d85761a3d02084e0b7c346
+  metadata.gz: fca4df06c4d57130a5053954a6429beac7d6ce0d6f6d1ee26194753aea11732c
+  data.tar.gz: 496c1116e14068768cb482723d1be6c6daebfc26f45d9972da3ab36d572eae69
 SHA512:
-  metadata.gz: affc333ba8f7aad5487cef5d38ec5e5c18fb0c73b3fade57489fa25bd9a3f14f5fbf66b56d6083cb5081555a0c36706b45d9d7166f206133b7eba8301eee5876
-  data.tar.gz: 29e1deb16e19017e12c94c40ad56af0bdde7361b166c7f51b727139fd98758496361006ea77934254041a70626d9d8db0d116a1080f454a2d12d24a04a7ed67b
+  metadata.gz: 1d15a4186fd29c584767e64c7f015b6424ce72bae04d39b283529f48478923075662bc2ecdc5e0ac03a73c51bcc344a9140cc775123a33c02e2dc76f9860cf73
+  data.tar.gz: 4d0ee98f92b44fa1e1345efdac6378626c31ba11c42cf0a6be12ab065f9e9854799eec16edb363da670b01eacd8421623631d2259c296f66f8b9892cd6f2eaa5

data/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to SpinelKit are documented here.
 
+## [0.3.0] - 2026-07-09
+
+### Changed
+- **Converted to a spin package** (spin is Spinel's package system;
+  [#3](https://github.com/OriPekelman/spinelkit/issues/3)). The package root
+  is now the require root: `lib/spinel_kit{,.rb}` moved to the repo top level,
+  `spin.toml` carries the identity (`name = "spinel_kit"`), and the gem
+  mirrors the layout with `require_paths = ["."]` — one tree serves both
+  consumers. Tests split by oracle: `test/*.rb` are compiled `spin test`
+  snapshot programs with committed `.expected` files (verified byte-identical
+  under CRuby and under spinel master `f9a81b1d`, 4/4); the CRuby minitest
+  parity suite moved to `test/parity/`.
+
+### Removed
+- **`SpinelKit::Json` and `SpinelKit::Json::Builder`** (`lib/spinel_kit/json.rb`,
+  `json_decoder.rb`, `json_builder.rb`, their `sig/` RBS and the parity test).
+  Spinel now bundles `json` as a require-gated stdlib package — a typed native
+  binding (`native_func :parse/:generate/:dump`) into the runtime's
+  `sp_json.c` — so the compiler provides the stdlib surface SpinelKit was
+  shimming ([#3](https://github.com/OriPekelman/spinelkit/issues/3)).
+  Verified on spinel master `f9a81b1d` with a tep-shaped consumer under
+  `SPINEL_REQUIRE_GATE=1`: byte-identical CRuby parity and **no
+  cross-degrade**; values from `JSON.parse` must be coerced at the boundary
+  (`.to_s`/`.to_i`/`.to_f`/`.map { |x| x.to_i }`) to stay fully typed —
+  without coercion, direct sinks widen to `untyped` (slow path, still
+  correct output).
+
+  **Migration:** `require "json"`; `JSON.parse(s)["k"].to_i` replaces
+  `SpinelKit::Json.get_int(s, "k")` (same shape for `get_str`/`get_float`/
+  `get_int_array`); `h.key?("k")` replaces `has_key?(s, "k")`;
+  `JSON.generate(hash)` replaces `encode_pair_*`/`from_*` and the Builder
+  (Ruby hashes are insertion-ordered; `native_obj_reflect` covers Structs).
+
+## [0.2.0] - 2026-06-08
+
+### Added
+- **`SpinelKit::Hex`** (`lib/spinel_kit/hex.rb`) — hex digit/byte codec:
+  `nibble` (hex char → 0..15), `nibble_char` (0..15 → uppercase hex char),
+  `byte2` (byte → two lowercase hex chars), `to_int` (leading hex digits →
+  int). Consolidates a `hex_nibble` that was **byte-identical** across
+  `Tep::Url`, `Tep::Llm`, and `SpinelKit::Json`'s decoder.
+- **`SpinelKit::Url`** (`lib/spinel_kit/url.rb`) — the `CGI`/`URI`-component
+  surface Spinel can't get from stdlib: `escape`/`unescape` (RFC 3986
+  percent-codec), `parse_query` (form-urlencoded → Hash), `split_url`
+  (scheme/host/port/path/query). Ported from `Tep::Url`; uses `SpinelKit::Hex`
+  and is self-contained (inline typed-hash seeding + substring search).
+
+`SpinelKit::Json` keeps its own private `hex2`/`hex_nibble` so a JSON-only
+consumer never compiles `Hex` (Spinel has no tree-shaking) — the small
+duplication is the surface-isolation cost.
+
 ## [0.1.1] - 2026-06-08
 
 ### Fixed

data/README.md

@@ -1,22 +1,43 @@
 # SpinelKit
 
+[![CI](https://github.com/OriPekelman/spinelkit/actions/workflows/ci.yml/badge.svg)](https://github.com/OriPekelman/spinelkit/actions/workflows/ci.yml)
 [![Gem Version](https://img.shields.io/gem/v/spinel_kit)](https://rubygems.org/gems/spinel_kit)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 ![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D)
 ![Pure Ruby](https://img.shields.io/badge/native%20ext-none-brightgreen)
 
-**The Spinel stdlib-surface gem.** A pure-Ruby, Spinel-safe toolkit holding
-the generic "stdlib substitute" shims that every Spinel-compiled project would
-otherwise hand-roll.
+**The non-stdlib toolkit for Spinel-compiled apps.** A pure-Ruby, Spinel-safe
+library holding the shims [Spinel](https://github.com/matz/spinel) (the
+Ruby→native AOT compiler) does not provide and that every Spinel project
+would otherwise hand-roll: **git provenance, URL percent-codec + query
+parsing, a minimal levelled logger, and a hex codec**.
+[toy](https://github.com/OriPekelman/toy) and
+[tep](https://github.com/OriPekelman/tep) grew these independently — parts
+came out *byte-identical* — and SpinelKit is that code, consolidated once.
 
-[Spinel](https://github.com/matz/spinel) is a Ruby→native AOT compiler. It
-cannot lower large chunks of the CRuby standard library — the `json` gem's
-C-extension fast path and its metaprogrammed pure-Ruby fallback, stdlib
-`Logger`, C-extension git bindings, and more. So every Spinel project re-derives
-the same shims. [toy](https://github.com/OriPekelman/toy) and
-[tep](https://github.com/OriPekelman/tep) grew theirs independently, and the
-JSON escape/quote/hex code came out *byte-identical*. SpinelKit is that code,
-consolidated once.
+## Where JSON went
+
+SpinelKit began as "the stdlib-surface gem," and its founding surface was a
+JSON codec. Spinel now **bundles `json` as a require-gated stdlib package** —
+a typed native binding straight into the runtime's `sp_json.c` — so the
+compiler provides the stdlib surface itself and `SpinelKit::Json` was retired
+in 0.3.0 ([#3](https://github.com/OriPekelman/spinelkit/issues/3)). Migration:
+
+```ruby
+require "json"                        # bare stdlib require, no manifest entry
+
+h = JSON.parse(body)
+model      = h["model"].to_s          # coerce at the parse boundary and
+max_tokens = h["max_tokens"].to_i     # everything downstream stays fully
+temp       = h["temperature"].to_f    # specialized under whole-program
+ids        = h["prompt"].map { |x| x.to_i }  # inference
+
+JSON.generate({ "ok" => true, "n" => max_tokens })   # replaces the Builder
+```
+
+Coerce parsed values once at the boundary (`.to_s`/`.to_i`/`.to_f`/mapped
+`.to_i`) — verified against spinel master: byte-identical CRuby parity, no
+cross-degrade, and full re-typification with the coercions in place.
 
 ## Installation
 
@@ -37,20 +58,20 @@ cleanly into a Spinel build via [bundler-spinel](https://github.com/OriPekelman/
 
 The first thing we did was audit the
 [spinelgems](https://github.com/OriPekelman/spinelgems) compatibility catalog
-(verdict ladder: `verified > loaded > clean > risky > rejected`) for an existing
-gem to reuse — that would have been the biggest win. **There wasn't one.** These
-shims *are* the ecosystem's gaps:
+(verdict ladder: `verified > loaded > clean > risky > rejected`) for existing
+gems to reuse — that would have been the biggest win. **There weren't any.**
+These shims *are* the ecosystem's gaps:
 
 | Surface | Catalog finding | Decision |
 |---------|-----------------|----------|
-| JSON    | `json` **rejected** (C-ext + metaprogrammed fallback); `oj` **risky** (C-ext) | implement |
 | Log     | `logger` **rejected** (unresolved calls) | implement |
 | Git     | `rugged` **rejected** (C); `gitkite`/`git_manager` only **clean**, unmet `needs:` | implement (read `.git/HEAD`) |
+| Url/Hex | `CGI`/`URI` stdlib not lowered; no verified gem | implement |
 | Path    | `hike` **verified** at an older rev, only **loaded** now; overkill for basename/join | deferred |
 | Bytes   | `unicode_utils`/`utf8-cleaner` **clean** only; toy's need is tokenizer-specific | deferred |
 
-See [`docs/gem-audit-first.md`](docs/gem-audit-first.md) for the full audit and
-the verification-request issues we filed on spinelgems.
+See [`docs/gem-audit-first.md`](docs/gem-audit-first.md) for the full audit
+(which also covers the since-retired JSON surface).
 
 ## What's in it
 
@@ -60,31 +81,8 @@ require "spinel_kit"   # everything (CRuby / convenience)
 
 For a **Spinel-compiled** consumer, require only the surface you use — Spinel
 has no tree-shaking, so every loaded method is compiled (and an uncalled one
-can degrade). The Json surface is split into three files for exactly this
-reason: `spinel_kit/json` (encoders), `spinel_kit/json_decoder` (decoders), and
-`spinel_kit/json_builder` (the builder). e.g. tep requires `json` + `json_decoder`;
-toy requires `json_builder`.
-
-- **`SpinelKit::Json`** — a JSON-over-HTTP codec: encoders
-  (`escape`/`quote`/`encode_pair_*`/`from_*`, in `spinel_kit/json`) and flat-key
-  decoders (`get_str`/`get_int`/`get_float`/`get_int_array`/`has_key?`, in
-  `spinel_kit/json_decoder`).
-
-  ```ruby
-  SpinelKit::Json.get_int('{"age":33}', "age")             # => 33
-  SpinelKit::Json.from_int_hash({"a" => 1, "b" => 2})      # => {"a":1,"b":2}
-  ```
-
-- **`SpinelKit::Json::Builder`** — an incremental ordered-object builder
-  (`add_str`/`add_num`/`add_bool`/`add_raw`/`add_obj`/`dump`), in its own file
-  so a builder-only consumer never compiles the codec, and vice versa.
-
-  ```ruby
-  j = SpinelKit::Json::Builder.new
-  j.add_str("kind", "run_start")
-  j.add_num("t", 1715000000)
-  j.dump                                     # => {"kind":"run_start","t":1715000000}
-  ```
+can degrade): `spinel_kit/hex`, `spinel_kit/url` (pulls in hex),
+`spinel_kit/git`, `spinel_kit/log`.
 
 - **`SpinelKit::Git`** — git provenance from `.git/HEAD`.
 
@@ -94,6 +92,15 @@ toy requires `json_builder`.
   g.branch       # => "main"
   ```
 
+- **`SpinelKit::Url`** — the `CGI`/`URI`-component surface:
+  `escape`/`unescape` (RFC 3986 percent-codec), `parse_query`
+  (form-urlencoded → Hash), `split_url` (scheme/host/port/path/query).
+
+  ```ruby
+  SpinelKit::Url.escape("a b&c")            # => "a%20b%26c"
+  SpinelKit::Url.parse_query("x=1&y=z")     # => {"x"=>"1", "y"=>"z"}
+  ```
+
 - **`SpinelKit::Log`** — a minimal levelled logger (CRuby `Logger` doesn't
   compile under Spinel).
 
@@ -103,6 +110,9 @@ toy requires `json_builder`.
   log.info("server up")
   ```
 
+- **`SpinelKit::Hex`** — hex digit/byte encode + decode (`nibble`,
+  `nibble_char`, `byte2`, `to_int`); the shared surface `Url` builds on.
+
 ## Design constraints (read before editing)
 
 SpinelKit is **pure Ruby, no native extension** (`spinel-ext.json` is `[]`) and
@@ -110,24 +120,44 @@ has **no runtime dependencies**, so it vendors cleanly via `bundler-spinel`. The
 surface uses plain, standard names; the `j_`/`tj_`/`gi_` prefixes the donor
 copies carried were a workaround for a Spinel whole-program-inference bug that
 has since been fixed upstream (verified with toy's `gate-poly-degrade` on the
-current compiler). One numeric caveat remains for `add_num` — see
-[`docs/spinel-discipline.md`](docs/spinel-discipline.md).
+current compiler). See [`docs/spinel-discipline.md`](docs/spinel-discipline.md).
+
+## Package formats: spin package + gem, one tree
+
+This repo **is a [spin](https://github.com/matz/spin-index) package** (spin is
+Spinel's package system): the package root is the require root
+(`spinel_kit.rb` + `spinel_kit/` at top level), `spin.toml` carries the
+identity, and the top-level `test/*.rb` programs are compiled snapshot tests
+(`spin test` — each diffs against its committed `.expected`, byte-identical
+under CRuby too). Spinel projects take it with:
+
+```sh
+spin add spinel_kit            # index form, once seeded — or:
+spin add spinel_kit --git https://github.com/OriPekelman/spinelkit
+```
+
+The same tree still ships as the `spinel_kit` **gem** for CRuby-side
+consumers (`require_paths` is the package root), and vendors via
+`bundler-spinel` as before.
 
 ## Status
 
-Pre-alpha (`0.1.0`). The shims are implemented, CRuby-verified, and the surface
-is the single canonical one (the donor prefixes and duplicated escapers are
-gone — the Spinel inference bug that motivated them is fixed). Consumer adoption
-is the next phase: because we author every repo in this set, tep and toy
-**migrate to `SpinelKit::*` directly and delete their donor modules** — we
-standardize and clean rather than leave compatibility aliases behind. See
-[`docs/adoption.md`](docs/adoption.md). Tracking issue:
-[OriPekelman/toy#44](https://github.com/OriPekelman/toy/issues/44).
+Pre-alpha (`0.3.0` — the JSON retirement + spin package conversion). tep and
+toy migrated to `SpinelKit::*` directly and deleted their donor modules (see
+[`docs/adoption.md`](docs/adoption.md)); their JSON call sites migrate to the
+bundled stdlib `json` next
+([tep#217](https://github.com/OriPekelman/tep/issues/217),
+[tep#213](https://github.com/OriPekelman/tep/issues/213)), and their
+dependency declarations move to `spin.toml`
+([tep#234](https://github.com/OriPekelman/tep/issues/234),
+[toy#107](https://github.com/OriPekelman/toy/issues/107)). Repositioning
+tracked in [#3](https://github.com/OriPekelman/spinelkit/issues/3).
 
 ## Development
 
 ```sh
-rake test            # CRuby-side parity tests (never compiled)
+rake test            # CRuby-side parity tests, test/parity/ (never compiled)
+spin test            # compiled snapshot tests, test/*.rb vs .expected
 rake rbs:validate    # syntax-check the advisory RBS in sig/
 gem build spinel_kit.gemspec
 ```

data/docs/adoption.md

@@ -1,5 +1,13 @@
 # Adoption — standardize and clean (not shim-and-alias)
 
+> **Historical note (2026-07-08).** This doc describes the 0.1–0.2 era
+> migration of tep and toy onto `SpinelKit::*`, including the Json surface.
+> `SpinelKit::Json`/`Builder` were **retired in 0.3.0** — Spinel now bundles
+> `json` as a stdlib package, and the Json call sites below migrate again, to
+> bare `require "json"` (see
+> [#3](https://github.com/OriPekelman/spinelkit/issues/3) and the CHANGELOG
+> migration note). The Git/Url/Log/Hex parts remain accurate.
+
 Bootstrap landed the gem and its three shims. Adoption by tep and toy is the
 next phase. **Because we author every repo in this set — toy, tep, spinelgems,
 and Spinel itself — the goal is to standardize and clean, not to bolt

data/docs/spinel-discipline.md

@@ -2,7 +2,7 @@
 
 SpinelKit ships code that gets compiled into *other* programs by Spinel's
 whole-program AOT compiler. That changes the rules for how it must be written.
-This doc is the contract for anyone editing `lib/spinel_kit/*.rb`.
+This doc is the contract for anyone editing `spinel_kit/*.rb`.
 
 ## 1. The name-keyed inference bug — FIXED, prefixes dropped
 
@@ -35,28 +35,24 @@ names (`escape`/`quote`/`add_str`/`sha`/`branch`/plain `value`).
 - **Split the surface so consumers don't compile dead code.** Spinel has no
   tree-shaking: every loaded method is compiled, and a *set* of uncalled
   methods can degrade each other's (and nearby live methods') param types. We
-  saw this concretely — with the encoders and decoders in one class, an
-  encode-only program left the 9 decoder walkers dead; their `s` params
-  collapsed to `int` and dragged `escape`'s `s` to `int` too, silently
-  emitting `""` keys from `from_*_hash`. The fix was structural: encoders
-  (`json.rb`), decoders (`json_decoder.rb`), and builder (`json_builder.rb`)
-  live in separate files, so a consumer loads only a coherent surface it
-  actually exercises. Verified clean (0 emit-0, correct output) for the real
-  consumer shapes — builder-only (toy) and encode+decode (tep) — on rev
-  `57af7f9`. A consumer that loads a surface but leaves part of it uncalled can
-  still trip the gate; that's expected, and the gate is what flags it.
-- **`escape`/`quote`/`hex2` are single canonical methods** — the builder
-  carries its own byte-identical copies (so a builder-only compile pulls in no
-  codec); there is no `tj_*` prefix any more.
-- **Keep `get_float` inlined** (it does NOT delegate to a `parse_float_value`
-  helper). This is unrelated to the name bug — it's a value-walk *indirection*
-  issue where Spinel mis-widened the string arg `s` to int through the helper
-  call. Until that's separately confirmed fixed, leave it inlined.
+  saw this concretely in the retired Json surface — with the encoders and
+  decoders in one class, an encode-only program left the 9 decoder walkers
+  dead; their `s` params collapsed to `int` and dragged `escape`'s `s` to
+  `int` too, silently emitting `""` keys. The fix was structural: one
+  coherent surface per file (today: `hex.rb`, `url.rb`, `git.rb`, `log.rb`),
+  so a consumer loads only what it actually exercises. A consumer that loads
+  a surface but leaves part of it uncalled can still trip the gate; that's
+  expected, and the gate is what flags it.
 - **Never override `to_s`** — it merges across the whole program.
 - The stale cautionary comments in toy's `toy_json.rb`/`toy_git.rb` and the
   landmine memory note should be annotated "fixed upstream by `ac7720e`/
   `23ba632`, verified on `57af7f9`" when those repos are next touched.
 
+(Historical, retired with the Json surface in 0.3.0: the three-file Json
+split, the builder's byte-identical private escapers, and the keep-`get_float`
+-inlined rule. The last known instance of the value-walk indirection issue was
+verified fixed on master `b60fbd7`.)
+
 ## 2. The poly-degrade gate (how consumers verify SpinelKit is safe)
 
 Each consumer has a poly-degrade scan that compiles a canonical entrypoint and
@@ -101,6 +97,7 @@ destined for Spinel. SpinelKit's own decoders follow this rule.
   runs, but file output is the portable path.
 - `Time.now` exposes integer seconds only (no rich `strftime`) — `Log` formats
   with `Time.now.to_i`.
-- `Integer#chr` is not uniform for arbitrary bytes — `Json.byte_to_chr` uses a
-  printable-ASCII table with a `"?"` fallback.
+- `Integer#chr` is not uniform for arbitrary bytes — the retired Json surface
+  used a printable-ASCII table with a `"?"` fallback; apply the same pattern
+  if a surface ever needs byte→char again.
 - No C extensions — `spinel-ext.json` is `[]`.

data/sig/spinel_kit/hex.rbs

@@ -0,0 +1,8 @@
+module SpinelKit
+  class Hex
+    def self.nibble: (String c) -> Integer        # hex digit -> 0..15, or -1
+    def self.nibble_char: (Integer n) -> String   # 0..15 -> "0".."9","A".."F"
+    def self.byte2: (Integer n) -> String         # 0..255 -> two lowercase hex chars
+    def self.to_int: (String s) -> Integer        # leading hex digits -> int
+  end
+end

data/sig/spinel_kit/url.rbs

@@ -0,0 +1,9 @@
+module SpinelKit
+  class Url
+    def self.unescape: (String s) -> String
+    def self.escape: (String s) -> String
+    def self.parse_query: (String s) -> Hash[String, String]
+    def self.split_url: (String u) -> Hash[String, String]
+    def self.find_idx: (String s, String needle, Integer start) -> Integer
+  end
+end

data/spin.toml

@@ -0,0 +1,6 @@
+# spin package manifest — SpinelKit as an ordinary spin package.
+# The package NAME is the require string (`require "spinel_kit/git"` etc.);
+# the repo keeps its historical name. See issue #3 for the repositioning.
+[package]
+name = "spinel_kit"
+version = "0.3.0"

data/spinel_kit/hex.rb

@@ -0,0 +1,59 @@
+# SpinelKit::Hex -- hex digit/byte encode + decode: the pieces every Spinel
+# project re-rolls. The decode nibble appeared BYTE-IDENTICAL in Tep::Url,
+# in the retired SpinelKit::Json string decoder, and (as a multi-digit
+# variant) in Tep::Llm's chunked-transfer size parser. Pure string/byte ops,
+# Spinel-safe. Hex is the shared surface, e.g. for SpinelKit::Url.
+module SpinelKit
+  class Hex
+    # Hex digit char -> int 0..15, or -1 if not a hex digit (upper or lower).
+    def self.nibble(c)
+      if c >= "0" && c <= "9"
+        return c.getbyte(0) - "0".getbyte(0)
+      end
+      if c >= "a" && c <= "f"
+        return c.getbyte(0) - "a".getbyte(0) + 10
+      end
+      if c >= "A" && c <= "F"
+        return c.getbyte(0) - "A".getbyte(0) + 10
+      end
+      -1
+    end
+
+    # Int nibble 0..15 -> single UPPERCASE hex char ("0".."9","A".."F").
+    # (RFC 3986 percent-encoding uses uppercase.)
+    def self.nibble_char(n)
+      if n < 10
+        return ("0".getbyte(0) + n).chr
+      end
+      ("A".getbyte(0) + n - 10).chr
+    end
+
+    # Int byte 0..255 -> two-char LOWERCASE hex (15 -> "0f"). (JSON \u00XX
+    # and similar use lowercase.)
+    def self.byte2(n)
+      hex = "0123456789abcdef"
+      out = ""
+      out = out + hex[(n / 16) % 16, 1]
+      out = out + hex[n % 16, 1]
+      out
+    end
+
+    # Parse the leading hex digits of `s` -> int ("1a3" -> 419). Stops at the
+    # first non-hex char; returns 0 if there is no leading hex digit. Useful
+    # for chunked-transfer sizes and the like.
+    def self.to_int(s)
+      n = 0
+      i = 0
+      len = s.length
+      while i < len
+        v = Hex.nibble(s[i])
+        if v < 0
+          return n
+        end
+        n = n * 16 + v
+        i += 1
+      end
+      n
+    end
+  end
+end

data/spinel_kit/url.rb

@@ -0,0 +1,164 @@
+require_relative "hex"
+
+# SpinelKit::Url -- percent-encode/decode (the CGI / URI-component surface
+# Spinel can't get from stdlib) plus a form-query parser and a small URL
+# splitter. Ported from Tep::Url; the hex digits now come from SpinelKit::Hex.
+#
+# Self-contained: the empty str=>str hashes are seeded inline (the
+# `{"" => ""}`-then-delete idiom that pins Spinel's value type), and substring
+# search is a private `find_idx` (the `< 0` callsites can't narrow against
+# String#index's int|nil under Spinel's current model). All pure string ops.
+module SpinelKit
+  class Url
+    # "%41+b" -> "A b" (form-decode: `+` is space, `%XX` is a byte).
+    def self.unescape(s)
+      out = ""
+      i = 0
+      n = s.length
+      while i < n
+        c = s[i]
+        if c == "+"
+          out = out + " "
+          i += 1
+        elsif c == "%" && i + 2 < n
+          hi = Hex.nibble(s[i + 1])
+          lo = Hex.nibble(s[i + 2])
+          if hi >= 0 && lo >= 0
+            out = out + ((hi * 16 + lo).chr)
+            i += 3
+          else
+            out = out + c
+            i += 1
+          end
+        else
+          out = out + c
+          i += 1
+        end
+      end
+      out
+    end
+
+    # Percent-encode everything outside the RFC 3986 unreserved set
+    # (ALPHA / DIGIT / `-._~`); the rest becomes `%XX` with UPPERCASE hex.
+    # (Space -> `%20`, not `+` -- this is the URI-component, not form, encoder.)
+    #
+    # Byte-oriented: under Spinel `String#[]` indexes BYTES, so a multi-byte
+    # UTF-8 char is encoded byte-by-byte (correct %XX of each byte). Under CRuby,
+    # pass a binary string for the same behaviour (else `[]` splits on chars).
+    def self.escape(s)
+      out = ""
+      i = 0
+      while i < s.length
+        c = s[i]
+        if (c >= "a" && c <= "z") || (c >= "A" && c <= "Z") ||
+           (c >= "0" && c <= "9") || c == "-" || c == "." ||
+           c == "_" || c == "~"
+          out = out + c
+        else
+          b = c.getbyte(0)
+          out = out + "%" + Hex.nibble_char(b / 16) + Hex.nibble_char(b % 16)
+        end
+        i += 1
+      end
+      out
+    end
+
+    # "a=1&b=2&c" -> {"a"=>"1","b"=>"2","c"=>""}. Keys + values are
+    # form-decoded (`unescape`).
+    def self.parse_query(s)
+      h = {"" => ""}
+      h.delete("")
+      if s.length == 0
+        return h
+      end
+      pairs = s.split("&")
+      pairs.each do |pair|
+        if pair.length > 0
+          eq = Url.find_idx(pair, "=", 0)
+          if eq < 0
+            h[Url.unescape(pair)] = ""
+          else
+            k = pair[0, eq]
+            v = pair[eq + 1, pair.length - eq - 1]
+            h[Url.unescape(k)] = Url.unescape(v)
+          end
+        end
+      end
+      h
+    end
+
+    # Split `http(s)://host[:port]/path?query` into a str=>str hash keyed
+    # scheme / host / port / path / query. Without a scheme the input is
+    # treated as a path (host stays empty). Default ports follow the scheme
+    # (80 / 443); `query` is the raw substring after `?` (not decoded).
+    #
+    # One body on purpose: Spinel widens a Hash-typed value when a helper
+    # mutates it and the caller keeps reading, so `out` stays StrStrHash only
+    # if nothing factors the mutation out (find_idx returns an int, no mutate).
+    def self.split_url(u)
+      out = {"" => ""}
+      out.delete("")
+      out["scheme"] = ""
+      out["host"]   = ""
+      out["port"]   = ""
+      out["path"]   = "/"
+      out["query"]  = ""
+
+      rest = u
+      if rest.length >= 7 && rest[0, 7] == "http://"
+        out["scheme"] = "http"
+        out["port"]   = "80"
+        rest = rest[7, rest.length - 7]
+      elsif rest.length >= 8 && rest[0, 8] == "https://"
+        out["scheme"] = "https"
+        out["port"]   = "443"
+        rest = rest[8, rest.length - 8]
+      end
+
+      if out["scheme"].length > 0
+        slash = Url.find_idx(rest, "/", 0)
+        hostport = rest
+        tail     = "/"
+        if slash >= 0
+          hostport = rest[0, slash]
+          tail     = rest[slash, rest.length - slash]
+        end
+        colon = Url.find_idx(hostport, ":", 0)
+        if colon >= 0
+          out["host"] = hostport[0, colon]
+          out["port"] = hostport[colon + 1, hostport.length - colon - 1]
+        else
+          out["host"] = hostport
+        end
+        rest = tail
+      end
+
+      qi = Url.find_idx(rest, "?", 0)
+      if qi >= 0
+        out["path"]  = rest[0, qi]
+        out["query"] = rest[qi + 1, rest.length - qi - 1]
+      else
+        out["path"] = rest
+      end
+      if out["path"].length == 0
+        out["path"] = "/"
+      end
+      out
+    end
+
+    # First index of `needle` in `s` at/after `start`, or -1. Internal
+    # (Spinel-safe substring search; see the module comment).
+    def self.find_idx(s, needle, start)
+      nlen = needle.length
+      slen = s.length
+      pos = start
+      while pos <= slen - nlen
+        if s[pos, nlen] == needle
+          return pos
+        end
+        pos += 1
+      end
+      -1
+    end
+  end
+end

data/spinel_kit/version.rb

@@ -0,0 +1,6 @@
+# SpinelKit version. Kept in its own file so the gemspec can read it
+# without loading the rest of the library (the modules pull in no deps,
+# but this matches the toy/tep convention exactly).
+module SpinelKit
+  VERSION = "0.3.0"
+end

data/spinel_kit.rb

@@ -0,0 +1,39 @@
+# SpinelKit -- the non-stdlib toolkit for Spinel-compiled apps.
+#
+# A pure-Ruby, Spinel-safe toolkit holding the shims Spinel (the Ruby->native
+# AOT compiler) does not provide and that every Spinel-compiled project would
+# otherwise hand-roll:
+#
+#   SpinelKit::Hex -- hex digit/byte encode + decode.
+#   SpinelKit::Url -- percent-encode/decode + form-query + URL split.
+#   SpinelKit::Git -- git provenance from .git/HEAD (was Toy::Git).
+#   SpinelKit::Log -- minimal levelled logger (was Tep::Logger).
+#
+# JSON is NOT here any more. Spinel bundles `json` as a require-gated stdlib
+# package (a typed native binding into sp_json.c), so consumers write a bare
+# `require "json"` and use JSON.parse / JSON.generate, coercing parsed values
+# at the boundary (`.to_s` / `.to_i` / `.to_f` / `.map { |x| x.to_i }`) to
+# keep inference fully typed. The old SpinelKit::Json codec + Builder were
+# retired in 0.3.0 -- see CHANGELOG.md and issue #3.
+#
+# MINIMAL-SURFACE REQUIRING. This umbrella requires everything for
+# convenience (and for CRuby use). But because Spinel compiles every loaded
+# method with no tree-shaking, a Spinel-compiled consumer should require ONLY
+# the file(s) it uses, to avoid compiling -- and degrading -- code it never
+# calls:
+#
+#   require "spinel_kit/hex"           # hex digit/byte codec
+#   require "spinel_kit/url"           # percent-codec + query (pulls in hex)
+#   require "spinel_kit/git"
+#   require "spinel_kit/log"
+#
+# No native extension (spinel-ext.json is []), no runtime dependencies. See
+# docs/adoption.md and docs/spinel-discipline.md.
+require_relative "spinel_kit/version"
+require_relative "spinel_kit/hex"
+require_relative "spinel_kit/url"
+require_relative "spinel_kit/git"
+require_relative "spinel_kit/log"
+
+module SpinelKit
+end