fix: close the fail-loud gaps the docs audit found

Three defects surfaced by executing every documented example:

distill_forecast silently ignored unknown option keys (it reads values
via json_extract with no closed key list), so a misspelled option
trained a student with defaults instead of erroring. It now validates
against a closed key list through the shared options parser before
extraction, matching every other operation's contract.

predict() with a distilled student silently ignored a non-NULL
train_query: the caller thinks their conditioning rows matter and they
do not. A student named alongside a train_query is now rejected
(PREDICT_ERR_OPTIONS) with the fix in the message; NULL serves as
before.

backtest's model error message omitted tsb from the accepted list even
though tsb is accepted.

Regression tests for the first two; the interim doc qualifications
("distill_forecast is the one exception", "the query is not read") are
reverted to the strict contract they now describe. 185/220 tests pass
on plain/onnx builds, ASan clean, amalgamation compiles, site builds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: mstrathman

predict-distill.c

@@ -1986,6 +1986,23 @@ static int fdistill_train_teacher(sqlite3 *db, const char *tq,
 }
 #endif /* SQLITE_PREDICT_ONNX */
 
+/* distill_forecast option keys. Values are extracted with json_extract
+ * below; this closed list exists so an unknown or misspelled key fails
+ * loudly (the same contract as every other operation) instead of being
+ * silently ignored. */
+static const char *const FCST_DIST_OPTION_KEYS[] = {
+    "context", "horizon", "student_id", "hidden",
+    "epochs",  "lr",      "teacher",    "quantiles", NULL};
+
+static int fdist_opt_validate_cb(void *ctx, const char *key,
+                                 sqlite3_value *value, char **errmsg) {
+  UNUSED_PARAMETER(ctx);
+  UNUSED_PARAMETER(key);
+  UNUSED_PARAMETER(value);
+  UNUSED_PARAMETER(errmsg);
+  return 0; /* keys validated by the parser; values read via json_extract */
+}
+
 /* ---- distill_forecast vtab ---- */
 
 #define FD_MODEL 0
@@ -2110,6 +2127,17 @@ static int fd_filter(sqlite3_vtab_cursor *pCur, int idxNum, const char *idxStr,
   if (!tq)
     FD_FAIL("%s: train_query is required", PREDICT_ERR_SCHEMA);
   {
+    /* reject unknown option keys before extracting the known ones */
+    char *operr = NULL;
+    if (predict0_options_parse(db, options, FCST_DIST_OPTION_KEYS,
+                               fdist_opt_validate_cb, NULL, &operr)) {
+      sqlite3_free(vtab->base.zErrMsg);
+      vtab->base.zErrMsg = operr;
+      sqlite3_free(student_id);
+      sqlite3_free(levels);
+      sqlite3_free(teacher);
+      return SQLITE_ERROR;
+    }
     sqlite3_stmt *op = NULL;
     if (sqlite3_prepare_v2(
             db,

predict-forecast.c

@@ -2532,7 +2532,7 @@ static int bt_filter(sqlite3_vtab_cursor *pCur, int idxNum, const char *idxStr,
   if (!is_auto && !fixed_model) {
     int rc = bt_error(cur, PREDICT_ERR_MODEL_NOT_FOUND,
                       "backtest() supports the statistical models "
-                      "(theta-classic, stub-seasonal-naive) or auto: ",
+                      "(theta-classic, stub-seasonal-naive, tsb) or auto: ",
                       opts.model);
     forecast_opts_free(&opts);
     return rc;

predict-tabular.c

@@ -395,6 +395,16 @@ static int pr_filter(sqlite3_vtab_cursor *pCur, int idxNum,
       return rc;
     }
     if (m.runtime && strcmp(m.runtime, "tree") == 0) {
+      if (train_sql) {
+        /* a student carries its training in its blob; a train_query
+         * here would be silently ignored, so reject it loudly */
+        predict0_model_row_free(&m);
+        rc = pr_error(cur, PREDICT_ERR_OPTIONS,
+                      "a distilled student takes no train_query; pass NULL: ",
+                      model_id);
+        pred_opts_free(&opts);
+        return rc;
+      }
       rc = run_student(cur, db, model_id, apply_sql, &m, &opts);
     } else if (m.runtime && strcmp(m.runtime, "onnx") == 0) {
 #ifdef SQLITE_PREDICT_ONNX

tests/test_distill.py

@@ -436,3 +436,17 @@ def test_corrupt_student_blob_errors_not_crashes(db):
             db.execute("SELECT * FROM predict(NULL,'SELECT id, f1, f2 FROM a',"
                        " json_object('model','bad'))").fetchall()
         assert "PREDICT_ERR" in str(e.value)
+
+
+def test_student_rejects_train_query(db):
+    # a student carries its training in its blob: a train_query alongside
+    # it would be dead weight, so it is rejected, never silently ignored
+    db.execute("CREATE TABLE tt(f1 REAL, f2 REAL, label TEXT)")
+    db.executemany("INSERT INTO tt VALUES (?,?,?)",
+                   [(i * 0.3, (i * 7) % 5, "c%d" % (i % 2)) for i in range(60)])
+    db.execute("SELECT * FROM distill_predict('SELECT f1, f2, label FROM tt',"
+               " '{\"target\":\"label\",\"student_id\":\"guard-s\"}')").fetchone()
+    with pytest.raises(sqlite3.OperationalError, match="no train_query"):
+        db.execute("SELECT * FROM predict('SELECT f1, f2, label FROM tt',"
+                   " 'SELECT rowid, f1, f2 FROM tt',"
+                   " '{\"model\":\"guard-s\"}')").fetchall()

tests/test_forecast_student.py

@@ -328,3 +328,13 @@ def test_auto_stays_pure_without_a_registry(db):
     assert doc["model"] in ("theta-classic", "stub-seasonal-naive", "tsb")
     assert db.execute("SELECT count(*) FROM sqlite_master WHERE name LIKE"
                       " '_predict%'").fetchone()[0] == 0
+
+
+def test_distill_forecast_rejects_unknown_option_key(db):
+    # the fail-loud options contract applies to distill_forecast too
+    ncol = _load_windows(db)
+    with pytest.raises(sqlite3.OperationalError, match="OPTIONS"):
+        db.execute(
+            f"SELECT * FROM distill_forecast('SELECT {_cols(ncol)} FROM w',"
+            f" json_object('context',{L},'horizon',{H},"
+            f"'student_id','x','bogus',1))").fetchall()

website/src/content/docs/guides/distillation.md

@@ -27,8 +27,8 @@ SELECT row_ref, prediction, confidence FROM predict(NULL,
 
 The `NULL` first argument is the signature of serving a student: `predict`
 normally takes a training query for in-context models, but a student carries
-its training inside its blob, so pass `NULL`; a query in that position is
-not read when a student serves the call.
+its training inside its blob, so passing a query alongside a student is
+rejected (`PREDICT_ERR_OPTIONS`) rather than silently ignored.
 
 `student_kind` is `tree` (a single CART), `gbt` (a gradient-boosted forest
 with second-order leaves, which matches or beats tuned XGBoost on most

website/src/content/docs/reference/options.md

@@ -5,9 +5,7 @@ description: Every option each function accepts, passed as a trailing JSON objec
 
 Options are a single JSON object in the last argument. Unknown keys and
 wrong-typed values are rejected with `PREDICT_ERR_OPTIONS`, so a typo fails loud
-rather than being ignored. `distill_forecast` is the one exception today: it
-reads only its known keys and ignores anything else, so check its spelling
-yourself.
+rather than being ignored.
 
 ## forecast