Add a checked registry for engine environment variables

.github/workflows/ci.yml

@@ -12,6 +12,18 @@ permissions:
   contents: read
 
 jobs:
+  # The environment-variable registry (c/coli_env.h) against the sources. No
+  # build, no model, no GPU -- seconds, so it reports before anything else.
+  env-registry:
+    name: Env registry in sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: make -C c check-env
+
   engine:
     name: Engine (Linux, CPU)
     runs-on: ubuntu-latest

c/Makefile.deepseek-v4

@@ -245,27 +245,27 @@ $(V4_BINARY): $(V4_OBJS)
 $(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 \
+$(TARGET_OBJS) $(TEST_UNIT_OBJS): %.o: deepseek_v4.c coli_env.h 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 expert_store_registry.h
 	$(CC) $(CFLAGS) -D$* -c deepseek_v4.c -o $@
 
-$(V4_HOT_TEST_OBJ): deepseek_v4.c deepseek_v4.h deepseek_v4_internal.h \
+$(V4_HOT_TEST_OBJ): deepseek_v4.c coli_env.h deepseek_v4.h deepseek_v4_internal.h \
 		st.h json.h compat.h tensor.h quant.h route_trace.h \
 		native_quant.h native_quant_fp4_rows16.h expert_store_registry.h
 	$(CC) $(CFLAGS) -DCOLI_V4_TEST_HOOKS \
 		-DCOLI_V4_UNIT_EXPERT_STORE_HOT_ROWS16 -c deepseek_v4.c -o $@
 
-$(V4_BATCH_TEST_OBJ): deepseek_v4.c deepseek_v4.h deepseek_v4_internal.h \
+$(V4_BATCH_TEST_OBJ): deepseek_v4.c coli_env.h deepseek_v4.h deepseek_v4_internal.h \
 		tensor.h quant.h native_quant.h native_quant_batch.h
 	$(CC) $(CFLAGS) -DCOLI_V4_TEST_HOOKS \
 		-DCOLI_V4_UNIT_NATIVE_QUANT_BATCH -c deepseek_v4.c -o $@
 
 COLI_V4_UNIT_GENERATE_STATS.o: serve_codec.h
 
-$(V4_SERVE_TEST): tests/test_v4_serve_framing.c deepseek_v4.c deepseek_v4.h \
+$(V4_SERVE_TEST): tests/test_v4_serve_framing.c deepseek_v4.c coli_env.h deepseek_v4.h \
 		deepseek_v4_internal.h serve_codec.h $(V4_SERVE_TEST_OBJS)
 	$(CC) $(CFLAGS) $< $(V4_SERVE_TEST_OBJS) -o $@ $(LDFLAGS)
 

c/colibri.c

@@ -99,6 +99,7 @@ static inline void omp_set_num_threads(int n){ (void)n; }
 #include "edge_adapters.h"
 #include "edge_tok_internal.h"
 #endif
+#include "coli_env.h"
 #ifdef COLI_CUDA
 #include "backend_cuda.h"
 #endif
@@ -11136,6 +11137,11 @@ int main(int argc, char **argv){
         perror("[OMP] execv self-reexec failed, running untuned");
 #endif
     }
+    /* Registry check: an unknown or wrong-engine variable is silently ignored
+     * otherwise, and the run then reports a plausible number for the WRONG
+     * configuration. See coli_env.h. */
+    coli_env_check(CE_COLIBRI, "colibri");
+    coli_env_dump(CE_COLIBRI, "colibri");
     /* #718: the hot-team block above tunes wake latency but historically left
      * GLM at libgomp's logical-CPU default.  Memory-bound quantized matmuls can
      * collapse when SMT siblings share each core, measured 2.3x on a 5950X.

c/deepseek_v4.c

@@ -12,6 +12,8 @@
  * anything larger falls back to malloc exactly like before this change. */
 #define COLI_V4_ROUTE_STACK_EXPERTS 512
 
+#include "coli_env.h"
+
 #ifdef COLI_V4_UNIT_ST
 /* Shared st.h adapter and V4 tensor materialization helpers. */
 #include "deepseek_v4_internal.h"
@@ -12040,6 +12042,8 @@ static int has_sentence_end(const char *text, int length) {
 }
 
 int main(int argc, char **argv) {
+    coli_env_check(CE_DSV4, "deepseek-v4");
+    coli_env_dump(CE_DSV4, "deepseek-v4");
     if (argc < 3 || argc > 6) {
         fprintf(stderr, "usage: %s MODEL_DIR INPUT_TOKEN_ID [TOKEN_COUNT]\n"
                         "       %s MODEL_DIR --prompt TEXT [MAX_NEW_TOKENS] [--stop-sentence]\n",
@@ -14621,6 +14625,8 @@ static int v4_omp_reserve_loader_cpus(void) {
 #endif
 
 int main(int argc, char **argv) {
+    coli_env_check(CE_DSV4, "deepseek-v4");
+    coli_env_dump(CE_DSV4, "deepseek-v4");
 #ifdef _OPENMP
     if (!v4_omp_reserve_loader_cpus())
         fprintf(stderr, "[OMP] deepseek-v4: effective team size %d\n",

c/deepseek_v41.c

@@ -60,6 +60,7 @@
 #include "compat.h"
 #include "json.h"
 #include "st.h"
+#include "coli_env.h"
 #include "quant.h"
 #include "sparse_attn.h"
 #include "omp_tune.h"
@@ -3887,6 +3888,8 @@ static int *load_ids(jval *root, const char *key, int *count) {
 }
 
 int main(int argc, char **argv) {
+    coli_env_check(CE_DSV41, "deepseek-v41");
+    coli_env_dump(CE_DSV41, "deepseek-v41");
     /* Size the team to PHYSICAL cores before anything else touches the model.
      * This engine issues ~720 OpenMP regions per decoded token -- three per
      * expert application, 240 applications a token -- and every one of them is

c/glm53.c

@@ -89,6 +89,7 @@ static uint64_t g_metal_moe_rows = 0;
 static int g_vk_ready = 0;
 #endif
 #include "compat.h"
+#include "coli_env.h"
 #include "serve_poll.h"          /* CANCEL a meta' turno (#1332) */
 #include "route_trace.h"
 #include "decode_batch.h"   /* coli_submit_ext, coli_logprob_tail: canale logprobs */
@@ -3515,6 +3516,8 @@ static void serve_loop(GModel *m, Tok *tokenizer) {
 
 #ifndef GLM53_NO_MAIN
 int main(int argc, char **argv) {
+    coli_env_check(CE_GLM53, "glm53");
+    coli_env_dump(CE_GLM53, "glm53");
     /* Physical-core team sizing, the same shared helper colibri/inkling/
      * kimi_k3/olmoe/deepseek-v41 call. This engine has no OpenMP sizing of its
      * own, so on an SMT host it ran one thread per logical CPU; #718 measured

c/inkling.c

@@ -53,6 +53,7 @@
 #include "edge_adapters.h"
 #include "edge_tok_internal.h"
 #endif
+#include "coli_env.h"
 #ifdef COLI_CUDA
 #include "backend_cuda_ink.h"
 static int g_cuda = 0;
@@ -2580,6 +2581,11 @@ int main(int argc, char **argv) {
     }
 #endif  /* !COLI_CUDA && !__APPLE__ */
     coli_omp_tune_threads("inkling");
+    /* Registry check: an unknown or wrong-engine variable is silently ignored
+     * otherwise, and the run then reports a plausible number for the WRONG
+     * configuration. See coli_env.h. */
+    coli_env_check(CE_INKLING, "inkling");
+    coli_env_dump(CE_INKLING, "inkling");
     const char *snap = getenv("SNAP");
     if (!snap) { coli_print_launcher_help("Inkling"); return 1; }
     g_topp = getenv("TOPP") ? (float)atof(getenv("TOPP")) : 0.f;

c/kimi_k3.c

@@ -112,6 +112,7 @@
 #include "backend_cuda.h"
 #endif
 #include "omp_tune.h"
+#include "coli_env.h"
 #include "route_trace.h"
 #include "kv_prefix.h"
 #include "pin_pool.h"   /* coli_pin_slots_wanted: quanti scatti tenere */
@@ -3272,6 +3273,11 @@ static void serve_loop(Model *m, Tok *T){
 #ifndef KIMI_K3_NO_MAIN
 int main(int argc, char **argv){
     coli_omp_tune_threads("kimi_k3");   /* squadra sui core fisici, niente spin-wait: vedi omp_tune.h */
+    /* Registry check: an unknown or wrong-engine variable is silently ignored
+     * otherwise, and the run then reports a plausible number for the WRONG
+     * configuration. See coli_env.h. */
+    coli_env_check(CE_KIMI, "kimi_k3");
+    coli_env_dump(CE_KIMI, "kimi_k3");
     int serving=getenv("SERVE")&&getenv("SERVE")[0]=='1';
     /* Usage was printed only when there were NO arguments, so `--help` fell
      * through as the model directory and the engine went looking for

c/olmoe.c

@@ -42,6 +42,7 @@
 #include <omp.h>   /* omp_set_num_threads/omp_get_max_threads per omp_tune.h */
 #endif
 #include "omp_tune.h"
+#include "coli_env.h"
 #include "route_trace.h"                    /* shared routing telemetry (#700) */
 #include "kv_prefix.h"
 #include "pin_pool.h"                       /* piu scatti annidati */   /* riuso del prefisso tra turni (shared) */
@@ -1836,6 +1837,11 @@ static int *read_int_array(jval *o, const char *key, int *n_out) {
 #ifndef OLMOE_NO_MAIN
 int main(int argc, char **argv) {
     coli_omp_tune_threads("olmoe");   /* squadra sui core fisici, niente spin-wait: vedi omp_tune.h */
+    /* Registry check: an unknown or wrong-engine variable is silently ignored
+     * otherwise, and the run then reports a plausible number for the WRONG
+     * configuration. See coli_env.h. */
+    coli_env_check(CE_OLMOE, "olmoe");
+    coli_env_dump(CE_OLMOE, "olmoe");
     const char *snap = getenv("SNAP");
     if (!snap) { coli_print_launcher_help("OLMoE"); return 1; }
     g_pilot = getenv("PILOT") ? atoi(getenv("PILOT")) : 0;

c/qwen36.c

@@ -65,6 +65,7 @@ static int qwen36_max_ctx(void) {
 #include "pin_pool.h"   /* riuso del prefisso tra turni (shared) */
 #include "decode_batch.h" /* ColiSubmit + coli_submit_ext: le chiavi key=value di SUBMIT */
 #include "json.h"   /* tokenizer.json parsing (reuse minimal parser) */
+#include "coli_env.h"
 #include "qwen36_tier.h"   /* optional CUDA VRAM expert tier */
 #include "expert_ffn.h"    /* routed experts: planar int4 kernel + layer runner */
 #include "idot.h"          /* integer dot kernels for the dense trunk (COLI_DENSE_IDOT, COLI_DENSE_BITS) */
@@ -3711,6 +3712,8 @@ static void tier_warmstart(Model *m, int expert_is_int4) {
 }
 
 int main(int argc, char **argv) {
+    coli_env_check(CE_QWEN, "qwen36");
+    coli_env_dump(CE_QWEN, "qwen36");
     /* Physical-core team sizing, as colibri/inkling/kimi_k3/olmoe/deepseek-v41
      * do. Without it this engine takes one thread per logical CPU, which on an
      * SMT host doubles the team for no arithmetic and pays a barrier per tiny

c/qwen38.c

@@ -67,6 +67,7 @@ static int qwen38_max_ctx(void) {
 #include "tok_unicode.h"
 #include "tok_unicode_o200k.h"
 #include "qwen38_nfc.h"
+#include "coli_env.h"
 /* quant.h owns Colibri's authoritative E4M3 table.  This engine retains the
  * Qwen sibling's established dense kernels, so rename quant.h's two generic
  * helpers while including it; every format-specific symbol keeps its shared
@@ -1834,6 +1835,8 @@ static int q38_reference_mode(const char *path,int serve_mode){
 
 #ifndef QWEN38_TEST_SERVE
 int main(int argc, char **argv) {
+    coli_env_check(CE_QWEN38, "qwen38");
+    coli_env_dump(CE_QWEN38, "qwen38");
     /* Physical-core team sizing, as colibri/inkling/kimi_k3/olmoe/deepseek-v41
      * do. Without it this engine takes one thread per logical CPU, which on an
      * SMT host doubles the team for no arithmetic and pays a barrier per tiny

c/tests/test_env_registry.c

@@ -0,0 +1,32 @@
+#include <assert.h>
+#include "../coli_env.h"
+
+int main(void) {
+    const unsigned short engines[] = {CE_COLIBRI, CE_KIMI, CE_INKLING, CE_OLMOE,
+        CE_DSV4, CE_QWEN, CE_GLM53, CE_QWEN38, CE_DSV41};
+    for (unsigned i = 0; i < sizeof(engines) / sizeof(engines[0]); ++i) {
+        assert(coli_env_find("COLI_ENV_STRICT")->engines & engines[i]);
+        assert(coli_env_find("COLI_ENV_DUMP")->engines & engines[i]);
+    }
+    assert(coli_env_find("V41_DSPARK")->engines == CE_DSV41);
+    assert(coli_env_find("V41_READ_DEPTH")->engines == CE_DSV41);
+    assert(coli_env_find("Q38_TRUNK_GPU")->engines == CE_QWEN38);
+    assert(coli_env_find("COLI_PLACE")->engines == (CE_QWEN | CE_QWEN38));
+    assert(coli_env_find("CACHE_ROUTE")->engines & CE_QWEN);
+    assert(coli_env_find("SNAP")->engines & CE_DSV41);
+    assert(coli_env_is_ours("V41_DSPAR"));
+    assert(!strcmp(coli_env_suggest("V41_DSPAR"), "V41_DSPARK"));
+    assert(!coli_env_find("V41_DSPAR"));
+    const char *const typos[] = {"COLI_PREFIL_CHUNK", "COLIBRI_ENGINE_SUFFI",
+        "K3_BIT", "KIMI_DSA_INDEXE", "INK_BIT", "GLM53_BIT", "Q38_TRUNK_GP",
+        "Q36_CTX_MA", "QWEN_EXPERT_KERNL", "DSV4_UNKNOWN", "V4_REPLAY_TRAC", "V41_DSPAR"};
+    for (unsigned i = 0; i < sizeof(typos) / sizeof(typos[0]); ++i)
+        assert(coli_env_is_ours(typos[i]));
+    const char *const unrelated[] = {"EDITOR", "MY_VAR", "CUDA_VISIBLE_DEVICES",
+        "OMP_WAIT_POLICY", "QT_QPA_PLATFORM", "VK_ICD_FILENAMES", "QWEN", "V41", "Q38X_FOO"};
+    for (unsigned i = 0; i < sizeof(unrelated) / sizeof(unrelated[0]); ++i)
+        assert(!coli_env_is_ours(unrelated[i]));
+    assert(!strcmp(coli_env_suggest("QWEN_EXPERT_KERNL"), "QWEN_EXPERT_KERNEL"));
+    puts("test_env_registry: ok");
+    return 0;
+}

c/tests/test_env_registry_scanner.py

@@ -0,0 +1,50 @@
+"""Name coverage must follow calls, not formatting or source comments."""
+import contextlib
+import io
+from pathlib import Path
+import tempfile
+import unittest
+from unittest.mock import patch
+from tools import check_env_registry as registry
+
+
+class RegistryScannerTest(unittest.TestCase):
+    def setUp(self):
+        self.directory = tempfile.TemporaryDirectory()
+        self.addCleanup(self.directory.cleanup)
+        self.root = Path(self.directory.name)
+        self.patch = patch.object(registry, "C_DIR", str(self.root))
+        self.patch.start()
+        self.addCleanup(self.patch.stop)
+
+    def test_calls_across_lines_and_whitespace(self):
+        (self.root / "engine.c").write_text(
+            'getenv (\n "COLI_A");\nq38_env_bool(\n "Q38_B");\n'
+            'compat_getenv_utf8("COLI_C");\n')
+        self.assertEqual(registry.scan_sources(), {
+            "COLI_A": ["engine.c:1"], "Q38_B": ["engine.c:3"],
+            "COLI_C": ["engine.c:5"]})
+
+    def test_comments_and_strings_are_not_calls(self):
+        (self.root / "engine.c").write_text(
+            '// getenv("COLI_COMMENT")\n'
+            '/* q38_env_bool("Q38_COMMENT") */\n'
+            'const char *s = "getenv(\\"COLI_STRING\\")";\n'
+            'my_getenv("COLI_OTHER_FUNCTION");\n'
+            'getenv("COLI_REAL");\n')
+        self.assertEqual(registry.scan_sources(), {"COLI_REAL": ["engine.c:5"]})
+
+    def test_commented_read_cannot_keep_stale_registry_entry_alive(self):
+        (self.root / "engine.c").write_text('// getenv("COLI_OLD")\n')
+        (self.root / "coli_env.h").write_text(
+            'static const ColiEnvVar coli_env_table[] = {\n'
+            '    {"COLI_OLD", CE_BOOL, CE_QWEN, 0, NULL},\n};\n')
+        error = io.StringIO()
+        with contextlib.redirect_stderr(error):
+            self.assertEqual(registry.main(), 1)
+        self.assertIn("no code reads it: COLI_OLD", error.getvalue())
+
+    def test_fixture_directories_are_excluded(self):
+        (self.root / "tests").mkdir()
+        (self.root / "tests" / "fixture.c").write_text('getenv("FIXTURE_ONLY");')
+        self.assertEqual(registry.scan_sources(), {})