toy 0.8.0

data/sig/toy_compute.rbs

@@ -0,0 +1,450 @@
+# sig/toy_compute.rbs — type signatures for the SPINEL-ONLY compute
+# surface (lib/toy/compute.rb and everything it pulls). Companion to
+# sig/toy.rbs (the pure-Ruby Mat / model surface).
+#
+# WHY (toy#69): RBS type roots pin a method's param/return/ivar types
+# WITHOUT needing a call site — a standing defense against the
+# uncalled-param poly-widening family (spinel-dev#11/#12, the f7ae245
+# facets). As a published gem, this sig/ tree flows automatically into
+# every consumer's vendor tree (spinelgems#13: `spinel-compat vendor`
+# copies sig/ and advertises one `--rbs <into>/sig` root), so uncalled
+# toy methods in consumer builds stay concretely typed.
+#
+# SUPPORTED SUBSET (spinel docs/RBS-EXTRACT.md — seeds are ADVISORY;
+# inference runs on top and widens on observed contradiction):
+#   - Integer/Float/String/Symbol/bool/void/nil, nominal Foo::Bar,
+#     Array[T], Hash[String|Symbol, T], T?.
+#   - NO optional/keyword/rest/block params — a signature touching any
+#     is dropped WHOLESALE. NO untyped/self/tuples/generics.
+#   - FFI `:ptr` values have NO RBS spelling: every ptr-typed accessor
+#     (sess, t_seq_* tensor handles, gguf handles, g_* arch handles)
+#     and every method with a ptr param or ptr return is intentionally
+#     OMITTED here — the analyzer's own inference handles those. This
+#     is also why LoRA#realize! / *#realize_for_mmap can NOT be rescued
+#     by sig alone: their leading gguf_handle param is a ptr (see the
+#     lora-exclusion note in lib/toy/compute.rb; spinel-dev#12).
+#   - Unqualified type names resolve to TOP-LEVEL (probed on a699cf9),
+#     so every non-top-level reference below is fully qualified.
+#
+# Conventions match sig/toy.rbs: Array[Integer] = token-id lists,
+# Array[Float] = flat f32/f64 buffers, Mat = 2-D Float matrix.
+# Keep this file accurate against lib/.
+
+# ============================================================================
+# Toy:: value objects shared by the recipes (pure Ruby, no FFI).
+# ============================================================================
+module Toy
+  # ---- AdamW (lib/toy/llm/adamw.rb) — named hyper-params → Mat(1,7) ------
+  # Slots 5/6 are DUAL-MEANING per graph family; `mode` declares the
+  # convention and hp() fails loud when unset/mismatched.
+  class AdamW
+    attr_accessor lr:           Float
+    attr_accessor beta1:        Float
+    attr_accessor beta2:        Float
+    attr_accessor eps:          Float
+    attr_accessor weight_decay: Float
+    attr_accessor bias_correct: bool
+    attr_accessor mode:         Integer
+
+    def initialize: () -> void
+    def self.for_from_scratch: () -> Toy::AdamW
+    def self.for_lora:         () -> Toy::AdamW
+    # step is the caller's 1-indexed step; ignored when bias_correct
+    # is false. Returns the Mat(1,7) handed to the recipes' step!.
+    def hp: (Integer step) -> Mat
+    # Mode-aware builder: takes the 0-INDEXED loop step; applies lora's
+    # 1-indexed t internally (hp_for_step(k) == hp(k+1) in MODE_LORA).
+    def hp_for_step: (Integer step) -> Mat
+  end
+
+  # ---- Labels (lib/toy/llm/labels.rb) — one-hot label builders -----------
+  module Labels
+    def self.next_token:         (Array[Integer] seq_ids, Integer vocab,
+                                  Integer context, Integer batch) -> Mat
+    def self.next_token_guarded: (Array[Integer] seq_ids, Integer vocab,
+                                  Integer context, Integer batch) -> Mat
+    # toy#73 item 3 — the two non-shift-by-one objectives.
+    def self.fixed_target:  (Integer vocab, Integer context,
+                             Integer target_id) -> Mat
+    def self.one_hot_class: (Integer num_classes, Integer label) -> Mat
+  end
+
+  # ---- RunBundle (lib/toy/io/run_bundle.rb) — toy/v1 bundle writer -------
+  # Truncate-opens runs/<id>/events.jsonl in the ctor; run_start!/step!/
+  # run_end! emit the toy/v1 events; weights_dir is the checkpoint home.
+  # run_start stamps backend{kind: Toy::Device.name} automatically;
+  # git{sha,branch} is opt-in via git! (toy#73 A.3 — see the file header
+  # for why it cannot be automatic).
+  class RunBundle
+    attr_accessor rb_root:       String
+    attr_accessor rb_run_id:     String
+    attr_accessor rb_dir:        String
+    attr_accessor rb_active:     bool
+    attr_accessor rb_git_sha:    String
+    attr_accessor rb_git_branch: String
+
+    def initialize: (String runs_root, String run_id) -> void
+    def active: () -> bool
+    def events_path: () -> String
+    def weights_dir: () -> String
+    def git!: (String sha, String branch) -> void
+    def run_start_prefix: () -> String
+    # Per-arch starts (toy#73 A.3): model{}/config{} read off the cfg.
+    def run_start_llama!: (Toy::SmolLM2Config lcfg, Integer steps,
+                           Float lr, Integer seed) -> void
+    def run_start_vit!: (ViTTinyConfig vcfg, Integer steps,
+                         Float lr, Integer seed) -> void
+    def run_start!: (String arch, Integer vocab, Integer d_model,
+                     Integer n_layers, Integer context, Integer steps,
+                     Float lr, Integer seed) -> void
+    def step!: (Integer step, Float loss) -> void
+    def run_end!: (Integer final_step, Float final_loss) -> void
+    def self.json_escape: (String s) -> String
+  end
+
+  # ---- Device (lib/toy/compute{,_cuda,_metal}.rb) ------------------------
+  # The device-agnostic construction seam. ONLY `name` is declared:
+  # the factory methods (llama_engine, gpt2_engine, from_scratch_recipe,
+  # warm_start_recipe) return DIFFERENT classes per compute entry
+  # (LlamaSeqEngine vs LlamaSeqEngineCuda, ...), and this one sig tree
+  # serves all device builds — pinning a CPU return type would seed a
+  # contradiction into every CUDA/Metal build.
+  module Device
+    def self.name: () -> String
+  end
+end
+
+# ============================================================================
+# Toy::LLM:: — recipe options, training batch, recipes, engines.
+# ============================================================================
+module Toy
+  module LLM
+    # ---- RecipeOptions (lib/toy/llm/recipe_options.rb) -------------------
+    # Named realize-time options. Feed MONOMORPHIC values only (a poly
+    # assignment silently shifts training numerics — see the file's
+    # loud warning); these ivar seeds pin the expected types.
+    class RecipeOptions
+      attr_accessor t_seq:        Integer
+      attr_accessor t_batch:      Integer
+      attr_accessor weight_dtype: Integer
+      attr_accessor untied:       bool
+      attr_accessor qkv_bias:     bool
+      attr_accessor seed:         Integer
+      attr_accessor init_scale:   Float
+
+      def initialize: () -> void
+    end
+
+    # ---- TrainingBatch (lib/toy/llm/training_batch.rb) -------------------
+    # Validating wrapper for the per-step quartet. hp is caller-owned
+    # (Mat(1,7) from Toy::AdamW#hp).
+    class TrainingBatch
+      attr_accessor vocab:     Integer
+      attr_accessor context:   Integer
+      attr_accessor batch:     Integer
+      attr_accessor seq_ids:   Array[Integer]
+      attr_accessor positions: Array[Integer]
+      attr_accessor labels:    Mat
+      attr_accessor hp:        Mat
+
+      def initialize: (Integer vocab, Integer context, Integer batch_size) -> void
+      def fill!: (Array[Integer] new_seq_ids) -> void
+      # toy#73 item 3 — fixed-target objective (every position targets
+      # target_id; the lora-smoke shape).
+      def fill_fixed_target!: (Array[Integer] new_seq_ids,
+                               Integer target_id) -> void
+    end
+
+    # ---- ClassifyBatch (lib/toy/llm/classify_batch.rb) -------------------
+    # Image-classification sibling of TrainingBatch (toy#73 item 3):
+    # validates one (patches, label) record per fill!.
+    class ClassifyBatch
+      attr_accessor cb_classes:    Integer
+      attr_accessor cb_patch_flat: Integer
+      attr_accessor cb_n_patches:  Integer
+      attr_accessor image:         Mat
+      attr_accessor cls_idx:       Array[Integer]
+      attr_accessor labels:        Mat
+      attr_accessor hp:            Mat
+
+      def initialize: (Integer num_classes, Integer patch_flat,
+                       Integer n_patches) -> void
+      def fill!: (Array[Float] patches, Integer label) -> void
+    end
+
+    # ======================================================================
+    # Recipes (lib/toy/llm/recipes/) — the L4 named training plans.
+    # The engine-handle ivars (fs_cache, ws_cache, lora_cache, vt_cache)
+    # and stashed tensor handles (*_t_loss/_t_labels/_t_hp) are ptr-
+    # adjacent internals and stay inference-typed.
+    # ======================================================================
+    module Recipes
+      # ---- FromScratch — random-init train --------------------------------
+      class FromScratch
+        attr_accessor fs_cache:      Toy::LLM::Engine::LlamaSeqEngine
+        attr_accessor fs_step_index: Integer
+
+        def initialize: () -> void
+        def realize!: (Toy::SmolLM2Config cfg, Toy::LLM::RecipeOptions opts) -> void
+        # Returns the loss. m_labels/m_hp from Toy::Labels / Toy::AdamW#hp.
+        def step!: (Array[Integer] seq_ids, Array[Integer] positions,
+                    Mat m_labels, Mat m_hp, bool is_first) -> Float
+      end
+
+      # ---- WarmStart — random-init + donor-embed upload window ------------
+      class WarmStart
+        attr_accessor ws_cache:      Toy::LLM::Engine::LlamaSeqEngine
+        attr_accessor ws_step_index: Integer
+
+        def initialize: () -> void
+        # The pre-realize half of the donor plumbing (toy#73 item 4):
+        # the width cfg.donor_d_in must carry before realize_scratch!.
+        def self.donor_embed_width: (String donor_gguf_path) -> Integer
+        def realize_scratch!: (Toy::SmolLM2Config cfg, Toy::LLM::RecipeOptions opts) -> void
+        # Owns the donor GGUF read + dim-check + upload (toy#73 item 4).
+        def realize_warm!: (String donor_gguf_path, Toy::SmolLM2Config cfg) -> void
+        # The raw upload seam for ALREADY-READ buffers (PCA-lens flow).
+        def upload_donor!: (Array[Float] donor_buf_flat, Integer n_floats) -> void
+        def build!: () -> void
+        def step!: (Array[Integer] seq_ids, Array[Integer] positions,
+                    Mat m_labels, Mat m_hp, bool is_first) -> Float
+      end
+
+      # ---- LoRA — frozen mmap base + rank-r Q adapters ---------------------
+      # realize!(gguf_handle, cfg, rank, opts) is NOT declarable: its
+      # leading param is an FFI ptr (out of the RBS subset; the whole
+      # signature would be dropped). This is exactly why sig roots can
+      # not independently rescue the lora-in-compute exclusion (toy#52,
+      # spinel-dev#12) — see lib/toy/compute.rb.
+      class LoRA
+        attr_accessor lora_cache:      Toy::LLM::Engine::LlamaSeqEngine
+        attr_accessor lora_step_index: Integer
+
+        def initialize: () -> void
+        def step!: (Array[Integer] seq_ids, Array[Integer] positions,
+                    Mat m_labels, Mat m_hp, bool is_first) -> Float
+      end
+
+      # ---- VitTiny — ViT-Tiny from-scratch image classifier ----------------
+      class VitTiny
+        attr_accessor vt_cache: Toy::LLM::Engine::ViTTinyEngine
+
+        def initialize: () -> void
+        def realize!: (ViTTinyConfig cfg, Toy::LLM::RecipeOptions opts) -> void
+        # cls_idx is the single-element class-index array.
+        def step!: (Mat m_image, Array[Integer] cls_idx,
+                    Mat m_labels, Mat m_hp, bool is_first) -> Float
+      end
+    end
+
+    # ======================================================================
+    # Engines (lib/toy/llm/engine/) — the L4 forward/train drivers.
+    # Tensor-handle accessors (sess, t_seq_*, g_*, ft_globals_*) are
+    # FFI ptrs / ptr arrays — intentionally omitted (no RBS spelling).
+    # ======================================================================
+    module Engine
+      # ---- LlamaSeqEngine (llama_seq_engine.rb) ----------------------------
+      class LlamaSeqEngine
+        attr_accessor seq_has_untied_output:       bool
+        attr_accessor seq_has_qkv_bias:            bool
+        attr_accessor seq_t:                       Integer
+        attr_accessor seq_b:                       Integer
+        attr_accessor seq_d_model:                 Integer
+        attr_accessor seq_d_ff:                    Integer
+        attr_accessor seq_n_heads:                 Integer
+        attr_accessor seq_n_kv:                    Integer
+        attr_accessor seq_d_head:                  Integer
+        attr_accessor seq_group_size:              Integer
+        attr_accessor seq_n_layers:                Integer
+        attr_accessor seq_vocab_size:              Integer
+        attr_accessor seq_rope_base:               Float
+        attr_accessor seq_rope_scaling:            Toy::RopeScaling
+        attr_accessor seq_rms_eps:                 Float
+        attr_accessor seq_realized:                bool
+        attr_accessor seq_weight_dtype:            Integer
+        attr_accessor seq_lora_q_enabled:          bool
+        attr_accessor seq_lora_q_rank:             Integer
+        attr_accessor seq_lora_q_adamw_enabled:    bool
+        attr_accessor seq_full_finetune_enabled:   bool
+        attr_accessor ft_train_embeddings_enabled: bool
+
+        def initialize: () -> void
+        def enable_full_finetune_embeddings!: () -> bool
+        def enable_full_finetune!: () -> bool
+        def enable_lora_q!: (Integer r) -> Integer
+        def enable_lora_q_adamw!: () -> bool
+        # Pure ivar writes from cfg.*; pins the cfg slot CONCRETELY even
+        # from call sites the analyzer never sees live (the #52 chain).
+        def apply_seq_cfg!: (Toy::SmolLM2Config cfg) -> Float
+        # The from-scratch/warm-start realize. (The gguf-handle realizes —
+        # realize_for_mmap / realize_for_q8_copy / realize_for_full_finetune
+        # — take a leading FFI ptr and can not be declared.)
+        def realize_for_random_init: (Toy::SmolLM2Config cfg, Integer t_seq,
+                                      Integer t_batch, Integer weight_dtype,
+                                      bool untied, bool qkv_bias,
+                                      Integer seed, Float init_scale) -> bool
+        def upload_block_causal_mask!: () -> Integer
+        def upload_random_init!: (Integer seed, Float init_scale,
+                                  bool qkv_bias, bool untied) -> void
+        def upload_lora_q_init!: (Integer seed, Float init_scale) -> void
+        def build_and_realize!: () -> bool
+      end
+
+      # ---- GPT2SeqEngine (gpt2_seq_engine.rb) ------------------------------
+      class GPT2SeqEngine
+        attr_accessor g_vocab:    Integer
+        attr_accessor g_d_model:  Integer
+        attr_accessor g_n_heads:  Integer
+        attr_accessor g_d_head:   Integer
+        attr_accessor g_d_ff:     Integer
+        attr_accessor g_n_layers: Integer
+        attr_accessor g_context:  Integer
+        attr_accessor g_rng:      Integer
+
+        def initialize: () -> void
+        def realize!: (Integer vocab, Integer d_model, Integer n_heads,
+                       Integer d_ff, Integer n_layers, Integer context,
+                       Integer seed) -> void
+        def build_forward!: () -> void
+        def build_train_step!: () -> void
+        def step!: (Array[Integer] seq_ids, Array[Integer] positions,
+                    Mat m_labels, Mat m_hp, bool is_first) -> Float
+      end
+
+      # ---- ViTTinyEngine (vit_tiny_engine.rb) ------------------------------
+      class ViTTinyEngine
+        attr_accessor cfg:            ViTTinyConfig
+        attr_accessor n_patches:      Integer
+        attr_accessor seq_t:          Integer
+        attr_accessor patch_flat_dim: Integer
+        attr_accessor realized:       bool
+
+        def initialize: () -> void
+        def realize_for_random_init: (ViTTinyConfig cfg, Integer seed,
+                                      Float init_scale) -> bool
+        def upload_random_init!: (Integer seed, Float init_scale) -> void
+      end
+    end
+  end
+end
+
+# ============================================================================
+# ViTTinyConfig (lib/toy/models/toy_vit.rb) — top-level.
+# ============================================================================
+class ViTTinyConfig
+  attr_accessor image_size:   Integer
+  attr_accessor patch_size:   Integer
+  attr_accessor num_channels: Integer
+  attr_accessor d_model:      Integer
+  attr_accessor n_heads:      Integer
+  attr_accessor d_head:       Integer
+  attr_accessor d_ff:         Integer
+  attr_accessor n_layers:     Integer
+  attr_accessor num_classes:  Integer
+  attr_accessor ln_eps:       Float
+
+  def initialize: (Integer image_size, Integer patch_size,
+                   Integer num_channels, Integer d_model, Integer n_heads,
+                   Integer d_ff, Integer n_layers, Integer num_classes,
+                   Float ln_eps) -> void
+  # toy#73 A.3 — the canonical timm vit_tiny_patch16_224 shape
+  # (example 07 / train_vit / data/vit_smoke).
+  def self.tiny: () -> ViTTinyConfig
+end
+
+# ============================================================================
+# KV-cache decode engine (lib/toy/llm/engine/llama_kv_engine.rb) —
+# top-level classes ("LlamaKvEngine" is the FILE name; the classes keep
+# their historical names). Heavily ptr-typed; only the scalar config /
+# flag surface and the ptr-free methods are declared.
+# ============================================================================
+class SmolLM2KVFFICache
+  attr_accessor max_T:      Integer
+  attr_accessor d_model:    Integer
+  attr_accessor d_ff:       Integer
+  attr_accessor n_heads:    Integer
+  attr_accessor n_kv:       Integer
+  attr_accessor d_head:     Integer
+  attr_accessor group_size: Integer
+  attr_accessor n_layers:   Integer
+  attr_accessor vocab_size: Integer
+  attr_accessor rope_base:  Float
+  attr_accessor rms_eps:    Float
+  attr_accessor realized:   bool
+
+  def initialize: () -> void
+  def enable_kv_q8!: () -> bool
+  def enable_flash_attn!: () -> bool
+  def enable_moe!: (Integer n_experts, Integer n_experts_used) -> Integer
+  def enable_lora_q!: (Integer r) -> Integer
+  def enable_lora_q_adamw!: () -> bool
+  def set_weight_type: (Integer t) -> Integer
+  def upload_lora_q_init!: (Integer seed, Float init_scale) -> void
+  # realize_for_mmap / realize_and_load_auto / build_decode_step /
+  # load_weights / read_persistent_mat traffic in FFI ptrs — omitted.
+  def realize_for: (Integer max_T, Integer d_model, Integer d_ff,
+                    Integer n_heads, Integer n_kv, Integer n_layers,
+                    Integer vocab_size, Float rope_base, Float rms_eps,
+                    bool untied, bool qkv_bias) -> bool
+end
+
+module SmolLM2KV
+  # decode_step returns the [1, vocab] logits Mat for one token.
+  def self.upload_from: (SmolLM2KVFFICache kv_cache, Toy::SmolLM2 model) -> void
+  def self.decode_step: (SmolLM2KVFFICache kv_cache, Integer token_id,
+                         Integer pos) -> Mat
+end
+
+# ============================================================================
+# GGUFLoad (lib/toy/io/loaders/toy_smollm2_loader.rb, lib/toy/io/gguf_load.rb)
+# — capability flags + path-level loaders (ptr-free subset).
+# ============================================================================
+module GGUFLoad
+  # SmolLM2Flags#initialize takes optional positional args (out of the
+  # RBS subset — would be dropped wholesale), so only the ivars are
+  # seeded. These pins matter: flags readers feed RecipeOptions /
+  # engine realize params, and a poly flag value silently shifts
+  # training numerics (see lib/toy/llm/recipe_options.rb's warning).
+  class SmolLM2Flags
+    attr_accessor untied:         bool
+    attr_accessor qkv_bias:       bool
+    attr_accessor qk_norm:        bool
+    attr_accessor swa_window:     Integer
+    attr_accessor is_moe:         bool
+    attr_accessor n_experts:      Integer
+    attr_accessor n_experts_used: Integer
+    attr_accessor qk_norm_kind:   Integer
+    attr_accessor has_post_norms: bool
+    attr_accessor embed_scale:    Float
+    attr_accessor attn_softcap:   Float
+    attr_accessor final_softcap:  Float
+    attr_accessor swa_alternates: bool
+  end
+
+  def self.detect_smollm2_flags: (String path) -> GGUFLoad::SmolLM2Flags
+  def self.detect_weight_type: (String path) -> Integer
+end
+
+# ============================================================================
+# Training I/O + LR schedule (toy#73 item 2) — folded into the compute
+# entries; top-level modules, ptr-free.
+# ============================================================================
+# ---- ToyLR (lib/toy/train/toy_lr_schedule.rb) ------------------------------
+module ToyLR
+  def self.cosine: (Integer step, Integer n_steps, Float lr_max,
+                    Float lr_min, Integer warmup_steps) -> Float
+  def self.constant: (Integer step, Float lr) -> Float
+end
+
+# ---- ToyCorpusLoader (lib/toy/io/toy_corpus_loader.rb) ---------------------
+module ToyCorpusLoader
+  def self.read_seq: (String path, Integer byte_offset,
+                      Integer n_tokens) -> Array[Integer]
+end
+
+# ---- ToyImageLoader (lib/toy/io/toy_image_loader.rb) -----------------------
+module ToyImageLoader
+  def self.read_image: (String images_path, Integer image_idx,
+                        Integer record_floats) -> Array[Float]
+  def self.read_label: (String labels_path, Integer image_idx) -> Integer
+end

data/spinel-ext.json

@@ -0,0 +1,122 @@
+[
+  {
+    "name": "ggml",
+    "build": {
+      "tool": "cmake",
+      "dir": "vendor/ggml",
+      "patches": ["vendor-patches/*.patch"],
+      "args": ["-DBUILD_SHARED_LIBS=OFF", "-DGGML_STATIC=ON",
+               "-DGGML_CUDA=OFF", "-DGGML_METAL=OFF", "-DGGML_VULKAN=OFF",
+               "-DGGML_OPENCL=OFF", "-DGGML_BLAS=OFF", "-DGGML_OPENMP=OFF",
+               "-DGGML_ACCELERATE=OFF", "-DGGML_BUILD_EXAMPLES=OFF",
+               "-DGGML_BUILD_TESTS=OFF", "-DCMAKE_BUILD_TYPE=Release",
+               "-DCMAKE_POSITION_INDEPENDENT_CODE=ON"],
+      "artifacts": ["build/src/libggml.a",
+                    "build/src/libggml-base.a",
+                    "build/src/libggml-cpu.a"]
+    }
+  },
+  {
+    "name": "tinynn",
+    "build": { "tool": "make", "dir": "tinynn", "artifacts": ["libtinynn_ggml.a"] },
+    "placeholder": "-L. -Ltinynn -Lvendor/ggml/build/src -Wno-int-conversion",
+    "link": ["-L{dir}", "-L{dir:ggml}/build/src", "-Wno-int-conversion"]
+  },
+  {
+    "_comment": [
+      "OPT-IN GPU build-units (toy#45 Phase 3, merged here per toy#70 once",
+      "spinelgems#20 landed: `default: disabled` + --with-ext NAME /",
+      "SPINEL_EXT_ENABLE=...; cmake `build_dir` variants + copy-once shared",
+      "source dirs). A plain `vendor` substitutes `disabled_cflags` and never",
+      "attempts these builds. Enable: --with-ext cuda --with-ext cuda-shim",
+      "(CUDA) / --with-ext metal --with-ext metal-shim (macOS).",
+      "disabled_cflags DECISION (toy#70): the literal dev line itself — a",
+      "non-GPU vendor leaves the vendored ffi_cflags line byte-identical to",
+      "the dev tree (greppable, and still usable with hand-built archives);",
+      "the vendored GPU runner is unusable without the unit either way.",
+      "CUDA entries: re-validated end-to-end through `vendor --with-ext` on",
+      "gx10 (GB10 sm_121, CUDA 13.0) — see toy#70.",
+      "Metal entries: STRUCTURAL ONLY, Mac-validation-pending (toy#27);",
+      "artifact paths mirror the CUDA unit's layout symmetrically and the",
+      "root Makefile's build-metal configure; they fail loud on drift.",
+      "CMAKE_CUDA_ARCHITECTURES=121 mirrors the dev Makefile's GGML_CUDA_ARCH",
+      "default (GB10); other GPUs override via the SPINEL_EXT_<PLACEHOLDER>",
+      "full-replacement escape hatch. CMAKE_CUDA_COMPILER is pinned because",
+      "build-units run with the consumer's bare env — no PATH prepend like",
+      "the dev Makefile; /usr/local/cuda is the toolkit's default symlink."
+    ]
+  },
+  {
+    "name": "cuda",
+    "optional": true,
+    "default": "disabled",
+    "build": {
+      "tool": "cmake",
+      "dir": "vendor/ggml",
+      "build_dir": "build-cuda",
+      "patches": ["vendor-patches/*.patch"],
+      "args": ["-DBUILD_SHARED_LIBS=OFF", "-DGGML_STATIC=ON",
+               "-DGGML_CUDA=ON", "-DGGML_METAL=OFF", "-DGGML_VULKAN=OFF",
+               "-DGGML_OPENCL=OFF", "-DGGML_BLAS=OFF", "-DGGML_OPENMP=OFF",
+               "-DGGML_ACCELERATE=OFF", "-DGGML_BUILD_EXAMPLES=OFF",
+               "-DGGML_BUILD_TESTS=OFF", "-DCMAKE_BUILD_TYPE=Release",
+               "-DCMAKE_POSITION_INDEPENDENT_CODE=ON",
+               "-DCMAKE_CUDA_ARCHITECTURES=121", "-DGGML_NATIVE=OFF",
+               "-DCMAKE_CUDA_COMPILER=/usr/local/cuda/bin/nvcc"],
+      "artifacts": ["build-cuda/src/libggml.a",
+                    "build-cuda/src/libggml-base.a",
+                    "build-cuda/src/libggml-cpu.a",
+                    "build-cuda/src/ggml-cuda/libggml-cuda.a"]
+    }
+  },
+  {
+    "name": "cuda-shim",
+    "optional": true,
+    "default": "disabled",
+    "build": { "tool": "make", "dir": "tinynn", "targets": ["cuda"],
+               "artifacts": ["libtinynn_ggml_cuda.a"] },
+    "placeholder": "-L. -Ltinynn -Lvendor/ggml/build-cuda/src -Lvendor/ggml/build-cuda/src/ggml-cuda -L/usr/local/cuda/lib64 -Wno-int-conversion",
+    "disabled_cflags": "-L. -Ltinynn -Lvendor/ggml/build-cuda/src -Lvendor/ggml/build-cuda/src/ggml-cuda -L/usr/local/cuda/lib64 -Wno-int-conversion",
+    "link": ["-L{dir}", "-L{dir:cuda}/build-cuda/src",
+             "-L{dir:cuda}/build-cuda/src/ggml-cuda",
+             "-L/usr/local/cuda/lib64", "-Wno-int-conversion"]
+  },
+  {
+    "name": "metal",
+    "optional": true,
+    "default": "disabled",
+    "build": {
+      "tool": "cmake",
+      "dir": "vendor/ggml",
+      "build_dir": "build-metal",
+      "patches": ["vendor-patches/*.patch"],
+      "args": ["-DBUILD_SHARED_LIBS=OFF", "-DGGML_STATIC=ON",
+               "-DGGML_CUDA=OFF", "-DGGML_METAL=ON",
+               "-DGGML_METAL_EMBED_LIBRARY=ON",
+               "-DGGML_VULKAN=OFF", "-DGGML_OPENCL=OFF", "-DGGML_BLAS=OFF",
+               "-DGGML_OPENMP=OFF", "-DGGML_ACCELERATE=OFF",
+               "-DGGML_BUILD_EXAMPLES=OFF", "-DGGML_BUILD_TESTS=OFF",
+               "-DCMAKE_BUILD_TYPE=Release",
+               "-DCMAKE_POSITION_INDEPENDENT_CODE=ON"],
+      "artifacts": ["build-metal/src/libggml.a",
+                    "build-metal/src/libggml-base.a",
+                    "build-metal/src/libggml-cpu.a",
+                    "build-metal/src/ggml-metal/libggml-metal.a"]
+    }
+  },
+  {
+    "name": "metal-shim",
+    "optional": true,
+    "default": "disabled",
+    "build": { "tool": "make", "dir": "tinynn", "targets": ["metal"],
+               "artifacts": ["libtinynn_ggml_metal.a"] },
+    "placeholder": "-L. -Ltinynn -Lvendor/ggml/build-metal/src -Lvendor/ggml/build-metal/src/ggml-cpu -Lvendor/ggml/build-metal/src/ggml-metal -Wno-int-conversion -framework Foundation -framework Metal -framework MetalKit",
+    "disabled_cflags": "-L. -Ltinynn -Lvendor/ggml/build-metal/src -Lvendor/ggml/build-metal/src/ggml-cpu -Lvendor/ggml/build-metal/src/ggml-metal -Wno-int-conversion -framework Foundation -framework Metal -framework MetalKit",
+    "link": ["-L{dir}", "-L{dir:metal}/build-metal/src",
+             "-L{dir:metal}/build-metal/src/ggml-cpu",
+             "-L{dir:metal}/build-metal/src/ggml-metal",
+             "-Wno-int-conversion",
+             "-framework", "Foundation", "-framework", "Metal",
+             "-framework", "MetalKit"]
+  }
+]

data/tinynn/Makefile

@@ -0,0 +1,71 @@
+# Standalone build for the tinynn shim archive — consumed by spinel-ext.json's
+# "tinynn" build-unit (toy#45): `make -C tinynn` inside a consumer's vendor
+# tree, where ../vendor/ggml is the vendored (patched) ggml. The root Makefile
+# keeps its own copies of these rules for the dev flow; keep both in sync.
+CC       ?= cc
+CFLAGS   ?= -O2 -fPIC -Wall -Wextra
+GGML_INC := -I../vendor/ggml/include -I../vendor/ggml/src
+CUDA_DIR ?= /usr/local/cuda
+
+OBJS := tinynn_ggml.o tinynn_gguf.o tinynn_trace.o tinynn_events.o
+
+libtinynn_ggml.a: $(OBJS)
+	ar rcs $@ $(OBJS)
+
+# toy#71 Stage B — the CRuby-oracle shared object (MRI dlopens it via
+# Fiddle; see lib/toy/mri.rb). Self-contained: tinynn objects + the static
+# CPU ggml archives, -Wl,-Bsymbolic for the aarch64 vtable relocations,
+# --whole-archive so the backend registry survives, -lm trailing. Linux/
+# CPU only this stage (macOS dylib + CUDA/Metal variants are follow-ups).
+# Mirrors the root Makefile's libtinynn_shared rule — keep both in sync.
+shared: libtinynn_ggml_shared.so
+.PHONY: shared
+
+libtinynn_ggml_shared.so: $(OBJS)
+	$(CC) -shared -Wl,-Bsymbolic -o $@ $(OBJS) \
+	  -L../vendor/ggml/build/src \
+	  -Wl,--whole-archive -lggml -lggml-cpu -lggml-base -Wl,--no-whole-archive \
+	  -lstdc++ -lpthread -lm
+
+# Optional backend shims (toy#45 Phase 3). NOT in the default target —
+# they are separate build-unit targets ("targets": ["cuda"] / ["metal"]
+# in spinel-ext.json's default-disabled cuda-shim / metal-shim entries),
+# opt-in per spinelgems#20 (`vendor --with-ext NAME` / SPINEL_EXT_ENABLE).
+cuda: libtinynn_ggml_cuda.a
+.PHONY: cuda
+
+libtinynn_ggml_cuda.a: tinynn_backend_cuda.o
+	ar rcs $@ $<
+
+tinynn_backend_cuda.o: tinynn_backend_cuda.c
+	$(CC) $(CFLAGS) $(GGML_INC) -I$(CUDA_DIR)/include -c $< -o $@
+
+# Metal (macOS-only; Mac-validation-pending — toy#27). Mirrors the root
+# Makefile's rule: ObjC compile, no ARC objects, frameworks come in at
+# the consumer's link line.
+metal: libtinynn_ggml_metal.a
+.PHONY: metal
+
+libtinynn_ggml_metal.a: tinynn_backend_metal.o
+	ar rcs $@ $<
+
+tinynn_backend_metal.o: tinynn_backend_metal.m
+	$(CC) $(CFLAGS) -x objective-c $(GGML_INC) -c $< -o $@
+
+tinynn_ggml.o: tinynn_ggml.c tinynn_ggml.h tinynn_trace.h
+	$(CC) $(CFLAGS) $(GGML_INC) -c $< -o $@
+
+tinynn_gguf.o: tinynn_gguf.c tinynn_gguf.h
+	$(CC) $(CFLAGS) $(GGML_INC) -c $< -o $@
+
+tinynn_trace.o: tinynn_trace.c tinynn_trace.h
+	$(CC) $(CFLAGS) -c $< -o $@
+
+tinynn_events.o: tinynn_events.c tinynn_events.h
+	$(CC) $(CFLAGS) -c $< -o $@
+
+clean:
+	rm -f $(OBJS) libtinynn_ggml.a \
+	      tinynn_backend_cuda.o libtinynn_ggml_cuda.a \
+	      tinynn_backend_metal.o libtinynn_ggml_metal.a
+.PHONY: clean