Run frontier MoE models on hardware you already own β pure C, zero deps, experts streamed from disk. Tiny engine, immense model. π¦
C
v4: pluggable expert-store backend registry
Konner89365ae6b49f
diff --git a/c/.gitignore b/c/.gitignoreindex 04f8ca9a..98497fee 100644--- a/c/.gitignore+++ b/c/.gitignore@@ -3,8 +3,12 @@ glm_tiny/olmoe_hf/olmoe_i4/.build-config+# DeepSeek-V4 amalgamation build artifacts (make -f Makefile.deepseek-v4)build/COLI_V4_UNIT_*.o+expert_store_registry.o+deepseek_v4+test_expert_store_registrytests/test_st_mirrortests/test_st_preadtools/libiq3.sodiff --git a/c/Makefile b/c/Makefileindex 798d81fc..f79794b6 100644--- a/c/Makefile+++ b/c/Makefile@@ -1068,7 +1068,8 @@ V4_OWNERSHIP_OBJS = \$(V4_OWN_DIR)/COLI_V4_UNIT_RUNTIME.o \$(V4_OWN_DIR)/COLI_V4_UNIT_CONFIG.o \$(V4_OWN_DIR)/COLI_V4_UNIT_ST.o \- $(V4_OWN_DIR)/COLI_V4_UNIT_NATIVE_QUANT.o+ $(V4_OWN_DIR)/COLI_V4_UNIT_NATIVE_QUANT.o \+ $(V4_OWN_DIR)/expert_store_registry.o$(V4_OWN_DIR):mkdir -p $(V4_OWN_DIR)@@ -1085,6 +1086,12 @@ $(V4_OWN_DIR)/COLI_V4_UNIT_ST.o: deepseek_v4.c deepseek_v4.h deepseek_v4_interna$(V4_OWN_DIR)/COLI_V4_UNIT_NATIVE_QUANT.o: deepseek_v4.c deepseek_v4.h deepseek_v4_internal.h quant.h | $(V4_OWN_DIR)$(CC) $(V4_OWN_CFLAGS) -DCOLI_V4_UNIT_NATIVE_QUANT -c deepseek_v4.c -o $@+# The engine (RUNTIME unit) opens its expert store through the pluggable+# backend registry, so any test linking RUNTIME also links the registry object+# (which defines coli_expert_store_backend_open_selected + registers "auto").+$(V4_OWN_DIR)/expert_store_registry.o: expert_store_registry.c expert_store_registry.h expert_store.h | $(V4_OWN_DIR)+ $(CC) $(V4_OWN_CFLAGS) -c expert_store_registry.c -o $@+tests/test_v4_ownership$(EXE): tests/test_v4_ownership.c $(V4_OWNERSHIP_OBJS)$(CC) $(V4_OWN_CFLAGS) $< $(V4_OWNERSHIP_OBJS) -o $@ -pthread $(LDFLAGS)diff --git a/c/Makefile.deepseek-v4 b/c/Makefile.deepseek-v4index a6a38705..47083716 100644--- a/c/Makefile.deepseek-v4+++ b/c/Makefile.deepseek-v4@@ -162,19 +162,36 @@ include Makefile.deepseek-v4.unitsTARGET_OBJS = $(addsuffix .o,$(V4_TARGET_UNITS))TEST_UNIT_OBJS = $(addsuffix .o,$(V4_TEST_UNITS))-V4_OBJS = $(TARGET_OBJS) $(V4_WIN_EXTRA_OBJS)+V4_OBJS = $(TARGET_OBJS) $(V4_WIN_EXTRA_OBJS) $(REGISTRY_OBJ)+REGISTRY_OBJ = expert_store_registry.o-.PHONY: deepseek-v4 deepseek-v4-clean deepseek-v4-test-objs+.PHONY: deepseek-v4 deepseek-v4-objs deepseek-v4-clean deepseek-v4-test-objs \+ deepseek-v4-test-registry print-v4-objsdeepseek-v4: $(V4_BINARY)+# Build just the amalgamation unit + registry objects (no link). External+# trees (e.g. a downstream integration) reuse these .o's to link an+# alternative-backend deepseek_v4 binary without recompiling the units themselves.+deepseek-v4-objs: $(V4_OBJS)++# Echo the object list (target units + registry) for external linkers that need+# to link exactly what the plain deepseek_v4 binary links, no more.+print-v4-objs:+ @echo $(V4_OBJS)+$(V4_BINARY): $(V4_OBJS)$(CC) $(V4_OBJS) -o $@ $(LDFLAGS)+# Pluggable expert-store backend registry (standalone; not a deepseek_v4.c unit).+# Linked into the binary so the engine can dispatch COLI_EXPERT_STORE backends.+$(REGISTRY_OBJ): expert_store_registry.c expert_store_registry.h expert_store.h+ $(CC) $(CFLAGS) -c expert_store_registry.c -o $@+$(TARGET_OBJS) $(TEST_UNIT_OBJS): %.o: deepseek_v4.c deepseek_v4.h \deepseek_v4_internal.h deepseek_v4_dspark.inc st.h json.h compat.h tensor.h quant.h \route_trace.h \native_quant.h native_quant_batch.h native_quant_dual.h \- native_quant_fp4_rows16.h+ native_quant_fp4_rows16.h expert_store_registry.h$(CC) $(CFLAGS) -D$* -c deepseek_v4.c -o $@# The CUDA tier loader object. Compiled only on Windows, where it is appended@@ -189,5 +206,12 @@ backend_cuda_dsv4.o: backend_cuda_dsv4.cu backend_cuda_dsv4.hdeepseek-v4-test-objs: $(TEST_UNIT_OBJS)+# Registry unit test (no engine link β stubs the auto open fn).+deepseek-v4-test-registry: test_expert_store_registry+ ./test_expert_store_registry+test_expert_store_registry: test_expert_store_registry.c expert_store_registry.c \+ expert_store_registry.h expert_store.h+ $(CC) -O2 -Wall -Wextra test_expert_store_registry.c expert_store_registry.c -o $@+deepseek-v4-clean:- rm -f $(V4_BINARY) $(V4_OBJS) $(TEST_UNIT_OBJS)+ rm -f $(V4_BINARY) $(V4_OBJS) $(TEST_UNIT_OBJS) test_expert_store_registrydiff --git a/c/deepseek_v4.c b/c/deepseek_v4.cindex 32a14e6d..627d13a2 100644--- a/c/deepseek_v4.c+++ b/c/deepseek_v4.c@@ -1354,8 +1354,10 @@ static int v5_dense_inventory(const char *model_dir,int coli_v4_expert_store_open_planned(ColiV4Engine *engine,+ const ColiDeepSeekV4Config *config,const ColiDeepSeekV4ExpertStoreOptions *options, ColiExpertStore **output,char *error, size_t error_size) {+ (void)config; /* auto uses engine->runtime + engine->config; requires engine */if (!options || !engine) return -1;ColiDeepSeekV4ResourcePlan plan;ColiDeepSeekV4RuntimeOptions *runtime = &engine->runtime;@@ -8321,6 +8323,7 @@ int coli_v4_route_bf16(float *weights, int *indices, const float *hidden,#ifdef COLI_V4_UNIT_RUNTIME/* ######## deepseek_v4_runtime.c / engine ######## */#include "deepseek_v4_internal.h"+#include "expert_store_registry.h"#include <assert.h>#include <stdio.h>@@ -8667,8 +8670,8 @@ int coli_v4_engine_open(ColiV4Engine **output,return 0;}#endif- if (coli_v4_expert_store_open_planned(- engine,+ if (coli_expert_store_backend_open_selected(+ engine, &engine->config,&(ColiDeepSeekV4ExpertStoreOptions){engine->runtime.target_model_dir,engine->config.num_hidden_layers,@@ -10653,12 +10656,28 @@ int main(int argc, char **argv) {ColiSafetensorsIndex *index = NULL;ColiExpertStore *experts = NULL;if (coli_v4_config_load(&config, argv[1], error, sizeof(error)) ||- coli_st_index_open(&index, argv[1], error, sizeof(error)) ||- coli_deepseek_v4_expert_store_open(- &(ColiDeepSeekV4ExpertStoreOptions){- argv[1], config.num_hidden_layers, config.n_routed_experts,- UINT64_C(4) * 1024 * 1024 * 1024, -1, 0,- }, &experts, error, sizeof(error))) {+ coli_st_index_open(&index, argv[1], error, sizeof(error))) {+ fprintf(stderr, "%s\n", error);+ return 1;+ }+ ColiDeepSeekV4ExpertStoreOptions store_opts = {+ argv[1], config.num_hidden_layers, config.n_routed_experts,+ UINT64_C(4) * 1024 * 1024 * 1024, -1, 0,+ };+ /* Route through the pluggable backend registry when COLI_EXPERT_STORE names+ * a non-"auto" backend (e.g. a networked/remote store). The+ * CLI has no ColiV4Engine, so pass NULL engine + the loaded config; the+ * backend derives expert geometry from the config. Unset/"auto" keeps the+ * historical direct on-disk open. */+ const char *coli_be = getenv("COLI_EXPERT_STORE");+ if (coli_be && *coli_be && strcmp(coli_be, "auto") != 0) {+ if (coli_expert_store_backend_open_selected(+ NULL, &config, &store_opts, &experts, error, sizeof(error))) {+ fprintf(stderr, "%s\n", error);+ return 1;+ }+ } else if (coli_deepseek_v4_expert_store_open(+ &store_opts, &experts, error, sizeof(error))) {fprintf(stderr, "%s\n", error);return 1;}diff --git a/c/deepseek_v4_internal.h b/c/deepseek_v4_internal.hindex 9e1fc5d0..de4a108d 100644--- a/c/deepseek_v4_internal.h+++ b/c/deepseek_v4_internal.h@@ -10,6 +10,7 @@#include <stdio.h>#include "tensor.h"#include "expert_store.h"+#include "expert_store_registry.h"#include "native_quant.h"#include "native_quant_batch.h"#include "native_quant_dual.h"@@ -585,7 +586,7 @@ int coli_v4_shared_expert_forward_ref(float *output,extern "C" {#endif-typedef struct {+typedef struct ColiDeepSeekV4ExpertStoreOptions {const char *model_dir;int layers;int experts_per_layer;@@ -924,9 +925,13 @@ struct ColiV4Session {int spec_disabled;};-/* RAM-tiered expert open used by coli_v4_engine_open (replaces ld --wrap). */+/* RAM-tiered expert open used by coli_v4_engine_open (replaces ld --wrap).+ * `config` is the model geometry (== engine->config on the engine_open path);+ * it is forwarded by the backend registry so engine-less callers (the standalone+ * CLI) can use routed backends that only need geometry, not the engine. */int coli_v4_expert_store_open_planned(ColiV4Engine *engine,+ const ColiDeepSeekV4Config *config,const ColiDeepSeekV4ExpertStoreOptions *options,ColiExpertStore **store,char *error,diff --git a/c/expert_store_registry.c b/c/expert_store_registry.cnew file mode 100644index 00000000..526d8cd9--- /dev/null+++ b/c/expert_store_registry.c@@ -0,0 +1,104 @@+/*+ * Pluggable expert-store backend registry β implementation.+ *+ * See expert_store_registry.h for the design. Registration happens from C+ * constructors at static-link time (before main), so the table is read-only+ * once the engine runs and no locking is needed.+ */++#include "expert_store_registry.h"++#include <stdio.h>+#include <stdlib.h>+#include <string.h>++/* Keep the public registry symbols external even under -flto: backends live+ * in separately-compiled object files (e.g. a custom backend linked in later)+ * and call register() from their own constructors, so these symbols must+ * survive LTO inlining. Without this, gcc drops them when the only caller in+ * the current link is inside the same LTO set. */+#if defined(__GNUC__)+#define COLI_ESR_EXPORT __attribute__((externally_visible, used))+#else+#define COLI_ESR_EXPORT+#endif++/* The built-in on-disk/mmap backend, defined in the COLI_V4_UNIT_EXPERT_STORE_AUTO+ * amalgamation unit of deepseek_v4.c. Declared here (not via its header, which+ * is a large amalgamated translation unit) so this module stays standalone. */+int coli_v4_expert_store_open_planned(+ ColiV4Engine *engine,+ const ColiDeepSeekV4Config *config,+ const ColiDeepSeekV4ExpertStoreOptions *options,+ ColiExpertStore **output,+ char *error, size_t error_size);++#define COLI_EXPERT_STORE_MAX_BACKENDS 8++static struct {+ const char *name;+ ColiExpertStoreBackendOpenFn open_fn;+} g_backends[COLI_EXPERT_STORE_MAX_BACKENDS];+static int g_backend_count;++COLI_ESR_EXPORT+int coli_expert_store_backend_register(const char *name,+ ColiExpertStoreBackendOpenFn open_fn) {+ if (!name || !open_fn) return -1;+ for (int i = 0; i < g_backend_count; i++) {+ if (strcmp(g_backends[i].name, name) == 0) {+ g_backends[i].open_fn = open_fn; /* last-wins override */+ return 0;+ }+ }+ if (g_backend_count >= COLI_EXPERT_STORE_MAX_BACKENDS) return -1;+ g_backends[g_backend_count].name = name;+ g_backends[g_backend_count].open_fn = open_fn;+ g_backend_count++;+ return 0;+}++COLI_ESR_EXPORT+int coli_expert_store_backend_count(void) {+ return g_backend_count;+}++COLI_ESR_EXPORT+ColiExpertStoreBackendOpenFn+coli_expert_store_backend_lookup(const char *name) {+ if (!name) return NULL;+ for (int i = 0; i < g_backend_count; i++)+ if (strcmp(g_backends[i].name, name) == 0)+ return g_backends[i].open_fn;+ return NULL;+}++COLI_ESR_EXPORT+int coli_expert_store_backend_open_selected(+ ColiV4Engine *engine,+ const ColiDeepSeekV4Config *config,+ const ColiDeepSeekV4ExpertStoreOptions *options,+ ColiExpertStore **output,+ char *error, size_t error_size) {+ const char *name = getenv("COLI_EXPERT_STORE");+ if (!name || !*name) name = "auto";+ ColiExpertStoreBackendOpenFn fn = coli_expert_store_backend_lookup(name);+ if (!fn) {+ if (error && error_size)+ snprintf(error, error_size,+ "expert store backend '%s' is not registered "+ "(set COLI_EXPERT_STORE to a linked backend; "+ "default is 'auto')",+ name);+ return -1;+ }+ return fn(engine, config, options, output, error, error_size);+}++/* Register the built-in on-disk/mmap backend at static-link time so the+ * default (COLI_EXPERT_STORE unset) path is unchanged from before this seam. */+__attribute__((constructor))+static void coli_register_auto_backend(void) {+ coli_expert_store_backend_register("auto",+ coli_v4_expert_store_open_planned);+}\ No newline at end of filediff --git a/c/expert_store_registry.h b/c/expert_store_registry.hnew file mode 100644index 00000000..db96c422--- /dev/null+++ b/c/expert_store_registry.h@@ -0,0 +1,79 @@+#ifndef COLIBRI_EXPERT_STORE_REGISTRY_H+#define COLIBRI_EXPERT_STORE_REGISTRY_H++/*+ * Pluggable expert-store backend registry.+ *+ * The DeepSeek-V4 engine opens its expert store through a backend selected by+ * the COLI_EXPERT_STORE environment variable (default "auto" = the built-in+ * on-disk/mmap store). A backend registers a name + an open function matching+ * ColiExpertStoreBackendOpenFn. Backends ship as separate object files and+ * register themselves at link time via a C constructor, so the engine source+ * carries no backend-specific branching β adding a backend (e.g. a networked+ * store) is a link-time concern, not an engine edit.+ *+ * The built-in "auto" backend (coli_v4_expert_store_open_planned) is registered+ * by this module's own constructor, so with COLI_EXPERT_STORE unset the engine+ * behaves exactly as before this seam existed.+ */++#include <stddef.h>+#include "expert_store.h"+#include "deepseek_v4.h" /* ColiDeepSeekV4Config (engine-less CLI path passes it) */++#ifdef __cplusplus+extern "C" {+#endif++/* Forward declarations. The concrete structs live in deepseek_v4_internal.h;+ * the registry only forwards opaque pointers to the chosen backend, so a+ * backend object file that needs field access includes that header itself. */+typedef struct ColiV4Engine ColiV4Engine;+typedef struct ColiDeepSeekV4ExpertStoreOptions ColiDeepSeekV4ExpertStoreOptions;++/* Open a store for the given engine + config + options. `engine` carries the+ * runtime/planning state the built-in "auto" backend needs; `config` carries+ * the model geometry every backend needs and is the ONLY thing a backend+ * without an engine (e.g. a remote store opened from the standalone CLI+ * path, which has no ColiV4Engine) can rely on. `engine` may be NULL for+ * backends that only consume `config`; the "auto" backend requires a non-NULL+ * engine. Same return contract as coli_v4_expert_store_open_planned: zero on+ * success with *output written, non-zero on failure with a message. */+typedef int (*ColiExpertStoreBackendOpenFn)(+ ColiV4Engine *engine,+ const ColiDeepSeekV4Config *config,+ const ColiDeepSeekV4ExpertStoreOptions *options,+ ColiExpertStore **output,+ char *error, size_t error_size);++/* Register a backend under `name`. Intended to be called from a constructor in+ * the backend's object file (so registration happens at static-link time,+ * before main). Names match case-sensitively; a later registration with the+ * same name replaces the earlier (last-wins, letting a build deliberately+ * override "auto"). Returns 0 on success, -1 if name/open_fn is NULL or the+ * registry is full. */+int coli_expert_store_backend_register(const char *name,+ ColiExpertStoreBackendOpenFn open_fn);++/* Number of backends currently registered (mainly for tests/diagnostics). */+int coli_expert_store_backend_count(void);++/* Look up a backend's open function by name, or NULL if not registered. */+ColiExpertStoreBackendOpenFn+coli_expert_store_backend_lookup(const char *name);++/* Open a store via the backend selected by the COLI_EXPERT_STORE env var+ * (default "auto"). Returns zero on success; non-zero with an error message if+ * the selected backend is not registered or its open fails. This is what the+ * engine calls in place of a hardcoded open. */+int coli_expert_store_backend_open_selected(+ ColiV4Engine *engine,+ const ColiDeepSeekV4Config *config,+ const ColiDeepSeekV4ExpertStoreOptions *options,+ ColiExpertStore **output,+ char *error, size_t error_size);++#ifdef __cplusplus+}+#endif+#endif /* COLIBRI_EXPERT_STORE_REGISTRY_H */\ No newline at end of filediff --git a/c/test_expert_store_registry.c b/c/test_expert_store_registry.cnew file mode 100644index 00000000..a894ed02--- /dev/null+++ b/c/test_expert_store_registry.c@@ -0,0 +1,94 @@+/*+ * Unit test for the pluggable expert-store backend registry.+ *+ * Verifies:+ * - the built-in "auto" backend is registered at link time (constructor);+ * - lookup hits for "auto", misses for an unknown name;+ * - open_selected dispatches to COLI_EXPERT_STORE, errors cleanly on an+ * unregistered backend, and falls back to "auto" when the env is unset.+ *+ * The real auto open (coli_v4_expert_store_open_planned) lives in deepseek_v4.c;+ * we stub it here so this test links without the engine. The stub records that+ * it was called and returns a sentinel so we can observe dispatch.+ *+ * gcc -O2 test_expert_store_registry.c expert_store_registry.c -o test_expert_store_registry+ * ./test_expert_store_registry+ */+#include "expert_store_registry.h"+#include <stdio.h>+#include <stdlib.h>+#include <string.h>++static int g_auto_called = 0;++/* Stub for the built-in backend's open fn. */+int coli_v4_expert_store_open_planned(ColiV4Engine *engine,+ const ColiDeepSeekV4Config *config,+ const ColiDeepSeekV4ExpertStoreOptions *opts,+ ColiExpertStore **out,+ char *error, size_t error_size) {+ (void)engine; (void)config; (void)opts; (void)out; (void)error; (void)error_size;+ g_auto_called = 1;+ return -1; /* sentinel: dispatched but did not open */+}++int main(void) {+ int n = coli_expert_store_backend_count();+ if (n != 1) {+ printf("FAIL: expected 1 backend (auto) on startup, got %d\n", n);+ return 1;+ }+ if (!coli_expert_store_backend_lookup("auto")) {+ printf("FAIL: 'auto' not registered\n");+ return 1;+ }+ if (coli_expert_store_backend_lookup("does-not-exist")) {+ printf("FAIL: unknown backend unexpectedly found\n");+ return 1;+ }++ char err[128] = {0};+ ColiExpertStore *out = NULL;++ /* Unregistered backend selected by env -> clean error, no dispatch. */+ setenv("COLI_EXPERT_STORE", "example-not-linked", 1);+ g_auto_called = 0;+ int rc = coli_expert_store_backend_open_selected(NULL, NULL, NULL, &out, err, sizeof(err));+ if (rc == 0 || g_auto_called) {+ printf("FAIL: unregistered backend should error without dispatch (rc=%d, auto_called=%d)\n",+ rc, g_auto_called);+ return 1;+ }+ if (!strstr(err, "example-not-linked") || !strstr(err, "not registered")) {+ printf("FAIL: error message wrong: %s\n", err);+ return 1;+ }+ printf("unregistered backend -> clean error: %s\n", err);++ /* Env unset -> default 'auto' -> dispatch to the stub. */+ unsetenv("COLI_EXPERT_STORE");+ g_auto_called = 0;+ err[0] = 0;+ rc = coli_expert_store_backend_open_selected(NULL, NULL, NULL, &out, err, sizeof(err));+ if (!g_auto_called) {+ printf("FAIL: default 'auto' did not dispatch\n");+ return 1;+ }+ /* rc is the stub's -1 sentinel; what matters is that auto was dispatched. */+ (void)rc;+ printf("default (COLI_EXPERT_STORE unset) -> dispatched to 'auto'\n");++ /* Explicit 'auto' also dispatches. */+ setenv("COLI_EXPERT_STORE", "auto", 1);+ g_auto_called = 0;+ coli_expert_store_backend_open_selected(NULL, NULL, NULL, &out, err, sizeof(err));+ if (!g_auto_called) {+ printf("FAIL: explicit 'auto' did not dispatch\n");+ return 1;+ }+ unsetenv("COLI_EXPERT_STORE");+ printf("explicit 'auto' -> dispatched to 'auto'\n");++ printf("ALL OK\n");+ return 0;+}\ No newline at end of filediff --git a/c/tests/test_deepseek_v4_dspark_source.py b/c/tests/test_deepseek_v4_dspark_source.pyindex 9fc54dcb..5157cf7c 100644--- a/c/tests/test_deepseek_v4_dspark_source.py+++ b/c/tests/test_deepseek_v4_dspark_source.py@@ -22,7 +22,7 @@ class DeepSeekV4DSparkSourceTest(unittest.TestCase):def test_drafter_is_lazy_and_budgeted_before_target_cache(self):reserve = self.engine.index("engine->runtime.dspark_reserve_bytes =")- store = self.engine.index("coli_v4_expert_store_open_planned(", reserve)+ store = self.engine.index("coli_expert_store_backend_open_selected(", reserve)self.assertLess(reserve, store)self.assertIn("load=lazy verification=exact-target", self.engine)self.assertIn("double total_gb = coli_v4_dspark_cache_gb()", self.drafter)diff --git a/c/tests/test_v4_ownership.c b/c/tests/test_v4_ownership.cindex 6119c79b..b0d97a27 100644--- a/c/tests/test_v4_ownership.c+++ b/c/tests/test_v4_ownership.c@@ -12,11 +12,13 @@/* Stubs for symbols referenced by RUNTIME but unused in these tests. */int coli_v4_expert_store_open_planned(ColiV4Engine *engine,+ const ColiDeepSeekV4Config *config,const ColiDeepSeekV4ExpertStoreOptions *options,ColiExpertStore **store,char *error,size_t error_size) {(void)engine;+ (void)config;(void)options;(void)store;if (error && error_size)