hecks 2.9.0 → 3.0.0

data/rust/src/kernel/pattern.rs

@@ -0,0 +1,307 @@
+// Regex matcher for the dialect `Hecks::Bluebook::PatternSubset` admits (no backreferences,
+// lookaround or Perl classes). Unanchored search, like Ruby's `Regexp#match?`.
+
+#[derive(Debug, Clone)]
+enum Node {
+    Literal(char),
+    Any,
+    Class { negate: bool, ranges: Vec<(char, char)> },
+    // `^`/`$` match at line boundaries, as in Ruby.
+    LineStart,
+    LineEnd,
+    // `\A`/`\z`/`\Z` match only at the whole-string boundaries.
+    StringStart,
+    StringEnd,
+    Group(Vec<Node>),
+    Alt(Vec<Vec<Node>>),
+    Repeat { node: Box<Node>, min: usize, max: Option<usize> },
+}
+
+/// `true` if `text` contains a match for `pattern`; a pattern that fails to parse is `false`.
+pub fn matches(pattern: &str, text: &str) -> bool {
+    let Ok(nodes) = parse(pattern) else { return false };
+    let chars: Vec<char> = text.chars().collect();
+    // Only `\A` may skip to position 0; `^` can still match after a later `\n`.
+    let anchored_start = matches!(nodes.first(), Some(Node::StringStart));
+    if anchored_start {
+        return match_from(&nodes, 0, &chars, 0, &|_| true);
+    }
+    (0..=chars.len()).any(|start| match_from(&nodes, 0, &chars, start, &|_| true))
+}
+
+fn match_from(nodes: &[Node], idx: usize, text: &[char], ti: usize, cont: &dyn Fn(usize) -> bool) -> bool {
+    if idx == nodes.len() {
+        return cont(ti);
+    }
+    match &nodes[idx] {
+        Node::Literal(c) => ti < text.len() && text[ti] == *c && match_from(nodes, idx + 1, text, ti + 1, cont),
+        // Like Ruby without `/m`, `.` does not match `\n`.
+        Node::Any => ti < text.len() && text[ti] != '\n' && match_from(nodes, idx + 1, text, ti + 1, cont),
+        Node::Class { negate, ranges } => {
+            ti < text.len() && class_matches(*negate, ranges, text[ti]) && match_from(nodes, idx + 1, text, ti + 1, cont)
+        }
+        Node::LineStart => (ti == 0 || text[ti - 1] == '\n') && match_from(nodes, idx + 1, text, ti, cont),
+        Node::LineEnd => (ti == text.len() || text[ti] == '\n') && match_from(nodes, idx + 1, text, ti, cont),
+        Node::StringStart => ti == 0 && match_from(nodes, idx + 1, text, ti, cont),
+        Node::StringEnd => ti == text.len() && match_from(nodes, idx + 1, text, ti, cont),
+        Node::Group(inner) => match_from(inner, 0, text, ti, &|ti2| match_from(nodes, idx + 1, text, ti2, cont)),
+        Node::Alt(branches) => branches.iter().any(|b| match_from(b, 0, text, ti, &|ti2| match_from(nodes, idx + 1, text, ti2, cont))),
+        Node::Repeat { node, min, max } => match_repeat(node, 0, *min, *max, nodes, idx + 1, text, ti, cont),
+    }
+}
+
+// Greedy: try one more repetition first, then fall back to stopping at the current count.
+// The `ti2 == ti` check stops a zero-width repetition from looping forever.
+#[allow(clippy::too_many_arguments)]
+fn match_repeat(
+    node: &Node,
+    count: usize,
+    min: usize,
+    max: Option<usize>,
+    nodes: &[Node],
+    next_idx: usize,
+    text: &[char],
+    ti: usize,
+    cont: &dyn Fn(usize) -> bool,
+) -> bool {
+    let can_more = max.is_none_or(|m| count < m);
+    if can_more {
+        let one_more = std::slice::from_ref(node);
+        let matched = match_from(one_more, 0, text, ti, &|ti2| {
+            if ti2 == ti {
+                return false; // zero-width — stop growing, fall through to the min/stop check below
+            }
+            match_repeat(node, count + 1, min, max, nodes, next_idx, text, ti2, cont)
+        });
+        if matched {
+            return true;
+        }
+    }
+    count >= min && match_from(nodes, next_idx, text, ti, cont)
+}
+
+fn class_matches(negate: bool, ranges: &[(char, char)], c: char) -> bool {
+    let hit = ranges.iter().any(|(lo, hi)| *lo <= c && c <= *hi);
+    hit != negate
+}
+
+// `\t`, `\n` and `\r` become control characters; any other escape is the literal itself.
+fn escape_char(c: char) -> char {
+    match c {
+        't' => '\t',
+        'n' => '\n',
+        'r' => '\r',
+        other => other,
+    }
+}
+
+// Recursive descent: `alternation > concat > repeat > atom`.
+fn parse(pattern: &str) -> Result<Vec<Node>, ()> {
+    let chars: Vec<char> = pattern.chars().collect();
+    let mut p = Parser { chars: &chars, pos: 0 };
+    let node = p.parse_alt()?;
+    if p.pos != p.chars.len() {
+        return Err(());
+    }
+    Ok(node)
+}
+
+struct Parser<'a> {
+    chars: &'a [char],
+    pos: usize,
+}
+
+impl<'a> Parser<'a> {
+    fn peek(&self) -> Option<char> {
+        self.chars.get(self.pos).copied()
+    }
+
+    fn bump(&mut self) -> Option<char> {
+        let c = self.peek();
+        if c.is_some() {
+            self.pos += 1;
+        }
+        c
+    }
+
+    /// `alternation := concat ('|' concat)*`
+    fn parse_alt(&mut self) -> Result<Vec<Node>, ()> {
+        let first = self.parse_concat()?;
+        if self.peek() != Some('|') {
+            return Ok(first);
+        }
+        let mut branches = vec![first];
+        while self.peek() == Some('|') {
+            self.bump();
+            branches.push(self.parse_concat()?);
+        }
+        Ok(vec![Node::Alt(branches)])
+    }
+
+    /// `concat := repeat*`, ending at `|` or `)`.
+    fn parse_concat(&mut self) -> Result<Vec<Node>, ()> {
+        let mut nodes = Vec::new();
+        while let Some(c) = self.peek() {
+            if c == '|' || c == ')' {
+                break;
+            }
+            nodes.push(self.parse_repeat()?);
+        }
+        Ok(nodes)
+    }
+
+    /// `repeat := atom ('*' | '+' | '?' | '{' n (',' m?)? '}')?`
+    fn parse_repeat(&mut self) -> Result<Node, ()> {
+        let atom = self.parse_atom()?;
+        match self.peek() {
+            Some('*') => {
+                self.bump();
+                Ok(Node::Repeat { node: Box::new(atom), min: 0, max: None })
+            }
+            Some('+') => {
+                self.bump();
+                Ok(Node::Repeat { node: Box::new(atom), min: 1, max: None })
+            }
+            Some('?') => {
+                self.bump();
+                Ok(Node::Repeat { node: Box::new(atom), min: 0, max: Some(1) })
+            }
+            Some('{') => {
+                let save = self.pos;
+                self.bump();
+                match self.parse_bounded_repeat() {
+                    Some((min, max)) => Ok(Node::Repeat { node: Box::new(atom), min, max }),
+                    None => {
+                        // Not a well-formed `{n,m}`: read the brace as a literal.
+                        self.pos = save;
+                        Ok(atom)
+                    }
+                }
+            }
+            _ => Ok(atom),
+        }
+    }
+
+    /// Past the `{`. Returns `None` (not a quantifier) so the caller can read a literal `{`.
+    fn parse_bounded_repeat(&mut self) -> Option<(usize, Option<usize>)> {
+        let min = self.parse_digits()?;
+        match self.peek() {
+            Some('}') => {
+                self.bump();
+                Some((min, Some(min)))
+            }
+            Some(',') => {
+                self.bump();
+                if self.peek() == Some('}') {
+                    self.bump();
+                    Some((min, None))
+                } else {
+                    let max = self.parse_digits()?;
+                    if self.peek() == Some('}') {
+                        self.bump();
+                        Some((min, Some(max)))
+                    } else {
+                        None
+                    }
+                }
+            }
+            _ => None,
+        }
+    }
+
+    fn parse_digits(&mut self) -> Option<usize> {
+        let start = self.pos;
+        while matches!(self.peek(), Some(c) if c.is_ascii_digit()) {
+            self.bump();
+        }
+        if self.pos == start {
+            return None;
+        }
+        self.chars[start..self.pos].iter().collect::<String>().parse().ok()
+    }
+
+    fn parse_atom(&mut self) -> Result<Node, ()> {
+        match self.bump().ok_or(())? {
+            '.' => Ok(Node::Any),
+            '^' => Ok(Node::LineStart),
+            '$' => Ok(Node::LineEnd),
+            '(' => {
+                let inner = self.parse_alt()?;
+                if self.bump() != Some(')') {
+                    return Err(());
+                }
+                Ok(Node::Group(inner))
+            }
+            '[' => self.parse_class(),
+            '\\' => match self.bump().ok_or(())? {
+                'A' => Ok(Node::StringStart),
+                'z' | 'Z' => Ok(Node::StringEnd),
+                // an escaped metacharacter or control char: the literal itself
+                c => Ok(Node::Literal(escape_char(c))),
+            },
+            c => Ok(Node::Literal(c)),
+        }
+    }
+
+    /// `[...]`/`[^...]` with ranges. A leading `]` is a literal member (`[]abc]`).
+    fn parse_class(&mut self) -> Result<Node, ()> {
+        let negate = if self.peek() == Some('^') {
+            self.bump();
+            true
+        } else {
+            false
+        };
+        let mut ranges = Vec::new();
+        let mut first = true;
+        loop {
+            match self.peek() {
+                Some(']') if !first => {
+                    self.bump();
+                    break;
+                }
+                Some(c) => {
+                    self.bump();
+                    let lo = if c == '\\' { escape_char(self.bump().ok_or(())?) } else { c };
+                    if self.peek() == Some('-') && self.chars.get(self.pos + 1).is_some_and(|c| *c != ']') {
+                        self.bump();
+                        let hi_raw = self.bump().ok_or(())?;
+                        let hi = if hi_raw == '\\' { escape_char(self.bump().ok_or(())?) } else { hi_raw };
+                        ranges.push((lo, hi));
+                    } else {
+                        ranges.push((lo, lo));
+                    }
+                }
+                None => return Err(()),
+            }
+            first = false;
+        }
+        Ok(Node::Class { negate, ranges })
+    }
+}
+
+// Walks every row of the recorded pattern contract so dialect changes cannot drop a case.
+#[cfg(test)]
+mod tests {
+    use super::matches;
+    use crate::kernel::Json;
+
+    #[test]
+    fn matches_every_row_of_the_recorded_pattern_contract() {
+        let raw = include_str!("../../../spec/corpus/fixtures/patterns.json");
+        let parsed = Json::parse(raw).expect("patterns.json must parse");
+        let rows = parsed.as_array().expect("patterns.json must be a JSON array");
+        assert!(!rows.is_empty(), "the recorded contract must not be empty");
+
+        for row in rows {
+            let pattern = row.get("pattern").and_then(Json::as_str).expect("row must carry a pattern");
+            let input = row.get("input").and_then(Json::as_str).expect("row must carry an input");
+            let expected = matches!(row.get("matches"), Some(Json::Bool(true)));
+
+            assert_eq!(
+                matches(pattern, input),
+                expected,
+                "pattern {pattern:?} against {input:?} should match={expected}"
+            );
+        }
+    }
+}

data/rust/src/kernel/query_comparators.rs

@@ -0,0 +1,206 @@
+// Matching logic for the generated `QueryComparator` enum (`vocab::QueryComparator`),
+// mirroring Ruby's `QuerySpecification::Common::Comparison#holds?`.
+
+use super::Json;
+
+pub use super::vocab::QueryComparator;
+
+impl QueryComparator {
+    /// The wire's `op` string, or `None` if unrecognized (callers refuse, never default to `eq`).
+    pub fn parse(op: &str) -> Option<Self> {
+        QueryComparator::from_name(op)
+    }
+
+    /// `Comparison#holds?`; `held`/`want` arrive already reduced through `comparable`.
+    pub fn matches(self, held: &Json, want: &Json) -> bool {
+        match self {
+            QueryComparator::Eq => held == want,
+            QueryComparator::Ne => held != want,
+            QueryComparator::Gt => ordered(held, want) && as_f64(held) > as_f64(want),
+            QueryComparator::Gte => ordered(held, want) && as_f64(held) >= as_f64(want),
+            QueryComparator::Lt => ordered(held, want) && as_f64(held) < as_f64(want),
+            QueryComparator::Lte => ordered(held, want) && as_f64(held) <= as_f64(want),
+            QueryComparator::In => members(want).iter().any(|member| member == &to_s(held)),
+            QueryComparator::Contains => contains(held, want),
+            // Needs a repository, so `filter_entries_cross_domain` calls `none_in_state_matches`
+            // first; this arm keeps the match exhaustive with the same "not excluded" default.
+            QueryComparator::NoneInState => true,
+        }
+    }
+}
+
+/// `Comparison#none_in_state?`: `want` is `"Aggregate:state"`, `held` the referring foreign key.
+/// `cross_domain` is searched in order, first match wins; an empty slice answers `true`.
+pub fn none_in_state_matches(cross_domain: &[(&str, &dyn super::AggregateScan)], held: &Json, want: &Json) -> bool {
+    let Some((aggregate_name, state)) = to_s(want).split_once(':').map(|(a, s)| (a.to_string(), s.to_string()))
+    else {
+        return true;
+    };
+    let held_id = to_s(held);
+
+    for (domain_name, store) in cross_domain {
+        let qualified = format!("{domain_name}::{aggregate_name}");
+        let Some(entries) = store.scan(&qualified) else { continue };
+
+        let Some((_, record)) = entries.iter().find(|(id, _)| *id == held_id) else { return true };
+        let record_state = comparable(&record.dig("state").cloned().unwrap_or(Json::Null));
+        return to_s(&record_state) != state;
+    }
+
+    // No domain declares the aggregate: not excluded.
+    true
+}
+
+/// gt/gte/lt/lte are numeric-only; anything else is silently false, never a refusal.
+fn ordered(held: &Json, want: &Json) -> bool {
+    matches!(held, Json::Num(_, _) | Json::Float(_)) && matches!(want, Json::Num(_, _) | Json::Float(_))
+}
+
+/// Only called after `ordered` has gated the comparison, so the NaN fallback is unreachable.
+pub(crate) fn as_f64(value: &Json) -> f64 {
+    match value {
+        Json::Num(n, _) | Json::Float(n) => *n,
+        _ => f64::NAN,
+    }
+}
+
+/// Ruby's `#to_s` on a scalar already reduced by `comparable`.
+pub(crate) fn to_s(value: &Json) -> String {
+    match value {
+        Json::Str(s) => s.clone(),
+        // The exact source text wins when there is one (BUG#147) — see `Json::write`.
+        Json::Num(_, Some(raw)) => raw.clone(),
+        Json::Num(n, None) if n.fract() == 0.0 && n.abs() < 1e15 => (*n as i64).to_string(),
+        Json::Num(n, None) => n.to_string(),
+        // Ruby's `Float#to_s` always shows a decimal point (`10.0`).
+        Json::Float(n) => {
+            let rendered = n.to_string();
+            if rendered.contains('.') || rendered.contains('e') || rendered.contains('E') {
+                rendered
+            } else {
+                format!("{rendered}.0")
+            }
+        }
+        Json::Bool(b) => b.to_string(),
+        Json::Null => String::new(),
+        // A multi-member, non-numeric value object still arrives structured; JSON stands in
+        // for Ruby's `Hash#to_s`.
+        other => other.to_json_string(),
+    }
+}
+
+/// `Ports::Query::InMemory#comparable`: reduces a value object one level, to its numeric member
+/// or its only member; anything else passes through unchanged.
+pub fn comparable(value: &Json) -> Json {
+    comparable_ref(value).clone()
+}
+
+/// `comparable` without the copy: the reduced value is always `value` itself or a member of it.
+pub fn comparable_ref(value: &Json) -> &Json {
+    let Json::Object(fields) = value else { return value };
+
+    if let Some((_, numeric)) = fields.iter().find(|(_, v)| matches!(v, Json::Num(_, _) | Json::Float(_))) {
+        return numeric;
+    }
+    if fields.len() == 1 {
+        return &fields[0].1;
+    }
+    value
+}
+
+/// Reads `in`'s argument or a `list_of` value as elements; other text is comma-separated.
+fn members(value: &Json) -> Vec<String> {
+    if let Json::Array(items) = value {
+        return items.iter().map(|item| to_s(&comparable(item))).collect();
+    }
+    to_s(value).split(',').map(|piece| piece.trim().to_string()).collect()
+}
+
+/// Element membership for a `list_of` field, substring match for anything else.
+fn contains(held: &Json, want: &Json) -> bool {
+    if matches!(held, Json::Array(_)) {
+        return members(held).iter().any(|member| member == &to_s(want));
+    }
+    to_s(held).contains(&to_s(want))
+}
+
+// `none_in_state_matches`, including the cross-domain search no real deployment exercises.
+#[cfg(test)]
+mod none_in_state_tests {
+    use super::{none_in_state_matches, Json};
+    use crate::kernel::AggregateScan;
+
+    /// Stand-in for a generated `Store`: scans by the domain-qualified aggregate name.
+    struct FakeStore {
+        domain: &'static str,
+        aggregates: Vec<(&'static str, Vec<(String, Json)>)>,
+    }
+
+    impl AggregateScan for FakeStore {
+        fn scan(&self, aggregate: &str) -> Option<Vec<(String, Json)>> {
+            let bare = aggregate.strip_prefix(&format!("{}::", self.domain))?;
+            self.aggregates.iter().find(|(name, _)| *name == bare).map(|(_, entries)| entries.clone())
+        }
+    }
+
+    /// A record whose `state` is a single-field value object, as in the real corpus fixture.
+    fn record_in_state(state: &str) -> Json {
+        Json::obj(vec![("state", Json::obj(vec![("value", Json::str(state))]))])
+    }
+
+    #[test]
+    fn with_no_domains_to_search_answers_vacuously_true() {
+        // Ruby's `return true unless registry`.
+        assert!(none_in_state_matches(&[], &Json::str("c1"), &Json::str("Claim:held")));
+    }
+
+    #[test]
+    fn excludes_a_row_whose_target_is_currently_in_the_named_state() {
+        let store = FakeStore { domain: "AntiJoinGrowth", aggregates: vec![("Claim", vec![("c1".into(), record_in_state("held"))])] };
+        let stores: Vec<(&str, &dyn AggregateScan)> = vec![("AntiJoinGrowth", &store)];
+        assert!(!none_in_state_matches(&stores, &Json::str("c1"), &Json::str("Claim:held")));
+    }
+
+    #[test]
+    fn keeps_a_row_whose_target_has_moved_out_of_the_named_state() {
+        let store = FakeStore { domain: "AntiJoinGrowth", aggregates: vec![("Claim", vec![("c2".into(), record_in_state("released"))])] };
+        let stores: Vec<(&str, &dyn AggregateScan)> = vec![("AntiJoinGrowth", &store)];
+        assert!(none_in_state_matches(&stores, &Json::str("c2"), &Json::str("Claim:held")));
+    }
+
+    #[test]
+    fn keeps_a_row_whose_target_was_never_filed_at_all() {
+        // No record reads the same as a record in another state.
+        let store = FakeStore { domain: "AntiJoinGrowth", aggregates: vec![("Claim", vec![])] };
+        let stores: Vec<(&str, &dyn AggregateScan)> = vec![("AntiJoinGrowth", &store)];
+        assert!(none_in_state_matches(&stores, &Json::str("nonexistent"), &Json::str("Claim:held")));
+    }
+
+    #[test]
+    fn keeps_every_row_when_no_domain_declares_the_named_aggregate_at_all() {
+        let store = FakeStore { domain: "AntiJoinGrowth", aggregates: vec![] };
+        let stores: Vec<(&str, &dyn AggregateScan)> = vec![("AntiJoinGrowth", &store)];
+        assert!(none_in_state_matches(&stores, &Json::str("c1"), &Json::str("NoSuchAggregate:held")));
+    }
+
+    #[test]
+    fn searches_a_second_domain_when_the_first_does_not_declare_the_aggregate() {
+        // Cross-domain search; no real deployment has this shape.
+        let domain_a = FakeStore { domain: "DomainA", aggregates: vec![("Widget", vec![])] };
+        let domain_b =
+            FakeStore { domain: "DomainB", aggregates: vec![("Claim", vec![("c1".into(), record_in_state("held"))])] };
+        let stores: Vec<(&str, &dyn AggregateScan)> = vec![("DomainA", &domain_a), ("DomainB", &domain_b)];
+        assert!(!none_in_state_matches(&stores, &Json::str("c1"), &Json::str("Claim:held")));
+    }
+
+    #[test]
+    fn first_match_wins_when_two_domains_declare_the_same_bare_aggregate_name() {
+        // Pins first-match-wins (Ruby's `find_aggregate_by_name`): DomainA's "held" must win
+        // over DomainB's "released".
+        let first = FakeStore { domain: "DomainA", aggregates: vec![("Claim", vec![("c1".into(), record_in_state("held"))])] };
+        let second =
+            FakeStore { domain: "DomainB", aggregates: vec![("Claim", vec![("c1".into(), record_in_state("released"))])] };
+        let stores: Vec<(&str, &dyn AggregateScan)> = vec![("DomainA", &first), ("DomainB", &second)];
+        assert!(!none_in_state_matches(&stores, &Json::str("c1"), &Json::str("Claim:held")));
+    }
+}

data/rust/src/kernel/query_ordering.rs

@@ -0,0 +1,103 @@
+// Shared order/offset/limit tail for declared queries and read models, mirroring Ruby's
+// `Ports::Query::Ordering.apply` so both callers sort and cap identically.
+use super::{query_comparators, Json};
+
+/// A declared `order_by :field, :direction`; `nulls` folds Ruby's separate `nulls` option in here.
+#[derive(Debug, Clone, Copy)]
+pub struct OrderBy {
+    pub field: &'static str,
+    pub descending: bool,
+    pub nulls: NullsMode,
+}
+
+/// Null placement for a declared order; an unrecognized mode reads as `Native`, as in Ruby.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum NullsMode {
+    Native,
+    First,
+    Last,
+}
+
+/// A declared `limit N`: a literal count, or a caller-bound arg resolved from the call's `args`.
+#[derive(Debug, Clone, Copy)]
+pub enum Limit {
+    Literal(i64),
+    Arg(&'static str),
+}
+
+/// A declared `offset N`; resolves exactly like `Limit`, so it shares the type.
+pub type Offset = Limit;
+
+/// Sorts by id, layers the declared order, then skips `offset` and caps at `limit`.
+///
+/// The id sort is unconditional so ties, or no declared order, still give a total order.
+/// Offset applies before limit, as in SQL `LIMIT n OFFSET m`.
+pub fn apply(
+    mut rows: Vec<(String, Json)>,
+    order_by: Option<&OrderBy>,
+    offset: Option<&Offset>,
+    limit: Option<&Limit>,
+    args: &Json,
+) -> Vec<(String, Json)> {
+    rows.sort_by(|a, b| a.0.cmp(&b.0));
+
+    if let Some(order_by) = order_by {
+        rows = apply_declared_order(rows, order_by);
+    }
+
+    if let Some(offset) = offset {
+        let n = resolve_limit(offset, args).min(rows.len());
+        rows.drain(0..n);
+    }
+
+    if let Some(limit) = limit {
+        rows.truncate(resolve_limit(limit, args));
+    }
+
+    rows
+}
+
+// `sort_by` is stable, so the id order from `apply` survives ties without an index tie-break.
+fn apply_declared_order(rows: Vec<(String, Json)>, order_by: &OrderBy) -> Vec<(String, Json)> {
+    let (mut null_rows, mut valued_rows): (Vec<(String, Json)>, Vec<(String, Json)>) =
+        rows.into_iter().partition(|(_, record)| order_key(record, order_by.field) == Json::Null);
+
+    valued_rows.sort_by(|(_, a), (_, b)| compare_comparable(&order_key(a, order_by.field), &order_key(b, order_by.field)));
+
+    if order_by.descending {
+        valued_rows.reverse();
+        null_rows.reverse();
+    }
+
+    match order_by.nulls {
+        NullsMode::First => null_rows.into_iter().chain(valued_rows).collect(),
+        NullsMode::Last => valued_rows.into_iter().chain(null_rows).collect(),
+        NullsMode::Native if !order_by.descending => null_rows.into_iter().chain(valued_rows).collect(),
+        NullsMode::Native => valued_rows.into_iter().chain(null_rows).collect(),
+    }
+}
+
+// Reduced like a where clause's held value; a missing field reads as `Json::Null`.
+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 {
+    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)
+        }
+        (Json::Str(x), Json::Str(y)) => x.cmp(y),
+        _ => std::cmp::Ordering::Equal,
+    }
+}
+
+// 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 {
+    let raw = match limit {
+        Limit::Literal(n) => *n,
+        Limit::Arg(name) => args.get(name).and_then(Json::as_i64).unwrap_or(0),
+    };
+    raw.max(0) as usize
+}