spinel_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cf881dd39764d4001bad8e3a8df70eab2063d4083e8a2641ceec8ea6c299bbbd
+  data.tar.gz: b91ccadce9e0058db8df0e1fc82e64d912d60958b31b6f0c23986ed99ccdf662
+SHA512:
+  metadata.gz: 15b02b65083c60e8d9501d7c27e86c740f6cd62b814bcf4fc83c4a614b3f82fb434695cc8213e46f772cce441c51a48148658b4679ee8f4191213bef74345e43
+  data.tar.gz: 634f583e51bfa029ffe15a1a0b102e7e10f2916acd3632d85770002d91634d9a2bd5666a40c9deb11cf42b18e94ae1f2ff46b3475c1e4385692063a60990d356

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to SpinelKit are documented here.
+
+## [0.1.0] - 2026-06-08
+
+First release. Establishes the gem and lands the three core shims, consolidated
+from toy and tep. See [OriPekelman/toy#44](https://github.com/OriPekelman/toy/issues/44)
+for the rationale.
+
+### Added
+- `SpinelKit::Json` encoders (`lib/spinel_kit/json.rb`) — from `Tep::Json`:
+  `escape`/`quote`/`encode_pair_*`/`from_*`.
+- `SpinelKit::Json` decoders (`lib/spinel_kit/json_decoder.rb`) — from
+  `Tep::Json`: flat-key `get_str`/`get_int`/`get_float`/`get_int_array`/
+  `has_key?` + the hand-rolled walker.
+- `SpinelKit::Json::Builder` (`lib/spinel_kit/json_builder.rb`) — the
+  incremental ordered-object builder from `Toy::Json`, now
+  `add_str`/`add_num`/`add_bool`/`add_raw`/`add_obj`/`dump`, with its own
+  byte-identical escapers.
+- Encoders / decoders / builder are split across three files on purpose:
+  Spinel has no tree-shaking, so a consumer that loaded an unused half compiled
+  (and degraded) it — concretely, dead decoder walkers widened `escape`'s
+  string arg to `int` and silently emitted `""` keys from `from_*_hash`. With
+  the split, each real consumer shape compiles 0-warning and correct (verified
+  through the Spinel binary on rev `57af7f9`): builder-only (toy), and
+  encode+decode (tep).
+- `SpinelKit::Git` — `.git/HEAD` provenance (`sha`/`branch`), ported from
+  `Toy::Git`. tep gains it.
+- `SpinelKit::Log` — minimal levelled logger, ported from `Tep::Logger`. toy
+  gains it.
+
+### Naming
+- Dropped the donor `j_`/`tj_`/`gi_` prefixes in favour of plain, standard
+  names. Those prefixes worked around a Spinel name-keyed inference bug that
+  has since been fixed upstream (`ac7720e` #684, `23ba632` #1043), verified on
+  rev `57af7f9` via toy's `gate-poly-degrade` and its landmine-#16 probe.
+- `docs/gem-audit-first.md` — the spinelgems catalog audit justifying
+  implement-don't-reuse for each surface, the methodology, and links to the
+  filed verification-request issues.
+- `docs/spinel-discipline.md` — the poly-degrade naming rules and the
+  `Hash[missing]==0` / SafeHash gotcha.
+- `docs/adoption.md` — the deferred 3-way move (tep adopts, toy adopts).
+
+### Not yet done (deferred — see docs/adoption.md)
+- Consumer adoption: tep and toy still ship their own `*::Json`/`Git`/`Logger`.
+  The alias-and-vendor migration sequences behind this frozen API, gated by
+  each consumer's poly-degrade scan.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ori Pekelman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# SpinelKit
+
+[![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.
+
+[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.
+
+## Installation
+
+```sh
+gem install spinel_kit
+```
+
+Or in a Gemfile:
+
+```ruby
+gem "spinel_kit"
+```
+
+Pure Ruby, no native extension, no runtime dependencies — so it also vendors
+cleanly into a Spinel build via [bundler-spinel](https://github.com/OriPekelman/spinelgems).
+
+## Why a gem instead of reusing one?
+
+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:
+
+| 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`) |
+| 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.
+
+## What's in it
+
+```ruby
+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}
+  ```
+
+- **`SpinelKit::Git`** — git provenance from `.git/HEAD`.
+
+  ```ruby
+  g = SpinelKit::Git.read
+  g.sha          # => "a1b2c3..." (or "unknown" outside a repo)
+  g.branch       # => "main"
+  ```
+
+- **`SpinelKit::Log`** — a minimal levelled logger (CRuby `Logger` doesn't
+  compile under Spinel).
+
+  ```ruby
+  log = SpinelKit::Log.new
+  log.set_level("info")
+  log.info("server up")
+  ```
+
+## Design constraints (read before editing)
+
+SpinelKit is **pure Ruby, no native extension** (`spinel-ext.json` is `[]`) and
+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).
+
+## 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).
+
+## Development
+
+```sh
+rake test            # CRuby-side parity tests (never compiled)
+rake rbs:validate    # syntax-check the advisory RBS in sig/
+gem build spinel_kit.gemspec
+```
+
+MIT licensed.

data/docs/adoption.md

@@ -0,0 +1,114 @@
+# Adoption — standardize and clean (not shim-and-alias)
+
+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
+compatibility aliases on top of the old duplication.** Each consumer migrates
+to `SpinelKit::*` directly and **deletes** its donor module. No permanent
+`Tep::Json = SpinelKit::Json` shims left lying around.
+
+This is still a sequenced move — moving shared code into a new namespace can
+introduce poly-degrade collisions in a consumer's whole-program inference — so
+we migrate one consumer at a time and gate each on its poly-degrade scan. But
+the end-state is clean call sites, one canonical surface, and no aliases.
+
+## Consumption mechanism (and the current interim)
+
+The clean path is `gem "spinel_kit"` + `spinel-compat vendor`. But that flow
+does **not yet support transitive gem→gem dependencies** (no topo-sorted
+`deps.rb`, no inter-gem require resolution), so a consumer that is *itself* a
+vendored gem — like tep — can't yet pull spinel_kit through it. Tracked at
+[OriPekelman/spinelgems#19](https://github.com/OriPekelman/spinelgems/issues/19).
+
+**Interim:** the consumer vendors spinel_kit's lib (the surface it uses)
+**committed under its own `lib/spinel_kit/`**, re-synced from the published gem
+(e.g. tep's `make vendor-spinelkit`). Committed-under-`lib/` is what makes it
+travel correctly when the consumer is itself vendored. Once spinelgems#19 lands,
+switch to the gitignored `spinel-compat vendor` flow.
+
+## Migration per consumer
+
+For each of tep and toy:
+
+1. Add `gem "spinel_kit"` (path/git during dev) and `spinel-compat vendor`.
+2. **Rewrite the call sites** to the canonical names:
+   - tep: ~157 `Tep::Json.*` → `SpinelKit::Json.*`; `Tep::Logger` →
+     `SpinelKit::Log`.
+   - toy: the `Toy::Json.new` builder sites → `SpinelKit::Json.new`;
+     `Toy::Git.read` → `SpinelKit::Git.read`.
+   A mechanical find/replace per symbol; the names below are chosen so the
+   replacement is 1:1 (see "Canonical surface").
+3. **Delete the donor files** (`lib/tep/json.rb`, `lib/tep/logger.rb`,
+   `lib/toy/io/toy_json.rb`, `lib/toy/io/toy_git.rb`) — no alias, no subclass.
+4. Build + run that consumer's suite.
+5. **toy only:** `make gate-poly-degrade` must stay byte-identical to the
+   frozen baseline (`prep/poly_degrade_gate.rb`). toy is where the
+   name-collision corruption originally bit. If an emit-0 appears, fix the
+   colliding name in SpinelKit (then re-vendor) rather than re-baselining.
+
+Sequence tep first (simpler, no training landmine), then toy.
+
+## Canonical surface — already converged
+
+The kit exposes ONE clean surface, not the union of two prefixed donor copies:
+
+- **No `j_*`/`tj_*`/`gi_*` prefixes.** Those existed only to dodge a Spinel
+  name-keyed inference bug, which is now fixed upstream (`ac7720e` #684,
+  `23ba632` #1043; verified on rev `57af7f9` with toy's gate-poly-degrade — see
+  [`spinel-discipline.md`](spinel-discipline.md)). The builder uses
+  `add_str`/`add_num`/`add_bool`/`add_raw`/`add_obj`/`dump`; Git uses
+  `sha`/`branch`.
+- **No duplicated escapers.** `escape`/`quote`/`hex2` are single canonical
+  methods the builder calls.
+
+The Json surface is split across **three files** so each consumer compiles only
+what it uses — Spinel has no tree-shaking, so loading code a consumer never
+calls would compile (and degrade) it, which both trips the poly-degrade gate
+and, worse, was observed to silently miscompile (dead decoder walkers widened
+`escape`'s string arg to int, emitting `""` keys from `from_*_hash`). The split:
+`spinel_kit/json` (encoders), `spinel_kit/json_decoder` (decoders),
+`spinel_kit/json_builder` (builder). So:
+
+- **tep** `require "spinel_kit/json"` + `"spinel_kit/json_decoder"` (it both
+  encodes responses and decodes request bodies) + `spinel_kit/log`. Verified:
+  the full encode+decode surface compiles **0 warnings, correct** on rev
+  `57af7f9`.
+- **toy** `require "spinel_kit/json_builder"` + `spinel_kit/git`. Verified:
+  builder-only compiles **0 warnings, correct** (integers preserved, no
+  cross-module `value` poisoning).
+
+A consumer must actually exercise the surface it loads (real ones do). A
+program that loads decoders but never calls them — or encodes via `from_*_hash`
+without any other string-`quote` call — can still see the dead-method
+degradation; the poly-degrade gate is what catches that.
+
+The per-symbol replacement is then a clean rename:
+
+| donor call               | canonical call                  |
+|--------------------------|---------------------------------|
+| `Toy::Json.new`          | `SpinelKit::Json::Builder.new`  |
+| `j.j_str(k, v)`          | `j.add_str(k, v)`               |
+| `j.j_num(k, v)`          | `j.add_num(k, v)`               |
+| `j.j_dump`               | `j.dump`                        |
+| `Toy::Git.read.gi_sha`   | `SpinelKit::Git.read.sha`       |
+| `Tep::Json.get_str(s,k)` | `SpinelKit::Json.get_str(s,k)`  |
+| `Tep::Json.quote(s)`     | `SpinelKit::Json.quote(s)`      |
+| `Tep::Logger.new`        | `SpinelKit::Log.new`            |
+
+tep's encoder/decoder spellings (`escape`/`quote`/`encode_pair_*`/`from_*`/
+`get_*`) are unchanged — only the namespace moves. toy's builder is the one set
+of call sites that changes method names. Each consumer's compile should be
+warning-clean (no new emit-0) because it loads only its own surface — verify
+with the poly-degrade gate after the move.
+
+## Git/Log
+
+Once tep and toy are both on `SpinelKit::Json`, tep gains `SpinelKit::Git` and
+toy gains `SpinelKit::Log` — each was previously single-consumer. No aliasing
+needed; just use the canonical names at the new call sites.
+
+## Out of scope until a catalog change
+
+`Path` and `Bytes` stay where they are (see
+[`gem-audit-first.md`](gem-audit-first.md)). Revisit `Path` only if the filed
+`hike` re-verification flips it back to `verified`.

data/docs/gem-audit-first.md

@@ -0,0 +1,76 @@
+# Gem-audit-first methodology
+
+**Rule: before implementing any SpinelKit lib, audit the
+[spinelgems](../../spinelgems) catalog for an existing gem that already
+provides the capability. Reusing a verified gem is always the biggest win.
+Only implement when the catalog says nothing fit exists — and record why.**
+
+This is not a one-time check. Every new surface added to SpinelKit must pass
+through the same gate and append a row to the audit table below.
+
+## How to query the catalog
+
+The catalog is an append-only JSONL ledger keyed by gem name, with a verdict
+ladder. Records live at `../../spinelgems/ledger/compat.jsonl`:
+
+```
+{"gem":"X","version":"1.2.3","rev":"git:8d88ebe/aarch64-linux-gnu",
+ "verdict":"rejected|risky|clean|loaded|verified","reasons":[...],
+ "risks":[...],"probe":"...","at":"..."}
+```
+
+| Verdict     | Meaning |
+|-------------|---------|
+| `verified`  | Full-surface compile + load + behaviour smoke matches CRuby. **Only tier to trust for production.** (~159 gems) |
+| `loaded`    | Require-only differential load matches; logic untested. |
+| `clean`     | Static lower bound — compiles; **no behaviour run**. Overstates compatibility. |
+| `risky`     | Compiles but uses constructs Spinel degrades silently (`eval`, `define_method`, …). |
+| `rejected`  | Doesn't compile, or a detected silent no-op/miscompile. `reasons` names the missing feature. |
+
+Verdicts are scoped to an **engine revision** (the Spinel git SHA + platform).
+A `rejected` is "rejected *as of this rev, because of these features*," never
+forever — upgrading Spinel triggers an automatic re-probe.
+
+Query examples:
+
+```sh
+LEDGER=../../spinelgems/ledger/compat.jsonl
+grep '"verdict":"verified"' "$LEDGER" | jq -r '.gem'        # all verified
+grep -E '"gem":"(json|oj|logger|rugged)"' "$LEDGER" | jq -c # specific gems
+```
+
+Human attestations (highest-trust, version-pinned) live separately in
+`../../spinelgems/attestations.jsonl`.
+
+## The audit (as of engine rev `git:8d88ebe`, aarch64-linux-gnu)
+
+| SpinelKit surface | Candidate gems | Verdict | Decision | Notes |
+|-------------------|----------------|---------|----------|-------|
+| **Json** | `json` | rejected | **implement** | C-ext fast path + `define_method`/`class_eval` pure fallback — unlowerable. |
+|          | `oj`, `yajl-ruby`, `multi_json` | risky / rejected | | All C-ext or thin wrappers thereof. |
+| **Log**  | `logger` (stdlib) | rejected | **implement** | Metaprogrammed severity dispatch + formatter API; ~35 unresolved calls. |
+| **Git**  | `rugged` | rejected | **implement** | libgit2 C bindings — needs `dlopen`. We read `.git/HEAD` as a plain file instead. |
+|          | `gitkite`, `git_manager` | clean (unmet `needs:`) | | Only the cheap static tier; load-path-terminal, never behaviour-verified. |
+| **Path** *(deferred)* | `hike` | verified@`2183a92`, only `loaded` now | **re-verify, then maybe reuse** | A path-*search* lib (Trail#find) — overkill for basename/join/expand. Filed a re-verify issue; revisit if it re-verifies. |
+|          | `pathname` (stdlib) | rejected | | C-ext + eval. |
+| **Bytes** *(deferred)* | `unicode_utils`, `utf8-cleaner` | clean only | **defer** | toy's actual need (`cp_to_utf8` + GPT-2 byte tables) is tokenizer-specific; no general reuse. |
+| **SafeHash** | — | n/a | **document, don't implement** | Not a gem — a coding *pattern* (always `has_key?` before `Hash[]`, because Spinel returns `0` for a missing key). See [`spinel-discipline.md`](spinel-discipline.md). |
+
+## Verification-request issues filed on spinelgems
+
+Filed on `OriPekelman/spinelgems` (see [`spinelgems-issues.md`](spinelgems-issues.md)
+for the exact bodies; issue numbers backfilled here once created):
+
+1. **Re-verify `hike`** at the current engine rev — if it re-verifies,
+   SpinelKit::Path becomes a *reuse* instead of an implement.
+   → [spinelgems#16](https://github.com/OriPekelman/spinelgems/issues/16)
+2. **Rubric clarification: `gitkite` / `git_manager`** — confirm their `clean`
+   verdict is load-path-terminal, so SpinelKit::Git's implement decision is
+   catalog-blessed.
+   → [spinelgems#17](https://github.com/OriPekelman/spinelgems/issues/17)
+3. *(optional)* **`oj` closure** — confirm `risky` is C-ext-terminal (no
+   pure-Ruby path), closing the JSON-reuse question on the record.
+   → [spinelgems#18](https://github.com/OriPekelman/spinelgems/issues/18)
+
+We did **not** file issues for `json`, `logger`, or `rugged`: their rejections
+are unambiguous (C-ext / metaprogramming) and a re-probe wouldn't flip them.

data/docs/spinel-discipline.md

@@ -0,0 +1,106 @@
+# Spinel discipline — naming, poly-degrade, and the Hash gotcha
+
+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`.
+
+## 1. The name-keyed inference bug — FIXED, prefixes dropped
+
+The donor copies (`Toy::Json`, `Toy::Git`) carried `j_`/`tj_`/`gi_` prefixes on
+every method and parameter to dodge a Spinel bug:
+
+> A same-named method or attr-reader across unrelated classes, reached through
+> an unresolved receiver, could commit a wrong type and widen an unrelated
+> value to `poly` — degrading or corrupting compute **even when the offending
+> module was merely `require`d and never called.**
+
+This actually bit toy (landmines #12/#16 in the gx10-side memory note
+`feedback_spinel_type_inference_landmines.md`; #16 was filed as matz/spinel
+#1043). **It has since been fixed in the compiler** — the relevant commits are
+`ac7720e` ("same-named attr_accessor on unrelated classes no longer widens
+reader to poly", #684) and `23ba632` ("Don't let a Struct member name globally
+type-merge unrelated code", fixes #1043), part of a sustained campaign that
+made inference receiver-aware / method-scoped instead of name-keyed. Each ships
+a regression test in Spinel's CI.
+
+**Verified, not assumed.** On the current compiler (rev `57af7f9`) we compiled
+two-module reproducers — a builder whose `value` param legitimately goes poly
+alongside an unrelated method with its own `value` param — and confirmed no
+cross-method leakage; toy's own `gate-poly-degrade` and its landmine-#16 probe
+both pass. So **the prefixes are gone** and SpinelKit uses plain, standard
+names (`escape`/`quote`/`add_str`/`sha`/`branch`/plain `value`).
+
+**Remaining rules:**
+
+- **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.
+- **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.
+
+## 2. The poly-degrade gate (how consumers verify SpinelKit is safe)
+
+Each consumer has a poly-degrade scan that compiles a canonical entrypoint and
+counts Spinel's `cannot resolve call to '<x>' on <type> (emitting 0)` warnings,
+comparing against a frozen baseline of known-benign dead paths. A **new**
+warning is a regression.
+
+- toy: `make gate-poly-degrade` → `prep/poly_degrade_gate.rb`
+  (baseline-compare; `--record` to re-baseline).
+
+When toy/tep migrate to SpinelKit (see [`adoption.md`](adoption.md)), the gate
+must stay **byte-identical to baseline** after the move. If rewriting toy's call
+sites to `SpinelKit::Json.*` introduces an emit-0, treat it as a real
+regression — fix the cause, don't re-baseline. (This gate guards a broader
+failure mode than the old name bug — unresolved hot-path calls and missing
+requires that emit a literal `0` — so it stays in CI regardless.)
+
+## 3. The `Hash[missing] == 0` gotcha (a.k.a. "SafeHash")
+
+This is **not a class** SpinelKit ships — it's a coding rule, because under
+Spinel a missing hash key reads back as integer `0`, not `nil`:
+
+```ruby
+# WRONG under Spinel — absent key looks like rank 0 (highest priority):
+r = @merge_rank[key]
+
+# RIGHT — guard with has_key? first:
+if @merge_rank.has_key?(key)
+  r = @merge_rank[key]
+  ...
+end
+```
+
+In toy's tokenizer this exact bug made BPE apply spurious merges (every absent
+merge looked like rank 0). **Always `has_key?` before `Hash[]`** in any code
+destined for Spinel. SpinelKit's own decoders follow this rule.
+
+## 4. Other Spinel limits relevant here
+
+- No `STDERR` as a general writable destination in all contexts — `Log` prefers
+  a file path; the `$stderr.puts` fallback is the donor's and works where tep
+  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.
+- No C extensions — `spinel-ext.json` is `[]`.

data/docs/spinelgems-issues.md

@@ -0,0 +1,74 @@
+# spinelgems verification-request issues
+
+Issues filed on `OriPekelman/spinelgems` as part of the gem-audit-first pass
+(see [`gem-audit-first.md`](gem-audit-first.md)):
+[#16](https://github.com/OriPekelman/spinelgems/issues/16) (hike re-verify),
+[#17](https://github.com/OriPekelman/spinelgems/issues/17) (gitkite/git_manager
+rubric), [#18](https://github.com/OriPekelman/spinelgems/issues/18) (oj
+closure). Bodies below.
+
+---
+
+## 1. Re-verify `hike` at the current engine rev
+
+**Title:** Re-verify `hike` — was `verified`@2183a92, now only `loaded`
+
+**Body:**
+
+`hike` (path search / `Trail#find`) is the one candidate that could let a
+downstream consumer *reuse* a gem instead of hand-rolling path resolution
+(tracking: SpinelKit / toy#44). It shows `verified` at engine rev `2183a92`
+but only `loaded` at the current dominant rev — i.e. its require-only load
+still matches CRuby, but no behaviour smoke has run at this rev.
+
+- Gem: `hike` (latest 2.x)
+- Current verdict: `loaded` (please confirm with `spinel-compat probe hike`)
+- Ask: run a full `verify` so it returns to `verified` (or surfaces the
+  regression).
+- Proposed smoke: build a `Hike::Trail`, append two roots, assert
+  `trail.find("x.rb")` resolves the same path under CRuby and Spinel; assert a
+  miss returns `nil`/empty identically.
+
+If it re-verifies, `SpinelKit::Path` becomes a reuse instead of an implement.
+
+---
+
+## 2. Rubric clarification: `gitkite` / `git_manager`
+
+**Title:** Confirm `gitkite` / `git_manager` `clean` verdicts are load-path-terminal
+
+**Body:**
+
+For SpinelKit (toy#44) we decided to implement `.git/HEAD` provenance directly
+rather than depend on a git gem, because the only non-rejected candidates sit
+at the `clean` tier with unmet `needs:`. Before we lock that decision in, can
+you confirm the `clean` verdict for `gitkite` and `git_manager` is
+**load-path-terminal** (the `needs:<x>` cannot be satisfied by vendoring),
+i.e. they will not advance to `loaded`/`verified` without upstream changes?
+
+- Gems: `gitkite`, `git_manager`
+- Current verdict: `clean` with `needs:` reasons (please paste the `reasons`
+  array from the ledger)
+- Ask: confirm terminal, or tell us what would unblock them.
+
+This just makes the "implement, don't reuse" call catalog-blessed rather than
+assumed.
+
+---
+
+## 3. (optional) `oj` closure
+
+**Title:** Confirm `oj` `risky` is C-ext-terminal (no pure-Ruby path)
+
+**Body:**
+
+Closing the JSON-reuse question on the record for SpinelKit (toy#44). `json`
+is cleanly rejected (C-ext + metaprogrammed fallback). `oj` shows `risky` —
+can you confirm that's C-extension-terminal (the fast path is native, and the
+`method_missing` mimic path Spinel degrades), so there is no pure-Ruby
+configuration of `oj` that could reach `verified`?
+
+- Gem: `oj`
+- Current verdict: `risky`
+- Ask: confirm terminal for our purposes, or point at a pure-Ruby mode we
+  missed.

data/lib/spinel_kit/git.rb

@@ -0,0 +1,73 @@
+# SpinelKit::Git -- git provenance read from .git/HEAD.
+#
+# WHY THIS EXISTS. Spinel-compiled tooling that stamps a `git:{sha,branch}`
+# provenance field (toy's run_start events; any reproducible-build banner)
+# can't reach for a git gem: `rugged` is a C extension (rejected by the
+# spinelgems catalog), and `gitkite`/`git_manager` only reach the `clean`
+# tier with unmet `needs:` (load-path-terminal). Reading `.git/HEAD` as a
+# plain file is a dozen lines of pure Ruby with no FFI -- so this is that.
+# Ported from Toy::Git; tep gains it for free.
+#
+# Behaviour: reads .git/HEAD; if it's a `ref: refs/heads/<branch>` pointer,
+# the branch is the last path segment and the 40-char sha is read from the
+# pointed-at ref file; if HEAD is detached (a raw sha), sha = that, branch =
+# "HEAD". Anything missing/short -> "unknown". Caller-facing default stays
+# "unknown"/"unknown" so a non-repo checkout is non-fatal.
+#
+# NAMING. The Toy::Git copy carried a `gi_` prefix on every member/local to
+# dodge a Spinel whole-program-inference bug; that bug was fixed upstream
+# (see docs/spinel-discipline.md), so this uses plain `sha`/`branch`.
+#
+# USAGE:
+#   g = SpinelKit::Git.read
+#   git_sha    = g.sha
+#   git_branch = g.branch
+module SpinelKit
+  class Git
+    def initialize(sha, branch)
+      @sha    = sha
+      @branch = branch
+    end
+
+    def sha
+      @sha
+    end
+
+    def branch
+      @branch
+    end
+
+    # Read provenance from ./.git/HEAD. Returns a SpinelKit::Git
+    # (sha/branch).
+    def self.read
+      s = "unknown"
+      b = "unknown"
+      if File.exist?(".git/HEAD")
+        head = File.read(".git/HEAD")
+        if head.length > 0 && head[head.length - 1...head.length] == "\n"
+          head = head[0...head.length - 1]
+        end
+        if head.length > 5 && head[0...5] == "ref: "
+          ref_rel = head[5...head.length]
+          pp = ref_rel.split("/")
+          if pp.length >= 3
+            b = pp[pp.length - 1]
+          end
+          ref_path = ".git/" + ref_rel
+          if File.exist?(ref_path)
+            sha_raw = File.read(ref_path)
+            if sha_raw.length >= 40
+              s = sha_raw[0...40]
+            end
+          end
+        else
+          if head.length >= 40
+            s = head[0...40]
+            b = "HEAD"
+          end
+        end
+      end
+      SpinelKit::Git.new(s, b)
+    end
+  end
+end