hecks 4.0.0 → 6.0.0

data/rust/src/kernel/query_cursor.rs

@@ -0,0 +1,251 @@
+//! The position a cursor query pages by: one opaque token naming the last row's order value and
+//! identity, and the rule for which rows follow it. Mirrors Ruby's `Ports::Query::Cursor`, so a
+//! token minted by either engine is read by the other.
+
+use super::query_ordering::{self, NullsMode, OrderBy};
+use super::{Json, Refusal};
+use std::cmp::Ordering;
+
+type Rows = Vec<(String, Json)>;
+
+const ALPHABET: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/// The token naming a position: the URL-safe base64 (no padding) of the JSON array `[value, id]`.
+pub fn encode(value: &Json, id: &str) -> String {
+    let body = Json::Array(vec![value.clone(), Json::Str(id.to_string())]).to_json_string();
+    base64_url(body.as_bytes())
+}
+
+/// The token for `record`, read off the query's order field (null with no declared order).
+pub fn token_for(id: &str, record: &Json, order_by: Option<&OrderBy>) -> String {
+    let value = order_by.map_or(Json::Null, |order| {
+        query_ordering::order_key(record, order.field)
+    });
+    encode(&value, id)
+}
+
+/// A token read back: the order value (`Json::Null` for a null-keyed row) and the row id.
+fn decode(token: &str) -> Result<(Json, String), Refusal> {
+    let invalid = || {
+        Refusal::TypeMismatch(format!(
+            "after {token:?} is not a cursor this query handed out"
+        ))
+    };
+    let bytes = unbase64_url(token).ok_or_else(invalid)?;
+    let text = String::from_utf8(bytes).map_err(|_| invalid())?;
+    match Json::parse(&text) {
+        Ok(Json::Array(items)) => match items.as_slice() {
+            [value, Json::Str(id)] => Ok((value.clone(), id.clone())),
+            _ => Err(invalid()),
+        },
+        _ => Err(invalid()),
+    }
+}
+
+/// The rows that follow the token's position, in the order given; all of them with no token.
+pub fn rows_after(
+    rows: Rows,
+    order_by: Option<&OrderBy>,
+    after: Option<&str>,
+) -> Result<Rows, Refusal> {
+    let Some(token) = after else { return Ok(rows) };
+    let (held, held_id) = decode(token)?;
+    Ok(rows
+        .into_iter()
+        .filter(|(id, record)| follows(id, record, order_by, &held, &held_id))
+        .collect())
+}
+
+/// Splits rows fetched one past the page into the page and the token of the next one.
+pub fn split_page(
+    mut rows: Rows,
+    order_by: Option<&OrderBy>,
+    size: usize,
+) -> (Rows, Option<String>) {
+    if rows.len() <= size || size == 0 {
+        rows.truncate(size);
+        return (rows, None);
+    }
+    rows.truncate(size);
+    let next = rows
+        .last()
+        .map(|(id, record)| token_for(id, record, order_by));
+    (rows, next)
+}
+
+fn follows(
+    id: &str,
+    record: &Json,
+    order_by: Option<&OrderBy>,
+    held: &Json,
+    held_id: &str,
+) -> bool {
+    let Some(order) = order_by else {
+        return id > held_id;
+    };
+    let key = query_ordering::order_key(record, order.field);
+    sequence(&key, id, held, held_id, order) == Ordering::Greater
+}
+
+/// Where a row sits against the position in query order: the order value in its direction, nulls
+/// where `nulls` puts them, identity breaking ties in the same direction.
+fn sequence(key: &Json, id: &str, held: &Json, held_id: &str, order: &OrderBy) -> Ordering {
+    let (key_null, held_null) = (*key == Json::Null, *held == Json::Null);
+    if key_null != held_null {
+        return if key_null == nulls_first(order) {
+            Ordering::Less
+        } else {
+            Ordering::Greater
+        };
+    }
+    let by_value = if key_null {
+        Ordering::Equal
+    } else {
+        query_ordering::compare_comparable(key, held)
+    };
+    let forward = by_value.then_with(|| id.cmp(held_id));
+    if order.descending {
+        forward.reverse()
+    } else {
+        forward
+    }
+}
+
+const fn nulls_first(order: &OrderBy) -> bool {
+    match order.nulls {
+        NullsMode::First => true,
+        NullsMode::Last => false,
+        NullsMode::Native => !order.descending,
+    }
+}
+
+fn base64_url(bytes: &[u8]) -> String {
+    let mut out = String::new();
+    for chunk in bytes.chunks(3) {
+        let n = chunk
+            .iter()
+            .enumerate()
+            .fold(0u32, |acc, (i, b)| acc | (u32::from(*b) << (16 - 8 * i)));
+        for i in 0..=chunk.len() {
+            out.push(ALPHABET[((n >> (18 - 6 * i)) & 63) as usize] as char);
+        }
+    }
+    out
+}
+
+fn unbase64_url(text: &str) -> Option<Vec<u8>> {
+    let sextets: Option<Vec<u32>> = text
+        .trim_end_matches('=')
+        .bytes()
+        .map(|b| ALPHABET.iter().position(|a| *a == b).map(|p| p as u32))
+        .collect();
+    let sextets = sextets?;
+    let mut out = Vec::new();
+    for chunk in sextets.chunks(4) {
+        if chunk.len() == 1 {
+            return None;
+        }
+        let n = chunk
+            .iter()
+            .enumerate()
+            .fold(0u32, |acc, (i, s)| acc | (s << (18 - 6 * i)));
+        for i in 0..chunk.len() - 1 {
+            out.push((n >> (16 - 8 * i)) as u8);
+        }
+    }
+    Some(out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn order(descending: bool, nulls: NullsMode) -> OrderBy {
+        OrderBy {
+            field: "rating",
+            descending,
+            nulls,
+        }
+    }
+
+    fn row(id: &str, rating: Option<i64>) -> (String, Json) {
+        let value = rating.map_or(Json::Null, Json::int);
+        (id.to_string(), Json::obj(vec![("rating", value)]))
+    }
+
+    fn ids(rows: &Rows) -> Vec<&str> {
+        rows.iter().map(|(id, _)| id.as_str()).collect()
+    }
+
+    #[test]
+    fn a_token_is_ruby_base64_of_the_json_pair() {
+        // Ruby: Base64.urlsafe_encode64(JSON.generate([100, "r1"]), padding: false)
+        assert_eq!(encode(&Json::int(100), "r1"), "WzEwMCwicjEiXQ");
+    }
+
+    #[test]
+    fn a_token_reads_back_to_its_value_and_id() {
+        let (value, id) = decode(&encode(&Json::Null, "r9")).unwrap();
+        assert_eq!((value, id.as_str()), (Json::Null, "r9"));
+    }
+
+    #[test]
+    fn a_foreign_string_is_refused() {
+        assert!(matches!(
+            decode("not a cursor!"),
+            Err(Refusal::TypeMismatch(_))
+        ));
+    }
+
+    #[test]
+    fn ties_break_by_identity_and_nulls_by_placement() {
+        let ordered = order(false, NullsMode::First);
+        let rows = vec![
+            row("r2", None),
+            row("r4", None),
+            row("r1", Some(100)),
+            row("r3", Some(300)),
+            row("r6", Some(300)),
+        ];
+        let token = encode(&Json::int(300), "r3");
+        let after = rows_after(rows, Some(&ordered), Some(&token)).unwrap();
+        assert_eq!(ids(&after), vec!["r6"]);
+    }
+
+    #[test]
+    fn a_null_position_is_followed_by_later_nulls_then_values_when_nulls_lead() {
+        let ordered = order(false, NullsMode::First);
+        let rows = vec![row("r2", None), row("r4", None), row("r1", Some(100))];
+        let after = rows_after(rows, Some(&ordered), Some(&encode(&Json::Null, "r2"))).unwrap();
+        assert_eq!(ids(&after), vec!["r4", "r1"]);
+    }
+
+    #[test]
+    fn descending_reverses_values_and_ties() {
+        let ordered = order(true, NullsMode::Native);
+        let rows = vec![
+            row("r5", Some(500)),
+            row("r6", Some(300)),
+            row("r3", Some(300)),
+            row("r4", None),
+        ];
+        let after = rows_after(rows, Some(&ordered), Some(&encode(&Json::int(300), "r6"))).unwrap();
+        assert_eq!(ids(&after), vec!["r3", "r4"]);
+    }
+
+    #[test]
+    fn the_last_page_has_no_next_token() {
+        let rows = vec![row("r1", Some(1)), row("r2", Some(2))];
+        assert_eq!(split_page(rows, None, 2).1, None);
+    }
+
+    #[test]
+    fn a_full_page_names_its_last_row() {
+        let rows = vec![row("r1", Some(1)), row("r2", Some(2)), row("r3", Some(3))];
+        let (page, next) = split_page(rows, Some(&order(false, NullsMode::Native)), 2);
+        assert_eq!(
+            (ids(&page), next),
+            (vec!["r1", "r2"], Some(encode(&Json::int(2), "r2")))
+        );
+    }
+}

data/rust/src/kernel/query_ordering.rs

@@ -85,13 +85,13 @@ fn apply_declared_order(rows: Rows, order_by: &OrderBy) -> Rows {
     }
 }
 
-// Reduced like a where clause's held value; a missing field reads as `Json::Null`.
-fn order_key(record: &Json, field: &str) -> Json {
+/// Reduced like a where clause's held value; a missing field reads as `Json::Null`.
+pub(super) fn order_key(record: &Json, field: &str) -> Json {
     query_comparators::comparable(&record.dig(field).cloned().unwrap_or(Json::Null))
 }
 
-// Codegen only lets a declared field resolve to a number or a string, homogeneous per field.
-fn compare_comparable(a: &Json, b: &Json) -> std::cmp::Ordering {
+/// Codegen only lets a declared field resolve to a number or a string, homogeneous per field.
+pub(super) fn compare_comparable(a: &Json, b: &Json) -> std::cmp::Ordering {
     match (a, b) {
         (Json::Num(x, _) | Json::Float(x), Json::Num(y, _) | Json::Float(y)) => {
             x.partial_cmp(y).unwrap_or(std::cmp::Ordering::Equal)
@@ -101,8 +101,8 @@ fn compare_comparable(a: &Json, b: &Json) -> std::cmp::Ordering {
     }
 }
 
-// A missing or non-numeric arg reads as 0 (Ruby's `nil.to_i`); negatives floor to 0.
-fn resolve_limit(limit: &Limit, args: &Json) -> usize {
+/// A missing or non-numeric arg reads as 0 (Ruby's `nil.to_i`); negatives floor to 0.
+pub(super) fn resolve_limit(limit: &Limit, args: &Json) -> usize {
     let raw = match limit {
         Limit::Literal(n) => *n,
         Limit::Arg(name) => args.get(name).and_then(Json::as_i64).unwrap_or(0),

data/rust/src/kernel/read_model.rs

@@ -5,6 +5,7 @@ use super::refusal_wording::{
     InvariantViolationGroupByCollisionArgs, NotFoundReadModelReferenceMissingArgs,
     UnauthorizedTenantRequiredArgs,
 };
+use super::vocab::Reducer;
 use super::{
     named_query, query_comparators, query_ordering, repository, AggregateScan, Json,
     QueryCondition, QueryConditionValue, Refusal,
@@ -137,8 +138,67 @@ pub enum Reduction {
     All(&'static str),
 }
 
-/// The head's rows reduced as declared.
+impl Reduction {
+    /// The Vocabulary `Reducer` row this reduction is an instance of (ADR 0126).
+    pub const fn reducer(self) -> Reducer {
+        match self {
+            Self::Count => Reducer::Count,
+            Self::Median(_) => Reducer::Median,
+            Self::Sum(_) => Reducer::Sum,
+            Self::Avg(_) => Reducer::Avg,
+            Self::Min(_) => Reducer::Min,
+            Self::Max(_) => Reducer::Max,
+            Self::Percentile { .. } => Reducer::Percentile,
+            Self::Any(_) => Reducer::Any,
+            Self::All(_) => Reducer::All,
+        }
+    }
+
+    /// The declared field this reduction reads; `None` for `count`, which reads no field.
+    pub const fn field(self) -> Option<&'static str> {
+        match self {
+            Self::Count => None,
+            Self::Median(field)
+            | Self::Sum(field)
+            | Self::Avg(field)
+            | Self::Min(field)
+            | Self::Max(field)
+            | Self::Percentile { field, .. }
+            | Self::Any(field)
+            | Self::All(field) => Some(field),
+        }
+    }
+}
+
+/// A reducer's answer over no rows: its `Reducer` row's `identity`, read as JSON text.
+/// A number is the integer zero `sum` answers, without a raw spelling, as `sum` builds it.
+fn empty_answer(reducer: Reducer) -> Json {
+    match reducer.identity() {
+        "true" => Json::Bool(true),
+        "false" => Json::Bool(false),
+        number => number
+            .parse::<f64>()
+            .map_or(Json::Null, |value| Json::Num(value, None)),
+    }
+}
+
+/// Whether no row holds a value for the declared field, so the reduction answers its identity.
+fn holds_no_value(rows: &[(String, Json)], field: &'static str) -> bool {
+    rows.iter()
+        .filter_map(|(_, row)| row.get(field))
+        .map(query_comparators::comparable)
+        .all(|value| matches!(value, Json::Null))
+}
+
+/// The head's rows reduced as declared; a collection holding no value for the declared field
+/// answers the reducer's identity (ADR 0126).
 fn reduce(rows: &[(String, Json)], reduction: Reduction) -> Json {
+    if reduction
+        .field()
+        .is_some_and(|field| holds_no_value(rows, field))
+    {
+        return empty_answer(reduction.reducer());
+    }
     match reduction {
         Reduction::Count => Json::Num(rows.len() as f64, None),
         Reduction::Median(field) => median(rows, field),
@@ -164,11 +224,43 @@ pub enum LeafCheck {
     RefuseCollision(&'static str),
 }
 
+/// What a `group_by` leaf answers: the one row its key path reached, or the declared reduction
+/// of every row it reached (ADR 0126).
+#[derive(Debug, Clone, Copy)]
+enum Leaf {
+    Row(LeafCheck),
+    Reduce(Reduction),
+}
+
 /// One level of nesting per declared `group_by` field. Grouping is a Vec-based linear scan, not
 /// a `HashMap`, because `Json` has no `Hash` impl and groups must stay in first-occurrence order
 /// (matching Ruby's `Hash#group_by`) so both runtimes report the same first collision.
 pub fn nest(rows: Vec<Json>, fields: &[&str], check: LeafCheck) -> Result<Json, Refusal> {
-    nest_level(rows, fields, fields, check, &[])
+    nest_level(rows, fields, fields, Leaf::Row(check), &[])
+}
+
+/// `nest` with each leaf reduced as declared in place of holding one row (ADR 0126): the
+/// generated per-read-model group function of a read model that groups and reduces.
+pub fn nest_reduced(
+    rows: Vec<Json>,
+    fields: &[&str],
+    reduction: Reduction,
+) -> Result<Json, Refusal> {
+    nest_level(rows, fields, fields, Leaf::Reduce(reduction), &[])
+}
+
+/// A leaf's rows as `(id, row)` pairs, the shape `reduce` reads.
+fn leaf_pairs(group: Vec<Json>) -> Vec<(String, Json)> {
+    group
+        .into_iter()
+        .map(|row| {
+            let id = row
+                .get("id")
+                .map(super::query_comparators::to_s)
+                .unwrap_or_default();
+            (id, row)
+        })
+        .collect()
 }
 
 /// One level of `nest`. `all_fields` is the whole declared `group_by`
@@ -178,7 +270,7 @@ fn nest_level(
     rows: Vec<Json>,
     all_fields: &[&str],
     fields: &[&str],
-    check: LeafCheck,
+    answer: Leaf,
     reached: &[(&str, Json)],
 ) -> Result<Json, Refusal> {
     let Some((field, rest)) = fields.split_first() else {
@@ -210,10 +302,10 @@ fn nest_level(
     for (key, group) in groups {
         let mut path = reached.to_vec();
         path.push((field, key.clone()));
-        let value = if rest.is_empty() {
-            leaf(group, all_fields, check, &path)?
-        } else {
-            nest_level(group, all_fields, rest, check, &path)?
+        let value = match (rest.is_empty(), answer) {
+            (true, Leaf::Row(check)) => leaf(group, all_fields, check, &path)?,
+            (true, Leaf::Reduce(reduction)) => reduce(&leaf_pairs(group), reduction),
+            (false, _) => nest_level(group, all_fields, rest, answer, &path)?,
         };
         // A non-String key must stringify the same way Ruby's `Hash#[]=` does when used as a
         // JSON object key.
@@ -533,6 +625,65 @@ mod nest_tests {
 /// Exercises `ReferenceHopCondition`'s fold end-to-end through `run`, not just the isolated
 /// `apply_filtered_head_options` helper, so a wiring mistake at either call site fails this the
 /// same way it would fail a real caller.
+/// ADR 0126 — a grouped reduction answers each leaf's reduction, and an empty collection
+/// answers the reducer's declared identity.
+#[cfg(test)]
+mod nest_reduced_tests {
+    use super::*;
+
+    fn item(id: &str, aisle: &str, units: i64) -> Json {
+        Json::obj(vec![
+            ("aisle", Json::str(aisle)),
+            ("units", Json::int(units)),
+            ("id", Json::str(id)),
+        ])
+    }
+
+    #[test]
+    fn sums_each_group_in_first_seen_order() {
+        let rows = vec![item("i1", "a", 4), item("i2", "b", 7), item("i3", "a", 6)];
+
+        let nested = nest_reduced(rows, &["aisle"], Reduction::Sum("units")).expect("sums");
+
+        assert_eq!(
+            nested,
+            Json::obj(vec![
+                ("a", Json::Num(10.0, None)),
+                ("b", Json::Num(7.0, None))
+            ])
+        );
+    }
+
+    #[test]
+    fn counts_each_group_without_refusing_a_shared_key() {
+        let rows = vec![item("i1", "a", 4), item("i2", "a", 6)];
+
+        let nested = nest_reduced(rows, &["aisle"], Reduction::Count).expect("counts");
+
+        assert_eq!(nested, Json::obj(vec![("a", Json::Num(2.0, None))]));
+    }
+
+    #[test]
+    fn answers_each_reducers_declared_identity_over_no_rows() {
+        let answers: Vec<Json> = Reducer::ALL.iter().map(|r| empty_answer(*r)).collect();
+
+        assert_eq!(
+            answers,
+            vec![
+                Json::Num(0.0, None),
+                Json::Num(0.0, None),
+                Json::Null,
+                Json::Null,
+                Json::Null,
+                Json::Null,
+                Json::Null,
+                Json::Bool(false),
+                Json::Bool(true),
+            ]
+        );
+    }
+}
+
 #[cfg(test)]
 mod reference_hop_tests {
     use super::*;
@@ -757,6 +908,7 @@ mod reference_hop_tests {
             order_by: None,
             offset: None,
             limit: None,
+            cursor: false,
             authorization: None,
         };
 
@@ -914,6 +1066,7 @@ mod reference_hop_tests {
             order_by: None,
             offset: None,
             limit: None,
+            cursor: false,
             authorization: None,
         };
 
@@ -1128,11 +1281,7 @@ fn apply_filtered_head_options(
     store: &impl AggregateScan,
 ) -> Result<Vec<(String, Json)>, Refusal> {
     for condition in filtered.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);
         rows = repository::filter_entries(rows, condition.field, condition.comparator, &want);
     }
 
@@ -1157,11 +1306,7 @@ pub(super) fn apply_reference_hops(
     store: &impl AggregateScan,
 ) -> Result<Vec<(String, Json)>, Refusal> {
     for hop in hops {
-        let inner_want = match hop.inner_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 inner_want = hop.inner_value.resolve(args);
         let scan = |aggregate: &str| {
             store
                 .scan(aggregate)