toy 0.8.0

data/prep/progress

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# prep/progress — run a build command with a single-line progress bar
+# driven by [NN%] markers in the child's output (cmake/make print
+# these natively). Full output is teed to LOG so nothing is lost.
+#
+# On non-zero exit:
+#   - the progress line is finalised on its own line
+#   - the last 40 lines of LOG are dumped to stderr
+#   - the script propagates the child's exit code
+# Errors are NEVER silenced; the LOG always contains the full output.
+#
+# Usage:
+#   LOG=path/to/build.log LABEL="ggml-cpu" prep/progress -- CMD [ARG...]
+#
+# Honoured env vars:
+#   LOG     (required) tee target
+#   LABEL   (optional) short tag printed alongside the bar
+#   NO_TTY  (optional) force plain "[NN%] msg" lines (CI / pipes)
+#
+# bash 3.2+ (macOS default ships 3.2). Uses awk for the line filter,
+# tee for the log split, a tmpfile for the exit code (PIPESTATUS would
+# also work but tmpfile keeps the structure parallel to prep/quietly).
+
+set -e -u -o pipefail
+
+LOG=${LOG:?prep/progress: LOG=path is required}
+LABEL=${LABEL:-build}
+
+# Strip a leading -- separator if present (so callers can write
+# `prep/progress -- cmake --build …` for symmetry with prep/quietly).
+if [ "${1:-}" = "--" ]; then
+  shift
+fi
+if [ $# -eq 0 ]; then
+  echo "prep/progress: missing command" >&2
+  exit 2
+fi
+
+# Make the log directory; don't fail if LOG=/dev/stderr or similar.
+log_dir=$(dirname "$LOG" 2>/dev/null || true)
+if [ -n "$log_dir" ] && [ "$log_dir" != "." ] && [ ! -d "$log_dir" ]; then
+  mkdir -p "$log_dir"
+fi
+
+# Detect TTY for the bar / cursor-hide. NO_TTY=1 forces plain mode for
+# CI logs (where \r would just produce one long line per percent).
+if [ -t 1 ] && [ -z "${NO_TTY:-}" ]; then
+  TTY=1
+else
+  TTY=0
+fi
+
+status_file=$(mktemp -t toy-progress.XXXXXX)
+cleanup() {
+  if [ "$TTY" = "1" ]; then printf '\033[?25h'; fi
+  rm -f "$status_file"
+}
+trap cleanup EXIT INT TERM
+
+if [ "$TTY" = "1" ]; then printf '\033[?25l'; fi  # hide cursor
+
+# Subshell: run the build, merge stderr→stdout, capture exit code.
+# tee splits to the logfile (everything, unfiltered).
+# awk parses [NN%] and redraws a single-line progress bar.
+( set +e; "$@" 2>&1; echo $? > "$status_file" ) \
+  | tee "$LOG" \
+  | LABEL="$LABEL" TTY="$TTY" awk '
+      BEGIN {
+        label = ENVIRON["LABEL"]; tty = ENVIRON["TTY"] + 0
+        last_pct = -1
+        bar_len = 30
+      }
+      function bar(pct,    filled, b, i) {
+        filled = int(pct * bar_len / 100)
+        b = ""
+        for (i = 0; i < filled; i++) b = b "="
+        if (filled < bar_len) { b = b ">"; i++ }
+        for (; i < bar_len; i++) b = b " "
+        return b
+      }
+      {
+        line = $0
+        # Match [NN%] or [ N%] or [100%] at start of line. cmake/make
+        # both emit this. Anything else passes through silently (the
+        # log has it all; we want the terminal quiet).
+        if (match(line, /^\[ *[0-9]+%\]/)) {
+          end = index(line, "%]")
+          pct = substr(line, 2, end - 2) + 0
+          msg = substr(line, end + 2)
+          sub(/^[[:space:]]+/, "", msg)
+          # Truncate msg so the bar line fits in ~110 cols total.
+          if (length(msg) > 70) msg = substr(msg, 1, 67) "..."
+          if (tty) {
+            if (pct != last_pct) {
+              printf "\r\033[K  [%s] %3d%%  %-12s  %s", bar(pct), pct, label, msg
+              fflush()
+              last_pct = pct
+            }
+          } else {
+            printf "  [%3d%%] %s  %s\n", pct, label, msg
+            fflush()
+          }
+        }
+      }
+      END {
+        if (tty) { printf "\n" }
+      }
+    '
+
+status=$(cat "$status_file")
+if [ "$status" != "0" ]; then
+  echo "" >&2
+  echo "  ✗ $LABEL failed (exit $status). Last 40 lines of $LOG:" >&2
+  echo "  ─────────────────────────────────────────────────────" >&2
+  tail -40 "$LOG" >&2 || true
+  echo "  ─────────────────────────────────────────────────────" >&2
+fi
+exit "$status"

data/prep/quietly

@@ -0,0 +1,64 @@
+#!/bin/sh
+# prep/quietly — filter known-harmless output lines while preserving
+# the child command's exit code. Patterns are extended-regex; lines
+# matching ANY pattern (anywhere in the line) are dropped. Stdout and
+# stderr are merged (both are filtered the same way) — this is meant
+# for cosmetic noise reduction, not for hiding real diagnostics.
+#
+# Usage:
+#   prep/quietly PATTERN [PATTERN...] -- CMD [ARG...]
+#
+# Example:
+#   prep/quietly 'cannot resolve call to' 'ignoring duplicate libraries' -- \
+#     spinel examples/foo.rb -o examples/foo
+#
+# Errors are NEVER silenced: the exit code of CMD is the exit code of
+# this script. If you see no output at all, that's an indicator the
+# patterns are too broad — narrow them.
+#
+# POSIX sh (bash 3.x / dash / busybox sh / zsh-emulated-sh). Uses
+# awk (universally available) for the line filter.
+
+set -eu
+
+patterns=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --)
+      shift
+      break
+      ;;
+    *)
+      if [ -z "$patterns" ]; then
+        patterns=$1
+      else
+        patterns="$patterns|$1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [ $# -eq 0 ]; then
+  echo "prep/quietly: missing command (use -- to separate patterns from command)" >&2
+  exit 2
+fi
+
+if [ -z "$patterns" ]; then
+  exec "$@"
+fi
+
+# Capture child exit code via a tmpfile written from inside the
+# subshell. POSIX-portable; PIPESTATUS is bash-only.
+status_file=$(mktemp -t quietly.XXXXXX)
+trap 'rm -f "$status_file"' EXIT INT TERM
+
+# Subshell: run the child with stderr merged into stdout so a single
+# pipeline can filter both. Disable `set -e` inside the subshell so a
+# non-zero exit from the child doesn't short-circuit before we record
+# its status — that's the whole point of saving it.
+( set +e; "$@" 2>&1; echo $? > "$status_file" ) | \
+    awk -v pat="$patterns" 'BEGIN{re="(" pat ")"} $0 !~ re {print}'
+
+# awk exit code is irrelevant — we want the child's.
+exit "$(cat "$status_file")"

data/sig/toy.rbs

@@ -0,0 +1,397 @@
+# sig/toy.rbs — type signatures for the Toy:: surface.
+#
+# Used by Steep (typecheck), the Phuong–Hutter algorithm-card emitter
+# (source of truth), and Spinel's `--rbs sig` flag (analyzer-arbitration
+# hint; seeds are ADVISORY — see spinel docs/RBS-EXTRACT.md for the
+# supported subset). Since toy#69 the Makefile passes `--rbs sig` on
+# every spinel invocation (SPINEL_RBS_FLAG), and `spinel-compat vendor`
+# ships this tree to consumers (spinelgems#13). The compute surface
+# (recipes / engines / value objects) lives in sig/toy_compute.rbs.
+# Keep this file accurate against lib/.
+#
+# Conventions:
+#   - Mat is a 2-D Float matrix with flat f64 storage. Where shape is
+#     load-bearing in a method body, the docstring uses shape names
+#     (T = sequence length, D = d_model, Dh = d_head, etc.).
+#   - Array[Integer] is used for token-id lists; Array[Float] for
+#     1-D real vectors (norm gammas, biases).
+#   - All `forward: (Mat) -> Mat` methods are pure in the
+#     `x → output` sense; they may build internal tensors but do not
+#     mutate the input.
+#   - The `param_count` method counts trainable parameters; tied
+#     embeddings are counted once at the model level.
+
+# ============================================================================
+# Mat — 2D Float matrix, flat row-major f64 storage.
+# (Lives in lib/toy/models/transformer.rb.)
+# ============================================================================
+class Mat
+  attr_accessor nrows: Integer
+  attr_accessor ncols: Integer
+  attr_accessor flat:  Array[Float]
+
+  def initialize: (Integer nrows, Integer ncols) -> void
+
+  def fill_random: (Float scale) -> void
+  def fill_zero:   () -> void
+
+  # (m × n) · (n × p) → (m × p)
+  def matmul:   (Mat other) -> Mat
+  # self · otherᵀ
+  def matmul_t: (Mat other) -> Mat
+  # selfᵀ · other
+  def t_matmul: (Mat other) -> Mat
+
+  def transpose: () -> Mat
+  def plus:      (Mat other) -> Mat
+  def add!:      (Mat other) -> Mat
+  def scale!:    (Float s)   -> Mat
+  def get:       (Integer i, Integer j) -> Float
+  def set_at:    (Integer i, Integer j, Float v) -> void
+
+  # Introspection.
+  def shape: () -> String          # "[5, 768]"
+  def info:  () -> String          # "Mat[5, 768] min=… max=… mean=…"
+end
+
+# ============================================================================
+# Toy:: building blocks.
+# ============================================================================
+module Toy
+  type activation = :gelu_new
+
+  # ---- LayerNorm (HF GPT-2 style: γ, β, ε) -------------------------------
+  class LayerNorm
+    attr_accessor gamma: Array[Float]
+    attr_accessor beta:  Array[Float]
+    attr_accessor d:     Integer
+    attr_accessor eps:   Float
+
+    def initialize:  (Integer d) -> void
+    def forward:     (Mat x) -> Mat        # [T, D] → [T, D]
+    def summary:     () -> String
+    def param_count: () -> Integer
+  end
+
+  # ---- RMSNorm (Llama-family: γ only, no β) ------------------------------
+  class RMSNorm
+    attr_accessor gamma: Array[Float]
+    attr_accessor d:     Integer
+    attr_accessor eps:   Float
+
+    def initialize:  (Integer d) -> void
+    def forward:     (Mat x) -> Mat        # [T, D] → [T, D]
+    def summary:     () -> String
+    def param_count: () -> Integer
+  end
+
+  # ---- Linear (matmul + optional bias) -----------------------------------
+  class Linear
+    attr_accessor w:        Mat
+    attr_accessor b:        Array[Float]
+    attr_accessor has_bias: bool
+    attr_accessor in_dim:   Integer
+    attr_accessor out_dim:  Integer
+
+    def initialize:  (Integer in_dim, Integer out_dim, bool with_bias) -> void
+    def forward:     (Mat x) -> Mat        # [T, in_dim] → [T, out_dim]
+    def summary:     () -> String
+    def param_count: () -> Integer
+  end
+
+  # ---- Embedding (lookup table) ------------------------------------------
+  class Embedding
+    attr_accessor weight: Mat              # [V, D]
+    attr_accessor vocab:  Integer
+    attr_accessor d:      Integer
+
+    def initialize:  (Integer vocab, Integer d) -> void
+    def lookup:      (Array[Integer] ids)          -> Mat   # [T] → [T, D]
+    def slice:       (Integer start, Integer count) -> Mat   # rows [s, s+c)
+    def summary:     () -> String
+    def param_count: () -> Integer
+  end
+
+  # ---- CausalSelfAttention (HF GPT-2 multi-head, biased) -----------------
+  class CausalSelfAttention
+    attr_accessor w_q:      Array[Mat]     # length n_heads; each [D, Dh]
+    attr_accessor w_k:      Array[Mat]
+    attr_accessor w_v:      Array[Mat]
+    attr_accessor b_q:      Array[Array[Float]]
+    attr_accessor b_k:      Array[Array[Float]]
+    attr_accessor b_v:      Array[Array[Float]]
+    attr_accessor w_o:      Mat
+    attr_accessor b_o:      Array[Float]
+    attr_accessor d_model:  Integer
+    attr_accessor n_heads:  Integer
+    attr_accessor d_head:   Integer
+    attr_accessor inv_sqrt: Float
+
+    def initialize:  (Integer d_model, Integer n_heads) -> void
+    def forward:     (Mat x) -> Mat        # [T, D] → [T, D]
+    def head:        (Mat x, Integer h) -> Mat  # [T, D] → [T, Dh]
+    def summary:     () -> String
+    def param_count: () -> Integer
+  end
+
+  # ---- GQAttention (Llama-family grouped-query, RoPE-on-Q/K) -------------
+  class GQAttention
+    attr_accessor w_q:        Array[Mat]   # length n_heads
+    attr_accessor w_k:        Array[Mat]   # length n_kv
+    attr_accessor w_v:        Array[Mat]   # length n_kv
+    attr_accessor w_o:        Mat
+    attr_accessor n_heads:    Integer
+    attr_accessor n_kv:       Integer
+    attr_accessor d_model:    Integer
+    attr_accessor d_head:     Integer
+    attr_accessor group_size: Integer      # n_heads / n_kv
+    attr_accessor inv_sqrt:   Float
+    attr_accessor rope:       RoPE
+
+    def initialize:  (Integer d_model, Integer n_heads, Integer n_kv, RoPE rope_obj) -> void
+    def forward:     (Mat x, Integer pos_start) -> Mat       # [T, D] → [T, D]
+    def attend:      (Mat x, Integer hq, Mat k_h, Mat v_h, Integer pos_start) -> Mat
+    def summary:     () -> String
+    def param_count: () -> Integer
+  end
+
+  # ---- FFN (GPT-2 MLP: Linear → GeLU → Linear) ---------------------------
+  class FFN
+    attr_accessor w1:      Mat            # [D, Df]
+    attr_accessor w2:      Mat            # [Df, D]
+    attr_accessor b1:      Array[Float]
+    attr_accessor b2:      Array[Float]
+    attr_accessor d_model: Integer
+    attr_accessor d_ff:    Integer
+    attr_accessor act:     activation
+
+    def initialize:  (Integer d_model, Integer d_ff, activation act_sym) -> void
+    def forward:     (Mat x) -> Mat        # [T, D] → [T, D]
+    def summary:     () -> String
+    def param_count: () -> Integer
+  end
+
+  # ---- SwiGLU (Llama-family gated FFN, no biases) -----------------------
+  class SwiGLU
+    attr_accessor w_gate:  Mat            # [D, Df]
+    attr_accessor w_up:    Mat            # [D, Df]
+    attr_accessor w_down:  Mat            # [Df, D]
+    attr_accessor d_model: Integer
+    attr_accessor d_ff:    Integer
+
+    def initialize:  (Integer d_model, Integer d_ff) -> void
+    def forward:     (Mat x) -> Mat        # [T, D] → [T, D]
+    def summary:     () -> String
+    def param_count: () -> Integer
+  end
+
+  # ---- RoPE (rotate_half; precomputed cos/sin tables) --------------------
+  class RoPE
+    attr_accessor cos_tbl: Array[Float]
+    attr_accessor sin_tbl: Array[Float]
+    attr_accessor d_head:  Integer
+    attr_accessor max_seq: Integer
+
+    def initialize:  (Integer d_head, Integer max_seq, Float theta_base) -> void
+    # Rotates `x` in place. Row t corresponds to absolute position
+    # pos_start + t.
+    def rotate!:     (Mat x, Integer pos_start) -> void
+    def summary:     () -> String
+    def param_count: () -> Integer        # always 0 (cos/sin precomputed)
+  end
+
+  # ========================================================================
+  # SmolLM2 / Llama-family model.
+  # (Lives in lib/toy/models/toy_smollm2.rb.)
+  # ========================================================================
+
+  # ---- RopeScaling — RoPE frequency-scaling parameters --------------------
+  # Carried on SmolLM2Config; the GGUF loader sets it from
+  # rope_scaling.* metadata. kind ∈ :none / :linear / :llama3.
+  class RopeScaling
+    attr_accessor kind:             Symbol
+    attr_accessor freq_scale:       Float
+    attr_accessor orig_max_pos:     Integer
+    attr_accessor factor:           Float
+    attr_accessor low_freq_factor:  Float
+    attr_accessor high_freq_factor: Float
+    attr_accessor ext_factor:       Float
+    attr_accessor attn_factor:      Float
+    attr_accessor beta_fast:        Float
+    attr_accessor beta_slow:        Float
+
+    def initialize: (Symbol kind, Float freq_scale, Integer orig_max_pos,
+                     Float factor, Float low_freq_factor,
+                     Float high_freq_factor, Float ext_factor,
+                     Float attn_factor, Float beta_fast,
+                     Float beta_slow) -> void
+    def self.none:   () -> Toy::RopeScaling
+    def self.linear: (Float factor) -> Toy::RopeScaling
+    def self.llama3: (Float factor, Float low_freq, Float high_freq,
+                      Integer orig_max_pos) -> Toy::RopeScaling
+    # Returns the (d_head/2)-element per-dim freq_factors array.
+    def self.compute_llama3_freq_factors: (Integer d_head, Float freq_base,
+                                           Integer orig_max_pos, Float factor,
+                                           Float low_freq, Float high_freq) -> Array[Float]
+  end
+
+  class SmolLM2Config
+    attr_accessor vocab:        Integer
+    attr_accessor d_model:      Integer
+    attr_accessor n_heads:      Integer
+    attr_accessor n_kv:         Integer
+    attr_accessor d_ff:         Integer
+    attr_accessor n_layers:     Integer
+    attr_accessor ctx:          Integer
+    attr_accessor rope_base:    Float
+    attr_accessor rms_eps:      Float
+    attr_accessor rope_scaling: Toy::RopeScaling
+    attr_accessor head_dim:     Integer
+    attr_accessor donor_d_in:   Integer
+
+    # THE #52 CONSTRUCTOR SLOT: this ctor sits on the shared path that
+    # uncalled forwarders (LoRA#realize! → realize_for_mmap → .new)
+    # union poly args into (spinel-dev#12). The seed pins it.
+    def initialize: (Integer vocab, Integer d_model, Integer n_heads,
+                     Integer n_kv, Integer d_ff, Integer n_layers,
+                     Integer ctx, Float rope_base, Float rms_eps) -> void
+    def self.smollm2_135m: () -> Toy::SmolLM2Config
+    def self.tiny:         () -> Toy::SmolLM2Config
+    def self.mid:          () -> Toy::SmolLM2Config
+    def self.mha: (Integer vocab, Integer d_model, Integer heads,
+                   Integer d_ff, Integer layers, Integer ctx,
+                   Float rope_base, Float rms_eps) -> Toy::SmolLM2Config
+    def self.gqa: (Integer vocab, Integer d_model, Integer heads,
+                   Integer n_kv, Integer d_ff, Integer layers, Integer ctx,
+                   Float rope_base, Float rms_eps) -> Toy::SmolLM2Config
+  end
+
+  class SmolLM2Block
+    attr_accessor rn1:  RMSNorm
+    attr_accessor rn2:  RMSNorm
+    attr_accessor attn: GQAttention
+    attr_accessor ffn:  SwiGLU
+
+    def initialize:  (SmolLM2Config cfg, RoPE rope_obj) -> void
+    # x: [T, D], pos_start: absolute position of row 0.
+    def forward:     (Mat x, Integer pos_start) -> Mat
+    def param_count: () -> Integer
+  end
+
+  class SmolLM2
+    attr_accessor cfg:               SmolLM2Config
+    attr_accessor token_embed:       Embedding
+    attr_accessor final_norm:        RMSNorm
+    attr_accessor stack:             Array[SmolLM2Block]   # length cfg.n_layers
+    attr_accessor rope:              RoPE
+    attr_accessor output_proj:       Mat                   # [V, D]; used only when untied
+    attr_accessor has_untied_output: bool
+
+    def initialize:               (SmolLM2Config cfg) -> void
+    def enable_untied_output!:    () -> void
+    # ids: token IDs (length T), pos_start: absolute position of row 0.
+    # Returns logits of shape [T, V].
+    def forward:                  (Array[Integer] ids, Integer pos_start) -> Mat
+    def param_count:              () -> Integer
+  end
+
+  # ========================================================================
+  # Free-standing helpers.
+  # ========================================================================
+  def self.add_bias!:    (Mat x, Array[Float] b) -> void
+  def self.causal_mask!: (Mat scores) -> void
+  def self.softmax_rows!: (Mat m) -> void
+  def self.gelu_new:     (Mat x) -> Mat
+  def self.silu!:        (Mat m) -> void
+  def self.hadamard!:    (Mat dst, Mat src) -> void
+  def self.hstack_heads: (Array[Mat] per_head, Integer n_heads,
+                          Integer d_head, Integer d_model) -> Mat
+  def self.tap:          (String label, Mat x) -> Mat
+  def self.tap_info:     (String label, Mat x) -> Mat
+  def self.fmt_count:    (Integer n) -> String
+end
+
+# ============================================================================
+# GPT-2 model — HF-shape (LayerNorm with γ+β, biases on every Linear,
+# learned absolute position embeddings, tied input/output embed).
+# Top-level (not inside Toy::) because lib/gpt2.rb declares them at the
+# top level; the class is `GPT2LM`, not `GPT2`. Per-head Q/K/V parameters
+# live as Array<Mat> / Array<Array<Float>> rather than per-class
+# Linear/CausalSelfAttention objects — this mirrors the Block layout in
+# lib/transformer.rb so a future FFI cache can reuse the same shape.
+# ============================================================================
+class GPT2Block
+  attr_accessor ln1_gamma: Array[Float]
+  attr_accessor ln1_beta:  Array[Float]
+  attr_accessor ln2_gamma: Array[Float]
+  attr_accessor ln2_beta:  Array[Float]
+  attr_accessor w_q:       Array[Mat]            # length n_heads, each [D, Dh]
+  attr_accessor w_k:       Array[Mat]
+  attr_accessor w_v:       Array[Mat]
+  attr_accessor b_q:       Array[Array[Float]]
+  attr_accessor b_k:       Array[Array[Float]]
+  attr_accessor b_v:       Array[Array[Float]]
+  attr_accessor w_o:       Mat                    # [D, D]
+  attr_accessor w_ff1:     Mat                    # [D, Df]
+  attr_accessor w_ff2:     Mat                    # [Df, D]
+  attr_accessor b_o:       Array[Float]
+  attr_accessor b_ff1:     Array[Float]
+  attr_accessor b_ff2:     Array[Float]
+
+  def initialize: (Integer d_model, Integer d_head, Integer d_ff, Integer n_heads) -> void
+end
+
+class GPT2LM
+  attr_accessor vocab_size:     Integer
+  attr_accessor d_model:        Integer
+  attr_accessor d_ff:           Integer
+  attr_accessor n_heads:        Integer
+  attr_accessor d_head:         Integer
+  attr_accessor n_layers:       Integer
+  attr_accessor context_length: Integer
+  attr_accessor ln_eps:         Float
+  attr_accessor token_embed:    Mat                # [V, D]
+  attr_accessor pos_embed:      Mat                # [ctx, D]
+  attr_accessor ln_f_gamma:     Array[Float]
+  attr_accessor ln_f_beta:      Array[Float]
+  attr_accessor gpt2_blocks:    Array[GPT2Block]
+
+  def initialize: (Integer vocab_size, Integer d_model, Integer d_ff,
+                   Integer n_heads, Integer n_layers,
+                   Integer context_length) -> void
+  # ids: token IDs (length T); start_pos: absolute position of row 0.
+  # Returns logits of shape [T, V] (tied output embedding via x · token_embedᵀ).
+  def forward: (Array[Integer] token_ids, Integer start_pos) -> Mat
+end
+
+# ============================================================================
+# Tokenizer — GGUF-embedded BPE decoder. (lib/toy/io/tokenizer.rb)
+# Declared here to pin Spinel's analyzer; cross-class polymorphism on
+# `length` was widening Mat#nrows to sp_RbVal in compiled artifacts.
+# ============================================================================
+class Tokenizer
+  attr_reader vocab_size:  Integer
+  attr_reader bos_id:      Integer
+  attr_reader eos_id:      Integer
+  attr_reader pad_id:      Integer
+  attr_reader unk_id:      Integer
+  attr_reader present:     bool
+  attr_reader spm:         bool
+  attr_reader spm_unigram: bool
+  attr_accessor add_bos:   bool
+
+  # initialize is NOT declared: it takes 2 trailing DEFAULT args
+  # (model_name = "", add_bos = false), which are outside the RBS
+  # subset — and a deliberately-truncated 6-param declaration is NOT
+  # safe: the seed pinned a 6-slot signature against the 8-slot
+  # compiled ctor and broke the C compile of toy-infer with
+  # "too few arguments to function 'sp_Tokenizer_new'" (probed on
+  # a699cf9 during toy#69 adoption — a wrong-ARITY seed is the one
+  # case that is NOT an advisory no-op). Keep arity exact or absent.
+
+  def token_at: (Integer id) -> String
+  def decode:   (Array[Integer] ids) -> String
+  def encode:   (String text)        -> Array[Integer]
+
+  def self.from_gguf: (String path) -> Tokenizer
+end