lora-ruby 0.6.0 → 0.8.4

data/src/lib.rs

@@ -14,24 +14,28 @@
 //! tagged `Hash`es (string keys) with a `"kind"` discriminator.
 
 use std::collections::BTreeMap;
-use std::ffi::c_void;
-use std::mem::MaybeUninit;
 use std::sync::{Arc, Mutex};
 
 use magnus::{
-    function, method, prelude::*, r_hash::ForEach, value::ReprValue, Error as MagnusError,
-    ExceptionClass, Float, Integer, RArray, RHash, RModule, RString, Ruby, Symbol, Value,
+    function, method, prelude::*, value::ReprValue, Error as MagnusError, RHash, RString, Ruby,
+    Value,
 };
 
 use lora_database::{
-    Database as InnerDatabase, DatabaseOpenOptions, ExecuteOptions, InMemoryGraph, LoraValue,
-    QueryResult, ResultFormat, SnapshotConfig, SnapshotOptions, WalConfig,
-};
-use lora_store::{
-    LoraBinary, LoraDate, LoraDateTime, LoraDuration, LoraLocalDateTime, LoraLocalTime, LoraPoint,
-    LoraTime, LoraVector, RawCoordinate, VectorCoordinateType, VectorValues,
+    Database as InnerDatabase, DatabaseOpenOptions, ExecuteOptions, InMemoryGraph, QueryResult,
+    ResultFormat, SnapshotConfig, SnapshotOptions, WalConfig,
 };
 
+mod errors;
+mod from_ruby;
+mod gvl;
+mod to_ruby;
+
+use errors::{invalid_params, query_error, query_error_from_anyhow};
+use from_ruby::{hash_get_any, read_nonnegative_u64, ruby_optional_to_json, ruby_value_to_params};
+use gvl::without_gvl;
+use to_ruby::{lora_value_to_ruby, query_plan_to_ruby, query_profile_to_ruby};
+
 // ============================================================================
 // Module / exception registration
 // ============================================================================
@@ -65,6 +69,8 @@ fn init(ruby: &Ruby) -> Result<(), MagnusError> {
     database.define_singleton_method("new", function!(database_new, -1))?;
     database.define_singleton_method("open_wal", function!(database_open_wal, -1))?;
     database.define_method("execute", method!(database_execute, -1))?;
+    database.define_method("explain", method!(database_explain, -1))?;
+    database.define_method("profile", method!(database_profile, -1))?;
     database.define_method("clear", method!(database_clear, 0))?;
     database.define_method("close", method!(database_close, 0))?;
     database.define_method("node_count", method!(database_node_count, 0))?;
@@ -85,34 +91,6 @@ fn init(ruby: &Ruby) -> Result<(), MagnusError> {
     Ok(())
 }
 
-// ============================================================================
-// Error lookups
-// ============================================================================
-
-fn lora_module(ruby: &Ruby) -> RModule {
-    ruby.class_object()
-        .const_get::<_, RModule>("LoraRuby")
-        .expect("LoraRuby module is defined by `init` before any method runs")
-}
-
-fn lora_error_class(ruby: &Ruby, name: &str) -> ExceptionClass {
-    // `const_get::<_, ExceptionClass>` converts the stored RClass into
-    // an ExceptionClass — this is the sound path, because our subclasses
-    // of StandardError retain the exception-class trait on the Ruby
-    // side even though `define_class` typed them as RClass.
-    lora_module(ruby)
-        .const_get::<_, ExceptionClass>(name)
-        .unwrap_or_else(|_| ruby.exception_standard_error())
-}
-
-fn query_error(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    MagnusError::new(lora_error_class(ruby, "QueryError"), msg.into())
-}
-
-fn invalid_params(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
-    MagnusError::new(lora_error_class(ruby, "InvalidParamsError"), msg.into())
-}
-
 // ============================================================================
 // Database
 // ============================================================================
@@ -252,7 +230,7 @@ fn database_save_snapshot(
     let (path, options) = snapshot_file_args(ruby, args)?;
     let db = database_inner(ruby, rb_self)?;
     let meta = without_gvl(move || db.save_snapshot_to_with_options(&path, &options))
-        .map_err(|e| query_error(ruby, format!("{e}")))?;
+        .map_err(|e| query_error_from_anyhow(ruby, e))?;
     snapshot_meta_to_rhash(ruby, meta)
 }
 
@@ -265,14 +243,14 @@ fn database_load_snapshot(
     let db = database_inner(ruby, rb_self)?;
     let meta =
         without_gvl(move || db.load_snapshot_from_with_credentials(&path, credentials.as_ref()))
-            .map_err(|e| query_error(ruby, format!("{e}")))?;
+            .map_err(|e| query_error_from_anyhow(ruby, e))?;
     snapshot_meta_to_rhash(ruby, meta)
 }
 
 fn snapshot_file_args(
     ruby: &Ruby,
     args: &[Value],
-) -> Result<(String, lora_database::SnapshotOptions), MagnusError> {
+) -> Result<(String, SnapshotOptions), MagnusError> {
     match args.len() {
         1 | 2 => {
             let path = RString::try_convert(args[0])?.to_string()?;
@@ -526,7 +504,7 @@ fn database_execute(ruby: &Ruby, rb_self: &Database, args: &[Value]) -> Result<R
     let row_arrays = match exec_result {
         Ok(QueryResult::RowArrays(r)) => r,
         Ok(_) => return Err(query_error(ruby, "expected RowArrays result")),
-        Err(e) => return Err(query_error(ruby, format!("{e}"))),
+        Err(e) => return Err(query_error_from_anyhow(ruby, e)),
     };
 
     let out = ruby.hash_new();
@@ -548,627 +526,54 @@ fn database_execute(ruby: &Ruby, rb_self: &Database, args: &[Value]) -> Result<R
     Ok(out)
 }
 
-// ============================================================================
-// LoraValue → Ruby
-// ============================================================================
-
-fn lora_value_to_ruby(ruby: &Ruby, value: &LoraValue) -> Result<Value, MagnusError> {
-    match value {
-        LoraValue::Null => Ok(ruby.qnil().as_value()),
-        LoraValue::Bool(b) => Ok(if *b {
-            ruby.qtrue().as_value()
-        } else {
-            ruby.qfalse().as_value()
-        }),
-        LoraValue::Int(i) => Ok(ruby.integer_from_i64(*i).as_value()),
-        LoraValue::Float(f) => Ok(ruby.float_from_f64(*f).as_value()),
-        LoraValue::String(s) => Ok(ruby.str_new(s).as_value()),
-        LoraValue::List(items) => {
-            let arr = ruby.ary_new();
-            for item in items {
-                arr.push(lora_value_to_ruby(ruby, item)?)?;
-            }
-            Ok(arr.as_value())
-        }
-        LoraValue::Map(m) => {
-            let h = ruby.hash_new();
-            for (k, v) in m {
-                h.aset(ruby.str_new(k), lora_value_to_ruby(ruby, v)?)?;
-            }
-            Ok(h.as_value())
-        }
-        LoraValue::Node(id) => {
-            let h = ruby.hash_new();
-            h.aset(ruby.str_new("kind"), ruby.str_new("node"))?;
-            h.aset(ruby.str_new("id"), ruby.integer_from_i64(*id as i64))?;
-            h.aset(ruby.str_new("labels"), ruby.ary_new())?;
-            h.aset(ruby.str_new("properties"), ruby.hash_new())?;
-            Ok(h.as_value())
-        }
-        LoraValue::Relationship(id) => {
-            let h = ruby.hash_new();
-            h.aset(ruby.str_new("kind"), ruby.str_new("relationship"))?;
-            h.aset(ruby.str_new("id"), ruby.integer_from_i64(*id as i64))?;
-            Ok(h.as_value())
-        }
-        LoraValue::Path(p) => {
-            let h = ruby.hash_new();
-            h.aset(ruby.str_new("kind"), ruby.str_new("path"))?;
-            let nodes = ruby.ary_new();
-            for n in &p.nodes {
-                nodes.push(ruby.integer_from_i64(*n as i64))?;
-            }
-            let rels = ruby.ary_new();
-            for r in &p.rels {
-                rels.push(ruby.integer_from_i64(*r as i64))?;
-            }
-            h.aset(ruby.str_new("nodes"), nodes)?;
-            h.aset(ruby.str_new("rels"), rels)?;
-            Ok(h.as_value())
-        }
-        LoraValue::Date(v) => tagged_iso(ruby, "date", v.to_string()),
-        LoraValue::Time(v) => tagged_iso(ruby, "time", v.to_string()),
-        LoraValue::LocalTime(v) => tagged_iso(ruby, "localtime", v.to_string()),
-        LoraValue::DateTime(v) => tagged_iso(ruby, "datetime", v.to_string()),
-        LoraValue::LocalDateTime(v) => tagged_iso(ruby, "localdatetime", v.to_string()),
-        LoraValue::Duration(v) => tagged_iso(ruby, "duration", v.to_string()),
-        LoraValue::Point(p) => point_to_ruby(ruby, p),
-        LoraValue::Vector(v) => vector_to_ruby(ruby, v),
-        LoraValue::Binary(v) => binary_to_ruby(ruby, v),
-    }
-}
-
-fn binary_to_ruby(ruby: &Ruby, value: &LoraBinary) -> Result<Value, MagnusError> {
-    let h = ruby.hash_new();
-    h.aset(ruby.str_new("kind"), ruby.str_new("binary"))?;
-    h.aset(
-        ruby.str_new("length"),
-        ruby.integer_from_i64(value.len() as i64),
-    )?;
-    let segments = ruby.ary_new();
-    for segment in value.segments() {
-        segments.push(ruby.str_from_slice(segment))?;
-    }
-    h.aset(ruby.str_new("segments"), segments)?;
-    Ok(h.as_value())
-}
-
-fn vector_to_ruby(ruby: &Ruby, v: &LoraVector) -> Result<Value, MagnusError> {
-    let h = ruby.hash_new();
-    h.aset(ruby.str_new("kind"), ruby.str_new("vector"))?;
-    h.aset(
-        ruby.str_new("dimension"),
-        ruby.integer_from_i64(v.dimension as i64),
-    )?;
-    h.aset(
-        ruby.str_new("coordinateType"),
-        ruby.str_new(v.coordinate_type().as_str()),
-    )?;
-
-    let values = ruby.ary_new();
-    match &v.values {
-        VectorValues::Float64(vs) => {
-            for x in vs {
-                values.push(ruby.float_from_f64(*x))?;
-            }
-        }
-        VectorValues::Float32(vs) => {
-            for x in vs {
-                values.push(ruby.float_from_f64(*x as f64))?;
-            }
-        }
-        VectorValues::Integer64(vs) => {
-            for x in vs {
-                values.push(ruby.integer_from_i64(*x))?;
-            }
-        }
-        VectorValues::Integer32(vs) => {
-            for x in vs {
-                values.push(ruby.integer_from_i64(*x as i64))?;
-            }
-        }
-        VectorValues::Integer16(vs) => {
-            for x in vs {
-                values.push(ruby.integer_from_i64(*x as i64))?;
-            }
-        }
-        VectorValues::Integer8(vs) => {
-            for x in vs {
-                values.push(ruby.integer_from_i64(*x as i64))?;
-            }
-        }
-    }
-    h.aset(ruby.str_new("values"), values)?;
-    Ok(h.as_value())
-}
-
-fn tagged_iso(ruby: &Ruby, kind: &str, iso: String) -> Result<Value, MagnusError> {
-    let h = ruby.hash_new();
-    h.aset(ruby.str_new("kind"), ruby.str_new(kind))?;
-    h.aset(ruby.str_new("iso"), ruby.str_new(&iso))?;
-    Ok(h.as_value())
-}
-
-/// Render a `LoraPoint` into the canonical external point shape — kept
-/// 1:1 aligned with the `LoraPoint` union emitted by `lora-node` /
-/// `lora-wasm` / `lora-python`.
-fn point_to_ruby(ruby: &Ruby, p: &LoraPoint) -> Result<Value, MagnusError> {
-    let h = ruby.hash_new();
-    h.aset(ruby.str_new("kind"), ruby.str_new("point"))?;
-    h.aset(ruby.str_new("srid"), ruby.integer_from_i64(p.srid as i64))?;
-    h.aset(ruby.str_new("crs"), ruby.str_new(p.crs_name()))?;
-    h.aset(ruby.str_new("x"), ruby.float_from_f64(p.x))?;
-    h.aset(ruby.str_new("y"), ruby.float_from_f64(p.y))?;
-    if let Some(z) = p.z {
-        h.aset(ruby.str_new("z"), ruby.float_from_f64(z))?;
-    }
-    if p.is_geographic() {
-        h.aset(
-            ruby.str_new("longitude"),
-            ruby.float_from_f64(p.longitude()),
-        )?;
-        h.aset(ruby.str_new("latitude"), ruby.float_from_f64(p.latitude()))?;
-        if let Some(height) = p.height() {
-            h.aset(ruby.str_new("height"), ruby.float_from_f64(height))?;
-        }
-    }
-    Ok(h.as_value())
-}
-
-// ============================================================================
-// Ruby → LoraValue (params)
-// ============================================================================
-
-fn ruby_value_to_params(
-    ruby: &Ruby,
-    value: Value,
-) -> Result<BTreeMap<String, LoraValue>, MagnusError> {
-    let hash = RHash::try_convert(value)
-        .map_err(|_| invalid_params(ruby, "params must be a Hash keyed by parameter name"))?;
-    hash_to_string_map(ruby, hash)
-}
-
-fn hash_to_string_map(
-    ruby: &Ruby,
-    hash: RHash,
-) -> Result<BTreeMap<String, LoraValue>, MagnusError> {
-    let mut out = BTreeMap::new();
-    let mut inner_err: Option<MagnusError> = None;
-    hash.foreach(|k: Value, v: Value| {
-        let key = match coerce_key(ruby, k) {
-            Ok(s) => s,
-            Err(e) => {
-                inner_err = Some(e);
-                return Ok(ForEach::Stop);
-            }
-        };
-        match ruby_value_to_lora(ruby, v) {
-            Ok(lv) => {
-                out.insert(key, lv);
-                Ok(ForEach::Continue)
-            }
-            Err(e) => {
-                inner_err = Some(e);
-                Ok(ForEach::Stop)
-            }
-        }
-    })?;
-    if let Some(e) = inner_err {
-        return Err(e);
-    }
-    Ok(out)
-}
-
-fn coerce_key(ruby: &Ruby, v: Value) -> Result<String, MagnusError> {
-    // Accept both String and Symbol keys — idiomatic Ruby. Reject anything
-    // else loudly; silently stringifying would mask caller mistakes.
-    if let Ok(s) = RString::try_convert(v) {
-        return s.to_string();
-    }
-    if let Ok(s) = Symbol::try_convert(v) {
-        return Ok(s.name()?.into_owned());
-    }
-    Err(invalid_params(ruby, "param keys must be String or Symbol"))
-}
-
-fn ruby_optional_to_json(
-    ruby: &Ruby,
-    value: Value,
-) -> Result<Option<serde_json::Value>, MagnusError> {
-    if value.is_nil() {
-        Ok(None)
-    } else {
-        ruby_value_to_json(ruby, value).map(Some)
-    }
-}
-
-fn ruby_value_to_json(ruby: &Ruby, value: Value) -> Result<serde_json::Value, MagnusError> {
-    if value.is_nil() {
-        return Ok(serde_json::Value::Null);
-    }
-    if value.is_kind_of(ruby.class_true_class()) {
-        return Ok(serde_json::Value::Bool(true));
-    }
-    if value.is_kind_of(ruby.class_false_class()) {
-        return Ok(serde_json::Value::Bool(false));
-    }
-    if let Ok(i) = Integer::try_convert(value) {
-        let n = i
-            .to_i64()
-            .map_err(|_| invalid_params(ruby, "snapshot option integer does not fit in i64"))?;
-        return Ok(serde_json::Value::Number(n.into()));
-    }
-    if let Ok(f) = Float::try_convert(value) {
-        let Some(number) = serde_json::Number::from_f64(f.to_f64()) else {
-            return Err(invalid_params(ruby, "snapshot option float must be finite"));
-        };
-        return Ok(serde_json::Value::Number(number));
-    }
-    if let Ok(s) = RString::try_convert(value) {
-        return Ok(serde_json::Value::String(s.to_string()?));
-    }
-    if let Ok(sym) = Symbol::try_convert(value) {
-        return Ok(serde_json::Value::String(sym.name()?.into_owned()));
-    }
-    if let Ok(arr) = RArray::try_convert(value) {
-        let mut out = Vec::with_capacity(arr.len());
-        for item in arr.into_iter() {
-            out.push(ruby_value_to_json(ruby, item)?);
-        }
-        return Ok(serde_json::Value::Array(out));
-    }
-    if let Ok(hash) = RHash::try_convert(value) {
-        let mut out = serde_json::Map::new();
-        let mut error = None;
-        hash.foreach(|k: Value, v: Value| {
-            let key = match coerce_key(ruby, k) {
-                Ok(key) => key,
-                Err(e) => {
-                    error = Some(e);
-                    return Ok(ForEach::Stop);
-                }
-            };
-            let json = match ruby_value_to_json(ruby, v) {
-                Ok(json) => json,
-                Err(e) => {
-                    error = Some(e);
-                    return Ok(ForEach::Stop);
-                }
-            };
-            out.insert(key, json);
-            Ok(ForEach::Continue)
-        })?;
-        if let Some(error) = error {
-            return Err(error);
-        }
-        return Ok(serde_json::Value::Object(out));
-    }
-
-    let class_name = unsafe { value.classname() }.into_owned();
-    Err(invalid_params(
-        ruby,
-        format!("unsupported snapshot option type: {class_name}"),
-    ))
-}
-
-fn ruby_value_to_lora(ruby: &Ruby, v: Value) -> Result<LoraValue, MagnusError> {
-    if v.is_nil() {
-        return Ok(LoraValue::Null);
-    }
-    // Check true/false before Integer — Ruby's TrueClass / FalseClass are
-    // not Integer subclasses, but bool detection is cleaner first.
-    if v.is_kind_of(ruby.class_true_class()) {
-        return Ok(LoraValue::Bool(true));
-    }
-    if v.is_kind_of(ruby.class_false_class()) {
-        return Ok(LoraValue::Bool(false));
-    }
-    // Float MUST be checked before Integer — `Integer::try_convert`
-    // succeeds on Float because Ruby's `Float#to_int` (truncating
-    // coercion) makes `Float` implicitly convertible. Taking that path
-    // would turn `1.5` into `1` silently; callers never want that.
-    if let Ok(f) = Float::try_convert(v) {
-        return Ok(LoraValue::Float(f.to_f64()));
-    }
-    if let Ok(i) = Integer::try_convert(v) {
-        return match i.to_i64() {
-            Ok(n) => Ok(LoraValue::Int(n)),
-            Err(_) => Err(invalid_params(
-                ruby,
-                "integer parameter does not fit in i64",
-            )),
-        };
-    }
-    if let Ok(s) = RString::try_convert(v) {
-        return Ok(LoraValue::String(s.to_string()?));
-    }
-    if let Ok(sym) = Symbol::try_convert(v) {
-        // Symbols round-trip as strings — same approach as YAML/JSON
-        // mappings. Engine has no dedicated symbol value.
-        return Ok(LoraValue::String(sym.name()?.into_owned()));
-    }
-    if let Ok(arr) = RArray::try_convert(v) {
-        let mut out = Vec::with_capacity(arr.len());
-        for item in arr.into_iter() {
-            out.push(ruby_value_to_lora(ruby, item)?);
-        }
-        return Ok(LoraValue::List(out));
-    }
-    if let Ok(hash) = RHash::try_convert(v) {
-        return ruby_hash_to_cypher(ruby, hash);
-    }
-    let class_name = unsafe { v.classname() }.into_owned();
-    Err(invalid_params(
-        ruby,
-        format!("unsupported parameter type: {class_name}"),
-    ))
-}
-
-/// A Hash might be a tagged value (date / time / …/ point) or a plain
-/// map. Nodes / relationships / paths are opaque on the engine side and
-/// cannot be reconstructed as params — there's no `"kind" => "node"`
-/// tag handled here.
-fn ruby_hash_to_cypher(ruby: &Ruby, hash: RHash) -> Result<LoraValue, MagnusError> {
-    if let Some(kind) = lookup_kind(ruby, hash)? {
-        match kind.as_str() {
-            "date" => {
-                return parse_tagged(ruby, hash, "date", |iso| {
-                    LoraDate::parse(iso).map(LoraValue::Date)
-                });
-            }
-            "time" => {
-                return parse_tagged(ruby, hash, "time", |iso| {
-                    LoraTime::parse(iso).map(LoraValue::Time)
-                });
-            }
-            "localtime" => {
-                return parse_tagged(ruby, hash, "localtime", |iso| {
-                    LoraLocalTime::parse(iso).map(LoraValue::LocalTime)
-                });
-            }
-            "datetime" => {
-                return parse_tagged(ruby, hash, "datetime", |iso| {
-                    LoraDateTime::parse(iso).map(LoraValue::DateTime)
-                });
-            }
-            "localdatetime" => {
-                return parse_tagged(ruby, hash, "localdatetime", |iso| {
-                    LoraLocalDateTime::parse(iso).map(LoraValue::LocalDateTime)
-                });
-            }
-            "duration" => {
-                return parse_tagged(ruby, hash, "duration", |iso| {
-                    LoraDuration::parse(iso).map(LoraValue::Duration)
-                });
-            }
-            "point" => return build_point(ruby, hash),
-            "vector" => return build_vector(ruby, hash),
-            "binary" | "blob" => return build_binary(ruby, hash),
-            _ => { /* fall through to plain-map handling */ }
-        }
-    }
-
-    Ok(LoraValue::Map(hash_to_string_map(ruby, hash)?))
-}
-
-/// Look up `"kind"` (string) or `:kind` (symbol) under either key. Keeps
-/// constructor hashes usable with either Ruby idiom.
-fn lookup_kind(ruby: &Ruby, hash: RHash) -> Result<Option<String>, MagnusError> {
-    if let Some(v) = hash.get(ruby.str_new("kind")) {
-        return kind_as_string(v).map(Some);
-    }
-    if let Some(v) = hash.get(ruby.to_symbol("kind")) {
-        return kind_as_string(v).map(Some);
-    }
-    Ok(None)
-}
-
-fn kind_as_string(v: Value) -> Result<String, MagnusError> {
-    if let Ok(s) = RString::try_convert(v) {
-        return s.to_string();
-    }
-    if let Ok(s) = Symbol::try_convert(v) {
-        return Ok(s.name()?.into_owned());
-    }
-    // Anything else means "not a tagged constructor" — return empty so
-    // the caller falls through to plain-map handling instead of raising.
-    Ok(String::new())
-}
-
-fn parse_tagged(
-    ruby: &Ruby,
-    hash: RHash,
-    tag: &str,
-    parse: impl FnOnce(&str) -> Result<LoraValue, String>,
-) -> Result<LoraValue, MagnusError> {
-    let iso = read_string(ruby, hash, "iso")?
-        .ok_or_else(|| invalid_params(ruby, format!("{tag} value requires iso: String")))?;
-    parse(&iso).map_err(|e| invalid_params(ruby, format!("{tag}: {e}")))
-}
-
-fn build_point(ruby: &Ruby, hash: RHash) -> Result<LoraValue, MagnusError> {
-    let srid = read_u32(ruby, hash, "srid")?.unwrap_or(7203);
-    let x = read_f64(ruby, hash, "x")?.ok_or_else(|| invalid_params(ruby, "point.x required"))?;
-    let y = read_f64(ruby, hash, "y")?.ok_or_else(|| invalid_params(ruby, "point.y required"))?;
-    let z = read_f64(ruby, hash, "z")?;
-    Ok(LoraValue::Point(LoraPoint { x, y, z, srid }))
-}
-
-fn build_vector(ruby: &Ruby, hash: RHash) -> Result<LoraValue, MagnusError> {
-    let dimension = read_i64(ruby, hash, "dimension")?
-        .ok_or_else(|| invalid_params(ruby, "vector.dimension required"))?;
-    let coordinate_type_name = read_string(ruby, hash, "coordinateType")?
-        .ok_or_else(|| invalid_params(ruby, "vector.coordinateType required"))?;
-    let coordinate_type = VectorCoordinateType::parse(&coordinate_type_name).ok_or_else(|| {
-        invalid_params(
-            ruby,
-            format!("unknown vector coordinate type '{coordinate_type_name}'"),
-        )
-    })?;
-    let values_value = hash_get_either(ruby, hash, "values")
-        .ok_or_else(|| invalid_params(ruby, "vector.values required"))?;
-    let arr = RArray::try_convert(values_value)
-        .map_err(|_| invalid_params(ruby, "vector.values must be an Array"))?;
-
-    let mut raw = Vec::with_capacity(arr.len());
-    for item in arr.into_iter() {
-        if item.is_kind_of(ruby.class_true_class()) || item.is_kind_of(ruby.class_false_class()) {
-            return Err(invalid_params(
-                ruby,
-                "vector.values entries must be numeric",
-            ));
-        }
-        if let Ok(f) = Float::try_convert(item) {
-            let v = f.to_f64();
-            if !v.is_finite() {
-                return Err(invalid_params(
-                    ruby,
-                    "vector.values cannot be NaN or Infinity",
-                ));
-            }
-            raw.push(RawCoordinate::Float(v));
-            continue;
-        }
-        if let Ok(i) = Integer::try_convert(item) {
-            raw.push(RawCoordinate::Int(i.to_i64()?));
-            continue;
-        }
-        return Err(invalid_params(
-            ruby,
-            "vector.values entries must be numeric",
-        ));
-    }
-
-    let v = LoraVector::try_new(raw, dimension, coordinate_type)
-        .map_err(|e| invalid_params(ruby, e.to_string()))?;
-    Ok(LoraValue::Vector(v))
-}
-
-fn build_binary(ruby: &Ruby, hash: RHash) -> Result<LoraValue, MagnusError> {
-    let segments_value = hash_get_either(ruby, hash, "segments")
-        .ok_or_else(|| invalid_params(ruby, "binary.segments required"))?;
-    let arr = RArray::try_convert(segments_value)
-        .map_err(|_| invalid_params(ruby, "binary.segments must be an Array"))?;
-    let mut segments = Vec::with_capacity(arr.len());
-    for item in arr.into_iter() {
-        let segment = RString::try_convert(item)
-            .map_err(|_| invalid_params(ruby, "binary.segments entries must be Strings"))?;
-        segments.push(unsafe { segment.as_slice().to_vec() });
-    }
-    Ok(LoraValue::Binary(LoraBinary::from_segments(segments)))
-}
-
-fn read_i64(ruby: &Ruby, hash: RHash, key: &str) -> Result<Option<i64>, MagnusError> {
-    let Some(v) = hash_get_either(ruby, hash, key) else {
-        return Ok(None);
-    };
-    Ok(Some(Integer::try_convert(v)?.to_i64().map_err(|_| {
-        invalid_params(ruby, format!("{key} out of i64 range"))
-    })?))
-}
-
-// ---- Hash accessors that accept either string or symbol keys ------------
-
-fn hash_get_either(ruby: &Ruby, hash: RHash, key: &str) -> Option<Value> {
-    if let Some(v) = hash.get(ruby.str_new(key)) {
-        return Some(v);
-    }
-    hash.get(ruby.to_symbol(key))
-}
-
-fn hash_get_any(ruby: &Ruby, hash: RHash, keys: &[&str]) -> Option<Value> {
-    keys.iter().find_map(|key| hash_get_either(ruby, hash, key))
-}
-
-fn read_nonnegative_u64(ruby: &Ruby, value: Value) -> Result<u64, MagnusError> {
-    let n = Integer::try_convert(value)?.to_i64()?;
-    u64::try_from(n).map_err(|_| invalid_params(ruby, "option integer must be non-negative"))
-}
-
-fn read_string(ruby: &Ruby, hash: RHash, key: &str) -> Result<Option<String>, MagnusError> {
-    let Some(v) = hash_get_either(ruby, hash, key) else {
-        return Ok(None);
-    };
-    let s = RString::try_convert(v)?.to_string()?;
-    Ok(Some(s))
-}
-
-fn read_u32(ruby: &Ruby, hash: RHash, key: &str) -> Result<Option<u32>, MagnusError> {
-    let Some(v) = hash_get_either(ruby, hash, key) else {
-        return Ok(None);
-    };
-    let n = Integer::try_convert(v)?.to_i64()?;
-    u32::try_from(n)
-        .map(Some)
-        .map_err(|_| invalid_params(ruby, "srid out of u32 range"))
-}
-
-fn read_f64(ruby: &Ruby, hash: RHash, key: &str) -> Result<Option<f64>, MagnusError> {
-    let Some(v) = hash_get_either(ruby, hash, key) else {
-        return Ok(None);
+/// `explain(query, params = nil)` — compile a query and return the plan
+/// as a Ruby `Hash` without invoking the executor. Mutating queries
+/// produce no side effects.
+fn database_explain(ruby: &Ruby, rb_self: &Database, args: &[Value]) -> Result<RHash, MagnusError> {
+    let (query, params_value) = parse_query_params(ruby, args)?;
+    let params_map = match params_value {
+        Some(v) => Some(ruby_value_to_params(ruby, v)?),
+        None => None,
     };
-    // Accept either Float or Integer — `cartesian(1, 2)` passing ints
-    // shouldn't force the caller to call `.to_f` first.
-    if let Ok(f) = Float::try_convert(v) {
-        return Ok(Some(f.to_f64()));
-    }
-    if let Ok(i) = Integer::try_convert(v) {
-        return Ok(Some(i.to_i64()? as f64));
-    }
-    Ok(None)
+    let db = database_inner(ruby, rb_self)?;
+    let plan = without_gvl(move || db.explain(&query, params_map))
+        .map_err(|e| query_error_from_anyhow(ruby, e))?;
+    query_plan_to_ruby(ruby, &plan)
 }
 
-// ============================================================================
-// GVL release
-// ============================================================================
-
-/// Run `f` with Ruby's Global VM Lock released.
+/// `profile(query, params = nil)` — execute a query and return the plan
+/// plus runtime metrics as a Ruby `Hash`.
 ///
-/// Semantics match `rb_thread_call_without_gvl` — other Ruby threads can
-/// progress while `f` runs. The closure MUST NOT touch Ruby state (no
-/// `Value`s, no allocations into the Ruby heap), which we arrange by
-/// keeping all such work on the calling thread. Everything inside
-/// `database_execute`'s closure is pure Rust on pre-extracted data, so
-/// this is sound.
-fn without_gvl<F, R>(f: F) -> R
-where
-    F: FnOnce() -> R,
-    F: Send,
-    R: Send,
-{
-    struct Data<F, R> {
-        func: Option<F>,
-        result: MaybeUninit<R>,
-    }
-
-    unsafe extern "C" fn trampoline<F, R>(data: *mut c_void) -> *mut c_void
-    where
-        F: FnOnce() -> R,
-    {
-        let data = &mut *(data as *mut Data<F, R>);
-        let f = data
-            .func
-            .take()
-            .expect("without_gvl: closure already taken");
-        data.result.write(f());
-        std::ptr::null_mut()
-    }
-
-    let mut data = Data::<F, R> {
-        func: Some(f),
-        result: MaybeUninit::uninit(),
+/// **PROFILE executes the query for real.** Mutating queries are
+/// persisted exactly as in `execute`. Use `explain` to inspect a
+/// mutating plan without running it.
+fn database_profile(ruby: &Ruby, rb_self: &Database, args: &[Value]) -> Result<RHash, MagnusError> {
+    let (query, params_value) = parse_query_params(ruby, args)?;
+    let params_map = match params_value {
+        Some(v) => Some(ruby_value_to_params(ruby, v)?),
+        None => None,
     };
+    let db = database_inner(ruby, rb_self)?;
+    let prof = without_gvl(move || db.profile(&query, params_map))
+        .map_err(|e| query_error_from_anyhow(ruby, e))?;
+    query_profile_to_ruby(ruby, &prof)
+}
 
-    unsafe {
-        rb_sys::rb_thread_call_without_gvl(
-            Some(trampoline::<F, R>),
-            &mut data as *mut _ as *mut c_void,
-            // No unblock function — the engine doesn't implement
-            // cooperative cancellation, and a forced longjmp out of a
-            // mutex-holding section would be worse than waiting.
-            None,
-            std::ptr::null_mut(),
-        );
-        data.result.assume_init()
+fn parse_query_params(ruby: &Ruby, args: &[Value]) -> Result<(String, Option<Value>), MagnusError> {
+    match args.len() {
+        1 => Ok((RString::try_convert(args[0])?.to_string()?, None)),
+        2 => {
+            let q = RString::try_convert(args[0])?.to_string()?;
+            let p = if args[1].is_nil() {
+                None
+            } else {
+                Some(args[1])
+            };
+            Ok((q, p))
+        }
+        n => Err(MagnusError::new(
+            ruby.exception_arg_error(),
+            format!("wrong number of arguments (given {n}, expected 1..2)"),
+        )),
     }
 }