fix: fail fast on incompatible ONNX Runtime

rust/Cargo.toml

@@ -113,8 +113,8 @@ default = [
 jemalloc = ["dep:tikv-jemallocator", "dep:tikv-jemalloc-ctl"]
 dev-tools = []
 no-jail = []
-neural = ["dep:ort", "dep:ndarray"]
-embeddings = ["dep:ort", "dep:ndarray"]
+neural = ["dep:ort", "dep:ndarray", "dep:libloading"]
+embeddings = ["dep:ort", "dep:ndarray", "dep:libloading"]
 ort-cuda = ["ort?/cuda"]
 ort-webgpu = ["ort?/webgpu"]
 ort-rocm = ["ort?/rocm"]

rust/src/core/embedding_index.rs

@@ -138,10 +138,13 @@ pub fn build_or_update(root: &Path, bm25: &super::bm25_index::BM25Index) -> Embe
             }
         }
 
-        let Some(engine) = crate::core::embeddings::shared_engine() else {
-            let reason = "embedding model files found but engine failed to load (check logs / RUST_LOG=info)";
-            tracing::info!("[embedding_index] build_or_update skipped: {reason}");
-            return EmbeddingBuildOutcome::ModelNotAvailable(reason.to_string());
+        let engine = match crate::core::embeddings::shared_engine_result() {
+            Ok(engine) => engine,
+            Err(e) => {
+                let reason = format!("embedding model files found but engine failed to load: {e}");
+                tracing::warn!("[embedding_index] build_or_update failed: {reason}");
+                return EmbeddingBuildOutcome::ModelNotAvailable(reason);
+            }
         };
 
         let model_name = engine.model_name();

rust/src/core/embeddings/mod.rs

@@ -101,7 +101,7 @@ impl EmbeddingEngine {
         // deterministic regardless via score quantization; this is extra hardening.
         let deterministic = deterministic_inference();
         let eps = if deterministic {
-            Vec::new()
+            vec![ort::ep::CPU::default().build()]
         } else {
             crate::core::ort_execution_providers::gpu_execution_providers()
         };
@@ -110,7 +110,16 @@ impl EmbeddingEngine {
         } else {
             std::thread::available_parallelism().map_or(4, |n| n.get().max(1))
         };
+        tracing::info!(
+            model = %config.name,
+            model_path = %model_path.display(),
+            deterministic,
+            num_cpus,
+            execution_providers = eps.len(),
+            "Loading ONNX embedding model"
+        );
         crate::core::ort_environment::ensure_ort_env(&eps)?;
+        tracing::debug!("ONNX Runtime environment ready; creating embedding session builder");
         let mut session = ort::session::Session::builder()
             .map_err(|e| anyhow::anyhow!("ORT builder: {e}"))?
             .with_intra_threads(num_cpus)
@@ -119,6 +128,7 @@ impl EmbeddingEngine {
             .map_err(|e| anyhow::anyhow!("ORT optimization: {e}"))?
             .commit_from_file(&model_path)
             .map_err(|e| anyhow::anyhow!("ORT load model: {e}"))?;
+        tracing::debug!("ONNX embedding session loaded; inspecting graph signature");
 
         let input_names: Vec<String> = session
             .inputs()
@@ -177,6 +187,7 @@ impl EmbeddingEngine {
             config.max_seq_len,
         )
         .unwrap_or(config.dimensions);
+        tracing::debug!(dimensions, "ONNX embedding dimensions resolved");
 
         tracing::info!(
             "Embedding engine loaded: model={}, {}d, max_seq_len={}, topology={}",
@@ -678,10 +689,17 @@ static SHARED_ENGINE: std::sync::OnceLock<anyhow::Result<EmbeddingEngine>> =
 /// For non-blocking access, use `try_shared_engine()` instead.
 #[cfg(feature = "embeddings")]
 pub fn shared_engine() -> Option<&'static EmbeddingEngine> {
+    shared_engine_result().ok()
+}
+
+/// Global singleton embedding engine with the load error preserved for callers
+/// that can surface diagnostics to users.
+#[cfg(feature = "embeddings")]
+pub fn shared_engine_result() -> anyhow::Result<&'static EmbeddingEngine> {
     SHARED_ENGINE
         .get_or_init(EmbeddingEngine::load_default)
         .as_ref()
-        .ok()
+        .map_err(|e| anyhow::anyhow!("{e}"))
 }
 
 /// Non-blocking variant: returns the engine ONLY if already loaded.

rust/src/core/ort_environment.rs

@@ -15,6 +15,7 @@
 //! If no copy is found, [`ensure_ort_env`] returns an eager error — session
 //! creation hangs rather than failing, so we fail fast.
 
+use std::ffi::{CStr, c_char, c_void};
 use std::path::{Path, PathBuf};
 use std::sync::OnceLock;
 
@@ -54,16 +55,68 @@ fn init_ort(eps: &[ExecutionProviderDispatch]) -> anyhow::Result<()> {
     let path = resolve_ort_dylib()?;
 
     tracing::debug!("Loading libonnxruntime from {}", path.display());
-    ort::init_from(&path)
-        .map_err(|e| anyhow::anyhow!("ort::init_from({}) failed: {e}", path.display()))?
-        .with_name("lean-ctx")
+    validate_ort_dylib_version(&path)?;
+    tracing::debug!("Calling ort::init_from");
+    let init = ort::init_from(&path)
+        .map_err(|e| anyhow::anyhow!("ort::init_from({}) failed: {e}", path.display()))?;
+    tracing::debug!("ort::init_from returned; committing ONNX Runtime environment");
+    init.with_name("lean-ctx")
         .with_execution_providers(eps)
         .commit();
+    tracing::debug!("ONNX Runtime environment commit returned");
 
     tracing::info!("ONNX Runtime initialised ({})", path.display());
     Ok(())
 }
 
+type OrtGetApiBase = unsafe extern "C" fn() -> *const OrtApiBase;
+type GetVersionString = unsafe extern "C" fn() -> *const c_char;
+
+#[repr(C)]
+struct OrtApiBase {
+    get_api: *const c_void,
+    get_version_string: GetVersionString,
+}
+
+fn validate_ort_dylib_version(path: &Path) -> anyhow::Result<()> {
+    // SAFETY: the path was resolved by resolve_ort_dylib; loading a shared
+    // library executes its initializers, which is the accepted risk of any
+    // dlopen-based ORT discovery (same trust boundary as ort::init_from).
+    let lib = unsafe { libloading::Library::new(path) }
+        .map_err(|e| anyhow::anyhow!("failed to load {}: {e}", path.display()))?;
+    // SAFETY: OrtGetApiBase is the stable C entry point every ONNX Runtime
+    // exports; the signature matches the ORT C API declaration.
+    let get_api_base: libloading::Symbol<OrtGetApiBase> = unsafe { lib.get(b"OrtGetApiBase") }
+        .map_err(|_| anyhow::anyhow!("{} does not export OrtGetApiBase", path.display()))?;
+    // SAFETY: the symbol was just resolved from the loaded library and takes
+    // no arguments; it returns a pointer we null-check before use.
+    let base = unsafe { get_api_base() };
+    anyhow::ensure!(
+        !base.is_null(),
+        "OrtGetApiBase returned null for {}",
+        path.display()
+    );
+
+    // SAFETY: base is non-null (checked above) and points to the static
+    // OrtApiBase; GetVersionString takes no arguments.
+    let version = unsafe { ((*base).get_version_string)() };
+    // SAFETY: GetVersionString returns a static NUL-terminated C string owned
+    // by the runtime for the lifetime of the library.
+    let version = unsafe { CStr::from_ptr(version) }.to_string_lossy();
+    let minor = version
+        .split('.')
+        .nth(1)
+        .and_then(|part| part.parse::<u32>().ok())
+        .unwrap_or(0);
+    anyhow::ensure!(
+        minor >= ort::MINOR_VERSION,
+        "{} is ONNX Runtime {version}, but this lean-ctx build requires ONNX Runtime >= 1.{}.x; install a matching onnxruntime package or point ORT_DYLIB_PATH at a newer libonnxruntime",
+        path.display(),
+        ort::MINOR_VERSION,
+    );
+    Ok(())
+}
+
 // ---------------------------------------------------------------------------
 // Library resolution
 // ---------------------------------------------------------------------------