From 1ac61e0aba88d34844f36f6c0edc5ae17b1c3f3a Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 24 Oct 2026 18:03:35 +0530 Subject: [PATCH 01/13] feat(udf): UdfError and QRY-014 (#180) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015NBT2Yx9JUQKYvv2CvC9py --- docs/ERROR_REFERENCE.md | 21 +++++++++++++++++++ src/error.rs | 20 ++++++++++++++++++ src/lib.rs | 1 + src/query/datalog/functions.rs | 37 ++++++++++++++++++++++++++++++++++ 4 files changed, 79 insertions(+) diff --git a/docs/ERROR_REFERENCE.md b/docs/ERROR_REFERENCE.md index a49dde7705..888b72472f 100644 --- a/docs/ERROR_REFERENCE.md +++ b/docs/ERROR_REFERENCE.md @@ -151,6 +151,7 @@ with no `CodedError` anywhere in its chain. | QRY-011 | Unknown window function | Query Execution | | QRY-012 | Query memory limit exceeded | Query Execution | | QRY-013 | Rule head entity is not an entity | Query Execution | +| QRY-014 | User function failed | Query Execution | | STG-001 | Invalid header: too short | Storage | | STG-002 | Invalid magic number: not a .graph file | Storage | | STG-003 | Invalid v4/v5/v6 header too short (deprecated) | Storage | @@ -2405,6 +2406,26 @@ db.execute("(query [:find ?g (count ?e) :where [?e :g ?g]])")?; ``` *`?n` binds a string, so rule `named` gives a String as its entity* +### QRY-014 User function failed + +**Error text**: `user function `{}` failed: {}` + +**Cause**: A user-defined predicate or aggregate registered with `try_register_predicate` or `try_register_aggregate` returned `Err(UdfError)`, or a language binding's callback threw. The first argument is the function's name and the second is the `UdfError`'s message. The query stops at the failing call: no later call of any user function is made for it. A cursor returns the rows it gathered before the failure first, then this error, then no more rows. A query inside a `WriteTransaction` that fails this way leaves the transaction open. Functions registered with `register_predicate` or `register_aggregate` never fail this way. + +**Resolution**: +- Read the message: it is the one the function gave. +- Fix the input the function rejected, or make the function handle it (return `Ok(false)` for a predicate that should not match). + +**Example**: +```rust +db.try_register_predicate("email?", |v| match v { + Value::String(s) => Ok(s.contains('@')), + _ => Err(UdfError::new("not a string")), +})?; +db.execute("(query [:find ?e :where [?e :mail ?m] [(email? ?m)]])")?; +``` +*An entity's `:mail` is an integer, so `email?` fails with `not a string`* + --- ## STG — Storage Errors diff --git a/src/error.rs b/src/error.rs index 6ce57d4343..771172b4cc 100644 --- a/src/error.rs +++ b/src/error.rs @@ -177,6 +177,7 @@ pub(crate) enum ErrorCode { Qry011, Qry012, Qry013, + Qry014, Int000, Stg001, Stg002, @@ -1114,6 +1115,12 @@ pub(crate) const REGISTRY: &[(ErrorCode, &str, &str, ErrorCategory)] = &[ "rule head entity is not an entity: rule '{}' gives a {} where a ref or a keyword is needed", ErrorCategory::Query, ), + ( + ErrorCode::Qry014, + "QRY-014", + "user function `{}` failed: {}", + ErrorCategory::Query, + ), ( ErrorCode::Int000, "INT-000", @@ -2341,6 +2348,7 @@ mod tests { | ErrorCode::Qry011 | ErrorCode::Qry012 | ErrorCode::Qry013 + | ErrorCode::Qry014 | ErrorCode::Stg001 | ErrorCode::Stg002 | ErrorCode::Stg003 @@ -2610,6 +2618,7 @@ mod tests { ErrorCode::Qry011, ErrorCode::Qry012, ErrorCode::Qry013, + ErrorCode::Qry014, ErrorCode::Stg001, ErrorCode::Stg002, ErrorCode::Stg003, @@ -2765,6 +2774,17 @@ mod tests { assert_eq!(e.to_string(), "[API-018] log writer is closed"); } + #[test] + fn qry014_names_the_failing_function_and_its_message() { + let e = MinigrafError::from(err_coded!(ErrorCode::Qry014, "email?", "bad input")); + assert_eq!(e.code(), "QRY-014"); + assert_eq!(e.category(), ErrorCategory::Query); + assert_eq!( + e.to_string(), + "[QRY-014] user function `email?` failed: bad input" + ); + } + #[test] fn registry_entry_resolves_int000() { let (code_str, template, category) = registry_entry(ErrorCode::Int000); diff --git a/src/lib.rs b/src/lib.rs index 3eb2f87019..59f1e45fa0 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -107,6 +107,7 @@ pub mod browser; pub use db::OpenOptionsWithPath; pub use db::{IntegrityReport, Minigraf, OpenOptions, SyncMode, WriteTransaction}; pub use error::{ErrorCategory, MinigrafError}; +pub use query::datalog::functions::UdfError; pub use repl::Repl; // EAV value types — users construct and match on these diff --git a/src/query/datalog/functions.rs b/src/query/datalog/functions.rs index c62fb9f2a3..20674dc648 100644 --- a/src/query/datalog/functions.rs +++ b/src/query/datalog/functions.rs @@ -4,6 +4,35 @@ use std::any::Any; use std::collections::HashMap; use std::sync::Arc; +/// Why a user-defined function failed. Its message is in the query's +/// `QRY-014` error. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct UdfError { + message: String, +} + +impl UdfError { + /// A failure with this message. + pub fn new(message: impl Into) -> Self { + UdfError { + message: message.into(), + } + } + + /// The message the function gave. + pub fn message(&self) -> &str { + &self.message + } +} + +impl std::fmt::Display for UdfError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(&self.message) + } +} + +impl std::error::Error for UdfError {} + /// A built-in aggregate; `aggregate.rs` holds its arithmetic (#547). #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum Builtin { @@ -149,6 +178,14 @@ mod tests { use super::*; use crate::graph::types::Value; + #[test] + fn udf_error_displays_its_message() { + let e = UdfError::new("not a string"); + assert_eq!(e.message(), "not a string"); + assert_eq!(e.to_string(), "not a string"); + assert_eq!(e.clone(), e); + } + #[test] fn registry_knows_all_builtins() { let reg = FunctionRegistry::with_builtins(); From c5e7235005943608d60dd3bedd2321a3b3189bea Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 24 Oct 2026 18:07:43 +0530 Subject: [PATCH 02/13] feat(udf): fallible UDF descriptors and try_register_* (#180) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015NBT2Yx9JUQKYvv2CvC9py --- src/db.rs | 112 +++++- src/query/datalog/aggregate.rs | 6 +- src/query/datalog/aggregate/tests.rs | 5 +- src/query/datalog/executor.rs | 2 +- src/query/datalog/functions.rs | 53 ++- tests/udf_test.rs | 526 +++++++++++++++------------ 6 files changed, 441 insertions(+), 263 deletions(-) diff --git a/src/db.rs b/src/db.rs index 185a0b7c79..d06132aaba 100644 --- a/src/db.rs +++ b/src/db.rs @@ -24,7 +24,8 @@ use crate::query::datalog::evaluator::DEFAULT_MAX_DERIVED_FACTS; use crate::query::datalog::executor::DatalogExecutor; use crate::query::datalog::executor::QueryResult; use crate::query::datalog::functions::{ - AggImpl, AggregateDesc, FunctionRegistry, PredicateDesc, UdfFinaliseFn, UdfOps, UdfStepFn, + AggImpl, AggregateDesc, FunctionRegistry, PredicateDesc, UdfError, UdfFinaliseFn, UdfInitFn, + UdfOps, UdfStepFn, }; use crate::query::datalog::parser::parse_datalog_command; use crate::query::datalog::parser::statement::{self, Kind}; @@ -1470,6 +1471,56 @@ impl Minigraf { step: impl Fn(&mut Acc, &Value) + Send + Sync + 'static, finalise: impl Fn(&Acc, usize) -> Value + Send + Sync + 'static, ) -> Result<(), MinigrafError> + where + Acc: Any + Send + 'static, + { + self.register_aggregate_inner( + name, + move || Ok(init()), + move |acc, v| { + step(acc, v); + Ok(()) + }, + move |acc, n| Ok(finalise(acc, n)), + ) + .map_err(MinigrafError::from) + } + + /// Register a custom aggregate function whose calls may fail. + /// + /// As [`register_aggregate`](Self::register_aggregate), except that + /// `init`, `step` and `finalise` return a `Result`. A call that returns + /// `Err(UdfError)` fails the query with `QRY-014`, naming the function + /// and the error's message, and no later call of any user function is + /// made for that query. + /// + /// # Errors + /// + /// Returns an error if `name` is already registered (built-in or UDF) + /// or the function registry lock is poisoned. + /// + /// # Example + /// ``` + /// # use minigraf::db::Minigraf; + /// # use minigraf::{UdfError, Value}; + /// let db = Minigraf::in_memory().unwrap(); + /// db.try_register_aggregate( + /// "intsum", + /// || Ok(0i64), + /// |acc: &mut i64, v: &Value| match v { + /// Value::Integer(i) => { *acc += i; Ok(()) } + /// _ => Err(UdfError::new("not an integer")), + /// }, + /// |acc: &i64, _n: usize| Ok(Value::Integer(*acc)), + /// ).unwrap(); + /// ``` + pub fn try_register_aggregate( + &self, + name: &str, + init: impl Fn() -> std::result::Result + Send + Sync + 'static, + step: impl Fn(&mut Acc, &Value) -> std::result::Result<(), UdfError> + Send + Sync + 'static, + finalise: impl Fn(&Acc, usize) -> std::result::Result + Send + Sync + 'static, + ) -> Result<(), MinigrafError> where Acc: Any + Send + 'static, { @@ -1480,26 +1531,26 @@ impl Minigraf { fn register_aggregate_inner( &self, name: &str, - init: impl Fn() -> Acc + Send + Sync + 'static, - step: impl Fn(&mut Acc, &Value) + Send + Sync + 'static, - finalise: impl Fn(&Acc, usize) -> Value + Send + Sync + 'static, + init: impl Fn() -> std::result::Result + Send + Sync + 'static, + step: impl Fn(&mut Acc, &Value) -> std::result::Result<(), UdfError> + Send + Sync + 'static, + finalise: impl Fn(&Acc, usize) -> std::result::Result + Send + Sync + 'static, ) -> Result<()> where Acc: Any + Send + 'static, { - let init_boxed: Arc Box + Send + Sync> = - Arc::new(move || Box::new(init()) as Box); + let init_boxed: UdfInitFn = Arc::new(move || Ok(Box::new(init()?) as Box)); let step_boxed: UdfStepFn = Arc::new(move |acc, v| { // `init_boxed` always creates `Box`, so downcast is infallible. - if let Some(typed_acc) = acc.downcast_mut::() { - step(typed_acc, v); + match acc.downcast_mut::() { + Some(typed_acc) => step(typed_acc, v), + None => Ok(()), } }); - let finalise_boxed: UdfFinaliseFn = Arc::new(move |acc, n| { - acc.downcast_ref::() - .map(|typed_acc| finalise(typed_acc, n)) - .unwrap_or(Value::Null) - }); + let finalise_boxed: UdfFinaliseFn = + Arc::new(move |acc, n| match acc.downcast_ref::() { + Some(typed_acc) => finalise(typed_acc, n), + None => Ok(Value::Null), + }); let desc = AggregateDesc { impl_: AggImpl::Udf(UdfOps { @@ -1538,6 +1589,39 @@ impl Minigraf { &self, name: &str, f: impl Fn(&Value) -> bool + Send + Sync + 'static, + ) -> Result<(), MinigrafError> { + self.register_predicate_inner(name, move |v| Ok(f(v))) + .map_err(MinigrafError::from) + } + + /// Register a custom single-argument filter predicate whose calls may + /// fail. + /// + /// As [`register_predicate`](Self::register_predicate), except that `f` + /// returns a `Result`. A call that returns `Err(UdfError)` fails the + /// query with `QRY-014`, naming the predicate and the error's message, + /// and no later call of any user function is made for that query. It + /// is never read as `false`. + /// + /// # Errors + /// + /// Returns an error if `name` is already registered (built-in or UDF) + /// or the function registry lock is poisoned. + /// + /// # Example + /// ``` + /// # use minigraf::db::Minigraf; + /// # use minigraf::{UdfError, Value}; + /// let db = Minigraf::in_memory().unwrap(); + /// db.try_register_predicate("email?", |v: &Value| match v { + /// Value::String(s) => Ok(s.contains('@')), + /// _ => Err(UdfError::new("not a string")), + /// }).unwrap(); + /// ``` + pub fn try_register_predicate( + &self, + name: &str, + f: impl Fn(&Value) -> std::result::Result + Send + Sync + 'static, ) -> Result<(), MinigrafError> { self.register_predicate_inner(name, f) .map_err(MinigrafError::from) @@ -1546,7 +1630,7 @@ impl Minigraf { fn register_predicate_inner( &self, name: &str, - f: impl Fn(&Value) -> bool + Send + Sync + 'static, + f: impl Fn(&Value) -> std::result::Result + Send + Sync + 'static, ) -> Result<()> { let desc = PredicateDesc { f: Arc::new(f), diff --git a/src/query/datalog/aggregate.rs b/src/query/datalog/aggregate.rs index 8f0419197f..405a5c3126 100644 --- a/src/query/datalog/aggregate.rs +++ b/src/query/datalog/aggregate.rs @@ -402,7 +402,7 @@ impl Udf { fn of(registry: &FunctionRegistry, name: &str) -> Option { match ®istry.get(name)?.impl_ { AggImpl::Udf(ops) => Some(Udf { - acc: (ops.init)(), + acc: (ops.init)().ok()?, step: ops.step.clone(), finalise: ops.finalise.clone(), n: 0, @@ -412,12 +412,12 @@ impl Udf { } fn add(&mut self, v: &Value) { - (self.step)(&mut self.acc, v); + let _ = (self.step)(&mut self.acc, v); self.n += 1; } fn value(&self) -> Value { - (self.finalise)(&self.acc, self.n) + (self.finalise)(&self.acc, self.n).unwrap_or(Value::Null) } } diff --git a/src/query/datalog/aggregate/tests.rs b/src/query/datalog/aggregate/tests.rs index 0582fdf1e8..472d6a628d 100644 --- a/src/query/datalog/aggregate/tests.rs +++ b/src/query/datalog/aggregate/tests.rs @@ -321,15 +321,16 @@ fn registry_with_udf() -> FunctionRegistry { "total".to_string(), AggregateDesc { impl_: AggImpl::Udf(UdfOps { - init: Arc::new(|| Box::new(0i64) as Box), + init: Arc::new(|| Ok(Box::new(0i64) as Box)), step: Arc::new(|acc, v| { if let (Some(n), Value::Integer(x)) = (acc.downcast_mut::(), v) { *n += x; } + Ok(()) }), finalise: Arc::new(|acc, n| { let total = acc.downcast_ref::().copied().unwrap_or(0); - Value::Integer(total * 100 + i64::try_from(n).unwrap_or(0)) + Ok(Value::Integer(total * 100 + i64::try_from(n).unwrap_or(0))) }), }), }, diff --git a/src/query/datalog/executor.rs b/src/query/datalog/executor.rs index 9e7f06def4..14ef5a18e3 100644 --- a/src/query/datalog/executor.rs +++ b/src/query/datalog/executor.rs @@ -806,7 +806,7 @@ pub(crate) fn eval_expr( UnaryOp::NilQ => Ok(Value::Boolean(matches!(v, Value::Null))), UnaryOp::Udf(name) => { let desc = registry.and_then(|r| r.get_predicate(name)).ok_or(())?; - Ok(Value::Boolean((desc.f)(&v))) + Ok(Value::Boolean((desc.f)(&v).map_err(|_| ())?)) } } } diff --git a/src/query/datalog/functions.rs b/src/query/datalog/functions.rs index 20674dc648..21a42fc489 100644 --- a/src/query/datalog/functions.rs +++ b/src/query/datalog/functions.rs @@ -45,21 +45,32 @@ pub enum Builtin { SumDistinct, } +/// Type alias for the type-erased UDF accumulator init closure. +pub type UdfInitFn = Arc Result, UdfError> + Send + Sync>; + /// Type alias for the type-erased UDF accumulator step closure. -pub type UdfStepFn = Arc, &Value) + Send + Sync>; +pub type UdfStepFn = + Arc, &Value) -> Result<(), UdfError> + Send + Sync>; /// Type alias for the type-erased UDF accumulator finalise closure. -pub type UdfFinaliseFn = Arc, usize) -> Value + Send + Sync>; +pub type UdfFinaliseFn = + Arc, usize) -> Result + Send + Sync>; + +/// Type alias for a predicate closure. +pub type PredicateFn = Arc Result + Send + Sync>; /// Closure-based aggregate ops for UDFs. -/// The accumulator is type-erased as `Box`. +/// The accumulator is type-erased as `Box`. Every closure +/// may fail; a failure fails the query with `QRY-014` (#180). +#[derive(Clone)] pub struct UdfOps { - pub init: Arc Box + Send + Sync>, + pub init: UdfInitFn, pub step: UdfStepFn, pub finalise: UdfFinaliseFn, } /// Implementation discriminator for aggregate functions. +#[derive(Clone)] pub enum AggImpl { /// Built-in: computed by `aggregate::Agg` and `aggregate::Running`. Builtin(Builtin), @@ -68,12 +79,14 @@ pub enum AggImpl { } /// Descriptor for a registered predicate function. +#[derive(Clone)] pub struct PredicateDesc { - pub f: Arc bool + Send + Sync>, + pub f: PredicateFn, pub is_builtin: bool, } /// Descriptor for one registered aggregate function. +#[derive(Clone)] pub struct AggregateDesc { pub impl_: AggImpl, } @@ -82,6 +95,8 @@ pub struct AggregateDesc { /// /// In 7.7a this holds only built-ins. Phase 7.7b adds /// `register_aggregate_desc` / `register_predicate_desc` public methods. +/// A clone copies the maps; the closures are shared (#180). +#[derive(Clone)] pub struct FunctionRegistry { aggregates: HashMap, /// Registered filter predicates, including built-in name sentinels. @@ -127,7 +142,7 @@ impl FunctionRegistry { reg.predicates.insert( name.to_string(), PredicateDesc { - f: Arc::new(|_| false), // sentinel; never called via registry + f: Arc::new(|_| Ok(false)), // sentinel; never called via registry is_builtin: true, }, ); @@ -219,16 +234,18 @@ mod tests { "myfn".to_string(), AggregateDesc { impl_: AggImpl::Udf(UdfOps { - init: Arc::new(|| Box::new(0i64) as Box), + init: Arc::new(|| Ok(Box::new(0i64) as Box)), step: Arc::new(|acc, v| { if let (Some(n), Value::Integer(i)) = (acc.downcast_mut::(), v) { *n += i; } + Ok(()) }), finalise: Arc::new(|acc, _n| { - acc.downcast_ref::() + Ok(acc + .downcast_ref::() .map(|n| Value::Integer(*n)) - .unwrap_or(Value::Null) + .unwrap_or(Value::Null)) }), }), }, @@ -242,9 +259,9 @@ mod tests { let mut reg = FunctionRegistry::with_builtins(); let make_desc = || AggregateDesc { impl_: AggImpl::Udf(UdfOps { - init: Arc::new(|| Box::new(0i64) as Box), - step: Arc::new(|_acc, _v| {}), - finalise: Arc::new(|_acc, _n| Value::Null), + init: Arc::new(|| Ok(Box::new(0i64) as Box)), + step: Arc::new(|_acc, _v| Ok(())), + finalise: Arc::new(|_acc, _n| Ok(Value::Null)), }), }; reg.register_aggregate_desc("myfn".to_string(), make_desc()) @@ -262,9 +279,9 @@ mod tests { "sum".to_string(), AggregateDesc { impl_: AggImpl::Udf(UdfOps { - init: Arc::new(|| Box::new(0i64) as Box), - step: Arc::new(|_acc, _v| {}), - finalise: Arc::new(|_acc, _n| Value::Null), + init: Arc::new(|| Ok(Box::new(0i64) as Box)), + step: Arc::new(|_acc, _v| Ok(())), + finalise: Arc::new(|_acc, _n| Ok(Value::Null)), }), }, ); @@ -277,7 +294,7 @@ mod tests { reg.register_predicate_desc( "email?".to_string(), PredicateDesc { - f: Arc::new(|v| matches!(v, Value::String(s) if s.contains('@'))), + f: Arc::new(|v| Ok(matches!(v, Value::String(s) if s.contains('@')))), is_builtin: false, }, ) @@ -286,7 +303,7 @@ mod tests { let second = reg.register_predicate_desc( "email?".to_string(), PredicateDesc { - f: Arc::new(|_v| false), + f: Arc::new(|_v| Ok(false)), is_builtin: false, }, ); @@ -299,7 +316,7 @@ mod tests { let result = reg.register_predicate_desc( "string?".to_string(), PredicateDesc { - f: Arc::new(|_v| false), + f: Arc::new(|_v| Ok(false)), is_builtin: false, }, ); diff --git a/tests/udf_test.rs b/tests/udf_test.rs index 45006e6ec3..a497b67095 100644 --- a/tests/udf_test.rs +++ b/tests/udf_test.rs @@ -2,8 +2,9 @@ //! //! Testing conventions: no `{:?}` of Result/Value/Fact in assert messages. -use minigraf::Value; use minigraf::db::Minigraf; +use minigraf::{MinigrafError, Value}; +use std::any::Any; // ─── helpers ───────────────────────────────────────────────────────────────── @@ -17,57 +18,107 @@ fn seed(db: &Minigraf, cmds: &[&str]) { } } +/// How a test registers its functions: each test runs once per way, so the +/// `try_register_*` methods with closures that never fail are checked to +/// give the same rows as `register_*` (#180). +#[derive(Clone, Copy)] +enum Reg { + Plain, + Try, +} + +const REGS: [Reg; 2] = [Reg::Plain, Reg::Try]; + +impl Reg { + fn aggregate( + self, + db: &Minigraf, + name: &str, + init: impl Fn() -> Acc + Send + Sync + 'static, + step: impl Fn(&mut Acc, &Value) + Send + Sync + 'static, + finalise: impl Fn(&Acc, usize) -> Value + Send + Sync + 'static, + ) -> Result<(), MinigrafError> { + match self { + Reg::Plain => db.register_aggregate(name, init, step, finalise), + Reg::Try => db.try_register_aggregate( + name, + move || Ok(init()), + move |acc, v| { + step(acc, v); + Ok(()) + }, + move |acc, n| Ok(finalise(acc, n)), + ), + } + } + + fn predicate( + self, + db: &Minigraf, + name: &str, + f: impl Fn(&Value) -> bool + Send + Sync + 'static, + ) -> Result<(), MinigrafError> { + match self { + Reg::Plain => db.register_predicate(name, f), + Reg::Try => db.try_register_predicate(name, move |v| Ok(f(v))), + } + } +} + // ─── Test 1: custom aggregate (geometric mean) ─────────────────────────────── #[test] fn custom_aggregate_geometric_mean() { - let db = db(); - // geometric mean = exp(mean of ln(values)) - db.register_aggregate( - "geomean", - || (0.0_f64, 0usize), // (sum_of_ln, count) - |acc: &mut (f64, usize), v: &Value| { - if let Value::Float(f) = v { - if *f > 0.0 { - acc.0 += f.ln(); + for reg in REGS { + let db = db(); + // geometric mean = exp(mean of ln(values)) + reg.aggregate( + &db, + "geomean", + || (0.0_f64, 0usize), // (sum_of_ln, count) + |acc: &mut (f64, usize), v: &Value| { + if let Value::Float(f) = v { + if *f > 0.0 { + acc.0 += f.ln(); + acc.1 += 1; + } + } else if let Value::Integer(i) = v + && *i > 0 + { + acc.0 += (*i as f64).ln(); acc.1 += 1; } - } else if let Value::Integer(i) = v - && *i > 0 - { - acc.0 += (*i as f64).ln(); - acc.1 += 1; - } - }, - |acc: &(f64, usize), _n: usize| { - if acc.1 == 0 { - Value::Null - } else { - Value::Float((acc.0 / acc.1 as f64).exp()) - } - }, - ) - .expect("register geomean"); + }, + |acc: &(f64, usize), _n: usize| { + if acc.1 == 0 { + Value::Null + } else { + Value::Float((acc.0 / acc.1 as f64).exp()) + } + }, + ) + .expect("register geomean"); - seed( - &db, - &[r#"(transact [[:a :item/score 2] [:b :item/score 8]])"#], - ); + seed( + &db, + &[r#"(transact [[:a :item/score 2] [:b :item/score 8]])"#], + ); - let result = db - .execute(r#"(query [:find (geomean ?score) :where [?e :item/score ?score]])"#) - .expect("query failed"); + let result = db + .execute(r#"(query [:find (geomean ?score) :where [?e :item/score ?score]])"#) + .expect("query failed"); - if let minigraf::QueryResult::QueryResults { results, .. } = result { - assert_eq!(results.len(), 1); - // geomean(2, 8) = sqrt(16) = 4.0 - if let Value::Float(f) = &results[0][0] { - assert!((*f - 4.0).abs() < 1e-9, "expected ~4.0"); + if let minigraf::QueryResult::QueryResults { results, .. } = result { + assert_eq!(results.len(), 1); + // geomean(2, 8) = sqrt(16) = 4.0 + if let Value::Float(f) = &results[0][0] { + assert!((*f - 4.0).abs() < 1e-9, "expected ~4.0"); + } else { + panic!("expected Float result"); + } } else { - panic!("expected Float result"); + panic!("expected QueryResults"); } - } else { - panic!("expected QueryResults"); } } @@ -75,39 +126,42 @@ fn custom_aggregate_geometric_mean() { #[test] fn custom_aggregate_empty_result() { - let db = db(); - db.register_aggregate( - "geomean2", - || (0.0_f64, 0usize), - |acc: &mut (f64, usize), v: &Value| { - if let Value::Float(f) = v - && *f > 0.0 - { - acc.0 += f.ln(); - acc.1 += 1; - } - }, - |acc: &(f64, usize), _n: usize| { - if acc.1 == 0 { - Value::Null - } else { - Value::Float((acc.0 / acc.1 as f64).exp()) - } - }, - ) - .expect("register geomean2"); - - // No facts — empty result - let result = db - .execute(r#"(query [:find (geomean2 ?score) :where [?e :item/score ?score]])"#) - .expect("query failed"); - - if let minigraf::QueryResult::QueryResults { results, .. } = result { - // Empty input → no groups → no output rows (consistent with built-in behaviour - // for non-count aggregates when no facts match) - assert!(results.is_empty() || results[0][0] == Value::Null); - } else { - panic!("expected QueryResults"); + for reg in REGS { + let db = db(); + reg.aggregate( + &db, + "geomean2", + || (0.0_f64, 0usize), + |acc: &mut (f64, usize), v: &Value| { + if let Value::Float(f) = v + && *f > 0.0 + { + acc.0 += f.ln(); + acc.1 += 1; + } + }, + |acc: &(f64, usize), _n: usize| { + if acc.1 == 0 { + Value::Null + } else { + Value::Float((acc.0 / acc.1 as f64).exp()) + } + }, + ) + .expect("register geomean2"); + + // No facts — empty result + let result = db + .execute(r#"(query [:find (geomean2 ?score) :where [?e :item/score ?score]])"#) + .expect("query failed"); + + if let minigraf::QueryResult::QueryResults { results, .. } = result { + // Empty input → no groups → no output rows (consistent with built-in behaviour + // for non-count aggregates when no facts match) + assert!(results.is_empty() || results[0][0] == Value::Null); + } else { + panic!("expected QueryResults"); + } } } @@ -115,35 +169,38 @@ fn custom_aggregate_empty_result() { #[test] fn custom_predicate_filter() { - let db = db(); - db.register_predicate( - "email?", - |v: &Value| matches!(v, Value::String(s) if s.contains('@')), - ) - .expect("register email?"); - - seed( - &db, - &[r#"(transact [ - [:alice :person/email "alice@example.com"] - [:bob :person/email "notanemail"] - ])"#], - ); - - let result = db - .execute(r#"(query [:find ?e :where [?e :person/email ?addr] [(email? ?addr)]])"#) - .expect("query failed"); - - if let minigraf::QueryResult::QueryResults { results, .. } = result { - assert_eq!(results.len(), 1, "only alice has a valid email"); - // Entity IDs are stored as Value::Ref(deterministic UUID derived from the keyword). - // We verify the result is a Ref (entity ID) rather than checking the exact UUID. - assert!( - matches!(results[0][0], Value::Ref(_)), - "entity result must be a Ref" + for reg in REGS { + let db = db(); + reg.predicate( + &db, + "email?", + |v: &Value| matches!(v, Value::String(s) if s.contains('@')), + ) + .expect("register email?"); + + seed( + &db, + &[r#"(transact [ + [:alice :person/email "alice@example.com"] + [:bob :person/email "notanemail"] + ])"#], ); - } else { - panic!("expected QueryResults"); + + let result = db + .execute(r#"(query [:find ?e :where [?e :person/email ?addr] [(email? ?addr)]])"#) + .expect("query failed"); + + if let minigraf::QueryResult::QueryResults { results, .. } = result { + assert_eq!(results.len(), 1, "only alice has a valid email"); + // Entity IDs are stored as Value::Ref(deterministic UUID derived from the keyword). + // We verify the result is a Ref (entity ID) rather than checking the exact UUID. + assert!( + matches!(results[0][0], Value::Ref(_)), + "entity result must be a Ref" + ); + } else { + panic!("expected QueryResults"); + } } } @@ -151,46 +208,49 @@ fn custom_predicate_filter() { #[test] fn udf_as_window_function() { - let db = db(); - db.register_aggregate( - "winsum", - || 0i64, - |acc: &mut i64, v: &Value| { - if let Value::Integer(i) = v { - *acc += i; - } - }, - |acc: &i64, _n: usize| Value::Integer(*acc), - ) - .expect("register winsum"); - - seed( - &db, - &[r#"(transact [ - [:a :item/score 1] - [:b :item/score 2] - [:c :item/score 3] - ])"#], - ); - - let result = db - .execute( - r#"(query [:find ?e (winsum ?score :over (:order-by ?score)) - :where [?e :item/score ?score]])"#, + for reg in REGS { + let db = db(); + reg.aggregate( + &db, + "winsum", + || 0i64, + |acc: &mut i64, v: &Value| { + if let Value::Integer(i) = v { + *acc += i; + } + }, + |acc: &i64, _n: usize| Value::Integer(*acc), ) - .expect("query failed"); - - if let minigraf::QueryResult::QueryResults { results, .. } = result { - assert_eq!(results.len(), 3, "three rows"); - // After ordering by score: rows are 1,2,3; cumulative sums are 1,3,6 - let mut sums: Vec = results - .iter() - .map(|r| if let Value::Integer(n) = r[1] { n } else { -1 }) - .collect(); - sums.sort(); - assert_eq!(sums, vec![1, 3, 6]); - } else { - panic!("expected QueryResults"); + .expect("register winsum"); + + seed( + &db, + &[r#"(transact [ + [:a :item/score 1] + [:b :item/score 2] + [:c :item/score 3] + ])"#], + ); + + let result = db + .execute( + r#"(query [:find ?e (winsum ?score :over (:order-by ?score)) + :where [?e :item/score ?score]])"#, + ) + .expect("query failed"); + + if let minigraf::QueryResult::QueryResults { results, .. } = result { + assert_eq!(results.len(), 3, "three rows"); + // After ordering by score: rows are 1,2,3; cumulative sums are 1,3,6 + let mut sums: Vec = results + .iter() + .map(|r| if let Value::Integer(n) = r[1] { n } else { -1 }) + .collect(); + sums.sort(); + assert_eq!(sums, vec![1, 3, 6]); + } else { + panic!("expected QueryResults"); + } } } @@ -198,36 +258,43 @@ fn udf_as_window_function() { #[test] fn name_collision_builtin_aggregate() { - let db = db(); - let result = db.register_aggregate( - "sum", - || 0i64, - |_acc: &mut i64, _v: &Value| {}, - |acc: &i64, _n: usize| Value::Integer(*acc), - ); - assert!(result.is_err(), "shadowing built-in 'sum' must return Err"); + for reg in REGS { + let db = db(); + let result = reg.aggregate( + &db, + "sum", + || 0i64, + |_acc: &mut i64, _v: &Value| {}, + |acc: &i64, _n: usize| Value::Integer(*acc), + ); + assert!(result.is_err(), "shadowing built-in 'sum' must return Err"); + } } // ─── Test 6: name collision — UDF-on-UDF ───────────────────────────────────── #[test] fn name_collision_udf_on_udf() { - let db = db(); - db.register_aggregate( - "myfn", - || 0i64, - |_acc: &mut i64, _v: &Value| {}, - |acc: &i64, _n: usize| Value::Integer(*acc), - ) - .expect("first registration"); - - let result = db.register_aggregate( - "myfn", - || 0i64, - |_acc: &mut i64, _v: &Value| {}, - |acc: &i64, _n: usize| Value::Integer(*acc), - ); - assert!(result.is_err(), "duplicate UDF name must return Err"); + for reg in REGS { + let db = db(); + reg.aggregate( + &db, + "myfn", + || 0i64, + |_acc: &mut i64, _v: &Value| {}, + |acc: &i64, _n: usize| Value::Integer(*acc), + ) + .expect("first registration"); + + let result = reg.aggregate( + &db, + "myfn", + || 0i64, + |_acc: &mut i64, _v: &Value| {}, + |acc: &i64, _n: usize| Value::Integer(*acc), + ); + assert!(result.is_err(), "duplicate UDF name must return Err"); + } } // ─── Test 7: unknown aggregate function → runtime error ────────────────────── @@ -261,52 +328,55 @@ fn unknown_predicate_runtime_error() { #[test] #[cfg_attr(target_os = "wasi", ignore = "spawns threads; WASI has no threads")] fn thread_safety() { - use std::sync::Arc; - - let db = Arc::new(db()); - - // Seed some facts. - db.execute(r#"(transact [[:a :x 1] [:b :x 2]])"#) - .expect("seed"); - - // Spawn reader threads. - let mut handles = Vec::new(); - for _ in 0..4 { - let db2 = Arc::clone(&db); - handles.push(std::thread::spawn(move || { - for _ in 0..10 { - db2.execute(r#"(query [:find ?e :where [?e :x _]])"#) - .expect("concurrent read"); - } - })); - } + for reg in REGS { + use std::sync::Arc; + + let db = Arc::new(db()); + + // Seed some facts. + db.execute(r#"(transact [[:a :x 1] [:b :x 2]])"#) + .expect("seed"); + + // Spawn reader threads. + let mut handles = Vec::new(); + for _ in 0..4 { + let db2 = Arc::clone(&db); + handles.push(std::thread::spawn(move || { + for _ in 0..10 { + db2.execute(r#"(query [:find ?e :where [?e :x _]])"#) + .expect("concurrent read"); + } + })); + } - // Register a UDF from the main thread while readers run. - db.register_aggregate( - "threadfn", - || 0i64, - |acc: &mut i64, v: &Value| { - if let Value::Integer(i) = v { - *acc += i; - } - }, - |acc: &i64, _n: usize| Value::Integer(*acc), - ) - .expect("register threadfn"); + // Register a UDF from the main thread while readers run. + reg.aggregate( + &db, + "threadfn", + || 0i64, + |acc: &mut i64, v: &Value| { + if let Value::Integer(i) = v { + *acc += i; + } + }, + |acc: &i64, _n: usize| Value::Integer(*acc), + ) + .expect("register threadfn"); - for h in handles { - h.join().expect("reader thread panicked"); - } + for h in handles { + h.join().expect("reader thread panicked"); + } - // Verify the UDF works after concurrent registration. - let result = db - .execute(r#"(query [:find (threadfn ?x) :where [?e :x ?x]])"#) - .expect("post-registration query"); - if let minigraf::QueryResult::QueryResults { results, .. } = result { - assert_eq!(results.len(), 1); - assert_eq!(results[0][0], Value::Integer(3)); // 1 + 2 - } else { - panic!("expected QueryResults"); + // Verify the UDF works after concurrent registration. + let result = db + .execute(r#"(query [:find (threadfn ?x) :where [?e :x ?x]])"#) + .expect("post-registration query"); + if let minigraf::QueryResult::QueryResults { results, .. } = result { + assert_eq!(results.len(), 1); + assert_eq!(results[0][0], Value::Integer(3)); // 1 + 2 + } else { + panic!("expected QueryResults"); + } } } @@ -314,23 +384,29 @@ fn thread_safety() { #[test] fn udf_predicate_works_in_rule_body() { - let db = db(); - db.register_predicate("large?", |v| matches!(v, Value::Integer(n) if *n > 100)) - .unwrap(); - db.execute(r#"(transact [[:e1 :score 200] [:e2 :score 50]])"#) - .unwrap(); - db.execute(r#"(rule [(high-scorer ?e) [?e :score ?v] [(large? ?v)]])"#) - .unwrap(); - let result = db - .execute(r#"(query [:find ?e :where (high-scorer ?e)])"#) + for reg in REGS { + let db = db(); + reg.predicate( + &db, + "large?", + |v| matches!(v, Value::Integer(n) if *n > 100), + ) .unwrap(); - if let minigraf::QueryResult::QueryResults { results, .. } = result { - assert_eq!( - results.len(), - 1, - "only the entity with score > 100 should match" - ); - } else { - panic!("expected QueryResults"); + db.execute(r#"(transact [[:e1 :score 200] [:e2 :score 50]])"#) + .unwrap(); + db.execute(r#"(rule [(high-scorer ?e) [?e :score ?v] [(large? ?v)]])"#) + .unwrap(); + let result = db + .execute(r#"(query [:find ?e :where (high-scorer ?e)])"#) + .unwrap(); + if let minigraf::QueryResult::QueryResults { results, .. } = result { + assert_eq!( + results.len(), + 1, + "only the entity with score > 100 should match" + ); + } else { + panic!("expected QueryResults"); + } } } From 36bbc3d50fbecf52aa2c89ac50a34eeb336d1e2a Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 24 Oct 2026 18:10:52 +0530 Subject: [PATCH 03/13] feat(udf): a failing predicate fails the query with QRY-014 (#180) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015NBT2Yx9JUQKYvv2CvC9py --- src/query/datalog/executor.rs | 62 ++++++++++++++---- src/query/engine/filter.rs | 11 +++- tests/udf_test.rs | 120 ++++++++++++++++++++++++++++++++++ 3 files changed, 178 insertions(+), 15 deletions(-) diff --git a/src/query/datalog/executor.rs b/src/query/datalog/executor.rs index 14ef5a18e3..7b72e516c3 100644 --- a/src/query/datalog/executor.rs +++ b/src/query/datalog/executor.rs @@ -787,14 +787,31 @@ fn check_find_functions(find: &[FindSpec], registry: &FunctionRegistry) -> Resul Ok(()) } -/// Returns `Err(())` on: unbound variable, type mismatch, division by zero, unknown UDF predicate. +/// Why [`eval_expr`] gives no value. +#[derive(Debug)] +pub(crate) enum EvalError { + /// Unbound variable, type mismatch, division by zero, unknown UDF + /// predicate: the expression has no value, and its row is dropped. + NoValue, + /// A user predicate failed (`QRY-014`, #180): the query fails. + Udf(anyhow::Error), +} + +#[cfg(test)] +impl PartialEq for EvalError { + fn eq(&self, other: &Self) -> bool { + std::mem::discriminant(self) == std::mem::discriminant(other) + } +} + +/// The value of `expr` under `binding`; see [`EvalError`] for its failures. pub(crate) fn eval_expr( expr: &Expr, binding: &std::collections::HashMap, registry: Option<&FunctionRegistry>, -) -> Result { +) -> Result { match expr { - Expr::Var(v) => binding.get(v).cloned().ok_or(()), + Expr::Var(v) => binding.get(v).cloned().ok_or(EvalError::NoValue), Expr::Lit(val) => Ok(val.clone()), Expr::UnaryOp(op, arg) => { let v = eval_expr(arg, binding, registry)?; @@ -805,19 +822,28 @@ pub(crate) fn eval_expr( UnaryOp::BooleanQ => Ok(Value::Boolean(matches!(v, Value::Boolean(_)))), UnaryOp::NilQ => Ok(Value::Boolean(matches!(v, Value::Null))), UnaryOp::Udf(name) => { - let desc = registry.and_then(|r| r.get_predicate(name)).ok_or(())?; - Ok(Value::Boolean((desc.f)(&v).map_err(|_| ())?)) + let desc = registry + .and_then(|r| r.get_predicate(name)) + .ok_or(EvalError::NoValue)?; + match (desc.f)(&v) { + Ok(b) => Ok(Value::Boolean(b)), + Err(e) => Err(EvalError::Udf(err_coded!( + ErrorCode::Qry014, + name, + e.message() + ))), + } } } } Expr::BinOp(op, lhs, rhs) => { let l = eval_expr(lhs, binding, registry)?; let r = eval_expr(rhs, binding, registry)?; - eval_binop(op, l, r) + eval_binop(op, l, r).map_err(|()| EvalError::NoValue) } Expr::Slot(_) => { // Unsubstituted bind slot — treat as eval error (unbound variable equivalent). - Err(()) + Err(EvalError::NoValue) } } } @@ -2004,7 +2030,10 @@ mod expr_eval_tests { #[test] fn test_eval_var_unbound_is_err() { let e = Expr::Var("?x".to_string()); - assert_eq!(eval_expr(&e, &HashMap::new(), None), Err(())); + assert_eq!( + eval_expr(&e, &HashMap::new(), None), + Err(EvalError::NoValue) + ); } #[test] @@ -2067,7 +2096,10 @@ mod expr_eval_tests { Box::new(Expr::Lit(Value::Integer(5))), Box::new(Expr::Lit(Value::Integer(0))), ); - assert_eq!(eval_expr(&e, &HashMap::new(), None), Err(())); + assert_eq!( + eval_expr(&e, &HashMap::new(), None), + Err(EvalError::NoValue) + ); } #[test] @@ -2104,11 +2136,14 @@ mod expr_eval_tests { Box::new(Expr::Lit(Value::String("hello".to_string()))), Box::new(Expr::Lit(Value::Integer(100))), ); - assert_eq!(eval_expr(&e, &HashMap::new(), None), Err(())); + assert_eq!( + eval_expr(&e, &HashMap::new(), None), + Err(EvalError::NoValue) + ); } /// Evaluate `a b` for two string literals. - fn eval_str_cmp(op: BinOp, a: &str, b: &str) -> Result { + fn eval_str_cmp(op: BinOp, a: &str, b: &str) -> Result { eval_expr( &Expr::BinOp( op, @@ -2736,7 +2771,10 @@ mod expr_eval_tests { Box::new(Expr::Lit(Value::Float(5.0))), Box::new(Expr::Lit(Value::Float(0.0))), ); - assert_eq!(eval_expr(&e, &HashMap::new(), None), Err(())); + assert_eq!( + eval_expr(&e, &HashMap::new(), None), + Err(EvalError::NoValue) + ); } #[test] diff --git a/src/query/engine/filter.rs b/src/query/engine/filter.rs index 2b27dd5bc4..8b7fc3a944 100644 --- a/src/query/engine/filter.rs +++ b/src/query/engine/filter.rs @@ -9,7 +9,7 @@ use super::cell::{Cell, join_eq}; use super::plan::{Out, Step, Term, Vars}; use super::project::value; use super::{Counters, Ctx, Operator}; -use crate::query::datalog::executor::{eval_expr, is_truthy}; +use crate::query::datalog::executor::{EvalError, eval_expr, is_truthy}; use crate::query::datalog::types::Expr; use anyhow::Result; use std::collections::HashMap; @@ -142,7 +142,8 @@ fn apply(step: &Step, mut batch: Batch, ctx: &mut Ctx<'_>) -> Result { Ok(batch) } -/// `expr` over row `i`, or `None` where the executor's evaluation fails. +/// `expr` over row `i`, or `None` where it has no value; a failing user +/// predicate fails the query (`QRY-014`, #180). fn eval( expr: &Expr, vars: &Vars, @@ -156,5 +157,9 @@ fn eval( binding.insert(name.clone(), value(cell, ctx)?); } } - Ok(eval_expr(expr, &binding, Some(ctx.functions)).ok()) + match eval_expr(expr, &binding, Some(ctx.functions)) { + Ok(v) => Ok(Some(v)), + Err(EvalError::NoValue) => Ok(None), + Err(EvalError::Udf(e)) => Err(e), + } } diff --git a/tests/udf_test.rs b/tests/udf_test.rs index a497b67095..4b6b317760 100644 --- a/tests/udf_test.rs +++ b/tests/udf_test.rs @@ -410,3 +410,123 @@ fn udf_predicate_works_in_rule_body() { } } } + +// ─── Failing user functions → QRY-014 (#180) ───────────────────────────────── + +use minigraf::{BindValue, UdfError}; +use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; + +/// `n` entities `:n 0` … `:n n-1`, in one transaction. +fn seed_n(db: &Minigraf, n: usize) { + let facts: String = (0..n).map(|i| format!("[:e{i} :n {i}]")).collect(); + db.execute(&format!("(transact [{facts}])")).expect("seed"); +} + +/// Registers `boom?`, a predicate that is true until its `fail_at`-th call, +/// which fails. Returns its call counter. +fn failing_predicate(db: &Minigraf, fail_at: usize) -> Arc { + let calls = Arc::new(AtomicUsize::new(0)); + let c = Arc::clone(&calls); + db.try_register_predicate("boom?", move |_| { + if c.fetch_add(1, Ordering::SeqCst) + 1 == fail_at { + Err(UdfError::new("bad value")) + } else { + Ok(true) + } + }) + .expect("register boom?"); + calls +} + +fn assert_qry014(err: &MinigrafError, name: &str, message: &str) { + assert_eq!(err.code(), "QRY-014"); + assert_eq!( + err.to_string(), + format!("[QRY-014] user function `{name}` failed: {message}") + ); +} + +#[test] +fn failing_predicate_fails_the_query_in_every_position() { + for (what, rule, query) in [ + ( + ":where", + None, + "(query [:find ?e :where [?e :n ?v] [(boom? ?v)]])", + ), + ( + "rule body", + Some("(rule [(ok ?e) [?e :n ?v] [(boom? ?v)]])"), + "(query [:find ?e :where (ok ?e)])", + ), + ( + "not body", + None, + "(query [:find ?e :where [?e :n ?v] (not [(boom? ?v)])])", + ), + ( + "or branch", + None, + "(query [:find ?e :where [?e :n ?v] (or [(boom? ?v)] [(nil? ?v)])])", + ), + ] { + let db = db(); + seed_n(&db, 10); + if let Some(rule) = rule { + db.execute(rule).expect("rule"); + } + let calls = failing_predicate(&db, 5); + let err = db.execute(query).expect_err(what); + assert_qry014(&err, "boom?", "bad value"); + assert_eq!( + calls.load(Ordering::SeqCst), + 5, + "{what}: no call after the failing one" + ); + } +} + +#[test] +fn failing_predicate_through_a_cursor_returns_earlier_rows_then_the_error() { + let db = db(); + seed_n(&db, 1500); + let calls = failing_predicate(&db, 1500); + let mut cursor = db + .query("(query [:find ?e :where [?e :n ?v] [(boom? ?v)]])") + .expect("opens"); + let mut rows = 0; + let err = loop { + match cursor.next_batch(100) { + Ok(Some(batch)) => rows += batch.len(), + Ok(None) => panic!("the cursor ended without the error"), + Err(e) => break e, + } + }; + assert!( + rows > 0 && rows < 1500, + "rows before the failure come first" + ); + assert_qry014(&err, "boom?", "bad value"); + assert!(cursor.next_batch(100).expect("after the error").is_none()); + assert_eq!( + calls.load(Ordering::SeqCst), + 1500, + "no call after the failing one" + ); +} + +#[test] +fn failing_predicate_fails_a_prepared_query() { + let db = db(); + seed_n(&db, 10); + let calls = failing_predicate(&db, 3); + let pq = db + .prepare("(query [:find ?e :where [?e :n ?v] [(>= ?v $min)] [(boom? ?v)]])") + .expect("prepare"); + let err = pq + .execute(&[("min", BindValue::Val(Value::Integer(0)))]) + .expect_err("fails"); + assert_qry014(&err, "boom?", "bad value"); + assert_eq!(calls.load(Ordering::SeqCst), 3); +} From ee8159638e32265db5d6abfbe7dbf81df8099352 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 24 Oct 2026 18:14:30 +0530 Subject: [PATCH 04/13] feat(udf): a failing aggregate or window fails the query with QRY-014 (#180) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015NBT2Yx9JUQKYvv2CvC9py --- src/query/datalog/aggregate.rs | 85 +++++++++++++++++----------- src/query/datalog/aggregate/tests.rs | 44 +++++++------- src/query/engine/aggregate.rs | 2 +- tests/udf_test.rs | 72 +++++++++++++++++++++++ 4 files changed, 147 insertions(+), 56 deletions(-) diff --git a/src/query/datalog/aggregate.rs b/src/query/datalog/aggregate.rs index 405a5c3126..08b787628d 100644 --- a/src/query/datalog/aggregate.rs +++ b/src/query/datalog/aggregate.rs @@ -2,7 +2,7 @@ //! built-in function, used by the executor and the engine, whose result //! does not depend on the order of its input. -use super::functions::{AggImpl, Builtin, FunctionRegistry, UdfFinaliseFn, UdfStepFn}; +use super::functions::{AggImpl, Builtin, FunctionRegistry, UdfError, UdfFinaliseFn, UdfStepFn}; use super::types::{FindSpec, Order, WindowFunc, WindowSpec}; use crate::error::{ErrorCode, err_coded}; use crate::graph::types::Value; @@ -389,8 +389,9 @@ impl Extreme { } } -/// A registered aggregate's state. +/// A registered aggregate's state. A failing call is `QRY-014` (#180). pub(crate) struct Udf { + name: Box, acc: Box, step: UdfStepFn, finalise: UdfFinaliseFn, @@ -399,30 +400,43 @@ pub(crate) struct Udf { } impl Udf { - fn of(registry: &FunctionRegistry, name: &str) -> Option { - match ®istry.get(name)?.impl_ { - AggImpl::Udf(ops) => Some(Udf { - acc: (ops.init)().ok()?, - step: ops.step.clone(), - finalise: ops.finalise.clone(), - n: 0, - }), - AggImpl::Builtin(_) => None, - } + /// A new accumulator of the registered aggregate `name`, or `None` + /// when `name` is not one; `init`'s failure is `QRY-014`. + fn of(registry: &FunctionRegistry, name: &str) -> Result> { + let Some(AggImpl::Udf(ops)) = registry.get(name).map(|d| &d.impl_) else { + return Ok(None); + }; + let acc = (ops.init)().map_err(|e| failed(name, &e))?; + Ok(Some(Udf { + name: name.into(), + acc, + step: ops.step.clone(), + finalise: ops.finalise.clone(), + n: 0, + })) } - fn add(&mut self, v: &Value) { - let _ = (self.step)(&mut self.acc, v); + fn add(&mut self, v: &Value) -> Result<()> { + (self.step)(&mut self.acc, v).map_err(|e| failed(&self.name, &e))?; self.n += 1; + Ok(()) } - fn value(&self) -> Value { - (self.finalise)(&self.acc, self.n).unwrap_or(Value::Null) + fn value(&self) -> Result { + (self.finalise)(&self.acc, self.n).map_err(|e| failed(&self.name, &e)) } } -/// One aggregate of one group (spec §3.2). Takes values one at a time and -/// never fails while taking them; [`Agg::finish`] decides the result. +/// `QRY-014`: the user function `name` failed with `e`. +fn failed(name: &str, e: &UdfError) -> anyhow::Error { + err_coded!(ErrorCode::Qry014, name, e.message()) +} + +impl Udf {} + +/// One aggregate of one group (spec §3.2). Takes values one at a time, +/// failing while taking them only for a user aggregate's `step` (`QRY-014`); +/// [`Agg::finish`] decides the result. pub(crate) enum Agg { Count(i64), /// The sum, and the type of the first value that is not a number. @@ -453,7 +467,7 @@ impl Agg { Builtin::SumDistinct => Agg::SumDistinct(BTreeSet::new()), }, AggImpl::Udf(_) => Agg::Udf( - Udf::of(registry, func).ok_or_else(|| err_coded!(ErrorCode::Int029, func))?, + Udf::of(registry, func)?.ok_or_else(|| err_coded!(ErrorCode::Int029, func))?, ), }) } @@ -469,10 +483,11 @@ impl Agg { } } - /// Take one value; `nil` is skipped by every aggregate. - pub(crate) fn step(&mut self, v: &Value) { + /// Take one value; `nil` is skipped by every aggregate. Only a user + /// aggregate fails (`QRY-014`). + pub(crate) fn step(&mut self, v: &Value) -> Result<()> { if matches!(v, Value::Null) { - return; + return Ok(()); } match self { Agg::Count(n) => *n = n.saturating_add(1), @@ -486,8 +501,9 @@ impl Agg { Agg::CountDistinct(set) | Agg::SumDistinct(set) => { set.insert(canonical(v)); } - Agg::Udf(u) => u.add(v), + Agg::Udf(u) => u.add(v)?, } + Ok(()) } /// The result: `Ok(None)` when the group is dropped (`min`/`max` with no @@ -527,7 +543,7 @@ impl Agg { s.value() } Agg::Udf(u) if u.n == 0 => Value::Null, - Agg::Udf(u) => u.value(), + Agg::Udf(u) => u.value()?, })) } } @@ -587,11 +603,12 @@ impl Running { AggImpl::Builtin(Builtin::CountDistinct | Builtin::SumDistinct) => { return Err(unknown()); } - AggImpl::Udf(_) => Running::Udf(Udf::of(registry, &name).ok_or_else(unknown)?), + AggImpl::Udf(_) => Running::Udf(Udf::of(registry, &name)?.ok_or_else(unknown)?), }) } - pub(crate) fn step(&mut self, v: &Value) { + /// Take one value. Only a user aggregate fails (`QRY-014`). + pub(crate) fn step(&mut self, v: &Value) -> Result<()> { match self { Running::Count(n) => { if !matches!(v, Value::Null) { @@ -603,18 +620,20 @@ impl Running { } Running::Min(e) => e.add(v, false), Running::Max(e) => e.add(v, true), - Running::Udf(u) => u.add(v), + Running::Udf(u) => u.add(v)?, } + Ok(()) } - pub(crate) fn value(&self) -> Value { - match self { + /// The running value. Only a user aggregate fails (`QRY-014`). + pub(crate) fn value(&self) -> Result { + Ok(match self { Running::Count(n) => Value::Integer(*n), Running::Sum(s) => s.value(), Running::Avg(s) => s.mean(), Running::Min(e) | Running::Max(e) => e.best.clone().unwrap_or(Value::Null), - Running::Udf(u) => u.value(), - } + Running::Udf(u) => u.value()?, + }) } } @@ -689,12 +708,12 @@ pub(crate) fn windows( let peers = keyed.get(start..end).unwrap_or(&[]); if let Some(acc) = running.as_mut() { for &r in peers { - acc.step(read(r, var)); + acc.step(read(r, var))?; } } for (pos, &r) in (start..end).zip(peers) { let value = match (&running, &ws.func) { - (Some(acc), _) => acc.value(), + (Some(acc), _) => acc.value()?, (None, WindowFunc::RowNumber) => position(pos)?, (None, _) => position(start)?, }; diff --git a/src/query/datalog/aggregate/tests.rs b/src/query/datalog/aggregate/tests.rs index 472d6a628d..02b581932f 100644 --- a/src/query/datalog/aggregate/tests.rs +++ b/src/query/datalog/aggregate/tests.rs @@ -47,7 +47,7 @@ fn finish(func: &str, vals: &[Value]) -> Result> { let reg = FunctionRegistry::with_builtins(); let mut agg = Agg::new(func, ®)?; for v in vals { - agg.step(v); + agg.step(v).unwrap(); } agg.finish(func) } @@ -344,7 +344,7 @@ fn registered_aggregate_steps_non_nil_values() { let reg = registry_with_udf(); let mut agg = Agg::new("total", ®).expect("registered"); for v in [i(2), Value::Null, i(3)] { - agg.step(&v); + agg.step(&v).unwrap(); } assert_eq!(agg.finish("total").ok().flatten(), Some(i(502))); let empty = Agg::new("total", ®).expect("registered"); @@ -366,34 +366,34 @@ fn window(src: &str) -> WindowSpec { fn running_values() { let reg = registry_with_udf(); let mut sum = Running::new(&window("(sum ?v :over (:order-by ?o))"), ®).expect("sum"); - assert_eq!(sum.value(), i(0)); - sum.step(&i(2)); - assert_eq!(sum.value(), i(2)); - sum.step(&Value::String("skipped".into())); - sum.step(&f(0.5)); - assert_eq!(sum.value(), f(2.5)); + assert_eq!(sum.value().unwrap(), i(0)); + sum.step(&i(2)).unwrap(); + assert_eq!(sum.value().unwrap(), i(2)); + sum.step(&Value::String("skipped".into())).unwrap(); + sum.step(&f(0.5)).unwrap(); + assert_eq!(sum.value().unwrap(), f(2.5)); let mut min = Running::new(&window("(min ?v :over (:order-by ?o))"), ®).expect("min"); - assert_eq!(min.value(), Value::Null); - min.step(&kw(":b")); - min.step(&kw(":a")); - assert_eq!(min.value(), kw(":a")); + assert_eq!(min.value().unwrap(), Value::Null); + min.step(&kw(":b")).unwrap(); + min.step(&kw(":a")).unwrap(); + assert_eq!(min.value().unwrap(), kw(":a")); let mut count = Running::new(&window("(count ?v :over (:order-by ?o))"), ®).expect("count"); - count.step(&Value::Null); - count.step(&i(1)); - assert_eq!(count.value(), i(1)); + count.step(&Value::Null).unwrap(); + count.step(&i(1)).unwrap(); + assert_eq!(count.value().unwrap(), i(1)); let mut avg = Running::new(&window("(avg ?v :over (:order-by ?o))"), ®).expect("avg"); - assert_eq!(avg.value(), Value::Null); - avg.step(&i(1)); - avg.step(&i(2)); - assert_eq!(avg.value(), f(1.5)); + assert_eq!(avg.value().unwrap(), Value::Null); + avg.step(&i(1)).unwrap(); + avg.step(&i(2)).unwrap(); + assert_eq!(avg.value().unwrap(), f(1.5)); let mut udf = Running::new(&window("(total ?v :over (:order-by ?o))"), ®).expect("udf"); - udf.step(&Value::Null); - udf.step(&i(4)); - assert_eq!(udf.value(), i(402)); + udf.step(&Value::Null).unwrap(); + udf.step(&i(4)).unwrap(); + assert_eq!(udf.value().unwrap(), i(402)); assert!( Running::new(&window("(nope ?v :over (:order-by ?o))"), ®) diff --git a/src/query/engine/aggregate.rs b/src/query/engine/aggregate.rs index 2a62c00fb1..79ef007f55 100644 --- a/src/query/engine/aggregate.rs +++ b/src/query/engine/aggregate.rs @@ -67,7 +67,7 @@ impl Acc { if agg.would_add(&v) { held.charge(value_bytes(&v) + HASH_ENTRY_OVERHEAD)?; } - agg.step(&v); + agg.step(&v)?; } } Ok(()) diff --git a/tests/udf_test.rs b/tests/udf_test.rs index 4b6b317760..46ec51be8c 100644 --- a/tests/udf_test.rs +++ b/tests/udf_test.rs @@ -530,3 +530,75 @@ fn failing_predicate_fails_a_prepared_query() { assert_qry014(&err, "boom?", "bad value"); assert_eq!(calls.load(Ordering::SeqCst), 3); } + +#[derive(Clone, Copy, PartialEq, Debug)] +enum Phase { + Init, + Step, + Finalise, +} + +/// Calls of a failing aggregate: every call, and the number of calls made +/// when it failed. +struct AggCalls { + total: Arc, + at_failure: Arc, +} + +/// Registers `boom`, a sum whose `fail_at`-th call of `phase` fails. +fn failing_aggregate(db: &Minigraf, phase: Phase, fail_at: usize) -> AggCalls { + let total = Arc::new(AtomicUsize::new(0)); + let at_failure = Arc::new(AtomicUsize::new(0)); + let counts: Arc<[AtomicUsize; 3]> = Arc::new(Default::default()); + let call = { + let (total, at_failure) = (Arc::clone(&total), Arc::clone(&at_failure)); + move |p: Phase| -> Result<(), UdfError> { + let n = total.fetch_add(1, Ordering::SeqCst) + 1; + if p == phase && counts[p as usize].fetch_add(1, Ordering::SeqCst) + 1 == fail_at { + at_failure.store(n, Ordering::SeqCst); + return Err(UdfError::new(format!("{p:?} failed"))); + } + Ok(()) + } + }; + let (c1, c2, c3) = (call.clone(), call.clone(), call); + db.try_register_aggregate( + "boom", + move || c1(Phase::Init).map(|()| 0i64), + move |acc: &mut i64, v: &Value| { + c2(Phase::Step)?; + if let Value::Integer(i) = v { + *acc += i; + } + Ok(()) + }, + move |acc: &i64, _n| c3(Phase::Finalise).map(|()| Value::Integer(*acc)), + ) + .expect("register boom"); + AggCalls { total, at_failure } +} + +#[test] +fn failing_aggregate_fails_the_query_in_every_phase() { + let aggregate = "(query [:find ?g (boom ?v) :where [?e :n ?v] [?e :g ?g]])"; + let window = "(query [:find ?e (boom ?v :over (:partition-by ?g :order-by ?v)) :where [?e :n ?v] [?e :g ?g]])"; + for query in [aggregate, window] { + for (phase, fail_at) in [(Phase::Init, 2), (Phase::Step, 4), (Phase::Finalise, 2)] { + let db = db(); + let facts: String = (0..10) + .map(|i| format!("[:e{i} :n {i}] [:e{i} :g {}]", i % 3)) + .collect(); + db.execute(&format!("(transact [{facts}])")).expect("seed"); + let calls = failing_aggregate(&db, phase, fail_at); + let err = db.execute(query).expect_err("fails"); + assert_qry014(&err, "boom", &format!("{phase:?} failed")); + let at = calls.at_failure.load(Ordering::SeqCst); + assert!(at > 0, "the failing call was made"); + assert_eq!( + calls.total.load(Ordering::SeqCst), + at, + "no call after the failing one" + ); + } + } +} From b94c36705d3e2ccdfe08f46ab7ea00a4971a371c Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 24 Oct 2026 18:19:55 +0530 Subject: [PATCH 05/13] feat(udf): queries read functions from a registry snapshot (#180) A query snapshots the function registry when it opens and holds no lock while a user function runs; registration swaps in a new registry. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015NBT2Yx9JUQKYvv2CvC9py --- src/browser/mod.rs | 8 +- src/db.rs | 22 ++--- src/query/datalog/executor.rs | 72 +++++++---------- src/query/datalog/functions.rs | 45 ++++++++++- src/query/datalog/prepared.rs | 6 +- src/query/engine/mod.rs | 25 +++--- src/query/engine/tests.rs | 3 +- tests/udf_reentry_test.rs | 142 +++++++++++++++++++++++++++++++++ 8 files changed, 236 insertions(+), 87 deletions(-) create mode 100644 tests/udf_reentry_test.rs diff --git a/src/browser/mod.rs b/src/browser/mod.rs index 7948950f1a..6bb8fd5a87 100644 --- a/src/browser/mod.rs +++ b/src/browser/mod.rs @@ -15,7 +15,7 @@ use crate::browser::buffer::BrowserBufferBackend; use crate::browser::indexeddb::IndexedDbBackend; use crate::graph::FactStorage; use crate::query::datalog::executor::{DatalogExecutor, QueryResult}; -use crate::query::datalog::functions::FunctionRegistry; +use crate::query::datalog::functions::Functions; use crate::query::datalog::parser::parse_datalog_command; use crate::query::datalog::prepared::{BindValue, PreparedQuery}; use crate::query::datalog::rules::RuleRegistry; @@ -30,7 +30,7 @@ use wasm_bindgen::prelude::*; struct BrowserDbInner { fact_storage: FactStorage, rules: Arc>, - functions: Arc>, + functions: Arc, pfs: PersistentFactStorage, /// `None` for in-memory databases (no IDB backing). idb: Option, @@ -67,7 +67,7 @@ impl BrowserDb { inner: Rc::new(RefCell::new(BrowserDbInner { fact_storage, rules: Arc::new(RwLock::new(RuleRegistry::new())), - functions: Arc::new(RwLock::new(FunctionRegistry::with_builtins())), + functions: Arc::new(Functions::with_builtins()), pfs, idb: None, withheld: Vec::new(), @@ -101,7 +101,7 @@ impl BrowserDb { inner: Rc::new(RefCell::new(BrowserDbInner { fact_storage, rules: Arc::new(RwLock::new(RuleRegistry::new())), - functions: Arc::new(RwLock::new(FunctionRegistry::with_builtins())), + functions: Arc::new(Functions::with_builtins()), pfs, idb: Some(idb), withheld: Vec::new(), diff --git a/src/db.rs b/src/db.rs index d06132aaba..2befbbb24c 100644 --- a/src/db.rs +++ b/src/db.rs @@ -24,8 +24,8 @@ use crate::query::datalog::evaluator::DEFAULT_MAX_DERIVED_FACTS; use crate::query::datalog::executor::DatalogExecutor; use crate::query::datalog::executor::QueryResult; use crate::query::datalog::functions::{ - AggImpl, AggregateDesc, FunctionRegistry, PredicateDesc, UdfError, UdfFinaliseFn, UdfInitFn, - UdfOps, UdfStepFn, + AggImpl, AggregateDesc, Functions, PredicateDesc, UdfError, UdfFinaliseFn, UdfInitFn, UdfOps, + UdfStepFn, }; use crate::query::datalog::parser::parse_datalog_command; use crate::query::datalog::parser::statement::{self, Kind}; @@ -425,7 +425,7 @@ struct Inner { rules: Arc>, /// Function registry for aggregates and window functions. /// `RwLock` is used in anticipation of the 7.7b `register_aggregate`/`register_predicate` mutation API. - functions: Arc>, + functions: Arc, /// Serialises all writes. Holds `WriteContext` which contains the PFS/WAL /// for file-backed databases. write_lock: Mutex, @@ -633,7 +633,7 @@ impl Minigraf { inner: Arc::new(Inner { fact_storage, rules: Arc::new(RwLock::new(RuleRegistry::new())), - functions: Arc::new(RwLock::new(FunctionRegistry::with_builtins())), + functions: Arc::new(Functions::with_builtins()), write_lock: Mutex::new(ctx), options, }), @@ -1561,9 +1561,7 @@ impl Minigraf { }; self.inner .functions - .write() - .map_err(|_| err_coded!(ErrorCode::Api008))? - .register_aggregate_desc(name.to_string(), desc) + .register(|reg| reg.register_aggregate_desc(name.to_string(), desc)) } /// Register a custom single-argument filter predicate. @@ -1638,9 +1636,7 @@ impl Minigraf { }; self.inner .functions - .write() - .map_err(|_| err_coded!(ErrorCode::Api008))? - .register_predicate_desc(name.to_string(), desc) + .register(|reg| reg.register_predicate_desc(name.to_string(), desc)) } } @@ -2562,11 +2558,7 @@ mod tests { let db = Minigraf::in_memory().unwrap(); - let poison_db = db.clone(); - let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(move || { - let _guard = poison_db.inner.functions.write().unwrap(); - panic!("intentionally poisoning the function registry lock for a test"); - })); + db.inner.functions.poison(); let err = db .register_predicate("always_true", |_: &Value| true) diff --git a/src/query/datalog/executor.rs b/src/query/datalog/executor.rs index 7b72e516c3..d48dc16e49 100644 --- a/src/query/datalog/executor.rs +++ b/src/query/datalog/executor.rs @@ -1,4 +1,4 @@ -use super::functions::FunctionRegistry; +use super::functions::{FunctionRegistry, Functions}; use super::matcher::{edn_to_entity_id, edn_to_value}; use super::rules::RuleRegistry; use super::types::{ @@ -123,7 +123,7 @@ pub struct DatalogExecutor { snapshot: Option, rules: Arc>, // RwLock pre-wired for 7.7b register_aggregate API. - functions: Arc>, + functions: Arc, /// The most facts a rule query may derive, base facts not counted (#553). max_derived_facts: usize, /// The most bytes an engine query may hold (#549). @@ -137,7 +137,7 @@ impl DatalogExecutor { storage, snapshot: None, rules: Arc::new(RwLock::new(RuleRegistry::new())), - functions: Arc::new(RwLock::new(FunctionRegistry::with_builtins())), + functions: Arc::new(Functions::with_builtins()), max_derived_facts: crate::query::datalog::evaluator::DEFAULT_MAX_DERIVED_FACTS, query_memory_limit: usize::MAX, } @@ -149,7 +149,7 @@ impl DatalogExecutor { pub fn new_with_rules_and_functions( storage: FactStorage, rules: Arc>, - functions: Arc>, + functions: Arc, ) -> Self { DatalogExecutor { storage, @@ -166,11 +166,7 @@ impl DatalogExecutor { /// [`new_with_rules_and_functions`] to share the registry from `Minigraf::Inner`. #[allow(dead_code)] pub fn new_with_rules(storage: FactStorage, rules: Arc>) -> Self { - Self::new_with_rules_and_functions( - storage, - rules, - Arc::new(RwLock::new(FunctionRegistry::with_builtins())), - ) + Self::new_with_rules_and_functions(storage, rules, Arc::new(Functions::with_builtins())) } /// Create a `DatalogExecutor` with custom complexity limits. @@ -180,7 +176,7 @@ impl DatalogExecutor { pub fn new_with_limits( storage: FactStorage, rules: Arc>, - functions: Arc>, + functions: Arc, max_derived_facts: usize, ) -> Self { DatalogExecutor { @@ -317,19 +313,16 @@ impl DatalogExecutor { } fn open_query(&self, query: DatalogQuery) -> Result { + // The query reads every function from this one snapshot, its checks + // included, and holds no lock while a user function runs (#180). + let functions = self.functions.snapshot()?; // Resolve :find functions up front so an unknown name fails whether or // not any row matches (#414). - { - let registry = self - .functions - .read() - .map_err(|_| err_coded!(ErrorCode::Qry008))?; - check_find_functions(&query.find, ®istry)?; - } + check_find_functions(&query.find, &functions)?; // A rule query (#548). if query.uses_rules() { - return self.open_rule_query(&query); + return self.open_rule_query(&query, functions); } // Warn about queries with no binding mechanism @@ -346,20 +339,10 @@ impl DatalogExecutor { return Err(e); } }; - { - let registry = self - .functions - .read() - .map_err(|_| err_coded!(ErrorCode::Qry008))?; - check_clauses(&query, ®istry)?; - } + check_clauses(&query, &functions)?; let snapshot = self.read_snapshot()?; - let stream = crate::query::engine::open( - snapshot.clone(), - plan, - self.functions.clone(), - self.query_memory_limit, - )?; + let stream = + crate::query::engine::open(snapshot.clone(), plan, functions, self.query_memory_limit)?; #[cfg(test)] crate::query::engine::RUNS.with(|r| r.set(r.get() + 1)); Ok(Answer::Stream(Box::new(stream))) @@ -368,7 +351,11 @@ impl DatalogExecutor { /// A rule query on the streaming engine (#548). Its errors come in the /// executor's order: pseudo-attributes, then the rules, then unknown /// predicates. - fn open_rule_query(&self, query: &DatalogQuery) -> Result { + fn open_rule_query( + &self, + query: &DatalogQuery, + functions: Arc, + ) -> Result { let plan = { let registry = self .rules @@ -421,14 +408,10 @@ impl DatalogExecutor { plan, &seeds, &keywords, - self.functions.clone(), + Arc::clone(&functions), limits, )?; - let registry = self - .functions - .read() - .map_err(|_| err_coded!(ErrorCode::Qry008))?; - check_predicates(&names, ®istry)?; + check_predicates(&names, &functions)?; Ok(stream) }; let stream = open(plan)?; @@ -851,7 +834,6 @@ pub(crate) fn eval_expr( #[cfg(test)] mod tests { use super::*; - use crate::query::datalog::functions::FunctionRegistry; use crate::query::datalog::parser::parse_datalog_command; use crate::query::datalog::rules::RuleRegistry; use crate::query::datalog::types::WhereClause; @@ -1918,7 +1900,7 @@ mod tests { fn test_per_query_max_derived_facts_overrides_executor_default() { let storage = FactStorage::new(); let rules = Arc::new(RwLock::new(RuleRegistry::new())); - let functions = Arc::new(RwLock::new(FunctionRegistry::with_builtins())); + let functions = Arc::new(Functions::with_builtins()); let mut executor = DatalogExecutor::new_with_rules_and_functions( storage, rules.clone(), @@ -1964,7 +1946,7 @@ mod tests { fn test_per_query_limit_does_not_bleed_into_next_query() { let storage = FactStorage::new(); let rules = Arc::new(RwLock::new(RuleRegistry::new())); - let functions = Arc::new(RwLock::new(FunctionRegistry::with_builtins())); + let functions = Arc::new(Functions::with_builtins()); let executor = DatalogExecutor::new_with_rules_and_functions( storage, rules.clone(), @@ -2661,8 +2643,8 @@ mod expr_eval_tests { fn execute_query_functions_lock_poisoned_error() { let storage = FactStorage::new(); let rules = Arc::new(RwLock::new(RuleRegistry::new())); - let functions = Arc::new(RwLock::new(FunctionRegistry::with_builtins())); - poison_rwlock(&functions); + let functions = Arc::new(Functions::with_builtins()); + functions.poison(); let executor = DatalogExecutor::new_with_rules_and_functions(storage, rules, functions); let cmd = parse_datalog_command(r#"(query [:find ?e :where [?e :name ?n]])"#).unwrap(); @@ -2679,7 +2661,7 @@ mod expr_eval_tests { fn execute_rule_rules_lock_poisoned_error() { let storage = FactStorage::new(); let rules = Arc::new(RwLock::new(RuleRegistry::new())); - let functions = Arc::new(RwLock::new(FunctionRegistry::with_builtins())); + let functions = Arc::new(Functions::with_builtins()); poison_rwlock(&rules); let executor = DatalogExecutor::new_with_rules_and_functions(storage, rules, functions); @@ -2699,7 +2681,7 @@ mod expr_eval_tests { // (distinct call site from execute_rule's rules.write()). let storage = FactStorage::new(); let rules = Arc::new(RwLock::new(RuleRegistry::new())); - let functions = Arc::new(RwLock::new(FunctionRegistry::with_builtins())); + let functions = Arc::new(Functions::with_builtins()); { // Register a rule normally first so the query recognises it as // rule-backed (uses_rules()) and takes the rules path. diff --git a/src/query/datalog/functions.rs b/src/query/datalog/functions.rs index 21a42fc489..66ead2b9d3 100644 --- a/src/query/datalog/functions.rs +++ b/src/query/datalog/functions.rs @@ -1,8 +1,8 @@ -use crate::error::{ErrorCode, bail_coded}; +use crate::error::{ErrorCode, bail_coded, err_coded}; use crate::graph::types::Value; use std::any::Any; use std::collections::HashMap; -use std::sync::Arc; +use std::sync::{Arc, RwLock}; /// Why a user-defined function failed. Its message is in the query's /// `QRY-014` error. @@ -188,6 +188,47 @@ impl FunctionRegistry { } } +/// The registry a database shares between its handles (#180, spec §5). A +/// query reads its functions from a [`snapshot`](Functions::snapshot) taken +/// when it opens, so no lock is held while a user function runs, and a +/// function registered later is not visible to it. Registration swaps in a +/// new registry. +pub struct Functions(RwLock>); + +impl Functions { + pub(crate) fn with_builtins() -> Self { + Functions(RwLock::new(Arc::new(FunctionRegistry::with_builtins()))) + } + + /// The registry now; a poisoned lock is `QRY-008`. + pub(crate) fn snapshot(&self) -> anyhow::Result> { + let reg = self.0.read().map_err(|_| err_coded!(ErrorCode::Qry008))?; + Ok(Arc::clone(®)) + } + + /// Apply `f` to a copy of the registry and swap the copy in if `f` + /// succeeds; a poisoned lock is `API-008`. + pub(crate) fn register( + &self, + f: impl FnOnce(&mut FunctionRegistry) -> anyhow::Result<()>, + ) -> anyhow::Result<()> { + let mut reg = self.0.write().map_err(|_| err_coded!(ErrorCode::Api008))?; + let mut next = FunctionRegistry::clone(®); + f(&mut next)?; + *reg = Arc::new(next); + Ok(()) + } + + /// Poison the lock, for the tests of `QRY-008` and `API-008`. + #[cfg(test)] + pub(crate) fn poison(&self) { + let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { + let _guard = self.0.write(); + panic!("poison the functions lock"); + })); + } +} + #[cfg(test)] mod tests { use super::*; diff --git a/src/query/datalog/prepared.rs b/src/query/datalog/prepared.rs index 39ae561b5e..2b6aa006dc 100644 --- a/src/query/datalog/prepared.rs +++ b/src/query/datalog/prepared.rs @@ -4,7 +4,7 @@ use crate::graph::FactStorage; use crate::graph::storage::Snapshot; use crate::graph::types::Value; use crate::query::datalog::executor::{DatalogExecutor, QueryResult}; -use crate::query::datalog::functions::FunctionRegistry; +use crate::query::datalog::functions::Functions; use crate::query::datalog::rules::RuleRegistry; use crate::query::datalog::types::{ AsOf, AttributeSpec, DatalogCommand, DatalogQuery, EdnValue, Expr, ValidAt, WhereClause, @@ -81,7 +81,7 @@ pub struct PreparedQuery { slot_names: Vec, fact_storage: FactStorage, rules: Arc>, - functions: Arc>, + functions: Arc, /// The database's `max_derived_facts` and `query_memory_limit`. limits: (usize, usize), } @@ -175,7 +175,7 @@ pub(crate) fn prepare_query( query: DatalogQuery, fact_storage: FactStorage, rules: Arc>, - functions: Arc>, + functions: Arc, limits: (usize, usize), ) -> Result { validate_no_attribute_slots(&query)?; diff --git a/src/query/engine/mod.rs b/src/query/engine/mod.rs index 9709faf746..e899e808d8 100644 --- a/src/query/engine/mod.rs +++ b/src/query/engine/mod.rs @@ -35,7 +35,7 @@ use ids::IdSpace; pub(crate) use meter::Meter; pub(crate) use plan::{Plan, plan, plan_rules, udfs}; pub(crate) use recursive::Limits; -use std::sync::{Arc, RwLock}; +use std::sync::Arc; #[cfg(test)] thread_local! { @@ -106,9 +106,9 @@ pub(crate) trait Operator: Send { pub(crate) struct Stream { snapshot: Snapshot, ids: IdSpace, - /// Read-locked for each pull. Predicates are never replaced once - /// registered (`INT-040`), so the answer does not change between pulls. - functions: Arc>, + /// The functions the query opened with (#180): no lock is held while a + /// user function runs, and a function registered later is not seen. + functions: Arc, root: Box, /// The bytes the query's holders count (#549); each holder keeps its /// own reference, so the stream keeps one for tests only. @@ -160,7 +160,7 @@ fn keys(snapshot: &Snapshot) -> Result> { pub(crate) fn open( snapshot: Snapshot, plan: Plan, - functions: Arc>, + functions: Arc, memory_limit: usize, ) -> Result { let keys = keys(&snapshot)?; @@ -199,7 +199,7 @@ pub(crate) fn open_rules( plan: plan::RulesPlan, seeds: &[(EntityId, String, Value)], keywords: &[String], - functions: Arc>, + functions: Arc, limits: recursive::Limits, ) -> Result { let meter = Meter::new(limits.query_memory); @@ -232,9 +232,6 @@ pub(crate) fn open_rules( } } rels.end_round(); - let functions = functions - .read() - .map_err(|_| err_coded!(ErrorCode::Qry008))?; let reads = recursive::Reads { snapshot: &snapshot, keys, @@ -260,7 +257,7 @@ fn stream( snapshot: Snapshot, ids: IdSpace, plan: Plan, - functions: Arc>, + functions: Arc, relations: Option, meter: Arc, (bound, bound_held): (TxBound, meter::Held), @@ -334,7 +331,7 @@ impl Stream { Stream { snapshot, ids: IdSpace::new(None, &meter), - functions: Arc::new(RwLock::new(FunctionRegistry::with_builtins())), + functions: Arc::new(FunctionRegistry::with_builtins()), root, meter, find: vec![0], @@ -367,10 +364,6 @@ impl Stream { } fn pull(&mut self) -> Result>>> { - let functions = self - .functions - .read() - .map_err(|_| err_coded!(ErrorCode::Qry008))?; let mut ctx = Ctx { snapshot: &self.snapshot, keys: self @@ -379,7 +372,7 @@ impl Stream { .as_deref() .and_then(CommittedReader::key_source), ids: &mut self.ids, - functions: &functions, + functions: &self.functions, derived: self.relations.as_ref(), bound: &self.bound, }; diff --git a/src/query/engine/tests.rs b/src/query/engine/tests.rs index 8a54b98e8e..1818b795ba 100644 --- a/src/query/engine/tests.rs +++ b/src/query/engine/tests.rs @@ -2866,8 +2866,7 @@ fn meter_peak_against_rss() { panic!("expected a query"); }; let plan = super::plan(&query).expect("an engine plan"); - let functions = - std::sync::Arc::new(std::sync::RwLock::new(FunctionRegistry::with_builtins())); + let functions = std::sync::Arc::new(FunctionRegistry::with_builtins()); let snapshot = db.snapshot().unwrap(); let reset = std::fs::write("/proc/self/clear_refs", "5").is_ok(); let before_kb = proc_status_kb("VmRSS"); diff --git a/tests/udf_reentry_test.rs b/tests/udf_reentry_test.rs new file mode 100644 index 0000000000..4627fe4221 --- /dev/null +++ b/tests/udf_reentry_test.rs @@ -0,0 +1,142 @@ +// File-backed (Minigraf::open, tempfile): native only, like the other file tests. +#![cfg(not(target_arch = "wasm32"))] +//! A query reads its functions from a snapshot of the registry taken when it +//! opens, and holds no lock while a user function runs, so a function may +//! call back into its own database (#180, spec §5). +//! +//! Testing conventions: no `{:?}` of Result/Value/Fact in assert messages. + +use minigraf::{Minigraf, QueryResult, Value}; +use std::sync::mpsc; +use std::thread; +use std::time::Duration; + +/// Runs `f` on a fresh thread and returns its result. A call that deadlocks +/// fails the test after 30 s instead of hanging it; the blocked thread is +/// left until the test process exits. +fn within_timeout(f: impl FnOnce() -> T + Send + 'static) -> T { + let (tx, rx) = mpsc::channel(); + thread::spawn(move || { + let _ = tx.send(f()); + }); + match rx.recv_timeout(Duration::from_secs(30)) { + Ok(v) => v, + Err(mpsc::RecvTimeoutError::Timeout) => panic!("deadlocked"), + Err(mpsc::RecvTimeoutError::Disconnected) => panic!("the call panicked"), + } +} + +fn rows(result: QueryResult) -> Vec> { + match result { + QueryResult::QueryResults { results, .. } => results, + _ => panic!("expected QueryResults"), + } +} + +// ─── Registry snapshot (plan step 9) ───────────────────────────────────────── + +#[test] +fn a_predicate_that_registers_a_function_returns() { + let n = within_timeout(|| { + let db = Minigraf::in_memory().unwrap(); + db.execute("(transact [[:a :n 1] [:b :n 2]])").unwrap(); + let inner = db.clone(); + db.register_predicate("reg?", move |v| { + if let Value::Integer(i) = v { + inner + .register_predicate(&format!("p{i}?"), |_| true) + .expect("registers"); + } + true + }) + .unwrap(); + let n = rows( + db.execute("(query [:find ?e :where [?e :n ?v] [(reg? ?v)]])") + .unwrap(), + ) + .len(); + // A later query sees what the callback registered. + db.execute("(query [:find ?e :where [?e :n ?v] [(p1? ?v)]])") + .expect("p1? is registered"); + n + }); + assert_eq!(n, 2); +} + +#[test] +fn an_aggregate_that_registers_a_function_returns() { + let sum = within_timeout(|| { + let db = Minigraf::in_memory().unwrap(); + db.execute("(transact [[:a :n 1] [:b :n 2]])").unwrap(); + let inner = db.clone(); + db.register_aggregate( + "regsum", + || 0i64, + move |acc: &mut i64, v: &Value| { + if let Value::Integer(i) = v { + *acc += i; + inner + .register_predicate(&format!("q{i}?"), |_| true) + .expect("registers"); + } + }, + |acc: &i64, _| Value::Integer(*acc), + ) + .unwrap(); + rows( + db.execute("(query [:find (regsum ?v) :where [?e :n ?v]])") + .unwrap(), + ) + }); + assert_eq!(sum, vec![vec![Value::Integer(3)]]); +} + +#[test] +fn a_rule_predicate_that_registers_a_function_returns() { + let n = within_timeout(|| { + let db = Minigraf::in_memory().unwrap(); + db.execute("(transact [[:a :n 1] [:b :n 2]])").unwrap(); + db.execute("(rule [(big ?e) [?e :n ?v] [(reg? ?v)]])") + .unwrap(); + let inner = db.clone(); + db.register_predicate("reg?", move |v| { + if let Value::Integer(i) = v { + inner + .register_predicate(&format!("r{i}?"), |_| true) + .expect("registers"); + } + true + }) + .unwrap(); + rows(db.execute("(query [:find ?e :where (big ?e)])").unwrap()).len() + }); + assert_eq!(n, 2); +} + +#[test] +fn a_cursor_keeps_the_functions_it_opened_with() { + let db = Minigraf::in_memory().unwrap(); + let facts: String = (0..3000).map(|i| format!("[:e{i} :n {i}]")).collect(); + db.execute(&format!("(transact [{facts}])")).unwrap(); + db.register_predicate("any?", |_| true).unwrap(); + + // Unknown at open: QRY-007, now and after a later registration. + let q = "(query [:find ?e :where [?e :n ?v] [(late? ?v)]])"; + assert_eq!(db.query(q).err().map(|e| e.code()), Some("QRY-007")); + + let mut cursor = db + .query("(query [:find ?e :where [?e :n ?v] [(any? ?v)]])") + .unwrap(); + let mut n = cursor.next_batch(10).unwrap().map_or(0, |b| b.len()); + // Registering between pulls neither blocks nor changes the open cursor. + db.register_predicate("late?", |_| true).unwrap(); + while let Some(batch) = cursor.next_batch(1000).unwrap() { + n += batch.len(); + } + assert_eq!(n, 3000); + assert_eq!( + rows(db.execute(q).unwrap()).len(), + 3000, + "a later query sees it" + ); +} From c3183d712d72b7e442a37f795fe4650b2a5d9846 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 24 Oct 2026 18:21:07 +0530 Subject: [PATCH 06/13] =?UTF-8?q?test(udf):=20re-entry=20from=20inside=20a?= =?UTF-8?q?=20user=20function,=20both=20columns=20of=20spec=20=C2=A75=20(#?= =?UTF-8?q?180)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015NBT2Yx9JUQKYvv2CvC9py --- tests/udf_reentry_test.rs | 296 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 296 insertions(+) diff --git a/tests/udf_reentry_test.rs b/tests/udf_reentry_test.rs index 4627fe4221..9ef807fe62 100644 --- a/tests/udf_reentry_test.rs +++ b/tests/udf_reentry_test.rs @@ -140,3 +140,299 @@ fn a_cursor_keeps_the_functions_it_opened_with() { "a later query sees it" ); } + +// ─── Re-entry from inside a user function (plan step 10, spec §5 table) ────── + +use minigraf::{FactFilter, MinigrafError}; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::{Arc, Mutex}; + +/// What a callback does on the database, once, from inside the outer query. +type Action = Box Result<(), MinigrafError> + Send + Sync>; + +/// The outer query: every `:n` fact, through the callback predicate `cb?`. +const OUTER: &str = "(query [:find ?e ?v :where [?e :n ?v] [(cb? ?v)]])"; +const PLAIN: &str = "(query [:find ?e ?v :where [?e :n ?v]])"; + +/// What the outer query gave, what the action returned (its error code, or +/// `None`), and the number of `:n` facts after the outer query. +struct Outcome { + rows: Vec>, + baseline: Vec>, + code: Option<&'static str>, + after: usize, +} + +fn sorted(mut rows: Vec>) -> Vec> { + rows.sort(); + rows +} + +/// Runs [`OUTER`] on a file database with committed facts (`:a`, `:b`) and a +/// pending one (`:c`), as a plain read or inside a `WriteTransaction`; the +/// callback runs `make`'s action on its first call. +fn reenter(make: fn(&Minigraf) -> Action, in_tx: bool) -> Outcome { + within_timeout(move || { + let dir = tempfile::tempdir().unwrap(); + let db = Minigraf::open(dir.path().join("g.graph")).unwrap(); + db.execute("(transact [[:a :n 1] [:b :n 2]])").unwrap(); + db.checkpoint().unwrap(); + db.execute("(transact [[:c :n 3]])").unwrap(); + let baseline = sorted(rows(db.execute(PLAIN).unwrap())); + + let action = make(&db); + let inner = db.clone(); + let started = Arc::new(AtomicBool::new(false)); + let code = Arc::new(Mutex::new(None)); + let c = Arc::clone(&code); + db.register_predicate("cb?", move |_| { + if !started.swap(true, Ordering::SeqCst) { + let r = action(&inner).err().map(|e| e.code()); + *c.lock().unwrap() = Some(r); + } + true + }) + .unwrap(); + + let result = if in_tx { + let mut wtx = db.begin_write().unwrap(); + let r = wtx.execute(OUTER).unwrap(); + wtx.commit().unwrap(); + r + } else { + db.execute(OUTER).unwrap() + }; + let code = code.lock().unwrap().take().expect("the callback ran"); + let after = rows(db.execute(PLAIN).unwrap()).len(); + db.verify().expect("the file is sound after the callback"); + Outcome { + rows: sorted(rows(result)), + baseline, + code, + after, + } + }) +} + +/// One row of spec §5's table: the plain-read column (the action runs, and +/// the outer query's rows are those of the database before it) and the +/// write-transaction column (`tx_code`). `after` is the number of `:n` +/// facts after the action ran in a plain read. +fn check_row(make: fn(&Minigraf) -> Action, tx_code: Option<&str>, after: usize) { + let plain = reenter(make, false); + assert_eq!(plain.code, None, "runs from inside a plain read"); + assert!( + plain.rows == plain.baseline, + "the outer query does not see the action" + ); + assert_eq!(plain.after, after, "a later query sees the action"); + + let tx = reenter(make, true); + assert_eq!(tx.code, tx_code, "inside a write transaction"); + assert!( + tx.rows == tx.baseline, + "the outer query's rows inside a write transaction" + ); + let tx_after = if tx_code.is_none() { after } else { 3 }; + assert_eq!(tx.after, tx_after); +} + +const INT001: Option<&str> = Some("INT-001"); + +#[test] +fn reentry_execute_query() { + check_row( + |_| Box::new(|db| db.execute("(query [:find ?v :where [_ :n ?v]])").map(drop)), + INT001, + 3, + ); +} + +#[test] +fn reentry_query_drained() { + check_row( + |_| { + Box::new(|db| { + db.query("(query [:find ?v :where [_ :n ?v]])")? + .collect::, _>>() + .map(drop) + }) + }, + INT001, + 3, + ); +} + +#[test] +fn reentry_prepare_and_execute() { + check_row( + |_| { + Box::new(|db| { + db.prepare("(query [:find ?v :where [_ :n ?v]])")? + .execute(&[]) + .map(drop) + }) + }, + INT001, + 3, + ); +} + +#[test] +fn reentry_prepared_execute() { + check_row( + |db| { + let pq = db.prepare("(query [:find ?v :where [_ :n ?v]])").unwrap(); + Box::new(move |_| pq.execute(&[]).map(drop)) + }, + INT001, + 3, + ); +} + +#[test] +fn reentry_prepared_query_drained() { + check_row( + |db| { + let pq = db.prepare("(query [:find ?v :where [_ :n ?v]])").unwrap(); + Box::new(move |_| pq.query(&[])?.collect::, _>>().map(drop)) + }, + INT001, + 3, + ); +} + +#[test] +fn reentry_fact_log() { + check_row( + |_| { + Box::new(|db| { + db.fact_log(&FactFilter::new())? + .collect::, _>>() + .map(drop) + }) + }, + INT001, + 3, + ); +} + +#[test] +fn reentry_transact() { + check_row( + |_| Box::new(|db| db.execute("(transact [[:z :n 99]])").map(drop)), + INT001, + 4, + ); +} + +#[test] +fn reentry_retract() { + check_row( + |_| Box::new(|db| db.execute("(retract [[:a :n 1]])").map(drop)), + INT001, + 2, + ); +} + +#[test] +fn reentry_rule() { + check_row( + |_| Box::new(|db| db.execute("(rule [(has-n ?e) [?e :n _]])").map(drop)), + INT001, + 3, + ); +} + +#[test] +fn reentry_begin_write_and_commit() { + check_row( + |_| { + Box::new(|db| { + let mut tx = db.begin_write()?; + tx.execute("(transact [[:y :n 98]])")?; + tx.commit() + }) + }, + INT001, + 4, + ); +} + +#[test] +fn reentry_checkpoint() { + check_row(|_| Box::new(|db| db.checkpoint()), INT001, 3); +} + +#[test] +fn reentry_verify() { + check_row(|_| Box::new(|db| db.verify().map(drop)), INT001, 3); +} + +#[test] +fn reentry_rebuild_indexes() { + check_row(|_| Box::new(|db| db.rebuild_indexes()), INT001, 3); +} + +#[test] +fn reentry_register_predicate() { + check_row( + |_| Box::new(|db| db.register_predicate("late?", |_| true)), + None, + 3, + ); + check_row( + |_| Box::new(|db| db.try_register_predicate("late?", |_| Ok(true))), + None, + 3, + ); +} + +#[test] +fn reentry_register_aggregate() { + check_row( + |_| { + Box::new(|db| { + db.register_aggregate("late", || 0i64, |_, _| {}, |a, _| Value::Integer(*a)) + }) + }, + None, + 3, + ); + check_row( + |_| { + Box::new(|db| { + db.try_register_aggregate( + "late", + || Ok(0i64), + |_, _| Ok(()), + |a, _| Ok(Value::Integer(*a)), + ) + }) + }, + None, + 3, + ); +} + +#[test] +fn reentry_nested_query_calling_a_second_function() { + check_row( + |db| { + let inner = db.clone(); + db.register_predicate("inner?", move |_| { + // A third level: a query from inside the nested query's UDF. + inner.execute("(query [:find ?v :where [_ :n ?v]])").is_ok() + }) + .unwrap(); + Box::new(|db| { + let n = + rows(db.execute("(query [:find ?v :where [_ :n ?v] [(inner? ?v)]])")?).len(); + assert_eq!(n, 3, "the nested query's own rows"); + Ok(()) + }) + }, + INT001, + 3, + ); +} From dcf4fbb20062e5c54a39b15048fcb977896fa399 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 24 Oct 2026 18:23:41 +0530 Subject: [PATCH 07/13] docs(udf): try_register_*, QRY-014, registry snapshot and re-entry (#180) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015NBT2Yx9JUQKYvv2CvC9py --- CHANGELOG.md | 1 + CLAUDE.md | 1 + ROADMAP.md | 2 +- docs/TEST_COVERAGE.md | 7 ++++++ src/db.rs | 52 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 62 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 98fe8e2ea7..78100bbc0d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,6 +50,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- **Fallible and re-entrant user functions** (#180, PR 1). `Minigraf::try_register_predicate` and `Minigraf::try_register_aggregate` take closures that return `Result<_, UdfError>` (`UdfError` is exported at the crate root). A call that returns `Err` fails the query with the new `QRY-014`, ``user function `` failed: ``, at the first failing call: it is never read as `false` or `nil`, and no later call of any user function is made for that query. `execute` and `PreparedQuery::execute` return it; a cursor returns the rows it gathered first, then the error, then `None`. `register_predicate` and `register_aggregate` are unchanged. A query now reads its functions from a snapshot of the registry taken when it opens, and holds no database lock while a user function runs: a function registered later is not seen by a query or cursor that is already open, and a user function may call back into its own database (query, prepare, read the fact log, write, define rules, register functions, checkpoint, verify, rebuild indexes). Its writes are not seen by the query that called it. Inside a `WriteTransaction` those calls return `INT-001` on that thread, except registration, which runs. Before, a user function that registered a function deadlocked. This is the core of UDF registration in the language bindings, which follows binding by binding. - **Set values: `#{...}`** (#316, PR 1 of 3). A fact's value can be a finite set of scalars, `[:alice :user/scopes #{:scope/read :scope/write}]`, written in query text, returned as `Value::Set(ValueSet)`, transacted, retracted and queried by exact value (`[?e :user/scopes #{:scope/write :scope/read}]`), joined on and grouped by. Duplicates are removed and element order does not matter. Two elements are the same when `Value`'s order says so: `0.0` and `-0.0` are one element (`-0.0` is kept), every NaN is one element, a keyword never equals a ref and `1` never equals `1.0`. A set cannot hold a set (`ValueSet::new` fails with the new `API-021`; in query text, `PRS-119`); its elements are literals only (`PRS-120`), and an unclosed `#{` is `PRS-121`. In format v8 a set has value tag `0x08`, after refs; a set whose encoded elements take at most 64 bytes is stored in its index keys, a longer one once in a value page, as a long string is. On a file database a stored set may take up to 4,068 bytes, counting each keyword element as 6 bytes and each ref as 10 (`WAL-003`). The REPL prints sets as `#{...}` and `BrowserDb` returns them as JSON arrays, in `Value`'s order. - **Every query runs on a streaming engine** (#473: #544, #545, #546, #547, #548, #549, #551). The executor, which turned every live fact of each pattern's attribute into a `Fact` before matching, held each row's bindings in a map and copied the database into a `FactStorage` for every rule query, no longer runs queries: its query path, `PatternMatcher` and the old rule evaluators are gone (#551), and the release binary is 1,153 KiB instead of 1,286 KiB (CI's size check). A query is now a tree of operators that pass batches of up to 1,024 rows of ids, read from the index keys, and turn ids into values only for the rows they return (#530). A pattern reads the narrowest key range its constants allow (`[?e :a C]` reads the AVET range of `C`, #518); a later pattern is an `IndexNestedLoopJoin` when its entity is bound and a `HashJoin` otherwise, built on the side with the smaller estimate (with no shared variable, the smaller product, #575); per-fact pseudo-attributes read their source's metadata column (#594). `not` / `not-join` is an `AntiJoin` and `or` / `or-join` a `Union` and `Distinct`: a body or branch with the same rows for every outer row runs once into a hash table, any other runs per outer row from a one-row seed. Aggregates keep one entry per group (one set of accumulators when ungrouped), windows hold their rows, and rule queries derive each stratum's relations semi-naively, with the magic-set rewrite, then read them as patterns. `:as-of` with a time bounds the transaction counter when transaction times rise with it, and otherwise keeps the versions of transactions at or before the time. Cursors (`Minigraf::query`, `PreparedQuery::query`, `BrowserDb.query`) pull one batch at a time, and closing or dropping one stops the work; a cursor still answers from the database as it was when it opened. Every operator that keeps state counts it against `OpenOptions::query_memory_limit` (#549, below). Answers are the executor's, as a bag, except for the changes under Breaking changes: until #551 every query in the test suite was also run by the executor and the answers had to agree, and the answers of the suites that relied on that are recorded in `tests/answers/`. Measured with the #394 envelope at 1M facts, executor → engine, p50 and peak RSS (`docs/BENCHMARKS.md` has every shape at 100K, 1M and 10M): `[?e :name "…"]` 288 ms → 22 µs; an attribute scan of 166,666 rows drained with `next_batch(1000)` 58 → 7 MiB (458 → 7 MiB at 10M); `[:p :follows ?f] [?f :name ?n]` 796 ms → 50 µs; an entity-bound `not` 760 → 27 ms; `[:find (count ?v) :where [?e ?a ?v]]` 3.01 s → 457 ms and 728 → 7 MiB (6.6 GiB → 7 MiB at 10M); an `or-join` of two hashed branches 1.44 s → 80 ms; `(boss :p ?b)` 43.9 s → 2.14 ms and 2.6 GiB → 4 MiB; the whole transitive closure of `:manager` 51.0 s → 3.21 s and 4.7 GiB → 318 MiB; `:as-of` with a time, a point query, 1.65 s → 0.8 ms and 435 → 4 MiB (17.2 s and 3.6 GiB → 0.9 ms and 5 MiB at 10M). - **Transactions of any size on a file database, in bounded memory** (#473, part 8: #550). `transact` and `retract` are read one fact at a time: the whole command is never tokenized, parsed or materialised at once, and a statement reports the same error code as before whatever its size. A transaction becomes *large* when its facts would pass the new `OpenOptions::transaction_chunk_facts` (default 65,536, kept between 1 and 1,000,000): `Minigraf::execute` of a larger statement, or the `WriteTransaction` statement that takes its staged facts past it. A large transaction holds at most one chunk of facts in memory. It writes them a chunk at a time into copy-on-write trees that become the next generation, and commits as a checkpoint: no WAL entry, and the uncheckpointed facts of earlier transactions go into the same checkpoint. What a large transaction stores is what a small one stores, with two differences you can see: its `tx_id` is the time it became large, not its commit time (a default `:valid-from` takes that time too), and errors from different chunks of one statement come in chunk order. In a large `WriteTransaction` a rejected statement still leaves the transaction usable and the earlier statements' facts as they were; a fact too large to store is rejected at its statement (`WAL-003`) rather than at `commit`; a handle that has failed is refused when the transaction becomes large (`STG-046`) rather than at `commit`; and inside the transaction `:as-of` its own transaction number sees every finished statement, since they share one number (staged statements of a small transaction each have their own until `commit`). A crash at any point before a large transaction's commit leaves the database as it was; the WAL file exists, header only, from before its first page write, so a new file reopens too. The first checkpoint after a WAL is found at open, or after a large transaction is rolled back, now writes a meta page before it deletes the WAL. Measured at 1M facts against v3 before this change (one `execute`, or a `WriteTransaction` of 10 statements): peak memory above the input text goes from 1.3–2.4 GiB to at most 55 MiB at the default (under 10 MiB at 16,384); with sequential entities it is faster (3.9 s from 9.1 s for short values), with random entities about as fast for short values (9.5 s from 11.4 s in one `execute`) and slower for long ones over 10 statements (34 s from 22 s; 16,384 takes up to twice as long as the default with random entities), and a transaction of several statements over random entities can leave the file up to 1.8× larger, since each statement keeps the pages its base references until it ends; later checkpoints reuse that space. diff --git a/CLAUDE.md b/CLAUDE.md index b004bf6be6..79c443caf3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -139,6 +139,7 @@ cargo run < demos/demo_negation.txt - `executor.rs`: `DatalogExecutor` — `transact`/`retract`/`rule` commands, and every query on the engine (`open_query`, `open_rule_query`; planner errors after the pseudo-attribute check, then every predicate the query and its rules name, `QRY-007`); its own query path is gone (#551) - `matcher.rs`: `edn_to_value`, `edn_to_entity_id` - `aggregate.rs`: `Agg` (one aggregate of one group) and `Running` (a window's running value), used by the engine; exact sums (`i128` integers saturated once, fixed-point floats rounded once), `value_order` (one total order of values for window sorts, peers, `rank` and `min`/`max`), `named_vars` (a window's tie-break variables), `windows` (each window's value per row: partitions, sort, peers) (#547) + - `functions.rs`: `FunctionRegistry` (built-ins and UDFs; `Clone` shares the closures), `Functions` — the registry a database shares, `RwLock>`: a query takes a `snapshot()` when it opens and holds no lock while a UDF runs, so UDFs may call back into the database; registration copies, inserts and swaps (#180). `UdfError`: a `try_register_*` closure's failure, `QRY-014`; `eval_expr`'s `EvalError` is `NoValue` (row dropped) or `Udf` (query fails) - `evaluator.rs`: `rule_invocation_to_pattern`, the rule limits and their errors - `stratification.rs`: `DependencyGraph`, `stratify()` — negative edges + cycle detection; a positive edge to a rule with `not`/`not-join`/`or`/`or-join` also raises the caller, off a cycle (#628) - `rules.rs`: `RuleRegistry` — thread-safe rule management diff --git a/ROADMAP.md b/ROADMAP.md index cd60db2c0c..c5dda309c3 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -104,7 +104,7 @@ Scope — features: - Query profiler (#185) - Set membership predicates (#316) - Prepared queries in every binding (#181; core and `BrowserDb.prepare` done on `v3`, the other bindings follow) -- UDF registration in every binding: the UniFFI ones, C, Node and the browser `BrowserDb` (#180) +- UDF registration in every binding: the UniFFI ones, C, Node and the browser `BrowserDb` (#180; core done on `v3`: fallible UDFs, `QRY-014`, registry snapshot and re-entry; the bindings follow) - `OpenOptions` exposed over UniFFI through `open_with_options`, so embedders can suppress the close-time checkpoint (#322; done on `v3` in every binding with #465) Scope — release-gate testing and documentation: diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md index 57715f4459..43c37d1b2f 100644 --- a/docs/TEST_COVERAGE.md +++ b/docs/TEST_COVERAGE.md @@ -285,6 +285,13 @@ These tests compare the database against an independent answer rather than a sin - `tests/write_tx_guard_test.rs` (#734): `checkpoint`, `verify`, `rebuild_indexes`, `prepare` and `PreparedQuery::execute`/`query` on a thread holding a `WriteTransaction` return `INT-001` (each under a 30 s timeout, so a deadlock fails instead of hanging), and the transaction then commits; outside a transaction they run. - `PreparedQuery::query` matches `PreparedQuery::execute`. - A cursor is `Send` and outlives its database handle. +- **User functions** (#180, `tests/udf_test.rs`, `tests/udf_reentry_test.rs`) + - Every UDF test runs once through `register_*` and once through `try_register_*` with closures that never fail, and gets the same rows. + - A `try_` predicate failing on its fifth call fails the query with `QRY-014` (name and message in the text) in `:where`, a rule body, a `not` body and an `or` branch, and is not called again; through a prepared query too. Through a cursor, the rows of the first batch come first, then the error, then `None`. + - A `try_` aggregate failing in `init`, `step` or `finalise`, as a `:find` aggregate and as a partitioned `:over` window: `QRY-014`, and no call after the failing one. + - A predicate, an aggregate and a rule's predicate that register a function from inside the call return (they deadlocked before; each under a 30 s timeout), and a later query sees the new function. Registering between a cursor's pulls neither blocks it nor changes its rows; an unknown predicate is `QRY-007` at open. + - Re-entry, one test per row of spec §5's table, on a file database with committed and pending facts, as a plain read and inside a `WriteTransaction`: `execute` of a query, `query` drained, `prepare` + `execute`, `PreparedQuery::execute` and `query`, `fact_log`, `transact`, `retract`, `rule`, `begin_write` + commit, `checkpoint`, `verify`, `rebuild_indexes`, both kinds of registration both ways, and a nested query whose UDF queries again. In a plain read each runs, the outer query's rows are the database's before the call, a later query sees the write, and `verify` is clean; in a transaction each returns `INT-001` except registration. + - Unit tests: `UdfError`'s message and `QRY-014`'s code, category and text. - **Fact log** (#430, `tests/fact_log_test.rs`) - `fact_log()` returns exactly the records written (assertions and retractions, with `tx_count` and `tx_id`), in non-decreasing `tx_count` in Tx order. Checked in memory, with everything pending, half checkpointed, fully checkpointed and after reopen, in both orders, with windows of 1 to 1,000 records and batch sizes of 1 to 1,000. - Every layout gives identical records, including valid-time windows and long string values. diff --git a/src/db.rs b/src/db.rs index 2befbbb24c..30a9ae0c80 100644 --- a/src/db.rs +++ b/src/db.rs @@ -1447,6 +1447,19 @@ impl Minigraf { /// result depends on that order (anything but a commutative, /// associative combination) may answer them differently. /// + /// # Snapshots and re-entry + /// + /// A query reads its functions from the registry as it was when the + /// query opened, so a function registered later is not visible to a + /// query or cursor that is already open; it is visible to every query + /// opened afterwards. No database lock is held while a user function + /// runs, so it may call back into the same database: query, prepare, + /// read the fact log, write, define rules, register functions, + /// checkpoint, verify or rebuild indexes. A write it makes is not seen + /// by the query that called it. Inside a [`WriteTransaction`] every one + /// of those calls except registration returns `INT-001` on that thread, + /// as it does outside a user function. + /// /// # Errors /// /// Returns an error if `name` is already registered (built-in or UDF) @@ -1494,6 +1507,19 @@ impl Minigraf { /// and the error's message, and no later call of any user function is /// made for that query. /// + /// # Snapshots and re-entry + /// + /// A query reads its functions from the registry as it was when the + /// query opened, so a function registered later is not visible to a + /// query or cursor that is already open; it is visible to every query + /// opened afterwards. No database lock is held while a user function + /// runs, so it may call back into the same database: query, prepare, + /// read the fact log, write, define rules, register functions, + /// checkpoint, verify or rebuild indexes. A write it makes is not seen + /// by the query that called it. Inside a [`WriteTransaction`] every one + /// of those calls except registration returns `INT-001` on that thread, + /// as it does outside a user function. + /// /// # Errors /// /// Returns an error if `name` is already registered (built-in or UDF) @@ -1568,6 +1594,19 @@ impl Minigraf { /// /// The predicate is usable in `[(name? ?var)]` `:where` clauses. /// + /// # Snapshots and re-entry + /// + /// A query reads its functions from the registry as it was when the + /// query opened, so a function registered later is not visible to a + /// query or cursor that is already open; it is visible to every query + /// opened afterwards. No database lock is held while a user function + /// runs, so it may call back into the same database: query, prepare, + /// read the fact log, write, define rules, register functions, + /// checkpoint, verify or rebuild indexes. A write it makes is not seen + /// by the query that called it. Inside a [`WriteTransaction`] every one + /// of those calls except registration returns `INT-001` on that thread, + /// as it does outside a user function. + /// /// # Errors /// /// Returns an error if `name` is already registered (built-in or UDF) @@ -1601,6 +1640,19 @@ impl Minigraf { /// and no later call of any user function is made for that query. It /// is never read as `false`. /// + /// # Snapshots and re-entry + /// + /// A query reads its functions from the registry as it was when the + /// query opened, so a function registered later is not visible to a + /// query or cursor that is already open; it is visible to every query + /// opened afterwards. No database lock is held while a user function + /// runs, so it may call back into the same database: query, prepare, + /// read the fact log, write, define rules, register functions, + /// checkpoint, verify or rebuild indexes. A write it makes is not seen + /// by the query that called it. Inside a [`WriteTransaction`] every one + /// of those calls except registration returns `INT-001` on that thread, + /// as it does outside a user function. + /// /// # Errors /// /// Returns an error if `name` is already registered (built-in or UDF) From efae0d1d117b303467a8402e1c7e681f157b5a0a Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 24 Oct 2026 18:30:03 +0530 Subject: [PATCH 08/13] docs(udf): API-008/QRY-008 causes, cursor rows on QRY-014 (#180) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015NBT2Yx9JUQKYvv2CvC9py --- CHANGELOG.md | 2 +- docs/ERROR_REFERENCE.md | 16 +++++++--------- src/db.rs | 4 ++-- src/query/datalog/executor.rs | 2 +- 4 files changed, 11 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 78100bbc0d..3f418fb948 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,7 +50,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- **Fallible and re-entrant user functions** (#180, PR 1). `Minigraf::try_register_predicate` and `Minigraf::try_register_aggregate` take closures that return `Result<_, UdfError>` (`UdfError` is exported at the crate root). A call that returns `Err` fails the query with the new `QRY-014`, ``user function `` failed: ``, at the first failing call: it is never read as `false` or `nil`, and no later call of any user function is made for that query. `execute` and `PreparedQuery::execute` return it; a cursor returns the rows it gathered first, then the error, then `None`. `register_predicate` and `register_aggregate` are unchanged. A query now reads its functions from a snapshot of the registry taken when it opens, and holds no database lock while a user function runs: a function registered later is not seen by a query or cursor that is already open, and a user function may call back into its own database (query, prepare, read the fact log, write, define rules, register functions, checkpoint, verify, rebuild indexes). Its writes are not seen by the query that called it. Inside a `WriteTransaction` those calls return `INT-001` on that thread, except registration, which runs. Before, a user function that registered a function deadlocked. This is the core of UDF registration in the language bindings, which follows binding by binding. +- **Fallible and re-entrant user functions** (#180, PR 1). `Minigraf::try_register_predicate` and `Minigraf::try_register_aggregate` take closures that return `Result<_, UdfError>` (`UdfError` is exported at the crate root). A call that returns `Err` fails the query with the new `QRY-014`, ``user function `` failed: ``, at the first failing call: it is never read as `false` or `nil`, and no later call of any user function is made for that query. `execute` and `PreparedQuery::execute` return it; a cursor treats it as any other read error, returning the rows of the batches finished before the failure, then the error, then `None`. `register_predicate` and `register_aggregate` are unchanged. A query now reads its functions from a snapshot of the registry taken when it opens, and holds no database lock while a user function runs: a function registered later is not seen by a query or cursor that is already open, and a user function may call back into its own database (query, prepare, read the fact log, write, define rules, register functions, checkpoint, verify, rebuild indexes). Its writes are not seen by the query that called it. Inside a `WriteTransaction` those calls return `INT-001` on that thread, except registration, which runs. Before, a user function that registered a function deadlocked. This is the core of UDF registration in the language bindings, which follows binding by binding. - **Set values: `#{...}`** (#316, PR 1 of 3). A fact's value can be a finite set of scalars, `[:alice :user/scopes #{:scope/read :scope/write}]`, written in query text, returned as `Value::Set(ValueSet)`, transacted, retracted and queried by exact value (`[?e :user/scopes #{:scope/write :scope/read}]`), joined on and grouped by. Duplicates are removed and element order does not matter. Two elements are the same when `Value`'s order says so: `0.0` and `-0.0` are one element (`-0.0` is kept), every NaN is one element, a keyword never equals a ref and `1` never equals `1.0`. A set cannot hold a set (`ValueSet::new` fails with the new `API-021`; in query text, `PRS-119`); its elements are literals only (`PRS-120`), and an unclosed `#{` is `PRS-121`. In format v8 a set has value tag `0x08`, after refs; a set whose encoded elements take at most 64 bytes is stored in its index keys, a longer one once in a value page, as a long string is. On a file database a stored set may take up to 4,068 bytes, counting each keyword element as 6 bytes and each ref as 10 (`WAL-003`). The REPL prints sets as `#{...}` and `BrowserDb` returns them as JSON arrays, in `Value`'s order. - **Every query runs on a streaming engine** (#473: #544, #545, #546, #547, #548, #549, #551). The executor, which turned every live fact of each pattern's attribute into a `Fact` before matching, held each row's bindings in a map and copied the database into a `FactStorage` for every rule query, no longer runs queries: its query path, `PatternMatcher` and the old rule evaluators are gone (#551), and the release binary is 1,153 KiB instead of 1,286 KiB (CI's size check). A query is now a tree of operators that pass batches of up to 1,024 rows of ids, read from the index keys, and turn ids into values only for the rows they return (#530). A pattern reads the narrowest key range its constants allow (`[?e :a C]` reads the AVET range of `C`, #518); a later pattern is an `IndexNestedLoopJoin` when its entity is bound and a `HashJoin` otherwise, built on the side with the smaller estimate (with no shared variable, the smaller product, #575); per-fact pseudo-attributes read their source's metadata column (#594). `not` / `not-join` is an `AntiJoin` and `or` / `or-join` a `Union` and `Distinct`: a body or branch with the same rows for every outer row runs once into a hash table, any other runs per outer row from a one-row seed. Aggregates keep one entry per group (one set of accumulators when ungrouped), windows hold their rows, and rule queries derive each stratum's relations semi-naively, with the magic-set rewrite, then read them as patterns. `:as-of` with a time bounds the transaction counter when transaction times rise with it, and otherwise keeps the versions of transactions at or before the time. Cursors (`Minigraf::query`, `PreparedQuery::query`, `BrowserDb.query`) pull one batch at a time, and closing or dropping one stops the work; a cursor still answers from the database as it was when it opened. Every operator that keeps state counts it against `OpenOptions::query_memory_limit` (#549, below). Answers are the executor's, as a bag, except for the changes under Breaking changes: until #551 every query in the test suite was also run by the executor and the answers had to agree, and the answers of the suites that relied on that are recorded in `tests/answers/`. Measured with the #394 envelope at 1M facts, executor → engine, p50 and peak RSS (`docs/BENCHMARKS.md` has every shape at 100K, 1M and 10M): `[?e :name "…"]` 288 ms → 22 µs; an attribute scan of 166,666 rows drained with `next_batch(1000)` 58 → 7 MiB (458 → 7 MiB at 10M); `[:p :follows ?f] [?f :name ?n]` 796 ms → 50 µs; an entity-bound `not` 760 → 27 ms; `[:find (count ?v) :where [?e ?a ?v]]` 3.01 s → 457 ms and 728 → 7 MiB (6.6 GiB → 7 MiB at 10M); an `or-join` of two hashed branches 1.44 s → 80 ms; `(boss :p ?b)` 43.9 s → 2.14 ms and 2.6 GiB → 4 MiB; the whole transitive closure of `:manager` 51.0 s → 3.21 s and 4.7 GiB → 318 MiB; `:as-of` with a time, a point query, 1.65 s → 0.8 ms and 435 → 4 MiB (17.2 s and 3.6 GiB → 0.9 ms and 5 MiB at 10M). - **Transactions of any size on a file database, in bounded memory** (#473, part 8: #550). `transact` and `retract` are read one fact at a time: the whole command is never tokenized, parsed or materialised at once, and a statement reports the same error code as before whatever its size. A transaction becomes *large* when its facts would pass the new `OpenOptions::transaction_chunk_facts` (default 65,536, kept between 1 and 1,000,000): `Minigraf::execute` of a larger statement, or the `WriteTransaction` statement that takes its staged facts past it. A large transaction holds at most one chunk of facts in memory. It writes them a chunk at a time into copy-on-write trees that become the next generation, and commits as a checkpoint: no WAL entry, and the uncheckpointed facts of earlier transactions go into the same checkpoint. What a large transaction stores is what a small one stores, with two differences you can see: its `tx_id` is the time it became large, not its commit time (a default `:valid-from` takes that time too), and errors from different chunks of one statement come in chunk order. In a large `WriteTransaction` a rejected statement still leaves the transaction usable and the earlier statements' facts as they were; a fact too large to store is rejected at its statement (`WAL-003`) rather than at `commit`; a handle that has failed is refused when the transaction becomes large (`STG-046`) rather than at `commit`; and inside the transaction `:as-of` its own transaction number sees every finished statement, since they share one number (staged statements of a small transaction each have their own until `commit`). A crash at any point before a large transaction's commit leaves the database as it was; the WAL file exists, header only, from before its first page write, so a new file reopens too. The first checkpoint after a WAL is found at open, or after a large transaction is rolled back, now writes a meta page before it deletes the WAL. Measured at 1M facts against v3 before this change (one `execute`, or a `WriteTransaction` of 10 statements): peak memory above the input text goes from 1.3–2.4 GiB to at most 55 MiB at the default (under 10 MiB at 16,384); with sequential entities it is faster (3.9 s from 9.1 s for short values), with random entities about as fast for short values (9.5 s from 11.4 s in one `execute`) and slower for long ones over 10 statements (34 s from 22 s; 16,384 takes up to twice as long as the default with random entities), and a transaction of several statements over random entities can leave the file up to 1.8× larger, since each statement keeps the pages its base references until it ends; later checkpoints reuse that space. diff --git a/docs/ERROR_REFERENCE.md b/docs/ERROR_REFERENCE.md index 888b72472f..905adee60e 100644 --- a/docs/ERROR_REFERENCE.md +++ b/docs/ERROR_REFERENCE.md @@ -2311,14 +2311,12 @@ predicate evaluation, or fact transacting. **Error text**: `functions lock poisoned` -**Cause**: An internal Rust mutex guarding the custom function registry was poisoned — a previous operation panicked while holding the lock. +**Cause**: The lock guarding the custom function registry was poisoned: a thread panicked while it held the lock. A query takes the lock only to copy the registry's handle when it opens. Since v3.0.0 no user code runs under it, so a custom function that panics does not poison it. **Resolution**: -- Restart the process. -- If panics recur when calling custom registered functions, investigate the function implementations for panics. -- If this occurs without any custom functions, file a bug. +- Restart the process. This indicates a bug in Minigraf; file an issue. -**Scenario**: `db.register_predicate()` or a query invoking a custom predicate panics; subsequent calls to any query return this error. +**Scenario**: A panic while a function was being registered left the registry lock poisoned; every later query returns this error. ### QRY-009 Rules lock poisoned @@ -2410,7 +2408,7 @@ db.execute("(query [:find ?g (count ?e) :where [?e :g ?g]])")?; **Error text**: `user function `{}` failed: {}` -**Cause**: A user-defined predicate or aggregate registered with `try_register_predicate` or `try_register_aggregate` returned `Err(UdfError)`, or a language binding's callback threw. The first argument is the function's name and the second is the `UdfError`'s message. The query stops at the failing call: no later call of any user function is made for it. A cursor returns the rows it gathered before the failure first, then this error, then no more rows. A query inside a `WriteTransaction` that fails this way leaves the transaction open. Functions registered with `register_predicate` or `register_aggregate` never fail this way. +**Cause**: A user-defined predicate or aggregate registered with `try_register_predicate` or `try_register_aggregate` returned `Err(UdfError)`, or a language binding's callback threw. The first argument is the function's name and the second is the `UdfError`'s message. The query stops at the failing call: no later call of any user function is made for it. A cursor treats it as any other read error: it returns the rows of the batches the query finished before the failure first, then this error, then no more rows. Rows of the batch the failure happens in are not returned. A query inside a `WriteTransaction` that fails this way leaves the transaction open. Functions registered with `register_predicate` or `register_aggregate` never fail this way. **Resolution**: - Read the message: it is the one the function gave. @@ -3241,12 +3239,12 @@ db.execute("(rule [(ancestor ?x ?y) [?x :parent ?y]])")?; **Error text**: `function registry lock poisoned: PoisonError { .. }` -**Cause**: An internal Rust mutex guarding the custom function/predicate registry was poisoned — a previous operation panicked while registering or invoking a custom function. +**Cause**: The lock guarding the custom function/predicate registry was poisoned: a thread panicked while it held the lock. The lock is held only while a query copies the registry's handle at open and while a function is registered. No user code runs under it: since v3.0.0 a query holds no registry lock while a custom function runs, so a function that panics does not poison it. **Resolution**: -- Restart the process. If panics recur during `db.register_predicate()` or `db.register_aggregate()` calls, investigate the closure implementations for panics. +- Restart the process. This indicates a bug in Minigraf; file an issue. -**Scenario**: A custom predicate closure registered via `db.register_predicate()` panics during a query, poisoning the function registry mutex. +**Scenario**: A panic inside `db.register_predicate()`, `db.register_aggregate()` or their `try_` forms while the registry lock is held; the next registration returns this error. ### API-009 WAL not initialized diff --git a/src/db.rs b/src/db.rs index 30a9ae0c80..0760863113 100644 --- a/src/db.rs +++ b/src/db.rs @@ -423,8 +423,8 @@ struct Inner { fact_storage: FactStorage, /// Shared rule registry, persists across all `execute()` calls. rules: Arc>, - /// Function registry for aggregates and window functions. - /// `RwLock` is used in anticipation of the 7.7b `register_aggregate`/`register_predicate` mutation API. + /// Function registry for aggregates, window functions and predicates; + /// each query reads a snapshot of it (#180). functions: Arc, /// Serialises all writes. Holds `WriteContext` which contains the PFS/WAL /// for file-backed databases. diff --git a/src/query/datalog/executor.rs b/src/query/datalog/executor.rs index d48dc16e49..4c640ca977 100644 --- a/src/query/datalog/executor.rs +++ b/src/query/datalog/executor.rs @@ -122,7 +122,7 @@ pub struct DatalogExecutor { /// takes its own snapshot of `storage`. snapshot: Option, rules: Arc>, - // RwLock pre-wired for 7.7b register_aggregate API. + /// The functions; each query reads one snapshot of them (#180). functions: Arc, /// The most facts a rule query may derive, base facts not counted (#553). max_derived_facts: usize, From 1337511cb787479adda5bffcdbada70c20e5e547 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 24 Oct 2026 19:25:00 +0530 Subject: [PATCH 09/13] docs: test counts for #180 PR 1 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015NBT2Yx9JUQKYvv2CvC9py --- CLAUDE.md | 2 +- docs/TEST_COVERAGE.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 771be82d2c..b63be8bcd4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -216,7 +216,7 @@ Auto-migrates v7 → v8 on open (spec §9, with a backup meta page). v1–v6 are ## Test Coverage -**1775 tests** (1762 passing, 13 ignored; unit + integration + doc). Engine answers once checked by the executor are frozen in `tests/answers/` (#551). +**1803 tests** (1790 passing, 13 ignored; unit + integration + doc). Engine answers once checked by the executor are frozen in `tests/answers/` (#551). See `docs/TEST_COVERAGE.md` for the full per-file breakdown. **Testing conventions** — see the Testing Conventions section below before writing any tests. diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md index d833c55332..bfa1c5cb2b 100644 --- a/docs/TEST_COVERAGE.md +++ b/docs/TEST_COVERAGE.md @@ -4,9 +4,9 @@ | | Default features | With `--features test-hooks` | |---|---|---| -| **Passing** | 1,762 | 1,780 | +| **Passing** | 1,790 | 1,808 | | **Ignored** | 13 | 14 | -| **Total** | 1,775 | 1,794 | +| **Total** | 1,803 | 1,822 | **Verified**: 2026-10-24 with `cargo test --quiet`. From d5136803304103f01f8bddf077b694b165c97fff Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 24 Oct 2026 19:38:03 +0530 Subject: [PATCH 10/13] docs: WASI test count for #180 PR 1 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015NBT2Yx9JUQKYvv2CvC9py --- docs/TEST_COVERAGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md index bfa1c5cb2b..6f0d67aad6 100644 --- a/docs/TEST_COVERAGE.md +++ b/docs/TEST_COVERAGE.md @@ -474,7 +474,7 @@ None of these are counted in the summary. The wasm32 targets run in CI (`.github - `importGraph()` deletes the replaced database's IndexedDB keys. - Two buffer tests check that releasing a page drops its bytes and any unflushed write, and that export writes a released page as zeros. - A native storage test checks that a file whose free pages are all zeros (as the browser exports them), both just migrated from v7 and after 20 saves, opens, verifies clean and keeps committing. The free-list test checks that a checkpoint reports exactly the ids it newly lists. -- **On `wasm32-wasip1` under Wasmtime**: the unit and integration tests that do not use a file run, 956 passing; ten that spawn threads or a child process are ignored on WASI. +- **On `wasm32-wasip1` under Wasmtime**: the unit and integration tests that do not use a file run, 1,121 passing (`wasm.yml`, #746); ten that spawn threads or a child process are ignored on WASI. ## Ignored Tests From 27cba5335d55c10a3371b9a20f76e699cc0243e1 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sun, 25 Oct 2026 03:50:57 +0530 Subject: [PATCH 11/13] docs: test counts after merging v3 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Urda7FD9CYYoxdeGGJa11x --- CLAUDE.md | 2 +- docs/TEST_COVERAGE.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9861ce9b5b..871fb23f06 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -216,7 +216,7 @@ Auto-migrates v7 → v8 on open (spec §9, with a backup meta page). v1–v6 are ## Test Coverage -**1803 tests** (1790 passing, 13 ignored; unit + integration + doc). Engine answers once checked by the executor are frozen in `tests/answers/` (#551). +**1824 tests** (1811 passing, 13 ignored; unit + integration + doc). Engine answers once checked by the executor are frozen in `tests/answers/` (#551). See `docs/TEST_COVERAGE.md` for the full per-file breakdown. **Testing conventions** — see the Testing Conventions section below before writing any tests. diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md index f973c9a45e..35f3d910df 100644 --- a/docs/TEST_COVERAGE.md +++ b/docs/TEST_COVERAGE.md @@ -4,9 +4,9 @@ | | Default features | With `--features test-hooks` | |---|---|---| -| **Passing** | 1,790 | 1,808 | +| **Passing** | 1,811 | 1,829 | | **Ignored** | 13 | 14 | -| **Total** | 1,803 | 1,822 | +| **Total** | 1,824 | 1,843 | **Verified**: 2026-10-24 with `cargo test --quiet`. From 2a815d0c6c1f45cbf69c22d70127d48847f895ee Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sun, 25 Oct 2026 04:01:48 +0530 Subject: [PATCH 12/13] docs: test counts after merging v3 (#745) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Urda7FD9CYYoxdeGGJa11x --- CLAUDE.md | 2 +- docs/TEST_COVERAGE.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4094a5e1e5..6bf4975e66 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -216,7 +216,7 @@ Auto-migrates v7 → v8 on open (spec §9, with a backup meta page). v1–v6 are ## Test Coverage -**1824 tests** (1811 passing, 13 ignored; unit + integration + doc). Engine answers once checked by the executor are frozen in `tests/answers/` (#551). +**1838 tests** (1824 passing, 14 ignored; unit + integration + doc). Engine answers once checked by the executor are frozen in `tests/answers/` (#551). See `docs/TEST_COVERAGE.md` for the full per-file breakdown. **Testing conventions** — see the Testing Conventions section below before writing any tests. diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md index 65fdc9097c..172b6c23f6 100644 --- a/docs/TEST_COVERAGE.md +++ b/docs/TEST_COVERAGE.md @@ -4,9 +4,9 @@ | | Default features | With `--features test-hooks` | |---|---|---| -| **Passing** | 1,811 | 1,829 | -| **Ignored** | 13 | 14 | -| **Total** | 1,824 | 1,843 | +| **Passing** | 1,824 | 1,847 | +| **Ignored** | 14 | 15 | +| **Total** | 1,838 | 1,862 | **Verified**: 2026-10-24 with `cargo test --quiet` (and `--features test-hooks`). From 7adf04d6e6f5b1b2ccbd04c11325f5fcecf952be Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sun, 25 Oct 2026 04:02:08 +0530 Subject: [PATCH 13/13] docs: ignored-test count in TEST_COVERAGE prose Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Urda7FD9CYYoxdeGGJa11x --- docs/TEST_COVERAGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md index 172b6c23f6..ac190c374e 100644 --- a/docs/TEST_COVERAGE.md +++ b/docs/TEST_COVERAGE.md @@ -487,7 +487,7 @@ None of these are counted in the summary. The wasm32 targets run in CI (`.github ## Ignored Tests -The thirteen ignored tests (fourteen with `test-hooks`) are intentionally excluded from a normal local run: +The fourteen ignored tests (fifteen with `test-hooks`) are intentionally excluded from a normal local run: - Four rustdoc examples that reference internal types and cannot compile as standalone examples. - One high-contention concurrency stress test intended for scheduled runs.