@clutor/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sagar Pinninti
+
+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.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @clutor/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `clutor` command and local server.
+
+```bash
+npm install -g @clutor/cli
+clutor plan deepseek-v3 --ram 16     # will it fit, and how fast could it possibly go
+clutor plan ./my-model.gguf          # exact figures from a real file
+clutor serve                         # OpenAI- and Ollama-compatible API on 127.0.0.1:4320, agent, MCP
+clutor code "fix the failing test" --verify "npm test"
+```
+
+Run `clutor --help`. Documentation: <https://github.com/isagarpinninti/clutor/blob/main/docs/GUIDE.md>.
+
+It does not run models itself; it supervises [llama.cpp](https://github.com/ggml-org/llama.cpp)'s `llama-server` or talks to any OpenAI-compatible server.

package/c/Makefile

@@ -0,0 +1,53 @@
+# Builds the Clutor engine. Needs only a C11 compiler and pthreads.
+CC ?= cc
+CFLAGS ?= -O2 -g -std=c11 -Wall -Wextra -Wpedantic -Wno-unused-parameter
+ifeq ($(shell uname -m),arm64)
+  CFLAGS += -mcpu=native
+endif
+ifeq ($(shell uname -m),x86_64)
+  CFLAGS += -mavx2
+endif
+LDLIBS = -lm -lpthread
+# BUILD can point somewhere writable when the source sits in a read-only installed package: make BUILD=$HOME/.clutor/bin
+BUILD ?= build
+SRC = src/gguf.c src/cache.c src/route.c src/kernel.c src/stream.c
+BIN = $(BUILD)/clutor-engine
+
+all: $(BIN)
+build:
+	mkdir -p build
+$(BIN): $(SRC) src/main.c $(wildcard src/*.h)
+	mkdir -p $(BUILD)
+	$(CC) $(CFLAGS) $(SRC) src/main.c -o $@ $(LDLIBS)
+build/test_engine: build $(SRC) test/test_engine.c $(wildcard src/*.h)
+	$(CC) $(CFLAGS) -Isrc $(SRC) test/test_engine.c -o $@ $(LDLIBS)
+FIXTURE = ../packages/core/test/fixtures/stories260K.gguf
+test: build/test_engine
+	./build/test_engine $(FIXTURE)
+
+# The kernel has one source and several compile-time paths. `make test` runs the one this machine picks; this builds and runs the others:
+# portable C (everywhere), NEON without the dot-product instruction (arm64), and AVX2 cross-built for x86_64 and run through Rosetta if it can.
+TEST_SRC = $(SRC) test/test_engine.c
+PATH_FLAGS = -O2 -g -std=c11 -Wall -Wextra -Wpedantic -Wno-unused-parameter -Isrc
+test-paths: build
+	$(CC) $(PATH_FLAGS) -DCL_FORCE_SCALAR $(TEST_SRC) -o build/test-scalar $(LDLIBS)
+	./build/test-scalar $(FIXTURE)
+ifeq ($(shell uname -m),arm64)
+	$(CC) $(PATH_FLAGS) -mcpu=native -DCL_NO_DOTPROD $(TEST_SRC) -o build/test-neon $(LDLIBS)
+	./build/test-neon $(FIXTURE)
+endif
+test-avx2: build
+	$(CC) -arch x86_64 $(PATH_FLAGS) -mavx2 $(TEST_SRC) -o build/test-avx2 $(LDLIBS)
+	arch -x86_64 ./build/test-avx2 $(FIXTURE)
+
+# Address + undefined-behaviour sanitizers on the unit tests and a threaded streaming run, then the thread sanitizer on the same run.
+SAN_RUN = stream $(SMALL) --tokens 60 --cache-mb 1 --stage 1 --io-threads 3 --smart 1,8,1 --policy adaptive
+sanitize: build
+	$(CC) -O1 -g -std=c11 -fsanitize=address,undefined -fno-omit-frame-pointer -Isrc $(SRC) test/test_engine.c -o build/test-asan $(LDLIBS)
+	./build/test-asan $(FIXTURE)
+	$(CC) -O1 -g -std=c11 -fsanitize=address,undefined -fno-omit-frame-pointer $(SRC) src/main.c -o build/engine-asan $(LDLIBS)
+	$(CC) -O1 -g -std=c11 -fsanitize=thread $(SRC) src/main.c -o build/engine-tsan $(LDLIBS)
+	@if [ -n "$(SMALL)" ]; then ./build/engine-asan $(SAN_RUN) >/dev/null && ./build/engine-tsan $(SAN_RUN) >/dev/null && echo "sanitizers clean on $(SMALL)"; else echo "(set SMALL=<moe.gguf> to also run the streaming engine under the sanitizers)"; fi
+clean:
+	rm -rf build
+.PHONY: all test test-paths test-avx2 sanitize clean

package/c/src/cache.c

@@ -0,0 +1,232 @@
+#include "cache.h"
+#include <stdlib.h>
+#include <string.h>
+
+#ifndef CL_DEFAULT_WINDOW_PCT
+#define CL_DEFAULT_WINDOW_PCT 1
+#endif
+typedef struct { int prev, next; uint32_t key; int list; int pin; } slot_t;
+typedef struct { int head, tail; uint32_t n; } dlist_t;
+
+struct cl_cache {
+  cl_policy policy;
+  uint32_t cache_cap, stage_cap, total, universe, win_cap, main_cap, prot_cap;
+  slot_t *s;
+  int *where;
+  dlist_t lists[5];
+  int free_head;
+  uint32_t free_n;
+  /* 4-bit count-min sketch: 4 rows, packed two counters per byte. */
+  uint8_t *cms;
+  uint32_t cms_mask;
+  uint64_t additions, sample;
+  /* adaptive window: compare hit rate across periods and keep moving the window the way that helped */
+  uint64_t hc_period, hc_acc, hc_hit;
+  double hc_prev;
+  int hc_dir;
+  cl_cache_stats st;
+};
+
+static uint64_t mix(uint64_t x) { x += 0x9e3779b97f4a7c15ull; x = (x ^ (x >> 30)) * 0xbf58476d1ce4e5b9ull; x = (x ^ (x >> 27)) * 0x94d049bb133111ebull; return x ^ (x >> 31); }
+static uint32_t cms_idx(const cl_cache *c, uint32_t key, int row) { return (uint32_t)(mix(((uint64_t)key << 3) ^ (uint64_t)(row + 1) * 0x2545f4914f6cdd1dull)) & c->cms_mask; }
+static uint32_t cms_get(const cl_cache *c, uint32_t i, int row) { uint8_t b = c->cms[(size_t)row * (c->cms_mask + 1) / 2 + i / 2]; return (i & 1) ? b >> 4 : b & 15; }
+static void cms_set(cl_cache *c, uint32_t i, int row, uint32_t v) {
+  uint8_t *p = &c->cms[(size_t)row * (c->cms_mask + 1) / 2 + i / 2];
+  *p = (i & 1) ? (uint8_t)((*p & 0x0f) | (v << 4)) : (uint8_t)((*p & 0xf0) | v);
+}
+uint32_t cl_cache_freq(const cl_cache *c, uint32_t key) {
+  uint32_t m = 15;
+  for (int r = 0; r < 4; r++) { uint32_t v = cms_get(c, cms_idx(c, key, r), r); if (v < m) m = v; }
+  return m;
+}
+static void cms_add(cl_cache *c, uint32_t key) {
+  uint32_t idx[4], cur[4], m = 15;
+  for (int r = 0; r < 4; r++) { idx[r] = cms_idx(c, key, r); cur[r] = cms_get(c, idx[r], r); if (cur[r] < m) m = cur[r]; }
+  if (m < 15) for (int r = 0; r < 4; r++) if (cur[r] == m) cms_set(c, idx[r], r, m + 1); /* conservative update */
+  if (++c->additions >= c->sample) { /* aging: halve every counter so old popularity fades */
+    size_t bytes = (size_t)4 * (c->cms_mask + 1) / 2;
+    for (size_t i = 0; i < bytes; i++) c->cms[i] = (uint8_t)((c->cms[i] >> 1) & 0x77);
+    c->additions = 0;
+    c->st.aging_resets++;
+  }
+}
+
+static void unlink_slot(cl_cache *c, int i) {
+  slot_t *s = &c->s[i];
+  dlist_t *l = &c->lists[s->list];
+  if (s->prev >= 0) c->s[s->prev].next = s->next; else l->head = s->next;
+  if (s->next >= 0) c->s[s->next].prev = s->prev; else l->tail = s->prev;
+  l->n--;
+  s->prev = s->next = -1;
+}
+static void push_front(cl_cache *c, int i, int list) {
+  slot_t *s = &c->s[i];
+  dlist_t *l = &c->lists[list];
+  s->list = list; s->prev = -1; s->next = l->head;
+  if (l->head >= 0) c->s[l->head].prev = i; else l->tail = i;
+  l->head = i;
+  l->n++;
+}
+static int tail_unpinned(const cl_cache *c, int list, int skip) {
+  for (int i = c->lists[list].tail; i >= 0; i = c->s[i].prev) if (!c->s[i].pin && i != skip) return i;
+  return -1;
+}
+static void release(cl_cache *c, int i) {
+  slot_t *s = &c->s[i];
+  if (s->list != CL_FREE) unlink_slot(c, i);
+  if (s->key != UINT32_MAX) c->where[s->key] = -1;
+  s->key = UINT32_MAX; s->pin = 0;
+  push_front(c, i, CL_FREE);
+}
+
+cl_cache *cl_cache_new(uint32_t cache_slots, uint32_t stage_slots, uint32_t universe, cl_policy policy, uint32_t window_pct) {
+  if (cache_slots == 0 || universe == 0) return NULL;
+  cl_cache *c = calloc(1, sizeof *c);
+  if (!c) return NULL;
+  c->policy = policy; c->cache_cap = cache_slots; c->stage_cap = stage_slots; c->universe = universe;
+  c->total = cache_slots + stage_slots + 1; /* one spare so an insert can precede the eviction it causes */
+  if (policy == CL_ADAPTIVE) { c->hc_period = (uint64_t)cache_slots * 8 > 500 ? (uint64_t)cache_slots * 8 : 500; c->hc_dir = 1; c->hc_prev = -1; if (!window_pct) window_pct = 10; }
+  if (policy == CL_LRU) { c->win_cap = cache_slots; c->main_cap = 0; }
+  else { if (!window_pct || window_pct > 90) window_pct = CL_DEFAULT_WINDOW_PCT;
+    c->win_cap = cache_slots * window_pct / 100 ? cache_slots * window_pct / 100 : 1; if (c->win_cap >= cache_slots) c->win_cap = cache_slots > 1 ? cache_slots - 1 : 1; c->main_cap = cache_slots - c->win_cap; }
+  c->prot_cap = c->main_cap * 4 / 5;
+  c->s = calloc(c->total, sizeof(slot_t));
+  c->where = malloc((size_t)universe * sizeof(int));
+  uint32_t w = 256;
+  while (w < universe * 4) w <<= 1;
+  c->cms_mask = w - 1;
+  c->cms = calloc((size_t)4 * w / 2, 1);
+  c->sample = (uint64_t)cache_slots * 10 > 1000 ? (uint64_t)cache_slots * 10 : 1000;
+  if (!c->s || !c->where || !c->cms) { cl_cache_free(c); return NULL; }
+  for (uint32_t k = 0; k < universe; k++) c->where[k] = -1;
+  for (int l = 0; l < 5; l++) c->lists[l].head = c->lists[l].tail = -1;
+  for (uint32_t i = 0; i < c->total; i++) { c->s[i].key = UINT32_MAX; c->s[i].prev = c->s[i].next = -1; push_front(c, (int)i, CL_FREE); }
+  return c;
+}
+void cl_cache_free(cl_cache *c) { if (!c) return; free(c->s); free(c->where); free(c->cms); free(c); }
+uint32_t cl_cache_total_slots(const cl_cache *c) { return c->total; }
+uint64_t cl_cache_meta_bytes(const cl_cache *c) { return sizeof *c + (uint64_t)c->total * sizeof(slot_t) + (uint64_t)c->universe * sizeof(int) + (uint64_t)4 * (c->cms_mask + 1) / 2; }
+int cl_cache_find(const cl_cache *c, uint32_t key) { return key < c->universe ? c->where[key] : -1; }
+cl_list cl_cache_list(const cl_cache *c, int slot) { return (cl_list)c->s[slot].list; }
+uint32_t cl_cache_slot_key(const cl_cache *c, int slot) { return c->s[slot].key; }
+cl_cache_stats cl_cache_get_stats(const cl_cache *c) { cl_cache_stats s = c->st; s.window_slots = c->win_cap; return s; }
+uint32_t cl_cache_count(const cl_cache *c) { return c->lists[CL_WINDOW].n + c->lists[CL_PROBATION].n + c->lists[CL_PROTECTED].n; }
+void cl_cache_pin(cl_cache *c, int slot) { c->s[slot].pin++; }
+void cl_cache_unpin(cl_cache *c, int slot) { if (c->s[slot].pin > 0) c->s[slot].pin--; }
+void cl_cache_abandon(cl_cache *c, int slot) { release(c, slot); }
+
+/* Brings the cache back to capacity after an insert. Returns 0 if everything evictable is pinned. */
+static int make_room(cl_cache *c, int keep) {
+  while (cl_cache_count(c) > c->cache_cap) {
+    if (c->policy == CL_LRU) {
+      int v = tail_unpinned(c, CL_WINDOW, keep);
+      if (v < 0) return 0;
+      c->st.evictions++; release(c, v);
+      continue;
+    }
+    if (c->lists[CL_WINDOW].n > c->win_cap) {
+      int cand = tail_unpinned(c, CL_WINDOW, keep);
+      if (cand >= 0) {
+        unlink_slot(c, cand); push_front(c, cand, CL_PROBATION);
+        if (c->lists[CL_PROBATION].n + c->lists[CL_PROTECTED].n > c->main_cap) {
+          int victim = tail_unpinned(c, CL_PROBATION, -1);
+          if (victim < 0) victim = cand;
+          int loser = (victim != cand && cl_cache_freq(c, c->s[cand].key) >= cl_cache_freq(c, c->s[victim].key)) ? victim : cand;
+          if (loser == cand) c->st.admit_rejects++;
+          c->st.evictions++; release(c, loser);
+        }
+        continue;
+      }
+    }
+    int v = tail_unpinned(c, CL_PROBATION, keep);
+    if (v < 0) v = tail_unpinned(c, CL_PROTECTED, keep);
+    if (v < 0) v = tail_unpinned(c, CL_WINDOW, keep);
+    if (v < 0) return 0;
+    c->st.evictions++; release(c, v);
+  }
+  return 1;
+}
+
+static void touch(cl_cache *c, int i) {
+  switch (c->s[i].list) {
+    case CL_WINDOW: unlink_slot(c, i); push_front(c, i, CL_WINDOW); break;
+    case CL_PROTECTED: unlink_slot(c, i); push_front(c, i, CL_PROTECTED); break;
+    case CL_PROBATION:
+      if (c->policy == CL_LRU) break;
+      unlink_slot(c, i); push_front(c, i, CL_PROTECTED);
+      while (c->lists[CL_PROTECTED].n > c->prot_cap) {
+        int d = tail_unpinned(c, CL_PROTECTED, i);
+        if (d < 0) break;
+        unlink_slot(c, d); push_front(c, d, CL_PROBATION);
+      }
+      break;
+    default: break;
+  }
+}
+
+static void set_window(cl_cache *c, uint32_t w) {
+  uint32_t lo = 1, hi = c->cache_cap > 1 ? c->cache_cap - 1 : 1;
+  if (w < lo) w = lo;
+  if (w > hi) w = hi;
+  c->win_cap = w; c->main_cap = c->cache_cap - w; c->prot_cap = c->main_cap * 4 / 5;
+}
+static void hill_climb(cl_cache *c, int hit) {
+  c->hc_acc++; c->hc_hit += (uint64_t)hit;
+  if (c->hc_acc < c->hc_period) return;
+  double rate = (double)c->hc_hit / (double)c->hc_acc;
+  if (c->hc_prev >= 0) {
+    if (rate < c->hc_prev - 0.002) c->hc_dir = -c->hc_dir; /* it got worse: turn around */
+    uint32_t step = c->cache_cap / 20 ? c->cache_cap / 20 : 1;
+    set_window(c, c->hc_dir > 0 ? c->win_cap + step : (c->win_cap > step ? c->win_cap - step : 1));
+  }
+  c->hc_prev = rate; c->hc_acc = c->hc_hit = 0;
+}
+static int take_free(cl_cache *c) {
+  int i = c->lists[CL_FREE].head;
+  if (i >= 0) unlink_slot(c, i);
+  return i;
+}
+
+int cl_cache_access(cl_cache *c, uint32_t key, int *slot) {
+  *slot = -1;
+  if (key >= c->universe) return -1;
+  cms_add(c, key);
+  int i = c->where[key];
+  if (i >= 0 && c->s[i].list == CL_STAGE) {
+    /* A prefetched expert was wanted: it joins the cache. */
+    c->st.stage_hits++;
+    if (c->policy == CL_ADAPTIVE) hill_climb(c, 1);
+    unlink_slot(c, i); push_front(c, i, CL_WINDOW);
+    c->s[i].pin++;
+    make_room(c, i);
+    *slot = i;
+    return 2;
+  }
+  if (i >= 0) { c->st.hits++; if (c->policy == CL_ADAPTIVE) hill_climb(c, 1); touch(c, i); c->s[i].pin++; *slot = i; return 1; }
+  c->st.misses++;
+  if (c->policy == CL_ADAPTIVE) hill_climb(c, 0);
+  int n = take_free(c);
+  if (n < 0) return -1;
+  c->s[n].key = key; c->s[n].pin = 1; c->where[key] = n;
+  push_front(c, n, CL_WINDOW);
+  c->st.inserts++;
+  if (!make_room(c, n)) { /* everything else is pinned: do not keep the over-capacity entry */ release(c, n); return -1; }
+  *slot = n;
+  return 0;
+}
+
+int cl_cache_stage(cl_cache *c, uint32_t key) {
+  if (key >= c->universe || c->where[key] >= 0 || c->stage_cap == 0) return -1;
+  if (c->lists[CL_STAGE].n >= c->stage_cap) {
+    int old = tail_unpinned(c, CL_STAGE, -1);
+    if (old < 0) return -1;
+    c->st.stage_wasted++;
+    release(c, old);
+  }
+  int n = take_free(c);
+  if (n < 0) return -1;
+  c->s[n].key = key; c->s[n].pin = 1; c->where[key] = n;
+  push_front(c, n, CL_STAGE);
+  c->st.stage_inserts++;
+  return n;
+}

package/c/src/cache.h

@@ -0,0 +1,48 @@
+/*
+ * Expert cache policy: decides WHICH expert occupies WHICH slot. It holds no data and takes no locks; the caller owns the buffers and
+ * serialises access. Two policies: plain LRU, and W-TinyLFU (a small admission window, then a segmented LRU whose admission is gated
+ * by a 4-bit count-min sketch of how often each expert has been wanted). A separate staging area (the "Buffer B" of the design) holds
+ * prefetched experts that are not yet wanted, so a prefetch can never evict something the policy chose to keep.
+ */
+#ifndef CL_CACHE_H
+#define CL_CACHE_H
+#include <stdint.h>
+
+typedef enum { CL_LRU = 0, CL_WTINYLFU = 1, CL_ADAPTIVE = 2 } cl_policy;
+typedef enum { CL_FREE = 0, CL_WINDOW, CL_PROBATION, CL_PROTECTED, CL_STAGE } cl_list;
+
+typedef struct {
+  uint64_t hits, misses, stage_hits, inserts, evictions, admit_rejects, stage_inserts, stage_wasted, aging_resets;
+  uint32_t window_slots; /* current admission window size */
+} cl_cache_stats;
+
+typedef struct cl_cache cl_cache;
+
+/* `universe` is the number of distinct keys (layers x experts); keys are 0..universe-1. */
+/* `window_pct` is the share of the cache used as the admission window (0 = default). */
+cl_cache *cl_cache_new(uint32_t cache_slots, uint32_t stage_slots, uint32_t universe, cl_policy policy, uint32_t window_pct);
+void cl_cache_free(cl_cache *c);
+uint32_t cl_cache_total_slots(const cl_cache *c);
+/* Bytes this cache allocates for itself: the struct, one slot record per slot, the key-to-slot map and the Count-Min Sketch. */
+uint64_t cl_cache_meta_bytes(const cl_cache *c); /* slots the caller must provide buffers for */
+
+int cl_cache_find(const cl_cache *c, uint32_t key); /* slot holding the key (cached or staged), or -1 */
+cl_list cl_cache_list(const cl_cache *c, int slot);
+uint32_t cl_cache_slot_key(const cl_cache *c, int slot);
+
+/* A demand access. Records the access in the frequency sketch. Result:
+ *  1 hit in the cache (slot returned, recency updated)   2 hit in staging (slot adopted into the cache)
+ *  0 miss: a slot was assigned and pinned; the caller must fill it   -1 miss and nothing could be evicted: bypass the cache */
+int cl_cache_access(cl_cache *c, uint32_t key, int *slot);
+/* A prefetch: assign a staging slot for `key` (pinned until `cl_cache_unpin`). Returns the slot, or -1 if already present / no room. */
+int cl_cache_stage(cl_cache *c, uint32_t key);
+
+void cl_cache_pin(cl_cache *c, int slot);
+void cl_cache_unpin(cl_cache *c, int slot);
+/* Drops a slot that was assigned but whose fill failed. */
+void cl_cache_abandon(cl_cache *c, int slot);
+
+uint32_t cl_cache_freq(const cl_cache *c, uint32_t key); /* estimated access count (0..15) */
+cl_cache_stats cl_cache_get_stats(const cl_cache *c);
+uint32_t cl_cache_count(const cl_cache *c); /* experts in the cache proper (not staging) */
+#endif

package/c/src/gguf.c

@@ -0,0 +1,242 @@
+#define _GNU_SOURCE
+#include "gguf.h"
+#include <errno.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#if defined(__BYTE_ORDER__) && __BYTE_ORDER__ != __ORDER_LITTLE_ENDIAN__
+#error "GGUF is little-endian; this reader assumes a little-endian host"
+#endif
+
+/* [elements per block, bytes per block, name], by ggml type id. Same table as the TypeScript reader. */
+static const struct { int id; uint32_t block, bytes; const char *name; } TYPES[] = {
+  {0, 1, 4, "F32"}, {1, 1, 2, "F16"}, {2, 32, 18, "Q4_0"}, {3, 32, 20, "Q4_1"}, {6, 32, 22, "Q5_0"}, {7, 32, 24, "Q5_1"}, {8, 32, 34, "Q8_0"}, {9, 32, 36, "Q8_1"},
+  {10, 256, 84, "Q2_K"}, {11, 256, 110, "Q3_K"}, {12, 256, 144, "Q4_K"}, {13, 256, 176, "Q5_K"}, {14, 256, 210, "Q6_K"}, {15, 256, 292, "Q8_K"},
+  {16, 256, 66, "IQ2_XXS"}, {17, 256, 74, "IQ2_XS"}, {18, 256, 98, "IQ3_XXS"}, {19, 256, 50, "IQ1_S"}, {20, 32, 18, "IQ4_NL"}, {21, 256, 110, "IQ3_S"},
+  {22, 256, 82, "IQ2_S"}, {23, 256, 136, "IQ4_XS"}, {24, 1, 1, "I8"}, {25, 1, 2, "I16"}, {26, 1, 4, "I32"}, {27, 1, 8, "I64"}, {28, 1, 8, "F64"},
+  {29, 256, 56, "IQ1_M"}, {30, 1, 2, "BF16"}, {34, 256, 54, "TQ1_0"}, {35, 256, 66, "TQ2_0"}, {39, 32, 17, "MXFP4"},
+};
+#define NTYPES (sizeof TYPES / sizeof TYPES[0])
+
+const char *cl_type_name(uint32_t type) {
+  for (size_t i = 0; i < NTYPES; i++) if ((uint32_t)TYPES[i].id == type) return TYPES[i].name;
+  return "unknown";
+}
+
+typedef struct { const uint8_t *p; size_t n, pos; int over, bad; } cur;
+
+static int need(cur *c, size_t k) {
+  if (c->over || c->n - c->pos < k) { c->over = 1; return 0; }
+  return 1;
+}
+static uint32_t rd32(cur *c) { uint32_t v = 0; if (need(c, 4)) { memcpy(&v, c->p + c->pos, 4); c->pos += 4; } return v; }
+static uint64_t rd64(cur *c) { uint64_t v = 0; if (need(c, 8)) { memcpy(&v, c->p + c->pos, 8); c->pos += 8; } return v; }
+
+#define MAX_STR (1u << 24)
+static void rdstr(cur *c, char *out, size_t cap) {
+  uint64_t len = rd64(c);
+  if (c->over) return;
+  if (len > MAX_STR) { c->bad = 1; return; }
+  if (!need(c, (size_t)len)) return;
+  if (out && cap) { size_t k = len < cap - 1 ? (size_t)len : cap - 1; memcpy(out, c->p + c->pos, k); out[k] = 0; }
+  c->pos += (size_t)len;
+}
+
+static size_t scalar_size(uint32_t t) {
+  switch (t) { case 0: case 1: case 7: return 1; case 2: case 3: return 2; case 4: case 5: case 6: return 4; case 10: case 11: case 12: return 8; default: return 0; }
+}
+static int is_int(uint32_t t) { return t <= 5 || t == 10 || t == 11; }
+
+static uint64_t read_int(cur *c, uint32_t t) {
+  switch (t) {
+    case 0: case 1: { if (!need(c, 1)) return 0; uint8_t v = c->p[c->pos++]; return t == 1 ? (uint64_t)(int64_t)(int8_t)v : v; }
+    case 2: case 3: { if (!need(c, 2)) return 0; uint16_t v; memcpy(&v, c->p + c->pos, 2); c->pos += 2; return t == 3 ? (uint64_t)(int64_t)(int16_t)v : v; }
+    case 4: return rd32(c);
+    case 5: return (uint64_t)(int64_t)(int32_t)rd32(c);
+    default: return rd64(c);
+  }
+}
+
+static void skip_value(cur *c, uint32_t t, int depth) {
+  if (c->over || c->bad) return;
+  if (depth > 4) { c->bad = 1; return; }
+  size_t s = scalar_size(t);
+  if (s) { if (need(c, s)) c->pos += s; return; }
+  if (t == 8) { rdstr(c, NULL, 0); return; }
+  if (t == 9) {
+    uint32_t et = rd32(c);
+    uint64_t n = rd64(c);
+    if (c->over) return;
+    if (n > (1ull << 32)) { c->bad = 1; return; }
+    size_t es = scalar_size(et);
+    if (es) {
+      if (n > (c->n - c->pos) / es + 1) { c->over = 1; return; }
+      if (!need(c, (size_t)n * es)) return;
+      c->pos += (size_t)n * es;
+      return;
+    }
+    for (uint64_t i = 0; i < n && !c->over && !c->bad; i++) skip_value(c, et, depth + 1);
+    return;
+  }
+  c->bad = 1;
+}
+
+typedef struct { char key[96]; uint64_t v; } kv_int;
+#define MAX_KV_INT 24
+
+static int tensor_nbytes(const cl_tensor *t, uint64_t *out) {
+  const uint32_t *bs = NULL;
+  uint32_t block = 0, bytes = 0;
+  (void)bs;
+  for (size_t i = 0; i < NTYPES; i++) if ((uint32_t)TYPES[i].id == t->type) { block = TYPES[i].block; bytes = TYPES[i].bytes; }
+  if (!block || t->ndims == 0) return 0;
+  if (t->dims[0] % block) return 0;
+  unsigned __int128 n = (t->dims[0] / block) * (unsigned __int128)bytes;
+  for (uint32_t i = 1; i < t->ndims; i++) { n *= t->dims[i]; if (n > ((unsigned __int128)1 << 62)) return 0; }
+  *out = (uint64_t)n;
+  return 1;
+}
+
+static int starts(const char *s, const char *p) { return strncmp(s, p, strlen(p)) == 0; }
+static int ends(const char *s, const char *suf) { size_t a = strlen(s), b = strlen(suf); return a >= b && !strcmp(s + a - b, suf); }
+
+static uint64_t find_int(const kv_int *kv, int n, const char *arch, const char *suffix) {
+  char want[160];
+  snprintf(want, sizeof want, "%s.%s", arch, suffix);
+  for (int i = 0; i < n; i++) if (!strcmp(kv[i].key, want)) return kv[i].v;
+  return 0;
+}
+
+/* 0 ok, 1 need a larger buffer, -1 bad file (message in err). */
+static int parse(cl_model *m, const uint8_t *buf, size_t n, char *err, size_t errlen) {
+  cur c = {buf, n, 0, 0, 0};
+  if (n >= 4 && memcmp(buf, "GGUF", 4)) { snprintf(err, errlen, "not a GGUF file (bad magic)"); return -1; }
+  c.pos = 4;
+  m->version = rd32(&c);
+  uint64_t nt = rd64(&c), nkv = rd64(&c);
+  if (c.over) return 1;
+  if (m->version != 2 && m->version != 3) { snprintf(err, errlen, "unsupported GGUF version %u", m->version); return -1; }
+  if (nt > 1000000 || nkv > 1000000) { snprintf(err, errlen, "implausible tensor or metadata count"); return -1; }
+  kv_int kv[MAX_KV_INT];
+  int nk = 0;
+  uint64_t alignment = 32;
+  m->arch[0] = m->name[0] = 0;
+  for (uint64_t i = 0; i < nkv; i++) {
+    char key[160];
+    rdstr(&c, key, sizeof key);
+    uint32_t t = rd32(&c);
+    if (c.over) return 1;
+    if (c.bad) { snprintf(err, errlen, "corrupt metadata"); return -1; }
+    if (!strcmp(key, "general.architecture") && t == 8) rdstr(&c, m->arch, sizeof m->arch);
+    else if (!strcmp(key, "general.name") && t == 8) rdstr(&c, m->name, sizeof m->name);
+    else if (is_int(t) && (ends(key, ".block_count") || ends(key, ".expert_count") || ends(key, ".expert_used_count") || !strcmp(key, "general.alignment"))) {
+      uint64_t v = read_int(&c, t);
+      if (!strcmp(key, "general.alignment")) { if (v > 0 && v <= (1u << 20)) alignment = v; }
+      else if (nk < MAX_KV_INT) { snprintf(kv[nk].key, sizeof kv[nk].key, "%s", key); kv[nk++].v = v; }
+    } else skip_value(&c, t, 0);
+    if (c.over) return 1;
+    if (c.bad) { snprintf(err, errlen, "corrupt metadata value in \"%s\"", key); return -1; }
+  }
+  m->n_tensors = nt;
+  m->tensors = calloc(nt ? nt : 1, sizeof(cl_tensor));
+  if (!m->tensors) { snprintf(err, errlen, "out of memory"); return -1; }
+  uint64_t rel[1]; (void)rel;
+  uint64_t *rels = calloc(nt ? nt : 1, sizeof(uint64_t));
+  if (!rels) { snprintf(err, errlen, "out of memory"); return -1; }
+  for (uint64_t i = 0; i < nt; i++) {
+    cl_tensor *t = &m->tensors[i];
+    rdstr(&c, t->name, sizeof t->name);
+    t->ndims = rd32(&c);
+    if (c.over) { free(rels); return 1; }
+    if (t->ndims == 0 || t->ndims > 4 || c.bad) { free(rels); snprintf(err, errlen, "tensor %llu has %u dimensions", (unsigned long long)i, t->ndims); return -1; }
+    for (uint32_t d = 0; d < t->ndims; d++) t->dims[d] = rd64(&c);
+    t->type = rd32(&c);
+    rels[i] = rd64(&c);
+    if (c.over) { free(rels); return 1; }
+  }
+  m->data_offset = ((c.pos + alignment - 1) / alignment) * alignment;
+  for (uint64_t i = 0; i < nt; i++) {
+    cl_tensor *t = &m->tensors[i];
+    t->offset = m->data_offset + rels[i];
+    if (!tensor_nbytes(t, &t->nbytes)) { t->nbytes = 0; m->unsized_tensors++; continue; }
+    if (t->offset > m->file_size || t->nbytes > m->file_size - t->offset) { free(rels); snprintf(err, errlen, "tensor \"%s\" points outside the file (truncated download?)", t->name); return -1; }
+  }
+  free(rels);
+
+  m->n_layers = (uint32_t)find_int(kv, nk, m->arch, "block_count");
+  m->n_experts = (uint32_t)find_int(kv, nk, m->arch, "expert_count");
+  m->n_used = (uint32_t)find_int(kv, nk, m->arch, "expert_used_count");
+  if (m->n_layers == 0 || m->n_layers > 4096) { snprintf(err, errlen, "the file does not say how many layers it has"); return -1; }
+  m->layers = calloc(m->n_layers, sizeof(cl_layer));
+  if (!m->layers) { snprintf(err, errlen, "out of memory"); return -1; }
+  for (uint64_t i = 0; i < nt; i++) {
+    const cl_tensor *t = &m->tensors[i];
+    if (!t->nbytes) continue;
+    m->total_bytes += t->nbytes;
+    unsigned layer = 0;
+    int off = 0;
+    if (!starts(t->name, "blk.") || sscanf(t->name + 4, "%u.%n", &layer, &off) != 1 || layer >= m->n_layers) { m->resident_bytes += t->nbytes; continue; }
+    const char *rest = t->name + 4 + off;
+    cl_layer *L = &m->layers[layer];
+    if (!strcmp(rest, "ffn_gate_inp.weight")) { L->router_bytes += t->nbytes; m->resident_bytes += t->nbytes; continue; }
+    if (starts(rest, "ffn_") && ends(rest, "_exps.weight") && L->n_exp < 3 && t->ndims >= 2) {
+      uint64_t ne = t->dims[t->ndims - 1];
+      if (ne > 0 && t->nbytes % ne == 0) {
+        if (m->n_experts < ne) m->n_experts = (uint32_t)ne;
+        L->exp_off[L->n_exp] = t->offset;
+        L->exp_slab[L->n_exp] = t->nbytes / ne;
+        L->expert_bytes += t->nbytes / ne;
+        L->n_exp++;
+        continue;
+      }
+    }
+    if (starts(rest, "ffn_") && strstr(rest, "_exps")) { snprintf(err, errlen, "tensor \"%s\": this expert layout is not supported (only fused per-layer expert tensors)", t->name); return -1; }
+    L->dense = realloc(L->dense, (size_t)(L->n_dense + 1) * sizeof(cl_range));
+    if (!L->dense) { snprintf(err, errlen, "out of memory"); return -1; }
+    L->dense[L->n_dense].offset = t->offset;
+    L->dense[L->n_dense].length = t->nbytes;
+    L->n_dense++;
+    L->dense_bytes += t->nbytes;
+  }
+  for (uint32_t l = 0; l < m->n_layers; l++) {
+    if (m->layers[l].n_exp) m->moe_layers++;
+    if (m->layers[l].dense_bytes > m->max_dense_bytes) m->max_dense_bytes = m->layers[l].dense_bytes;
+    if (m->layers[l].expert_bytes > m->max_expert_bytes) m->max_expert_bytes = m->layers[l].expert_bytes;
+  }
+  return 0;
+}
+
+void cl_model_close(cl_model *m) {
+  if (m->layers) for (uint32_t l = 0; l < m->n_layers; l++) free(m->layers[l].dense);
+  free(m->layers);
+  free(m->tensors);
+  memset(m, 0, sizeof *m);
+}
+
+int cl_model_open(cl_model *m, const char *path, char *err, size_t errlen) {
+  memset(m, 0, sizeof *m);
+  int fd = open(path, O_RDONLY);
+  if (fd < 0) { snprintf(err, errlen, "cannot open %s: %s", path, strerror(errno)); return 1; }
+  struct stat st;
+  if (fstat(fd, &st) || st.st_size < 24) { close(fd); snprintf(err, errlen, "%s is too small to be a GGUF file", path); return 1; }
+  m->file_size = (uint64_t)st.st_size;
+  size_t want = m->file_size < (1u << 20) ? (size_t)m->file_size : (1u << 20);
+  for (;;) {
+    uint8_t *buf = malloc(want);
+    if (!buf) { close(fd); snprintf(err, errlen, "out of memory"); return 1; }
+    ssize_t got = pread(fd, buf, want, 0);
+    if (got < 0 || (size_t)got != want) { free(buf); close(fd); snprintf(err, errlen, "cannot read %s", path); return 1; }
+    cl_model_close(m);
+    m->file_size = (uint64_t)st.st_size;
+    int r = parse(m, buf, want, err, errlen);
+    free(buf);
+    if (r == 0) { close(fd); return 0; }
+    if (r < 0) { close(fd); cl_model_close(m); return 1; }
+    if (want >= m->file_size || want >= ((size_t)1 << 29)) { close(fd); cl_model_close(m); snprintf(err, errlen, "the header is truncated or larger than 512 MiB"); return 1; }
+    want = want * 4 > m->file_size ? (size_t)m->file_size : want * 4;
+  }
+}

package/c/src/gguf.h

@@ -0,0 +1,48 @@
+/* GGUF v2/v3 reader: header, metadata we need, tensor table, and the layout the streamer needs (where each routed expert lives). */
+#ifndef CL_GGUF_H
+#define CL_GGUF_H
+#include <stddef.h>
+#include <stdint.h>
+
+typedef struct { uint64_t offset, length; } cl_range;
+
+typedef struct {
+  char name[160];
+  uint32_t ndims;
+  uint64_t dims[4];
+  uint32_t type;
+  uint64_t offset;  /* absolute file offset of the tensor data */
+  uint64_t nbytes;  /* 0 when the type or shape is not understood */
+} cl_tensor;
+
+typedef struct {
+  cl_range *dense;      /* attention, norms, shared experts, dense feed-forward: read for every token */
+  int n_dense;
+  uint64_t dense_bytes;
+  uint64_t router_bytes;
+  /* Routed experts are fused: one tensor per gate/up/down holds every expert, experts slowest-varying, so each is one slab. */
+  int n_exp;            /* 0 for a dense layer, else 1..3 */
+  uint64_t exp_off[3];  /* file offset of expert 0 of each fused tensor */
+  uint64_t exp_slab[3]; /* bytes of ONE expert in each fused tensor */
+  uint64_t expert_bytes;/* sum of exp_slab */
+} cl_layer;
+
+typedef struct {
+  char arch[64];
+  char name[128];
+  uint32_t version;
+  uint64_t file_size, data_offset;
+  uint32_t n_layers, n_experts, n_used;
+  cl_tensor *tensors;
+  uint64_t n_tensors;
+  cl_layer *layers;
+  uint64_t resident_bytes, max_dense_bytes, max_expert_bytes, total_bytes;
+  uint32_t moe_layers;
+  uint32_t unsized_tensors;
+} cl_model;
+
+/* Returns 0 on success. On failure returns nonzero and writes a message to err. */
+int cl_model_open(cl_model *m, const char *path, char *err, size_t errlen);
+void cl_model_close(cl_model *m);
+const char *cl_type_name(uint32_t type);
+#endif