fix(cli): -s seed flag was documented but not implemented

The CLI's --help text has long advertised "-s <seed>  Random seed
(default: 42)", but tools/quant.c had no parser case for -s and
src/engine/tq_generate.c hardcoded `unsigned long long rng_state = 42`
in two places. As a result, passing -s 1337 silently fell through
to the positional-arg branch, getting parsed as the model path:

  $ ./build_metal/quant model.gguf -p "..." -n 32 -T 0.7 -s 1337
  Loading model from 1337...
  tq_load_model: cannot open '1337'
  Failed to load model

Discovered while running the cliff-cell seed sweep for the
working-memory-cliff tech report (Phase 1B), where 60 of 60
attempted sampled trials degenerated to "model path = <seed>".

This commit:

1. Adds `unsigned long long rng_seed` to tq_gen_config_t in both
   include/turboquant/tq_engine.h and quant.h (the single header
   used by embedded users via QUANT_IMPLEMENTATION).
2. Initialises rng_seed to 42ULL in tq_default_gen_config (in both
   src/engine/tq_ops.c and quant.h).
3. Wires rng_state from config->rng_seed in tq_generate (both
   src/engine/tq_generate.c and quant.h), with a `?: 42ULL` fallback
   so legacy callers that never set rng_seed get bit-identical
   behaviour.
4. Adds the -s parser case in tools/quant.c, with `0 -> 42` reserved
   for "use default" so the documented default is preserved.
5. Adds build_metal/ to .gitignore alongside the existing
   build_nomt/ and build_nometal/ entries.

Backwards compatibility: zero behaviour change for any caller that
doesn't pass -s. Same RNG state, same first sampled token, same
output bit-for-bit. Verified by running both with and without -s 42
on Llama-3.2-1B-Q8_0 at T=0.7 and confirming identical output. Also
verified -s 42 vs -s 1337 produce *different* outputs (the test
that was previously impossible).

All 35 tests in build_metal/ pass after the change.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: unamedkr

.gitignore

@@ -63,6 +63,7 @@ tq_run.dSYM/
 docs/assets/hero_backup.png
 build_nomt/
 build_nometal/
+build_metal/
 
 .env
 

include/turboquant/tq_engine.h

@@ -383,6 +383,7 @@ typedef struct {
     int n_threads;
     float rep_penalty;    /* repetition penalty (default: 1.1, 1.0 = disabled) */
     int rep_window;       /* how many recent tokens to penalize (default: 32) */
+    unsigned long long rng_seed; /* sampling seed (default: 42, 0 = use 42 for back-compat) */
     /* KV cache persistence (Document-Level RAG: read once, query forever) */
     const char* save_kv_path; /* save KV cache after generation (NULL = don't save) */
     const char* load_kv_path; /* load pre-computed KV cache before generation (NULL = normal) */

quant.h

@@ -866,6 +866,7 @@ typedef struct {
     int n_threads;
     float rep_penalty;    /* repetition penalty (default: 1.1, 1.0 = disabled) */
     int rep_window;       /* how many recent tokens to penalize (default: 32) */
+    unsigned long long rng_seed; /* sampling seed (default: 42, 0 = use 42 for back-compat) */
     /* Callback for streaming output */
     void (*on_token)(const char* text, void* user_data);
     void* user_data;
@@ -4129,6 +4130,7 @@ tq_gen_config_t tq_default_gen_config(void) {
     config.n_threads = 1;
     config.rep_penalty = 1.1f;
     config.rep_window = 32;
+    config.rng_seed = 42ULL;
     config.on_token = NULL;
     config.user_data = NULL;
     return config;
@@ -15453,9 +15455,11 @@ int tq_generate(tq_model_t* model, tq_tokenizer_t* tokenizer,
         }
     }
 
-    /* Sample first generated token */
+    /* Sample first generated token. The seed is configurable via
+     * config->rng_seed (default 42); 0 falls back to 42 so existing
+     * callers that never set rng_seed get bit-identical behaviour. */
     int pos = n_prompt;
-    unsigned long long rng_state = 42;
+    unsigned long long rng_state = config->rng_seed ? config->rng_seed : 42ULL;
     int next_token = tq_sample_topp(state->logits, vocab_size,
                                      config->temperature, config->top_p,
                                      &rng_state);

src/engine/tq_generate.c

@@ -359,9 +359,12 @@ int tq_generate(tq_model_t* model, tq_tokenizer_t* tokenizer,
         }
     }
 
-    /* Sample first generated token */
+    /* Sample first generated token. The seed is configurable via
+     * config->rng_seed to support reproducible sampling sweeps; 0 falls
+     * back to the historical default of 42 so existing callers that
+     * never set rng_seed get bit-identical behaviour. */
     int pos = pos_after_prefill;
-    unsigned long long rng_state = 42;
+    unsigned long long rng_state = config->rng_seed ? config->rng_seed : 42ULL;
     int next_token = tq_sample_topp(state->logits, vocab_size,
                                      config->temperature, config->top_p,
                                      &rng_state);

src/engine/tq_ops.c

@@ -1682,6 +1682,7 @@ tq_gen_config_t tq_default_gen_config(void) {
     config.n_threads = 1;
     config.rep_penalty = 1.1f;
     config.rep_window = 32;
+    config.rng_seed = 42ULL;
     config.on_token = NULL;
     config.user_data = NULL;
     return config;

tools/quant.c

@@ -199,6 +199,7 @@ int main(int argc, char** argv) {
     const char* kl_baseline_file = NULL;
     const char* save_kv_file = NULL;   /* --save-kv: save KV cache after generation */
     const char* load_kv_file = NULL;   /* --load-kv: load pre-computed KV cache */
+    unsigned long long rng_seed = 42ULL; /* -s <seed>: sampling RNG seed */
 
     for (int i = 1; i < argc; i++) {
         if (argv[i][0] != '-') {
@@ -229,6 +230,9 @@ int main(int argc, char** argv) {
             }
         } else if (strcmp(argv[i], "-j") == 0 && i + 1 < argc) {
             n_threads = atoi(argv[++i]);
+        } else if (strcmp(argv[i], "-s") == 0 && i + 1 < argc) {
+            rng_seed = strtoull(argv[++i], NULL, 10);
+            if (rng_seed == 0ULL) rng_seed = 42ULL; /* 0 reserved for "use default" */
         } else if (strcmp(argv[i], "-q") == 0) {
             if (i + 1 < argc && argv[i + 1][0] != '-') {
                 const char* qarg = argv[++i];
@@ -1265,6 +1269,7 @@ int main(int argc, char** argv) {
     config.k_highres_window = k_highres_window;
     config.save_kv_path = save_kv_file;
     config.load_kv_path = load_kv_file;
+    config.rng_seed = rng_seed;
     config.on_token = print_token;
     config.user_data = NULL;