hecks 4.0.0 → 6.0.0

data/rust/src/kernel/json.rs

@@ -371,9 +371,21 @@ impl Json {
     }
 
     pub fn parse(input: &str) -> Result<Self, String> {
+        Self::parse_with(input, false)
+    }
+
+    /// Parses `input` keeping every number literal's source text, so writing the value back
+    /// reproduces each number exactly as given (`0.0` stays `0.0`, not `0`). For a document that
+    /// is only reshaped and written out again, never evaluated.
+    pub fn parse_keeping_number_text(input: &str) -> Result<Self, String> {
+        Self::parse_with(input, true)
+    }
+
+    fn parse_with(input: &str, keep_number_text: bool) -> Result<Self, String> {
         let mut parser = Parser {
             chars: input.chars().peekable(),
             depth: 0,
+            keep_number_text,
         };
         let value = parser.parse_value()?;
         parser.skip_ws();
@@ -703,6 +715,7 @@ fn write_escaped_string(s: &str, out: &mut String) {
 struct Parser<'a> {
     chars: std::iter::Peekable<std::str::Chars<'a>>,
     depth: usize,
+    keep_number_text: bool,
 }
 
 /// How deeply arrays and objects may nest before `parse` refuses. Each level is a recursive call,
@@ -895,7 +908,8 @@ impl Parser<'_> {
         // A literal with a `.`/exponent is a genuine `Float`, and Ruby's `Float` is the same
         // `f64` Rust's is, so there is nothing to preserve there.
         let is_plain_integer = !s.contains('.') && !s.contains(['e', 'E']);
-        let keeps_source = is_plain_integer && canonical_integer_digits(value) != s;
+        let keeps_source =
+            self.keep_number_text || (is_plain_integer && canonical_integer_digits(value) != s);
         // `1e999` parses to infinity with no source text kept, and `write` would print it as `inf`:
         // not JSON, so refuse it. A plain integer keeps its digits, which `write` re-emits as-is.
         if !value.is_finite() && !keeps_source {

data/rust/src/kernel/mod.rs

@@ -1,15 +1,15 @@
 //! Hand-written, domain-agnostic floor that every generated per-command function calls into.
 
-pub mod attribute_shapes;
 pub mod cli;
+pub mod collecting;
 pub mod dispatch;
-pub mod expr;
-pub mod expression_operators;
 pub mod json;
 pub mod named_query;
 pub mod needs;
 pub mod orchestrate;
 pub mod pattern;
+pub mod present;
+pub mod query_cursor;
 pub mod query_ordering;
 pub mod vocab;
 // Kept at its old path so existing `refusal_wording::RefusalSite` call sites still resolve.
@@ -19,7 +19,6 @@ pub mod read_model;
 pub mod reference_lookup;
 pub mod repository;
 pub mod routing;
-pub mod ruby_float;
 
 pub use dispatch::{
     aggregate_step_site, apply_entity_command, decode_aggregate_arguments, decode_entity_arguments,
@@ -31,6 +30,9 @@ pub use expr::{
     StripSide, Value, WithParent,
 };
 pub use json::Json;
+// The expression evaluator, its operators and the refusal type are their own crate, shared with
+// the host; the kernel re-exports them so every `crate::kernel::expr::…` path keeps working.
+pub use hecks_expr::{attribute_shapes, expr, expression_operators, ruby_float, Refusal};
 pub use named_query::{QueryCondition, QueryConditionValue, QueryDef};
 pub use orchestrate::{
     orchestrate, CompletedCompensation, CrossDomainPolicyRule, DispatchSpec, Handler,
@@ -44,8 +46,8 @@ pub use reference_lookup::{
 };
 pub use refusal_wording::RefusalSite;
 pub use repository::{
-    check_reference, check_role_via, filter_entries, holds_role_via, row_json, AggregateScan,
-    InMemoryRepository, Repository,
+    check_reference, check_role_via, check_roles_via, filter_entries, holds_role_via, row_json,
+    AggregateScan, InMemoryRepository, Repository,
 };
 pub use routing::{CommandInvocation, RoutingEnvelope};
 
@@ -66,67 +68,6 @@ pub struct Event {
     pub correlation: Option<std::collections::HashMap<String, String>>,
 }
 
-/// Why a command dispatch was refused; each variant carries the refusal message.
-///
-/// Ruby's `UnknownVerb` has no variant: routing an unknown command name happens before dispatch.
-/// `AbsentArgument` and `UnknownArgument` are raised only at the JSON boundary (`from_json`),
-/// where the input has no static shape; typed args structs make them unconstructible afterwards.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum Refusal {
-    GivenNotMet(String),
-    EnsuresNotMet(String),
-    InvariantViolation(String),
-    LifecycleRefused(String),
-    AlreadyExists(String),
-    NotFound(String),
-    TypeMismatch(String),
-    AbsentArgument(String),
-    UnknownArgument(String),
-    Unauthorized(String),
-    Fault(String),
-    /// `corrects` against a record that never emitted the corrected event.
-    NothingToCorrect(String),
-}
-
-impl Refusal {
-    /// The refusal class name, spelled as Ruby raises it; the semantics corpus compares it.
-    pub const fn kind(&self) -> &'static str {
-        match self {
-            Self::GivenNotMet(_) => "GivenNotMet",
-            Self::EnsuresNotMet(_) => "EnsuresNotMet",
-            Self::InvariantViolation(_) => "InvariantViolation",
-            Self::LifecycleRefused(_) => "LifecycleRefused",
-            Self::AlreadyExists(_) => "AlreadyExists",
-            Self::NotFound(_) => "NotFound",
-            Self::TypeMismatch(_) => "TypeMismatch",
-            Self::AbsentArgument(_) => "AbsentArgument",
-            Self::UnknownArgument(_) => "UnknownArgument",
-            Self::Unauthorized(_) => "Unauthorized",
-            Self::Fault(_) => "Fault",
-            Self::NothingToCorrect(_) => "NothingToCorrect",
-        }
-    }
-}
-
-impl std::fmt::Display for Refusal {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            Self::GivenNotMet(msg)
-            | Self::EnsuresNotMet(msg)
-            | Self::InvariantViolation(msg)
-            | Self::LifecycleRefused(msg)
-            | Self::AlreadyExists(msg)
-            | Self::NotFound(msg)
-            | Self::TypeMismatch(msg)
-            | Self::AbsentArgument(msg)
-            | Self::UnknownArgument(msg)
-            | Self::Unauthorized(msg)
-            | Self::Fault(msg)
-            | Self::NothingToCorrect(msg) => write!(f, "{msg}"),
-        }
-    }
-}
-
 /// The saved record plus the events it raised, or a refusal that leaves state untouched.
 pub type DispatchResult<T> = Result<(T, Vec<Event>), Refusal>;
 

data/rust/src/kernel/named_query.rs

@@ -3,7 +3,8 @@
 
 use super::refusal_wording::UnauthorizedTenantRequiredArgs;
 use super::{
-    query_comparators::QueryComparator, query_ordering, repository, AggregateScan, Json, Refusal,
+    query_comparators::QueryComparator, query_cursor, query_ordering, repository, AggregateScan,
+    Json, Refusal,
 };
 
 /// One declared query, compiled.
@@ -20,6 +21,8 @@ pub struct QueryDef {
     pub order_by: Option<query_ordering::OrderBy>,
     pub offset: Option<query_ordering::Offset>,
     pub limit: Option<query_ordering::Limit>,
+    /// `cursor` is declared: `limit` is the page size and the call's `after` names the position.
+    pub cursor: bool,
     /// `None` when no `authorize` is declared, or it declares no `tenant:`.
     pub authorization: Option<TenantAuth>,
 }
@@ -58,6 +61,21 @@ pub enum QueryConditionValue {
     /// A caller-bound attribute name, read from the call's `args`; a missing key reads as
     /// `Json::Null`, as Ruby's `resolve_query_value` does.
     Arg(&'static str),
+    /// `where(field: nil)`: resolves to `Json::Null`, which a field that is unset or null equals,
+    /// as `nil == nil` holds in Ruby. Emitted for an `eq`/`ne` against nil.
+    Null,
+}
+
+impl QueryConditionValue {
+    /// The operand this condition compares a row's field against, before `comparable` reduces it.
+    pub fn resolve(self, args: &Json) -> Json {
+        match self {
+            Self::Literal(text) => Json::Str(text.to_string()),
+            Self::NumericLiteral(n) => Json::Num(n, None),
+            Self::Arg(name) => args.get(name).cloned().unwrap_or(Json::Null),
+            Self::Null => Json::Null,
+        }
+    }
 }
 
 /// Runs a declared query: chained `filter_entries` per condition (keeping id order), then
@@ -98,11 +116,7 @@ pub fn run_cross_domain(
         .conditions
         .iter()
         .map(|condition| {
-            let want = match condition.value {
-                QueryConditionValue::Literal(text) => Json::Str(text.to_string()),
-                QueryConditionValue::NumericLiteral(n) => Json::Num(n, None),
-                QueryConditionValue::Arg(name) => args.get(name).cloned().unwrap_or(Json::Null),
-            };
+            let want = condition.value.resolve(args);
             (condition, super::query_comparators::comparable(&want))
         })
         .collect();
@@ -133,6 +147,10 @@ pub fn run_cross_domain(
         store,
     )?;
 
+    if def.cursor {
+        return cursor_rows(entries, def, args);
+    }
+
     Ok(query_ordering::apply(
         entries,
         def.order_by.as_ref(),
@@ -142,6 +160,49 @@ pub fn run_cross_domain(
     ))
 }
 
+/// The ordered rows after the call's `after`, capped at the page size.
+fn cursor_rows(
+    entries: Vec<(String, Json)>,
+    def: &QueryDef,
+    args: &Json,
+) -> Result<Vec<(String, Json)>, Refusal> {
+    let ordered = query_ordering::apply(entries, def.order_by.as_ref(), None, None, args);
+    let after = args.get("after").and_then(Json::as_str);
+    let mut rows = query_cursor::rows_after(ordered, def.order_by.as_ref(), after)?;
+    if let Some(limit) = def.limit.as_ref() {
+        rows.truncate(query_ordering::resolve_limit(limit, args));
+    }
+    Ok(rows)
+}
+
+/// One page of a cursor query: its rows, and the token of the page after them.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Page {
+    pub rows: Vec<(String, Json)>,
+    /// `None` on the last page.
+    pub after: Option<String>,
+}
+
+/// `run`, asked for one row past the page: that row proves a next page exists and is not answered.
+pub fn run_page(
+    store: &impl AggregateScan,
+    def: &QueryDef,
+    args: &Json,
+    caller_role: Option<&str>,
+) -> Result<Page, Refusal> {
+    let size = def
+        .limit
+        .as_ref()
+        .map_or(0, |limit| query_ordering::resolve_limit(limit, args));
+    let widened = QueryDef {
+        limit: Some(query_ordering::Limit::Literal(size as i64 + 1)),
+        ..*def
+    };
+    let rows = run(store, &widened, args, caller_role)?;
+    let (rows, after) = query_cursor::split_page(rows, def.order_by.as_ref(), size);
+    Ok(Page { rows, after })
+}
+
 /// Finds a query by verb; a linear scan is enough for the small generated `QUERIES` table.
 pub fn find<'a>(table: &'a [QueryDef], verb: &str) -> Option<&'a QueryDef> {
     table.iter().find(|def| def.verb == verb)
@@ -193,11 +254,7 @@ pub fn run_entity(
     }
 
     for condition in def.conditions {
-        let want = match condition.value {
-            QueryConditionValue::Literal(text) => Json::Str(text.to_string()),
-            QueryConditionValue::NumericLiteral(n) => Json::Num(n, None),
-            QueryConditionValue::Arg(name) => args.get(name).cloned().unwrap_or(Json::Null),
-        };
+        let want = condition.value.resolve(args);
         entries = repository::filter_entries(entries, condition.field, condition.comparator, &want);
     }
 
@@ -265,3 +322,160 @@ fn row_under_parent(parent_key: &str, parent_id: String, element: Json) -> Json
     }
     Json::Object(fields)
 }
+
+#[cfg(test)]
+mod cursor_tests {
+    use super::*;
+    use crate::kernel::query_ordering::{Limit, NullsMode, OrderBy};
+
+    struct Rows(Vec<(String, Json)>);
+
+    impl AggregateScan for Rows {
+        fn scan(&self, aggregate: &str) -> Option<Vec<(String, Json)>> {
+            (aggregate == "Shop::Item").then(|| self.0.clone())
+        }
+    }
+
+    fn item(id: &str, rank: i64) -> (String, Json) {
+        (id.to_string(), Json::obj(vec![("rank", Json::int(rank))]))
+    }
+
+    fn paged() -> QueryDef {
+        QueryDef {
+            verb: "Shop::Item.Paged",
+            aggregate: "Shop::Item",
+            conditions: &[],
+            reference_hop_conditions: &[],
+            order_by: Some(OrderBy {
+                field: "rank",
+                descending: false,
+                nulls: NullsMode::Native,
+            }),
+            offset: None,
+            limit: Some(Limit::Literal(2)),
+            cursor: true,
+            authorization: None,
+        }
+    }
+
+    fn walk(store: &Rows) -> Vec<Vec<String>> {
+        let (mut pages, mut after) = (Vec::new(), None::<String>);
+        loop {
+            let args = after.as_deref().map_or_else(
+                || Json::obj(vec![]),
+                |a| Json::obj(vec![("after", Json::str(a))]),
+            );
+            let page = run_page(store, &paged(), &args, None).unwrap();
+            pages.push(page.rows.iter().map(|(id, _)| id.clone()).collect());
+            match page.after {
+                Some(next) => after = Some(next),
+                None => return pages,
+            }
+        }
+    }
+
+    #[test]
+    fn walking_pages_yields_every_row_in_order_with_ties_by_identity() {
+        let store = Rows(vec![
+            item("b", 1),
+            item("a", 2),
+            item("d", 2),
+            item("c", 2),
+            item("e", 3),
+        ]);
+        assert_eq!(
+            walk(&store),
+            vec![vec!["b", "a"], vec!["c", "d"], vec!["e"]]
+        );
+    }
+
+    #[test]
+    fn a_page_after_the_last_row_is_empty_with_no_next_position() {
+        let store = Rows(vec![item("a", 1)]);
+        let token = query_cursor::encode(&Json::int(1), "a");
+        let page = run_page(
+            &store,
+            &paged(),
+            &Json::obj(vec![("after", Json::str(token))]),
+            None,
+        )
+        .unwrap();
+        assert_eq!(
+            page,
+            Page {
+                rows: vec![],
+                after: None
+            }
+        );
+    }
+}
+
+#[cfg(test)]
+mod null_condition_tests {
+    use super::{run, AggregateScan, QueryCondition, QueryConditionValue, QueryDef};
+    use crate::kernel::query_comparators::QueryComparator;
+    use crate::kernel::Json;
+
+    struct Rows(Vec<(String, Json)>);
+
+    impl AggregateScan for Rows {
+        fn scan(&self, aggregate: &str) -> Option<Vec<(String, Json)>> {
+            (aggregate == "Grant").then(|| self.0.clone())
+        }
+    }
+
+    const EQ_NULL: &[QueryCondition] = &[QueryCondition {
+        field: "ends_at",
+        comparator: QueryComparator::Eq,
+        value: QueryConditionValue::Null,
+    }];
+    const NE_NULL: &[QueryCondition] = &[QueryCondition {
+        field: "ends_at",
+        comparator: QueryComparator::Ne,
+        value: QueryConditionValue::Null,
+    }];
+
+    fn query(conditions: &'static [QueryCondition]) -> QueryDef {
+        QueryDef {
+            verb: "Grant.Live",
+            aggregate: "Grant",
+            conditions,
+            reference_hop_conditions: &[],
+            order_by: None,
+            offset: None,
+            limit: None,
+            cursor: false,
+            authorization: None,
+        }
+    }
+
+    fn rows() -> Rows {
+        let ended = Json::obj(vec![(
+            "ends_at",
+            Json::obj(vec![("value", Json::str("2026-01-01".to_string()))]),
+        )]);
+        let null = Json::obj(vec![("ends_at", Json::Null)]);
+        let absent = Json::obj(vec![("role", Json::str("Admin".to_string()))]);
+        Rows(vec![
+            ("ended".to_string(), ended),
+            ("null".to_string(), null),
+            ("absent".to_string(), absent),
+        ])
+    }
+
+    fn ids(conditions: &'static [QueryCondition]) -> Vec<String> {
+        let found = run(&rows(), &query(conditions), &Json::obj(vec![]), None).unwrap();
+        found.into_iter().map(|(id, _)| id).collect()
+    }
+
+    // `where(ends_at: nil)`: a field that is null or unset equals nil, as in Ruby.
+    #[test]
+    fn eq_null_keeps_the_rows_whose_field_is_null_or_unset() {
+        assert_eq!(ids(EQ_NULL), ["absent", "null"]);
+    }
+
+    #[test]
+    fn ne_null_keeps_the_rows_whose_field_is_set() {
+        assert_eq!(ids(NE_NULL), ["ended"]);
+    }
+}