Skip to content

Run frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦

C

colibri.c: steer the storage probe to verified-cold ranges; strict v2 cache (#379)

monotophica3d76fc49e41
diff --git a/c/Makefile b/c/Makefile
index 67ca106b..f3391f1d 100644
--- a/c/Makefile
+++ b/c/Makefile
@@ -214,7 +214,7 @@ else
PYTHON ?= python3
endif
CUDA_OBJ =
-TEST_BINS = tests/test_json$(EXE) tests/test_st$(EXE) tests/test_st_mirror$(EXE) tests/test_st_pread$(EXE) tests/test_tier$(EXE) tests/test_grammar$(EXE) tests/test_schema_gbnf$(EXE) tests/test_decode_batch$(EXE) tests/test_idot$(EXE) tests/test_i4_grouped$(EXE) tests/test_stops$(EXE) tests/test_topp$(EXE) tests/test_sample_nan$(EXE) tests/test_temp_env$(EXE) tests/test_tok_o200k$(EXE) tests/test_kv_alloc$(EXE) tests/test_int3$(EXE) tests/test_int3_load$(EXE) tests/test_i4_acc512$(EXE) tests/test_compat_direct$(EXE) tests/test_dsa_select$(EXE) tests/test_logit_nan$(EXE) tests/test_router_nan$(EXE) tests/test_pipe_block$(EXE) tests/test_e8_kernel$(EXE) tests/test_rans$(EXE) tests/test_corpus_draft$(EXE) tests/test_pilot_ring$(EXE) tests/test_cap_precedence$(EXE)
+TEST_BINS = tests/test_json$(EXE) tests/test_st$(EXE) tests/test_st_mirror$(EXE) tests/test_st_pread$(EXE) tests/test_tier$(EXE) tests/test_grammar$(EXE) tests/test_schema_gbnf$(EXE) tests/test_decode_batch$(EXE) tests/test_idot$(EXE) tests/test_i4_grouped$(EXE) tests/test_stops$(EXE) tests/test_topp$(EXE) tests/test_sample_nan$(EXE) tests/test_temp_env$(EXE) tests/test_tok_o200k$(EXE) tests/test_kv_alloc$(EXE) tests/test_int3$(EXE) tests/test_int3_load$(EXE) tests/test_i4_acc512$(EXE) tests/test_compat_direct$(EXE) tests/test_dsa_select$(EXE) tests/test_logit_nan$(EXE) tests/test_router_nan$(EXE) tests/test_pipe_block$(EXE) tests/test_e8_kernel$(EXE) tests/test_rans$(EXE) tests/test_corpus_draft$(EXE) tests/test_pilot_ring$(EXE) tests/test_cap_precedence$(EXE) tests/test_ssd_probe$(EXE)
ifneq (,$(LINUX))
TEST_BINS += tests/test_uring$(EXE)
endif
@@ -563,6 +563,9 @@ tests/test_corpus_draft$(EXE): tests/test_corpus_draft.c colibri.c st.h uring.h
tests/test_cap_precedence$(EXE): tests/test_cap_precedence.c colibri.c st.h uring.h json.h tok.h tok_unicode.h compat.h grammar.h tier.h quant.h sample.h kv_persist.h telemetry.h
$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
+tests/test_ssd_probe$(EXE): tests/test_ssd_probe.c colibri.c st.h uring.h json.h tok.h tok_unicode.h compat.h grammar.h tier.h quant.h sample.h kv_persist.h telemetry.h
+ $(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
+
# bench_dsa_select is a microbenchmark (old qsort vs new quickselect partial-select, #356),
# NOT a test gate -- intentionally absent from TEST_BINS. Build on demand: make tests/bench_dsa_select
tests/bench_dsa_select$(EXE): tests/bench_dsa_select.c colibri.c st.h uring.h json.h tok.h tok_unicode.h compat.h grammar.h tier.h quant.h sample.h kv_persist.h telemetry.h
diff --git a/c/colibri.c b/c/colibri.c
index 7c5f669c..0c330871 100644
--- a/c/colibri.c
+++ b/c/colibri.c
@@ -7580,16 +7580,128 @@ static void prof_config(Model *m, double ram_env, int est_ctx){
* (page-cache hits read 23-97 GB/s on the reference box; the real F_NOCACHE
* number was 14 GB/s), so this probes the actual model volume the same way
* compat_open_direct()/iobench.c's __APPLE__ branch do: open + F_NOCACHE,
- * random 16K-aligned pread, no readahead. Cheap and darwin-only: never touches
- * non-Metal or non-darwin builds.
- * Gated on __APPLE__ alone (not COLI_METAL) so these three functions build and
- * are unit-testable on any macOS binary, Metal or not; the call site in main()
- * is the one that additionally requires g_metal_enabled, i.e. COLI_METAL. */
-#ifdef __APPLE__
+ * random 16K-aligned pread, no readahead. F_NOCACHE alone is NOT enough: it
+ * bypasses the cache for NEW pages but still serves already-resident ones, so
+ * a warm shard measured 22.1 GB/s of RAM and latched it as "disk". The probe
+ * therefore steers its reads to ranges mincore reports cold, and refuses to
+ * conclude anything when the file offers too few cold bytes (veto below).
+ * Gating: the whole block builds only for the one consumer (COLI_METAL on
+ * __APPLE__), so the default build carries no orphaned probe code; tests
+ * define COLI_SSD_PROBE_TEST to compile it anywhere -- the decision layer
+ * (grammar parser, cold-tile steering, veto) is pure portable C by design,
+ * exercised by tests/test_ssd_probe.c on every platform. */
+#if (defined(COLI_METAL) && defined(__APPLE__)) || defined(COLI_SSD_PROBE_TEST)
#define COLI_SSD_PROBE_BLK (4u*1024*1024) /* 4 MB reads, 16K-aligned offsets */
#define COLI_SSD_PROBE_MAXB (300*1024*1024) /* "a few hundred MB", capped on fast media */
#define COLI_SSD_PROBE_SECS 0.35 /* wall-clock budget, well under the ~1s target */
+#define COLI_SSD_PROBE_COLD_FLOOR (64ll*1024*1024) /* fewer cold bytes than this = contaminated */
+#define COLI_SSD_CACHE_MAX 64 /* longest well-formed .coli_ssd, in bytes */
+
+/* digits [ "." digits ] -- returns chars consumed, 0 = no match. The ONLY
+ * number shape the cache grammar admits (see coli_ssd_cache_parse). */
+static size_t coli_ssd_scan_number(const char *p, size_t len){
+ size_t i=0;
+ while(i<len && p[i]>='0' && p[i]<='9') i++;
+ if(!i) return 0;
+ if(i<len && p[i]=='.'){
+ size_t j=i+1;
+ while(j<len && p[j]>='0' && p[j]<='9') j++;
+ if(j==i+1) return 0; /* "5." is garbage */
+ i=j;
+ }
+ return i;
+}
+
+/* Strict .coli_ssd grammar -- mirrored byte-for-byte by resource_plan.py's
+ * parse_ssd_cache() (keep the two in lockstep; test_ssd_probe.c and
+ * test_resource_plan.py chew the same vector file,
+ * tests/fixtures/ssd_cache_vectors.txt):
+ * v2: "v2 <gbs> <st_dev>" single spaces, at most one trailing \n
+ * legacy: "<gbs>" the pre-fix format, never trusted (re-probed)
+ * where <gbs> = digits["."digits], 0 < gbs < 1000, and <st_dev> = 1..20
+ * digits fitting unsigned 64-bit. Total length <= COLI_SSD_CACHE_MAX bytes,
+ * no NULs, nothing else. Everything outside the grammar is garbage and
+ * re-probes: strtod permissiveness ("inf", "nan", "0x8", "1e99", leading
+ * whitespace/signs) is deliberately out -- it let hand-edited or corrupt
+ * caches masquerade as measurements.
+ * Returns 2 = v2 (gbs+stdev filled), 1 = legacy (gbs filled), 0 = garbage. */
+static int coli_ssd_cache_parse(const char *buf, size_t len, double *gbs_out,
+ unsigned long long *stdev_out){
+ if(!len || len>COLI_SSD_CACHE_MAX || memchr(buf,0,len)) return 0;
+ if(buf[len-1]=='\n') len--; /* at most one trailing newline */
+ int v2 = len>=3 && !memcmp(buf,"v2 ",3);
+ const char *p = buf + (v2?3:0);
+ size_t left = len - (v2?3:0);
+ size_t n = coli_ssd_scan_number(p,left);
+ if(!n) return 0;
+ char num[COLI_SSD_CACHE_MAX+1];
+ memcpy(num,p,n); num[n]=0;
+ double gbs=strtod(num,NULL); /* shape already vetted above */
+ if(!(gbs>0 && gbs<1000)) return 0;
+ p+=n; left-=n;
+ if(!v2){
+ if(left) return 0;
+ *gbs_out=gbs;
+ return 1;
+ }
+ if(!left || *p!=' ') return 0;
+ p++; left--;
+ size_t d=0;
+ while(d<left && p[d]>='0' && p[d]<='9') d++;
+ if(!d || d!=left || d>20) return 0;
+ char dev[21];
+ memcpy(dev,p,d); dev[d]=0;
+ errno=0;
+ unsigned long long sd=strtoull(dev,NULL,10);
+ if(errno) return 0; /* 20 nines overflows u64: garbage */
+ *gbs_out=gbs; *stdev_out=sd;
+ return 2;
+}
+
+/* The single writer of the grammar above: "v2 %.3f %llu\n". %.3f of a value
+ * in (0,1000) is always digits.digits, so what this writes always re-parses
+ * -- the round-trip is pinned by test_ssd_probe.c. */
+static int coli_ssd_cache_format(char *buf, size_t bufsz, double gbs,
+ unsigned long long stdev){
+ int n=snprintf(buf,bufsz,"v2 %.3f %llu\n",gbs,stdev);
+ return (n>0 && (size_t)n<bufsz) ? n : -1;
+}
+
+/* Probe steering (#386 fix round): pure, so tests inject residency vectors --
+ * no mincore, no files. vec has one byte per page_sz-sized page, mincore
+ * convention (bit 0 set = resident in RAM). The file is tiled into
+ * non-overlapping COLI_SSD_PROBE_BLK windows; a window qualifies only when
+ * EVERY page in it is non-resident, because one warm page lets the page cache
+ * serve part of a "disk" read (a fully-resident shard measured 22.1 GB/s
+ * through F_NOCACHE and latched the fast-SSD default on unknown hardware).
+ * Emits qualifying window start offsets into tiles[] (caller sizes it at
+ * file_size/BLK+1 entries) and returns the count; *cold_bytes_out gets
+ * count*BLK, the bytes the probe can trust. */
+static size_t coli_ssd_probe_cold_tiles(const unsigned char *vec, size_t npages,
+ size_t page_sz, long long *tiles,
+ long long *cold_bytes_out){
+ size_t count=0;
+ if(page_sz && page_sz<=COLI_SSD_PROBE_BLK){
+ size_t per=(COLI_SSD_PROBE_BLK+page_sz-1)/page_sz;
+ for(size_t t=0; t+per<=npages; t+=per){
+ size_t i=0;
+ while(i<per && !(vec[t+i]&1)) i++;
+ if(i==per) tiles[count++]=(long long)t*(long long)page_sz;
+ }
+ }
+ if(cold_bytes_out) *cold_bytes_out=(long long)count*COLI_SSD_PROBE_BLK;
+ return count;
+}
+/* Contamination veto (#386 fix round): with fewer than COLI_SSD_PROBE_COLD_FLOOR
+ * verified-cold bytes to read, any measurement would be mostly RAM. An
+ * untrustworthy measurement behaves as SLOW: no number, no cache write, the
+ * conservative default holds, and the probe retries on a colder startup. */
+static int coli_ssd_probe_vetoed(long long cold_bytes){
+ return cold_bytes < COLI_SSD_PROBE_COLD_FLOOR;
+}
+
+#ifdef __APPLE__
/* Path of the first *.safetensors shard in snap_dir into out, or out[0]=0 if
* none. readdir order, unsorted (unlike st_init): any shard is representative
* for a bandwidth probe, so sorting would buy nothing. */
@@ -7605,10 +7717,15 @@ static void coli_ssd_probe_pick_shard(const char *snap_dir, char *out, size_t ou
closedir(d);
}
-/* F_NOCACHE random-read probe on one real shard. Returns measured GB/s, or -1
- * if the probe could not run at all (no shard, open failure, file too small)
- * -- callers must treat -1 as "not fast", never as an error to surface. */
-static double coli_ssd_probe_raw(const char *snap_dir){
+/* F_NOCACHE random-read probe on one real shard, steered to verified-cold
+ * ranges. Returns measured GB/s, or -1 if the probe could not run (no shard,
+ * open/map failure, file too small) or was vetoed as contaminated --
+ * callers treat -1 as "not fast", never as an error to surface;
+ * *contaminated_out distinguishes the veto so the caller can say why and
+ * skip the cache write. The mmap is address space only (nothing is faulted
+ * in): it exists so mincore can fill the residency vector. */
+static double coli_ssd_probe_raw(const char *snap_dir, int *contaminated_out){
+ if(contaminated_out) *contaminated_out=0;
char path[1280];
coli_ssd_probe_pick_shard(snap_dir,path,sizeof(path));
if(!path[0]) return -1;
@@ -7618,51 +7735,97 @@ static double coli_ssd_probe_raw(const char *snap_dir){
fcntl(fd,F_RDAHEAD,0); /* random access, not sequential streaming */
struct stat st;
if(fstat(fd,&st)!=0 || st.st_size<(off_t)(COLI_SSD_PROBE_BLK*2)){ close(fd); return -1; }
- void *buf=NULL;
- if(posix_memalign(&buf,16384,COLI_SSD_PROBE_BLK)!=0 || !buf){ close(fd); return -1; }
- long long span=(long long)st.st_size-COLI_SSD_PROBE_BLK;
- unsigned seed=0xC0117125u;
- double t0=now_s(); long long total=0;
- while(now_s()-t0<COLI_SSD_PROBE_SECS && total<COLI_SSD_PROBE_MAXB){
- long long off=((long long)rand_r(&seed)*16384LL)%(span>0?span:1);
- off&=~(long long)16383;
- ssize_t got=pread(fd,buf,COLI_SSD_PROBE_BLK,off);
- if(got<=0) break;
- total+=got;
+ size_t page_sz=(size_t)getpagesize();
+ size_t npages=((size_t)st.st_size+page_sz-1)/page_sz;
+ unsigned char *vec=malloc(npages);
+ long long *tiles=malloc(((size_t)st.st_size/COLI_SSD_PROBE_BLK+1)*sizeof *tiles);
+ void *map=(vec&&tiles)?mmap(NULL,(size_t)st.st_size,PROT_READ,MAP_SHARED,fd,0):MAP_FAILED;
+ double gbs=-1;
+ if(map!=MAP_FAILED && mincore(map,(size_t)st.st_size,(char*)vec)==0){
+ long long cold_bytes=0;
+ size_t ntiles=coli_ssd_probe_cold_tiles(vec,npages,page_sz,tiles,&cold_bytes);
+ if(coli_ssd_probe_vetoed(cold_bytes)){
+ if(contaminated_out) *contaminated_out=1;
+ }else{
+ void *buf=NULL;
+ if(posix_memalign(&buf,16384,COLI_SSD_PROBE_BLK)!=0) buf=NULL;
+ if(buf){
+ unsigned seed=0xC0117125u;
+ double t0=now_s(); long long total=0;
+ while(now_s()-t0<COLI_SSD_PROBE_SECS && total<COLI_SSD_PROBE_MAXB){
+ long long off=tiles[(size_t)rand_r(&seed)%ntiles];
+ ssize_t got=pread(fd,buf,COLI_SSD_PROBE_BLK,off);
+ if(got<=0) break;
+ total+=got;
+ }
+ double dt=now_s()-t0;
+ if(total>0 && dt>0) gbs=(double)total/1e9/dt;
+ free(buf);
+ }
+ }
}
- double dt=now_s()-t0;
- free(buf); close(fd);
- return (total>0 && dt>0) ? (double)total/1e9/dt : -1;
+ if(map!=MAP_FAILED) munmap(map,(size_t)st.st_size);
+ free(tiles); free(vec);
+ close(fd);
+ return gbs;
}
-/* Cache the measurement in <snap>/.coli_ssd (plain-text GB/s) so every startup
- * after the first reads a file instead of re-probing. A missing or unparsable
- * cache re-probes -- never trust a corrupt number over a fresh read. */
+/* Cache the measurement in <snap>/.coli_ssd so every startup after the first
+ * reads a file instead of re-probing. v2 records the volume's identity
+ * ("v2 <gbs> <st_dev>"): a cache is trusted ONLY when it parses under the
+ * strict grammar above AND its st_dev matches the model dir's current device
+ * -- a dir rsync'd to another volume (external drive, RAM disk) carries a
+ * measurement of the WRONG hardware and must re-probe. Legacy bare-number
+ * caches (written before steering existed, so possibly warm-contaminated)
+ * re-probe once and upgrade to v2. A vetoed run writes nothing and says why
+ * on stderr; the probe retries naturally on the next, colder, startup. */
static double coli_ssd_probe_cached(const char *snap_dir){
- char cpath[1280];
+ char cpath[1290];
snprintf(cpath,sizeof(cpath),"%s/.coli_ssd",snap_dir);
+ struct stat dst;
+ unsigned long long cur_dev = stat(snap_dir,&dst)==0 ? (unsigned long long)dst.st_dev : 0;
FILE *f=fopen(cpath,"r");
if(f){
- double cached=-1;
- int ok=fscanf(f,"%lf",&cached)==1 && cached>=0;
+ char buf[COLI_SSD_CACHE_MAX+2];
+ size_t n=fread(buf,1,sizeof(buf),f);
fclose(f);
- if(ok) return cached;
- }
- double gbs=coli_ssd_probe_raw(snap_dir);
- if(gbs>=0){
- /* tmp+rename, like stats_dump_q: the model dir is shared (a concurrent
- * serve + run pair may both probe a virgin dir) and a torn write must
- * never survive. Two racing probers both measure under mutual
- * contention -- a LOW reading, which is the safe direction: the
- * platform default just stays off. */
- char tpath[1290];
- snprintf(tpath,sizeof(tpath),"%s.tmp",cpath);
- FILE *w=fopen(tpath,"w");
- if(w){ fprintf(w,"%.3f\n",gbs); fclose(w); rename(tpath,cpath); }
+ double cached=0; unsigned long long sdev=0;
+ if(coli_ssd_cache_parse(buf,n,&cached,&sdev)==2 && sdev==cur_dev)
+ return cached;
+ /* v2 from another volume, legacy, or garbage: fall through, re-measure */
+ }
+ int contaminated=0;
+ double gbs=coli_ssd_probe_raw(snap_dir,&contaminated);
+ if(contaminated){
+ fprintf(stderr,"METAL: storage probe deferred -- the shard is already page-cache resident "
+ "(<%lld MB cold), a read now would measure RAM, not the disk; keeping the "
+ "conservative cache default, will re-measure on a cold start\n",
+ COLI_SSD_PROBE_COLD_FLOOR/(1024*1024));
+ return -1;
+ }
+ char line[COLI_SSD_CACHE_MAX+1];
+ if(gbs>0 && gbs<1000 && coli_ssd_cache_format(line,sizeof(line),gbs,cur_dev)>0){
+ /* mkstemp (unique name, O_EXCL) + rename: the model dir is shared (a
+ * concurrent serve + run pair may both probe a virgin dir) so a torn
+ * write must never survive, and a fixed, predictable temp name could
+ * be pre-planted as a symlink -- mkstemp cannot follow one. Two
+ * racing probers both measure under mutual contention: a LOW reading,
+ * the safe direction (the platform default just stays off). */
+ char tpath[1310];
+ snprintf(tpath,sizeof(tpath),"%s.XXXXXX",cpath);
+ int tfd=mkstemp(tpath);
+ if(tfd>=0){
+ size_t len=strlen(line);
+ int ok = write(tfd,line,len)==(ssize_t)len;
+ ok = fchmod(tfd,0644)==0 && ok; /* mkstemp's 0600 would hide it from group readers */
+ close(tfd);
+ if(!ok || rename(tpath,cpath)!=0) unlink(tpath);
+ }
}
return gbs;
}
#endif /* __APPLE__ */
+#endif /* (COLI_METAL && __APPLE__) || COLI_SSD_PROBE_TEST */
/* Expert-cache-cap precedence (#379, S2): explicit CLI positional > explicit
* CAP env > platform default (Metal + darwin + fast SSD) > historic default.
@@ -8037,7 +8200,8 @@ int main(int argc, char **argv){
* cache the result in the model dir, and let it set the cap/CAP_RAISE
* defaults -- never an explicit --cap/CAP/CAP_RAISE, per coli_resolve_cap()
* above. Silent when the probe ran but storage was slow (defaults unchanged);
- * one stderr line when the platform default actually engages. */
+ * one stderr line when the platform default actually engages, one when a
+ * contaminated (page-cache-warm) measurement is vetoed and deferred. */
double coli_ssd_gbs = -1;
#if defined(COLI_METAL) && defined(__APPLE__)
if(g_metal_enabled){
diff --git a/c/tests/fixtures/ssd_cache_vectors.txt b/c/tests/fixtures/ssd_cache_vectors.txt
new file mode 100644
index 00000000..29c95932
--- /dev/null
+++ b/c/tests/fixtures/ssd_cache_vectors.txt
@@ -0,0 +1,79 @@
+# .coli_ssd cache-grammar vectors (#379/#386) -- the SINGLE source of truth for
+# the strict grammar both readers must implement byte-for-byte:
+# C: colibri.c coli_ssd_cache_parse() (chewed by tests/test_ssd_probe.c)
+# Python: resource_plan.py parse_ssd_cache() (chewed by tests/test_resource_plan.py)
+# Add a vector here and BOTH suites pick it up; a reader change that is not
+# mirrored in the other language fails its half of the suite.
+#
+# Format, tab-separated fields:
+# v2 <gbs> <st_dev> <payload> payload must parse as v2 with these values
+# legacy <gbs> <payload> payload must parse as the legacy bare number
+# garbage <payload> payload must be rejected (re-probe / None)
+# Payload escapes: \n newline, \r CR, \t tab, \0 NUL, \s space, \\ backslash.
+# Spaces may also appear literally except at the payload's edges.
+
+# --- valid v2 -----------------------------------------------------------
+v2 9.742 16777233 v2 9.742 16777233\n
+v2 9.742 16777233 v2 9.742 16777233
+v2 0.001 0 v2 0.001 0\n
+v2 999.999 18446744073709551615 v2 999.999 18446744073709551615\n
+v2 8 42 v2 8 42\n
+v2 9.5 7 v2 0009.500 0000007\n
+
+# --- valid legacy (recognized, but the engine still re-probes + upgrades) ---
+legacy 22.139 22.139\n
+legacy 9.742 9.742
+legacy 8 8\n
+legacy 0.5 0.5\n
+# 63 digits + newline = 64 bytes, exactly at the length cap
+legacy 9 000000000000000000000000000000000000000000000000000000000000009\n
+
+# --- garbage: empty / whitespace ----------------------------------------
+garbage
+garbage \n
+garbage \s9.5\n
+garbage 9.5\s\n
+garbage 9.5\t\n
+garbage 9.5\r\n
+garbage 9.5\n\n
+# --- garbage: strtod-isms the strict grammar bans ------------------------
+garbage inf\n
+garbage -inf\n
+garbage nan\n
+garbage INF\n
+garbage 1e3\n
+garbage 0x8\n
+garbage +9.5\n
+garbage -9.5\n
+# --- garbage: malformed numbers ------------------------------------------
+garbage 5.\n
+garbage .5\n
+garbage 9,5\n
+garbage 9.5.1\n
+garbage 9.5 junk\n
+# --- garbage: out-of-range gbs -------------------------------------------
+garbage 0\n
+garbage 0.000\n
+garbage 1000\n
+garbage 1000.0\n
+garbage v2 0 1\n
+garbage v2 1000 1\n
+garbage v2 inf 1\n
+# --- garbage: malformed v2 ------------------------------------------------
+garbage v2 9.5\n
+garbage v2 9.5 \n
+garbage v2 9.5 16777233 extra\n
+garbage v2\s\s9.5 1\n
+garbage V2 9.5 1\n
+garbage v2\t9.5\t1\n
+garbage v2 9.5 -1\n
+garbage v2 9.5 1.5\n
+garbage v2 9.5 1e3\n
+garbage v2 9.5 1\n\n
+# --- garbage: st_dev beyond unsigned 64-bit or beyond 20 digits -----------
+garbage v2 9.5 18446744073709551616\n
+garbage v2 9.5 99999999999999999999\n
+garbage v2 9.5 123456789012345678901\n
+# --- garbage: length cap (64 digits + newline = 65 bytes) and NULs ---------
+garbage 0000000000000000000000000000000000000000000000000000000000000009\n
+garbage 9.5\0junk\n
diff --git a/c/tests/test_ssd_probe.c b/c/tests/test_ssd_probe.c
new file mode 100644
index 00000000..df78c68a
--- /dev/null
+++ b/c/tests/test_ssd_probe.c
@@ -0,0 +1,289 @@
+/* test_ssd_probe.c -- #379/#386 storage-probe hardening contract.
+ *
+ * Pins the probe's decision layer, which is pure C by design (colibri.c):
+ * - coli_ssd_cache_parse(): the STRICT .coli_ssd grammar, driven by the
+ * shared vector file tests/fixtures/ssd_cache_vectors.txt so the C reader
+ * and the Python reader (resource_plan.parse_ssd_cache, pinned by
+ * test_resource_plan.py over the SAME vectors) cannot drift apart.
+ * - coli_ssd_cache_format() -> parse round-trip: what the writer emits, the
+ * reader trusts.
+ * - coli_ssd_probe_cold_tiles() + coli_ssd_probe_vetoed(): cold-range
+ * steering and the contamination veto over injected residency vectors --
+ * all-cold, all-warm, mixed, and exactly-at-floor, no mincore, no files.
+ * On __APPLE__ it additionally exercises coli_ssd_probe_cached() end-to-end
+ * against a scratch dir: v2-with-matching-st_dev is trusted without touching
+ * any shard; mismatched st_dev, legacy and garbage caches all fall through to
+ * a re-probe; and a freshly written (page-cache-warm) shard is VETOED -- no
+ * cache file is written and no bandwidth number escapes.
+ * Portable: the pure layer builds and runs on every platform, same as
+ * test_cap_precedence.c. */
+#define COLI_SSD_PROBE_TEST 1
+#define main coli_glm_main_unused
+#include "../colibri.c"
+#undef main
+
+static int failures = 0;
+
+#define CHECK(cond, ...) do{ if(!(cond)){ fprintf(stderr,"FAIL "); fprintf(stderr,__VA_ARGS__); fprintf(stderr,"\n"); failures++; } }while(0)
+
+/* ---- shared grammar vectors ------------------------------------------- */
+
+/* \n \r \t \0 \s \\ unescape; returns payload length (may contain NULs). */
+static size_t unescape(const char *in, char *out, size_t outsz){
+ size_t n=0;
+ for(size_t i=0; in[i] && n+1<outsz; i++){
+ char c=in[i];
+ if(c=='\\' && in[i+1]){
+ i++;
+ switch(in[i]){
+ case 'n': c='\n'; break;
+ case 'r': c='\r'; break;
+ case 't': c='\t'; break;
+ case '0': c='\0'; break;
+ case 's': c=' '; break;
+ case '\\': c='\\'; break;
+ default: fprintf(stderr,"FAIL bad escape \\%c in vector file\n",in[i]); failures++; break;
+ }
+ }
+ out[n++]=c;
+ }
+ return n;
+}
+
+static void run_vectors(void){
+ FILE *f=fopen("tests/fixtures/ssd_cache_vectors.txt","r");
+ if(!f){ perror("tests/fixtures/ssd_cache_vectors.txt"); failures++; return; }
+ char line[512];
+ int nvec=0;
+ while(fgets(line,sizeof(line),f)){
+ size_t len=strlen(line);
+ if(len && line[len-1]=='\n') line[--len]=0;
+ if(!len || line[0]=='#') continue;
+ /* fields are tab-separated; the payload is everything after the last
+ * expectation field and may itself contain literal spaces */
+ char *kind=line;
+ char *f1=strchr(line,'\t'); if(f1) *f1++=0;
+ char payload[256]; size_t plen=0;
+ double want_gbs=0; unsigned long long want_dev=0; int want_kind=0;
+ if(!strcmp(kind,"garbage")){
+ want_kind=0;
+ plen = f1 ? unescape(f1,payload,sizeof(payload)) : 0;
+ }else if(!strcmp(kind,"legacy")){
+ want_kind=1;
+ char *f2=f1?strchr(f1,'\t'):NULL;
+ if(!f1||!f2){ CHECK(0,"vector line malformed: %s",kind); continue; }
+ *f2++=0;
+ want_gbs=strtod(f1,NULL);
+ plen=unescape(f2,payload,sizeof(payload));
+ }else if(!strcmp(kind,"v2")){
+ want_kind=2;
+ char *f2=f1?strchr(f1,'\t'):NULL;
+ char *f3=f2?strchr(f2+1,'\t'):NULL;
+ if(!f1||!f2||!f3){ CHECK(0,"vector line malformed: %s",kind); continue; }
+ *f2++=0; *f3++=0;
+ want_gbs=strtod(f1,NULL);
+ want_dev=strtoull(f2,NULL,10);
+ plen=unescape(f3,payload,sizeof(payload));
+ }else{
+ CHECK(0,"unknown vector kind: %s",kind);
+ continue;
+ }
+ double gbs=0; unsigned long long dev=0;
+ int got=coli_ssd_cache_parse(payload,plen,&gbs,&dev);
+ CHECK(got==want_kind,"vector %d (%s, %zu bytes): kind %d, want %d",nvec,kind,plen,got,want_kind);
+ if(got==want_kind && want_kind>=1)
+ CHECK(gbs==want_gbs,"vector %d: gbs %.6f, want %.6f",nvec,gbs,want_gbs);
+ if(got==want_kind && want_kind==2)
+ CHECK(dev==want_dev,"vector %d: st_dev %llu, want %llu",nvec,dev,want_dev);
+ nvec++;
+ }
+ fclose(f);
+ CHECK(nvec>=40,"vector file suspiciously short: %d vectors",nvec);
+ fprintf(stderr,"grammar vectors: %d checked\n",nvec);
+}
+
+/* ---- writer -> reader round-trip --------------------------------------- */
+
+static void run_roundtrip(void){
+ static const double vals[]={0.001,0.5,4.0,8.894,9.742,22.139,999.999};
+ static const unsigned long long devs[]={0,1,16777233,18446744073709551615ull};
+ for(size_t i=0;i<sizeof(vals)/sizeof(*vals);i++)
+ for(size_t j=0;j<sizeof(devs)/sizeof(*devs);j++){
+ char buf[COLI_SSD_CACHE_MAX+1];
+ int n=coli_ssd_cache_format(buf,sizeof(buf),vals[i],devs[j]);
+ CHECK(n>0,"format(%.3f,%llu) failed",vals[i],devs[j]);
+ if(n<=0) continue;
+ double gbs=0; unsigned long long dev=0;
+ int kind=coli_ssd_cache_parse(buf,(size_t)n,&gbs,&dev);
+ CHECK(kind==2,"round-trip '%s': kind %d",buf,kind);
+ /* the writer rounds to %.3f; the reader must return exactly that */
+ CHECK(kind==2 && dev==devs[j] && gbs>0 && gbs<1000
+ && (gbs>vals[i]-0.0005 && gbs<vals[i]+0.0005),
+ "round-trip '%s': gbs %.6f dev %llu (want ~%.3f %llu)",
+ buf,gbs,dev,vals[i],devs[j]);
+ }
+}
+
+/* ---- steering + veto over injected residency vectors ------------------- */
+
+#define PG 16384u /* Apple Silicon page size */
+#define PER (COLI_SSD_PROBE_BLK/PG) /* 256 pages per 4MB tile */
+
+static void run_steering(void){
+ enum { NT=20 }; /* 20 tiles = 80 MB */
+ size_t npages=(size_t)NT*PER;
+ unsigned char *vec=calloc(npages+PER,1);
+ long long tiles[NT+2]; long long cold=0; size_t n;
+
+ /* all-cold: every tile qualifies, offsets are the tile starts, no veto */
+ n=coli_ssd_probe_cold_tiles(vec,npages,PG,tiles,&cold);
+ CHECK(n==NT,"all-cold: %zu tiles, want %d",n,NT);
+ CHECK(cold==(long long)NT*COLI_SSD_PROBE_BLK,"all-cold: cold_bytes %lld",cold);
+ CHECK(!coli_ssd_probe_vetoed(cold),"all-cold must not veto");
+ for(size_t i=0;i<n;i++)
+ CHECK(tiles[i]==(long long)i*COLI_SSD_PROBE_BLK,"all-cold: tile %zu at %lld",i,tiles[i]);
+
+ /* all-warm: nothing qualifies -> veto */
+ memset(vec,1,npages);
+ n=coli_ssd_probe_cold_tiles(vec,npages,PG,tiles,&cold);
+ CHECK(n==0 && cold==0,"all-warm: %zu tiles, cold %lld",n,cold);
+ CHECK(coli_ssd_probe_vetoed(cold),"all-warm must veto");
+
+ /* mixed: ONE warm page poisons its whole tile (a 4MB read across it would
+ * be part RAM); warm page in tile 0 and tile 5 -> 18 qualifying tiles,
+ * none of them at offset 0 or 5*4MB */
+ memset(vec,0,npages);
+ vec[3]=1; vec[5*PER+PER/2]=1;
+ n=coli_ssd_probe_cold_tiles(vec,npages,PG,tiles,&cold);
+ CHECK(n==NT-2,"mixed: %zu tiles, want %d",n,NT-2);
+ for(size_t i=0;i<n;i++)
+ CHECK(tiles[i]!=0 && tiles[i]!=5ll*COLI_SSD_PROBE_BLK,"mixed: poisoned tile %lld selected",tiles[i]);
+ CHECK(!coli_ssd_probe_vetoed(cold),"mixed with 72MB cold must not veto");
+
+ /* exactly at the floor: 16 cold tiles = 64 MB passes, 15 = 60 MB vetoes */
+ memset(vec,1,npages);
+ for(size_t t=0;t<16;t++) memset(vec+t*PER,0,PER);
+ n=coli_ssd_probe_cold_tiles(vec,npages,PG,tiles,&cold);
+ CHECK(n==16 && cold==COLI_SSD_PROBE_COLD_FLOOR,"floor: %zu tiles, cold %lld",n,cold);
+ CHECK(!coli_ssd_probe_vetoed(cold),"exactly-at-floor (64MB) must not veto");
+ memset(vec+15*PER,1,PER);
+ n=coli_ssd_probe_cold_tiles(vec,npages,PG,tiles,&cold);
+ CHECK(n==15,"floor-1: %zu tiles",n);
+ CHECK(coli_ssd_probe_vetoed(cold),"one tile below the floor must veto");
+
+ /* partial tail tile (npages not a multiple of PER) is never selected:
+ * a short window cannot supply a full 4MB read */
+ memset(vec,0,npages+PER/2);
+ n=coli_ssd_probe_cold_tiles(vec,npages+PER/2,PG,tiles,&cold);
+ CHECK(n==NT,"partial tail: %zu tiles, want %d",n,NT);
+
+ /* 4K pages (Intel macs): 1024 pages per tile, same tiling */
+ n=coli_ssd_probe_cold_tiles(vec,3*(COLI_SSD_PROBE_BLK/4096),4096,tiles,&cold);
+ CHECK(n==3,"4K pages: %zu tiles, want 3",n);
+
+ free(vec);
+}
+
+/* ---- end-to-end cache decisions (darwin: real files, no real model) ----- */
+#ifdef __APPLE__
+static void write_file(const char *dir, const char *name, const char *data){
+ char p[1400]; snprintf(p,sizeof(p),"%s/%s",dir,name);
+ FILE *f=fopen(p,"w");
+ if(!f){ perror(p); failures++; return; }
+ fputs(data,f); fclose(f);
+}
+
+static int read_file(const char *dir, const char *name, char *out, size_t outsz){
+ char p[1400]; snprintf(p,sizeof(p),"%s/%s",dir,name);
+ FILE *f=fopen(p,"r");
+ if(!f) return -1;
+ size_t n=fread(out,1,outsz-1,f); out[n]=0; fclose(f);
+ return (int)n;
+}
+
+static void run_cached_decisions(void){
+ const char *tmp=getenv("TMPDIR");
+ char dirbuf[1200];
+ snprintf(dirbuf,sizeof(dirbuf),"%s/coli_ssd_probe_test.XXXXXX",
+ (tmp && strlen(tmp)<1100) ? tmp : "/tmp");
+ if(!mkdtemp(dirbuf)){ perror("mkdtemp"); failures++; return; }
+ struct stat st;
+ if(stat(dirbuf,&st)!=0){ failures++; return; }
+ unsigned long long dev=(unsigned long long)st.st_dev;
+ char cache[128], back[160];
+
+ /* v2 + matching st_dev: trusted as-is -- no shard is even needed */
+ snprintf(cache,sizeof(cache),"v2 7.500 %llu\n",dev);
+ write_file(dirbuf,".coli_ssd",cache);
+ double got=coli_ssd_probe_cached(dirbuf);
+ CHECK(got==7.5,"matching v2 cache: got %.3f, want 7.500",got);
+
+ /* v2 from another volume: NOT trusted -> re-probe (no shard here, so the
+ * probe cannot run and reports -1); the stale cache file is left in place */
+ snprintf(cache,sizeof(cache),"v2 7.500 %llu\n",dev+1);
+ write_file(dirbuf,".coli_ssd",cache);
+ got=coli_ssd_probe_cached(dirbuf);
+ CHECK(got==-1,"foreign-volume v2 cache must re-probe: got %.3f",got);
+
+ /* legacy bare number: NOT trusted -> re-probe (the upgrade-to-v2 write
+ * happens only when the re-probe succeeds; grammar + round-trip above pin
+ * the upgraded format) */
+ write_file(dirbuf,".coli_ssd","9.500\n");
+ got=coli_ssd_probe_cached(dirbuf);
+ CHECK(got==-1,"legacy cache must re-probe: got %.3f",got);
+
+ /* garbage: NOT trusted -> re-probe */
+ write_file(dirbuf,".coli_ssd","inf\n");
+ got=coli_ssd_probe_cached(dirbuf);
+ CHECK(got==-1,"garbage cache must re-probe: got %.3f",got);
+
+ /* contamination veto, end to end: a freshly WRITTEN 80MB shard is page-
+ * cache resident, so the probe must refuse to measure it -- and must NOT
+ * write any .coli_ssd */
+ {
+ char p[1400]; snprintf(p,sizeof(p),"%s/out-00000.safetensors",dirbuf);
+ FILE *f=fopen(p,"w");
+ if(f){
+ char *mb=malloc(1024*1024);
+ memset(mb,0xA5,1024*1024);
+ for(int i=0;i<80;i++) fwrite(mb,1,1024*1024,f);
+ free(mb); fclose(f);
+ char cp[1400]; snprintf(cp,sizeof(cp),"%s/.coli_ssd",dirbuf);
+ unlink(cp); /* start with no cache at all */
+ int contaminated=0;
+ double raw=coli_ssd_probe_raw(dirbuf,&contaminated);
+ if(!contaminated){
+ /* the OS evicted a fresh 80MB write already? environment too
+ * unusual to assert on -- report and move on, the pure veto
+ * tests above still hold the line */
+ fprintf(stderr,"note: fresh shard not resident (raw=%.3f), skipping veto e2e\n",raw);
+ }else{
+ CHECK(raw==-1,"vetoed raw probe must report -1: got %.3f",raw);
+ got=coli_ssd_probe_cached(dirbuf);
+ CHECK(got==-1,"vetoed cached probe must report -1: got %.3f",got);
+ CHECK(read_file(dirbuf,".coli_ssd",back,sizeof(back))==-1,
+ "vetoed probe must not write .coli_ssd (found: %s)",back);
+ }
+ unlink(p);
+ }
+ }
+ /* scrub the scratch dir */
+ char cp[1400]; snprintf(cp,sizeof(cp),"%s/.coli_ssd",dirbuf);
+ unlink(cp); rmdir(dirbuf);
+}
+#endif /* __APPLE__ */
+
+int main(void){
+ run_vectors();
+ run_roundtrip();
+ run_steering();
+#ifdef __APPLE__
+ run_cached_decisions();
+#endif
+ if(failures){
+ fprintf(stderr,"ssd probe tests: %d FAILURE(S)\n",failures);
+ return 1;
+ }
+ puts("ssd probe tests: ok");
+ return 0;
+}