feat: add utc time and session helpers

Author: journeytosilius

README.md

@@ -33,6 +33,7 @@ The language keeps market-data inputs and execution venues explicit:
 - `source` declares market data feeds
 - `execution` declares order-routing venues
 - `order ...` declares how entries and exits are placed
+- `hour_utc(<alias>.time)`, `weekday_utc(<alias>.time)`, and `session_utc(<alias>.time, start_hour, end_hour)` provide deterministic UTC time/session gating without hand-rolled timestamp math
 
 Documentation and tooling:
 

crates/palmscript/examples/README.md

@@ -60,6 +60,12 @@ For runnable public examples and workflow guidance, use the linked docs pages ab
 
 When you inspect these strategies from the CLI, `run backtest`, `run walk-forward`, and `run optimize` now support `--diagnostics summary|full-trace`. Use `summary` for the normal compact diagnostics payload and `full-trace` when you want one typed per-bar decision trace record per execution bar.
 
+Use `hour_utc(<alias>.time)`, `weekday_utc(<alias>.time)`, and
+`session_utc(<alias>.time, start_hour, end_hour)` when you want deterministic
+UTC session filters without manual millisecond arithmetic. `session_utc` treats
+its window as half-open `[start_hour, end_hour)` and supports overnight wraps
+such as `session_utc(spot.time, 22, 2)`.
+
 Execution-oriented commands now require at least one declared `execution`
 target in the script. The checked-in backtest and paper examples already
 declare those execution aliases explicitly. If a script declares exactly one

crates/palmscript/src/backtest/diagnostics/analysis.rs

@@ -11,6 +11,7 @@ use crate::backtest::{
     TradeExitClassification, TransferDiagnosticsSummary, TransferRouteDiagnosticSummary,
     WeekdayDiagnosticSummary,
 };
+use crate::interval::{hour_utc, weekday_utc};
 use crate::position::PositionSide;
 
 const TIME_BUCKET_HOURS_UTC: u8 = 4;
@@ -821,12 +822,3 @@ fn holding_time_bucket(bars_held: usize) -> HoldingTimeBucket {
         _ => HoldingTimeBucket::Bars32Plus,
     }
 }
-
-fn weekday_utc(time_ms: i64) -> u8 {
-    let days = time_ms.div_euclid(86_400_000);
-    ((days + 3).rem_euclid(7)) as u8
-}
-
-fn hour_utc(time_ms: i64) -> u8 {
-    time_ms.rem_euclid(86_400_000).div_euclid(3_600_000) as u8
-}

crates/palmscript/src/builtins.rs

@@ -84,6 +84,8 @@ pub enum BuiltinKind {
     ParabolicSarExt,
     RollingHighLowCloseBands,
     AdaptiveCycleTuple,
+    TimeTransform,
+    TimeSession,
     VenueAliasSelector,
     VenueRank,
     VenueSpread,
@@ -238,10 +240,13 @@ pub enum BuiltinId {
     SpreadBps = 143,
     RankAsc = 144,
     RankDesc = 145,
+    HourUtc = 146,
+    WeekdayUtc = 147,
+    SessionUtc = 148,
 }
 
 impl BuiltinId {
-    pub const RESERVED: [Self; 146] = [
+    pub const RESERVED: [Self; 149] = [
         Self::Open,
         Self::High,
         Self::Low,
@@ -388,9 +393,12 @@ impl BuiltinId {
         Self::SpreadBps,
         Self::RankAsc,
         Self::RankDesc,
+        Self::HourUtc,
+        Self::WeekdayUtc,
+        Self::SessionUtc,
     ];
 
-    pub const CALLABLE: [Self; 133] = [
+    pub const CALLABLE: [Self; 136] = [
         Self::Sma,
         Self::Ema,
         Self::Rsi,
@@ -524,6 +532,9 @@ impl BuiltinId {
         Self::SpreadBps,
         Self::RankAsc,
         Self::RankDesc,
+        Self::HourUtc,
+        Self::WeekdayUtc,
+        Self::SessionUtc,
     ];
 
     pub fn from_name(name: &str) -> Option<Self> {
@@ -674,6 +685,9 @@ impl BuiltinId {
             "spread_bps" => Some(Self::SpreadBps),
             "rank_asc" => Some(Self::RankAsc),
             "rank_desc" => Some(Self::RankDesc),
+            "hour_utc" => Some(Self::HourUtc),
+            "weekday_utc" => Some(Self::WeekdayUtc),
+            "session_utc" => Some(Self::SessionUtc),
             _ => None,
         }
     }
@@ -826,6 +840,9 @@ impl BuiltinId {
             143 => Some(Self::SpreadBps),
             144 => Some(Self::RankAsc),
             145 => Some(Self::RankDesc),
+            146 => Some(Self::HourUtc),
+            147 => Some(Self::WeekdayUtc),
+            148 => Some(Self::SessionUtc),
             _ => None,
         }
     }
@@ -978,6 +995,9 @@ impl BuiltinId {
             Self::SpreadBps => "spread_bps",
             Self::RankAsc => "rank_asc",
             Self::RankDesc => "rank_desc",
+            Self::HourUtc => "hour_utc",
+            Self::WeekdayUtc => "weekday_utc",
+            Self::SessionUtc => "session_utc",
         }
     }
 
@@ -1090,6 +1110,8 @@ impl BuiltinId {
             }
             Self::HtPhasor | Self::HtSine => BuiltinKind::RollingSingleInputTuple,
             Self::Mama => BuiltinKind::AdaptiveCycleTuple,
+            Self::HourUtc | Self::WeekdayUtc => BuiltinKind::TimeTransform,
+            Self::SessionUtc => BuiltinKind::TimeSession,
             Self::Cheapest | Self::Richest => BuiltinKind::VenueAliasSelector,
             Self::RankAsc | Self::RankDesc => BuiltinKind::VenueRank,
             Self::SpreadBps => BuiltinKind::VenueSpread,
@@ -1237,6 +1259,8 @@ impl BuiltinId {
             Self::Cheapest | Self::Richest => BuiltinArity::AtLeast(2),
             Self::RankAsc | Self::RankDesc => BuiltinArity::AtLeast(3),
             Self::SpreadBps => BuiltinArity::Exact(2),
+            Self::HourUtc | Self::WeekdayUtc => BuiltinArity::Exact(1),
+            Self::SessionUtc => BuiltinArity::Exact(3),
         }
     }
 
@@ -1333,6 +1357,9 @@ impl BuiltinId {
             Self::SpreadBps => "spread_bps(buy_exec, sell_exec)",
             Self::RankAsc => "rank_asc(target_exec, exec0, exec1[, execN...])",
             Self::RankDesc => "rank_desc(target_exec, exec0, exec1[, execN...])",
+            Self::HourUtc => "hour_utc(time_value)",
+            Self::WeekdayUtc => "weekday_utc(time_value)",
+            Self::SessionUtc => "session_utc(time_value, start_hour, end_hour)",
             Self::Ma => "ma(series, length, ma_type)",
             Self::Apo => "apo(series[, fast_length=12[, slow_length=26[, ma_type=ma_type.sma]]])",
             Self::Ppo => "ppo(series[, fast_length=12[, slow_length=26[, ma_type=ma_type.sma]]])",
@@ -1545,6 +1572,9 @@ impl BuiltinId {
             Self::SpreadBps => "Return the current cross-venue spread in basis points from buy execution close to sell execution close.",
             Self::RankAsc => "Return the 1-based ascending price rank of a declared execution alias within the provided venue set.",
             Self::RankDesc => "Return the 1-based descending price rank of a declared execution alias within the provided venue set.",
+            Self::HourUtc => "Return the UTC hour-of-day (0..23) for the provided timestamp input.",
+            Self::WeekdayUtc => "Return the UTC weekday (Monday=0 .. Sunday=6) for the provided timestamp input.",
+            Self::SessionUtc => "True when the provided UTC timestamp falls inside the half-open session window [start_hour, end_hour), with overnight wrap support.",
         }
     }
 }

crates/palmscript/src/compiler.rs

@@ -5729,6 +5729,63 @@ fn analyze_helper_builtin(
                     .fold(0, |mask, info| mask | info.update_mask),
             }
         }
+        BuiltinKind::TimeTransform => {
+            let time_info = arg_info[0];
+            if !time_info.ty.is_numeric_like() {
+                diagnostics.push(Diagnostic::new(
+                    DiagnosticKind::Type,
+                    format!("{callee} requires a numeric or series numeric timestamp input"),
+                    args[0].span,
+                ));
+            }
+            numeric_result(arg_info)
+        }
+        BuiltinKind::TimeSession => {
+            if !arg_info[0].ty.is_numeric_like() {
+                diagnostics.push(Diagnostic::new(
+                    DiagnosticKind::Type,
+                    format!(
+                        "{callee} requires a numeric or series numeric timestamp input as the first argument"
+                    ),
+                    args[0].span,
+                ));
+            }
+            for (index, (arg, info)) in args.iter().zip(arg_info.iter()).enumerate().skip(1) {
+                if !matches!(
+                    info.ty,
+                    InferredType::Concrete(Type::F64) | InferredType::Na
+                ) {
+                    diagnostics.push(Diagnostic::new(
+                        DiagnosticKind::Type,
+                        if index == 1 {
+                            format!(
+                                "{callee} requires a numeric UTC start hour as the second argument"
+                            )
+                        } else {
+                            format!(
+                                "{callee} requires a numeric UTC end hour as the third argument"
+                            )
+                        },
+                        arg.span,
+                    ));
+                }
+            }
+            validate_session_hour_literal(
+                callee,
+                "start hour",
+                &args[1],
+                immutable_values,
+                diagnostics,
+            );
+            validate_session_hour_literal(
+                callee,
+                "end hour",
+                &args[2],
+                immutable_values,
+                diagnostics,
+            );
+            bool_result(arg_info)
+        }
         BuiltinKind::Plot | BuiltinKind::MarketSeries => unreachable!(),
     }
 }
@@ -5818,6 +5875,8 @@ fn fallback_expr_info_for_builtin(builtin: BuiltinId, arg_info: &[ExprInfo]) ->
         | BuiltinKind::VolumeIndicator
         | BuiltinKind::AnchoredPriceVolume
         | BuiltinKind::VolatilityIndicator => ExprInfo::series(0),
+        BuiltinKind::TimeTransform => numeric_result(arg_info),
+        BuiltinKind::TimeSession => bool_result(arg_info),
         BuiltinKind::VenueAliasSelector => ExprInfo::scalar(Type::ExecutionAlias),
         BuiltinKind::VenueRank => ExprInfo::scalar(Type::F64),
         BuiltinKind::VenueSpread => ExprInfo::scalar(Type::F64),
@@ -6351,6 +6410,25 @@ fn validate_non_negative_literal(
     }
 }
 
+fn validate_session_hour_literal(
+    callee: &str,
+    noun: &str,
+    expr: &Expr,
+    immutable_values: &HashMap<String, Value>,
+    diagnostics: &mut Vec<Diagnostic>,
+) {
+    let Some(value) = literal_time_component(expr, immutable_values) else {
+        return;
+    };
+    if !(0.0..=24.0).contains(&value) || value.fract() != 0.0 {
+        diagnostics.push(Diagnostic::new(
+            DiagnosticKind::Type,
+            format!("{callee} {noun} must be an integer literal in the range 0..24"),
+            expr.span,
+        ));
+    }
+}
+
 fn expected_arity_message(callee: &str, arity: BuiltinArity) -> String {
     match arity {
         BuiltinArity::NonCallable => format!("{callee} is not callable"),
@@ -6402,6 +6480,17 @@ fn literal_window(expr: &Expr, immutable_values: &HashMap<String, Value>) -> Opt
     }
 }
 
+fn literal_time_component(expr: &Expr, immutable_values: &HashMap<String, Value>) -> Option<f64> {
+    match &expr.kind {
+        ExprKind::Number(value) => Some(*value),
+        ExprKind::Ident(name) => match immutable_values.get(name) {
+            Some(Value::F64(value)) => Some(*value),
+            _ => None,
+        },
+        _ => None,
+    }
+}
+
 fn literal_ma_type(expr: &Expr, immutable_values: &HashMap<String, Value>) -> Option<MaType> {
     match &expr.kind {
         ExprKind::Ident(name) => match immutable_values.get(name) {
@@ -7550,7 +7639,10 @@ impl<'a> Compiler<'a> {
             | BuiltinId::HtSine
             | BuiltinId::HtTrendline
             | BuiltinId::HtTrendmode
-            | BuiltinId::Mama => {
+            | BuiltinId::Mama
+            | BuiltinId::HourUtc
+            | BuiltinId::WeekdayUtc
+            | BuiltinId::SessionUtc => {
                 self.emit_runtime_builtin_call(
                     builtin, expr, args, expr_info, user_calls, callsite,
                 );
@@ -8778,7 +8870,11 @@ impl<'a> Compiler<'a> {
                         .with_span(expr.span),
                 );
             }
-            BuiltinKind::VenueAliasSelector | BuiltinKind::VenueRank | BuiltinKind::VenueSpread => {
+            BuiltinKind::VenueAliasSelector
+            | BuiltinKind::VenueRank
+            | BuiltinKind::VenueSpread
+            | BuiltinKind::TimeTransform
+            | BuiltinKind::TimeSession => {
                 for arg in args {
                     self.emit_expr(arg, expr_info, user_calls);
                 }

crates/palmscript/src/interval.rs

@@ -492,6 +492,28 @@ fn weekday_monday_based(days_since_epoch: i64) -> i64 {
     (days_since_epoch + 3).rem_euclid(7)
 }
 
+pub(crate) fn weekday_utc(time_ms: i64) -> u8 {
+    let (days_since_epoch, _) = split_days(time_ms);
+    weekday_monday_based(days_since_epoch) as u8
+}
+
+pub(crate) fn hour_utc(time_ms: i64) -> u8 {
+    let (_, remainder) = split_days(time_ms);
+    remainder.div_euclid(3_600_000) as u8
+}
+
+pub(crate) fn session_utc(time_ms: i64, start_hour: u8, end_hour: u8) -> bool {
+    if start_hour == end_hour {
+        return true;
+    }
+    let hour = hour_utc(time_ms);
+    if start_hour < end_hour {
+        hour >= start_hour && hour < end_hour
+    } else {
+        hour >= start_hour || hour < end_hour
+    }
+}
+
 fn civil_from_days(days_since_epoch: i64) -> (i32, u8, u8) {
     let z = days_since_epoch + 719_468;
     let era = if z >= 0 { z } else { z - 146_096 }.div_euclid(146_097);
@@ -519,7 +541,11 @@ fn days_from_civil(year: i32, month: u8, day: u8) -> i64 {
 
 #[cfg(test)]
 mod tests {
-    use super::{Interval, MarketField, SourceTemplate};
+    use super::{hour_utc, session_utc, weekday_utc, Interval, MarketField, SourceTemplate};
+
+    const JAN_1_2024_UTC_MS: i64 = 1_704_067_200_000;
+    const HOUR_MS: i64 = 3_600_000;
+    const DAY_MS: i64 = 24 * HOUR_MS;
 
     #[test]
     fn parses_all_supported_intervals() {
@@ -640,4 +666,22 @@ mod tests {
             Some(1_706_745_600_000)
         );
     }
+
+    #[test]
+    fn utc_time_helpers_extract_expected_components() {
+        assert_eq!(weekday_utc(JAN_1_2024_UTC_MS), 0);
+        assert_eq!(weekday_utc(JAN_1_2024_UTC_MS + DAY_MS), 1);
+        assert_eq!(hour_utc(JAN_1_2024_UTC_MS), 0);
+        assert_eq!(hour_utc(JAN_1_2024_UTC_MS + 23 * HOUR_MS), 23);
+    }
+
+    #[test]
+    fn utc_session_helper_supports_wrapped_windows() {
+        assert!(session_utc(JAN_1_2024_UTC_MS + 4 * HOUR_MS, 4, 8));
+        assert!(!session_utc(JAN_1_2024_UTC_MS + 8 * HOUR_MS, 4, 8));
+        assert!(session_utc(JAN_1_2024_UTC_MS + 23 * HOUR_MS, 22, 2));
+        assert!(session_utc(JAN_1_2024_UTC_MS + DAY_MS, 22, 2));
+        assert!(!session_utc(JAN_1_2024_UTC_MS + 21 * HOUR_MS, 22, 2));
+        assert!(session_utc(JAN_1_2024_UTC_MS, 0, 0));
+    }
 }