feat(onnx): ONNX runtime serving path for predict() (vector layout)

Adds the opt-in foundation-model serving path (make loadable-onnx,
-DSQLITE_PREDICT_ONNX). predict-onnx.c is the only file that links
onnxruntime; the core `loadable` stays pure C99, zero-dependency (0 onnx
symbols, 0 onnxruntime linkage, verified).

This pass implements the 'vector' io_spec layout: a self-contained,
pre-trained model (a distilled student or any exported tabular
classifier/regressor) mapping features -> prediction, dispatched through
the existing predict() model-backend seam. The 'in_context' layout (a
teacher such as TabFM that ingests the training rows as context) and the
GPU execution providers are the next pass, validated on the gated GPU
runner; requesting cuda/tensorrt here fails loud rather than silently
dropping to CPU.

Performance shape (per RFC 0005): sessions are cached process-global by
(weights, device, precision) and reused; query rows run in batches, not
one at a time; execution-provider selection is explicit.

Registry/plumbing:
- _predict_models gains weights_uri (external teacher weights) + io_spec
  (tensor mapping); the weight-source CHECK now allows an inline BLOB
  (small students) XOR a URI (large teachers). Idempotent column adds.
- predict_register(model_id, config_json) records a model and pins its
  weights by content hash so the receipt/replay path can detect changes.
- New error codes: MODEL_EXISTS, RUNTIME_UNAVAILABLE, IO_SPEC, INFERENCE.
- Receipts record the execution provider + precision; the CPU-fp32 path
  is deterministic, so replay is bit-exact (proven by the tests).
- License gate: a non-permissive model (TabFM is non-commercial) needs
  accept_license to match before it will run.

Tests (self-skip when the extension has no onnx runtime, so `make test`
ignores them): hand-built ONNX fixtures with reference outputs computed
independently in pure Python; classifier + regressor correctness, exact
replay, mutation detection, 2500-row multi-batch, non-numeric handling,
license gate, fail-loud device/precision, schema mismatches, and an RSS
leak soak. Plus an ASan/UBSan/LSan C soak (make test-asan-onnx) and a CI
onnx job on ubuntu.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: mstrathman <matthew.strathman@gmail.com>

Author: mstrathman

.github/workflows/ci.yml

@@ -106,3 +106,24 @@ jobs:
           make soak-wasm
       - name: Run under node
         run: node dist/soak.js
+
+  onnx:
+    name: onnx (cpu)
+    runs-on: ubuntu-latest
+    env:
+      ORT_VERSION: "1.27.1"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Fetch onnxruntime
+        run: |
+          curl -fsSL -o ort.tgz \
+            "https://github.com/microsoft/onnxruntime/releases/download/v${ORT_VERSION}/onnxruntime-linux-x64-${ORT_VERSION}.tgz"
+          tar xzf ort.tgz
+          echo "ONNXRUNTIME_PREFIX=$PWD/onnxruntime-linux-x64-${ORT_VERSION}" \
+            >> "$GITHUB_ENV"
+      - name: Build the onnx variant + run its tests
+        run: make test-onnx
+      - name: ASan + LSan soak of the onnx backend
+        run: make test-asan-onnx

Makefile

@@ -38,6 +38,18 @@ prefix?=dist
 TARGET_LOADABLE=$(prefix)/predict0.$(LOADABLE_EXTENSION)
 
 OBJS=sqlite-predict.c predict-forecast.c predict-receipts.c predict-tabular.c vendor/sha256.c
+ONNX_OBJS=$(OBJS) predict-onnx.c
+
+# onnxruntime is a build+runtime dependency of the loadable-onnx variant
+# only. Point ONNXRUNTIME_PREFIX at an install (dir with include/ + lib/),
+# or install it (macOS: `brew install onnxruntime`; the prefix is auto-
+# detected there). The include lives at include/ for tarball installs and
+# include/onnxruntime/ for brew, so both are on the search path.
+ONNXRUNTIME_PREFIX ?= $(shell brew --prefix onnxruntime 2>/dev/null)
+ONNX_CFLAGS=-DSQLITE_PREDICT_ONNX -I$(ONNXRUNTIME_PREFIX)/include \
+  -I$(ONNXRUNTIME_PREFIX)/include/onnxruntime
+ONNX_LDFLAGS=-L$(ONNXRUNTIME_PREFIX)/lib -lonnxruntime \
+  -Wl,-rpath,$(ONNXRUNTIME_PREFIX)/lib
 
 $(prefix):
 	mkdir -p $(prefix)
@@ -58,6 +70,14 @@ sqlite-predict.h: sqlite-predict.h.tmpl VERSION
 loadable: $(prefix) vendor/sqlite3ext.h sqlite-predict.h $(OBJS)
 	$(CC) -fPIC -shared -std=c99 -Wall -Wextra -Ivendor/ -I./ -O3 $(CFLAGS) $(OBJS) -o $(TARGET_LOADABLE) $(LDFLAGS)
 
+# opt-in ONNX build: same loadable, plus predict-onnx.c linked against
+# onnxruntime. Serves onnx-runtime models (distilled students, exported
+# classifiers) through predict(). The core `loadable` stays zero-dependency.
+loadable-onnx: $(prefix) vendor/sqlite3ext.h sqlite-predict.h $(ONNX_OBJS)
+	$(CC) -fPIC -shared -std=c99 -Wall -Wextra -Ivendor/ -I./ -O3 \
+	  $(ONNX_CFLAGS) $(CFLAGS) $(ONNX_OBJS) -o $(TARGET_LOADABLE) \
+	  $(LDFLAGS) $(ONNX_LDFLAGS)
+
 debug: $(prefix) vendor/sqlite3ext.h sqlite-predict.h $(OBJS)
 	$(CC) -fPIC -shared -std=c99 -Wall -Wextra -Ivendor/ -I./ -g -O0 -DSQLITE_PREDICT_DEBUG $(CFLAGS) $(OBJS) -o $(TARGET_LOADABLE) $(LDFLAGS)
 
@@ -66,6 +86,12 @@ test-loadable: loadable
 
 test: test-loadable
 
+# ONNX build + its tests. The onnx-marked tests build a fixture model and
+# exercise the runtime path; they self-skip when the loaded extension has
+# no onnx runtime, so the core `make test` above ignores them.
+test-onnx: loadable-onnx
+	cd tests && uv run pytest -q
+
 # ASan+UBSan on the C soak driver (standalone executable: no DYLD
 # injection needed, macOS SIP strips it for system binaries anyway).
 # Covers every operation, receipts, replay, and the error paths.
@@ -78,6 +104,21 @@ test-asan: vendor/sqlite3ext.h sqlite-predict.h
 	  tests/soak.c $(OBJS) vendor/sqlite3.c -o $(prefix)/soak-asan
 	UBSAN_OPTIONS=print_stacktrace=1 ./$(prefix)/soak-asan
 
+# ASan/UBSan soak for the onnx backend (leak-checked on Linux via LSan;
+# onnxruntime's own still-reachable allocations are filtered by onnx.supp).
+# Needs onnxruntime (ONNXRUNTIME_PREFIX) and the committed fixture model.
+test-asan-onnx: vendor/sqlite3ext.h sqlite-predict.h
+	mkdir -p $(prefix)
+	clang -std=c99 -g -O1 -fsanitize=address,undefined \
+	  -fno-omit-frame-pointer -fno-sanitize-recover=undefined \
+	  -DSQLITE_CORE -DSQLITE_PREDICT_STATIC -DSQLITE_STRICT_SUBTYPE=1 \
+	  $(ONNX_CFLAGS) -Ivendor/ -I./ \
+	  tests/soak_onnx.c $(ONNX_OBJS) vendor/sqlite3.c \
+	  -o $(prefix)/soak-onnx-asan $(ONNX_LDFLAGS)
+	LSAN_OPTIONS=suppressions=tests/onnx.supp \
+	  UBSAN_OPTIONS=print_stacktrace=1 \
+	  ./$(prefix)/soak-onnx-asan tests/fixtures/logreg.onnx
+
 # libFuzzer harness (statically links sqlite3.c; SQLITE_CORE build)
 fuzz-build: vendor/sqlite3ext.h sqlite-predict.h
 	mkdir -p $(prefix)
@@ -134,4 +175,5 @@ clean:
 format:
 	clang-format -i sqlite-predict.c predict-*.c
 
-.PHONY: loadable debug test test-loadable clean format
+.PHONY: loadable loadable-onnx debug test test-loadable test-onnx \
+  test-asan-onnx clean format

predict-internal.h

@@ -61,7 +61,11 @@ typedef size_t usize;
 #define PREDICT_ERR_PROBE "PREDICT_ERR_PROBE"
 #define PREDICT_ERR_LICENSE "PREDICT_ERR_LICENSE"
 #define PREDICT_ERR_MODEL_NOT_FOUND "PREDICT_ERR_MODEL_NOT_FOUND"
+#define PREDICT_ERR_MODEL_EXISTS "PREDICT_ERR_MODEL_EXISTS"
 #define PREDICT_ERR_MODEL_HASH "PREDICT_ERR_MODEL_HASH"
+#define PREDICT_ERR_RUNTIME_UNAVAILABLE "PREDICT_ERR_RUNTIME_UNAVAILABLE"
+#define PREDICT_ERR_IO_SPEC "PREDICT_ERR_IO_SPEC"
+#define PREDICT_ERR_INFERENCE "PREDICT_ERR_INFERENCE"
 #define PREDICT_ERR_STUDENT_EXISTS "PREDICT_ERR_STUDENT_EXISTS"
 #define PREDICT_ERR_RESOURCE "PREDICT_ERR_RESOURCE"
 #define PREDICT_ERR_RECEIPT_NOT_FOUND "PREDICT_ERR_RECEIPT_NOT_FOUND"
@@ -127,6 +131,73 @@ int predict0_receipts_ensure(sqlite3 *db, char **errmsg);
 /* content_hash of a registered model; sqlite3_malloc'd. NULL = absent. */
 char *predict0_registry_model_hash(sqlite3 *db, const char *model_id);
 
+/* A registry row, as the dispatcher and runtime backends see it. All
+ * strings are sqlite3_malloc'd; weights is a malloc'd copy of the inline
+ * BLOB (NULL when the model is URI-referenced or has no local weights). */
+typedef struct {
+  char *runtime;      /* 'onnx' | 'ggml' | 'tree' | 'remote' | 'bundled' */
+  char *kind;         /* 'tabular-fm' | 'student' | ... */
+  char *weights_uri;  /* external path to weights; NULL if inline/none */
+  char *io_spec;      /* JSON tensor mapping; NULL if not set */
+  char *license;      /* SPDX id */
+  char *content_hash; /* hex sha-256 pinning the exact weights */
+  void *weights;      /* inline weight bytes; NULL if URI/none */
+  int weights_len;
+} predict0_model_row;
+
+/* Look up a model. Returns 0 and fills *out on hit, 1 if absent, or an
+ * SQLITE_ error. Free *out with predict0_model_row_free on a hit. */
+int predict0_registry_lookup(sqlite3 *db, const char *model_id,
+                             predict0_model_row *out);
+void predict0_model_row_free(predict0_model_row *m);
+
+/* SHA-256 of a file's bytes, streamed. hex into out[65]. Returns 0 on
+ * success; on failure sets *errmsg (sqlite3_malloc'd, PREDICT_ERR_* lead). */
+int predict0_hash_file(const char *path, char out[PREDICT_HEX_BUFSIZE],
+                       char **errmsg);
+
+/* ---- runtime backends (predict-onnx.c, opt-in build) ---- */
+
+/* Backend-relevant options, parsed from the predict() JSON. Borrowed
+ * pointers into the caller's parsed options; valid for the call only. */
+typedef struct {
+  const char *device;         /* 'cpu'|'coreml'|'cuda'|'tensorrt'; NULL=cpu */
+  const char *precision;      /* 'fp32'|'fp16'|'int8'; NULL=fp32 */
+  const char *accept_license; /* SPDX the caller accepts; NULL=none */
+  int receipt;                /* emit a receipt? */
+} predict0_backend_opts;
+
+/* One prediction a runtime backend hands back, in apply-query order. */
+typedef struct {
+  int ref_type; /* SQLITE_INTEGER/FLOAT/TEXT/NULL of the row_ref */
+  i64 ref_i;
+  f64 ref_f;
+  char *ref_t;      /* sqlite3_malloc'd, for a TEXT ref */
+  char *prediction; /* sqlite3_malloc'd; NULL on status/error rows */
+  f64 confidence;
+  int has_conf;
+  const char *status; /* static string ('ok','non_numeric',...) */
+} predict0_result;
+
+void predict0_results_free(predict0_result *rows, int n);
+
+#ifdef SQLITE_PREDICT_ONNX
+/* Vector-layout ONNX inference: the model is self-contained (features ->
+ * prediction), so train_sql is not consulted. Reads row_ref + named
+ * features from apply_sql, maps them to the model's declared feature order,
+ * runs batched inference on the requested execution provider, and fills
+ * rows/n (apply order; free with predict0_results_free). When
+ * opts->receipt, emits a receipt and writes receipt_id_out. Returns
+ * SQLITE_OK, or an SQLITE_ code with *errmsg set (PREDICT_ERR_* lead). */
+int predict0_onnx_predict_vector(sqlite3 *db, const char *model_id,
+                                 const char *apply_sql,
+                                 const predict0_model_row *model,
+                                 const predict0_backend_opts *opts,
+                                 predict0_result **rows, int *n,
+                                 char receipt_id_out[PREDICT_ULID_BUFSIZE],
+                                 char **errmsg);
+#endif
+
 /* Deterministic logical digest of all user tables (schema + rows,
  * excluding _predict_% and sqlite_%), hex into out[65]. */
 int predict0_logical_digest(sqlite3 *db, char out[PREDICT_HEX_BUFSIZE], char **errmsg);