polydat_nodes/

param_helpers.rs

// Copyright 2024-2026 Jonathan Shook
// SPDX-License-Identifier: Apache-2.0

//! Parameter resolution and validation helpers (library_catalog.md,
//! "Parameter resolution and validation").
//!
//! These nodes are pass-throughs with assertions on the value they
//! carry. They let workloads say "this parameter must be defined",
//! "this number must be in range", "this string must match a
//! pattern" — with the assertion fired at the earliest point the
//! value is known. For compile-time-constant inputs, constant
//! folding collapses the assertion into a hard compile error. For
//! init-time-resolved workload params, the assertion fires on the
//! first evaluation (effectively init). For live-read inputs, the
//! assertion fires per cycle.
//!
//! Failure is reported via panic with a descriptive message. Panics
//! inside `eval` surface as workload startup errors for init-time
//! values and as cycle-time aborts for live-read inputs; both are
//! the intended consequence of a violated precondition.

use regex::Regex;

// =========================================================================
// required(input) — assert non-None, pass through
// =========================================================================

/// Assert that an input is defined (i.e. not `Value::None`).
///
/// Signature: `required(input: u64) -> u64`. The `Option<u64>`
/// wire shape opts the node into kernel-Rule-1 bypass (the macro
/// auto-emits `accepts_none_inputs() -> true` when any arg is
/// `Option<_>`); the body's `unwrap_or_else` is what actually
/// fires the diagnostic.
#[polydat::polydat_node(category = Arithmetic)]
fn required(
    input: Option<u64>,
    #[poly_default("value")] name: polydat::derive_support::Const<&str>,
) -> u64 {
    input.unwrap_or_else(|| panic!("required({}): value was not defined", name.0))
}

// =========================================================================
// this_or(primary, default) — first if defined else second
// =========================================================================

/// Return `primary` if it is defined, otherwise `default`.
///
/// Signature: `this_or(primary: Option<u64>, default: u64) -> u64`.
/// The typed-coalesce equivalent of `default_or` — `None` on
/// `primary` triggers the fallback. `Option<u64>` opts into
/// None-tolerance via the macro's auto-emitted
/// `accepts_none_inputs`.
#[polydat::polydat_node(category = Arithmetic)]
fn this_or(primary: Option<u64>, default: u64) -> u64 {
    primary.unwrap_or(default)
}

// =========================================================================
// is_positive(input) — assert > 0, pass through
// =========================================================================

/// Assert that a u64 value is strictly positive (> 0).
///
/// Signature: `is_positive(input: u64) -> u64`
#[polydat::polydat_node(category = Arithmetic)]
fn is_positive(
    input: u64,
    #[poly_default("value")] name: polydat::derive_support::Const<&str>,
) -> u64 {
    if input == 0 {
        panic!("is_positive({}): value must be > 0, got 0", name.0);
    }
    input
}

// =========================================================================
// in_range(input, lo, hi) — assert lo ≤ input ≤ hi, pass through
// =========================================================================

/// Assert that a u64 value is in the inclusive range `[lo, hi]`.
///
/// Signature: `in_range(input: u64, lo: u64, hi: u64) -> u64`
#[polydat::polydat_node(category = Arithmetic, validate = in_range_validate)]
fn in_range(
    input: u64,
    #[poly_default(0u64)] lo: polydat::derive_support::Const<u64>,
    #[poly_default(u64::MAX)] hi: polydat::derive_support::Const<u64>,
) -> u64 {
    if input < *lo || input > *hi {
        panic!("in_range: value {input} outside [{}, {}]", *lo, *hi);
    }
    input
}

/// `in_range`'s relation between its two bounds. Node-level because
/// no per-parameter constraint can compare two parameters.
fn in_range_validate(
    _name: &str,
    consts: &[polydat::dsl::factory::ConstArg],
) -> Result<(), String> {
    let lo = consts.first().map(|c| c.as_u64()).unwrap_or(0);
    let hi = consts.get(1).map(|c| c.as_u64()).unwrap_or(u64::MAX);
    if lo > hi {
        return Err(format!("lo ({lo}) must be <= hi ({hi})"));
    }
    Ok(())
}

// =========================================================================
// is_one_of(input, ...allowed) — assert input ∈ {allowed}, pass through
// =========================================================================

/// Assert that a u64 value is one of an enumerated allow-list.
/// Authored with the `Const<Vec<C>>` combinator and lowered through its slot kit (called from native code);
/// `classify_node` returns Fallback for it because a
/// `Const<Vec<u64>>` node publishes no `jit_constants`, so the
/// `JitOp::IsOneOfCheck` arm never fires.
#[polydat::polydat_node(category = Arithmetic, validate = is_one_of_validate)]
fn is_one_of(input: u64, allowed: polydat::derive_support::Const<&[u64]>) -> u64 {
    if !allowed.contains(&input) {
        panic!(
            "is_one_of: value {input} not in allowed set {:?}",
            allowed.0
        );
    }
    input
}

/// `is_one_of`'s allow-list must name at least one value. A list's
/// arity is a property of the whole argument rather than of any one
/// element, so it is stated at the node.
fn is_one_of_validate(
    _name: &str,
    consts: &[polydat::dsl::factory::ConstArg],
) -> Result<(), String> {
    if consts.is_empty() {
        return Err("at least one allowed value required".into());
    }
    Ok(())
}

// =========================================================================
// matches(input, pattern) — assert regex match, pass through
// =========================================================================

/// Build a Regex from a pattern, panicking on invalid input.
fn compile_matches_regex(pattern: &str) -> Regex {
    Regex::new(pattern).unwrap_or_else(|e| panic!("matches: invalid regex {pattern:?}: {e}"))
}

/// Assert that a string value matches a regex pattern.
#[polydat::polydat_node(category = Arithmetic)]
fn matches(
    input: &str,
    pattern: polydat::derive_support::Const<&str>,
    #[poly_const(compile_matches_regex, from = pattern)] re: &Regex,
) -> String {
    if !re.is_match(input) {
        panic!(
            "matches: value {input:?} does not match pattern {:?}",
            pattern.0
        );
    }
    input.to_string()
}

#[cfg(test)]
mod tests {
    use super::*;
    use polydat::ast::{PolydatNode, Value};

    #[test]
    fn required_passes_defined_value() {
        let n = Required::new("x".to_string());
        let mut out = [Value::None];
        n.eval(&[Value::U64(42)], &mut out);
        assert_eq!(out[0].as_u64(), 42);
    }

    #[test]
    #[should_panic(expected = "required(x): value was not defined")]
    fn required_panics_on_none() {
        let n = Required::new("x".to_string());
        let mut out = [Value::None];
        n.eval(&[Value::None], &mut out);
    }

    #[test]
    fn this_or_prefers_primary_when_defined() {
        let n = ThisOr::new();
        let mut out = [Value::None];
        n.eval(&[Value::U64(7), Value::U64(99)], &mut out);
        assert_eq!(out[0].as_u64(), 7);
    }

    #[test]
    fn this_or_falls_back_to_default_on_none() {
        let n = ThisOr::new();
        let mut out = [Value::None];
        n.eval(&[Value::None, Value::U64(99)], &mut out);
        assert_eq!(out[0].as_u64(), 99);
    }

    #[test]
    fn is_positive_passes_positive() {
        let n = IsPositive::new("rate".to_string());
        let mut out = [Value::None];
        n.eval(&[Value::U64(1)], &mut out);
        assert_eq!(out[0].as_u64(), 1);
    }

    #[test]
    #[should_panic(expected = "is_positive(rate)")]
    fn is_positive_panics_on_zero() {
        let n = IsPositive::new("rate".to_string());
        let mut out = [Value::None];
        n.eval(&[Value::U64(0)], &mut out);
    }

    #[test]
    fn in_range_passes_interior() {
        let n = InRange::new(10, 100);
        let mut out = [Value::None];
        n.eval(&[Value::U64(50)], &mut out);
        assert_eq!(out[0].as_u64(), 50);
        n.eval(&[Value::U64(10)], &mut out);
        assert_eq!(out[0].as_u64(), 10);
        n.eval(&[Value::U64(100)], &mut out);
        assert_eq!(out[0].as_u64(), 100);
    }

    #[test]
    #[should_panic(expected = "outside [10, 100]")]
    fn in_range_panics_below() {
        let n = InRange::new(10, 100);
        let mut out = [Value::None];
        n.eval(&[Value::U64(5)], &mut out);
    }

    #[test]
    #[should_panic(expected = "outside [10, 100]")]
    fn in_range_panics_above() {
        let n = InRange::new(10, 100);
        let mut out = [Value::None];
        n.eval(&[Value::U64(101)], &mut out);
    }

    #[test]
    fn is_one_of_passes_allowed() {
        let n = IsOneOf::new(vec![1, 2, 3, 5, 8]);
        let mut out = [Value::None];
        n.eval(&[Value::U64(5)], &mut out);
        assert_eq!(out[0].as_u64(), 5);
    }

    #[test]
    #[should_panic(expected = "not in allowed set")]
    fn is_one_of_panics_on_disallowed() {
        let n = IsOneOf::new(vec![1, 2, 3]);
        let mut out = [Value::None];
        n.eval(&[Value::U64(4)], &mut out);
    }

    #[test]
    fn matches_passes_matching_string() {
        let n = Matches::new(r"^\w+@\w+\.\w+$".to_string());
        let mut out = [Value::None];
        n.eval(&[Value::Str("jshook@example.com".into())], &mut out);
        assert_eq!(out[0].as_str(), "jshook@example.com");
    }

    #[test]
    #[should_panic(expected = "does not match pattern")]
    fn matches_panics_on_mismatch() {
        let n = Matches::new(r"^\d+$".to_string());
        let mut out = [Value::None];
        n.eval(&[Value::Str("abc".into())], &mut out);
    }
}