fv-streams-sql 0.9.0

The SQL front door for FusionVault Streams: a streaming SQL statement parses to a small typed logical plan and lowers to the same topology the TOML frontend produces — one runtime, two front doors. No DataFusion planner, no fork; expressions compile through the value dialect as the steps already do.
Documentation
//! The `EMIT CHANGES EVERY <n> ROWS|MS` clause: split off the statement, parsed, and attached to the
//! windowed aggregate.

use super::{Plan, Trigger, Win};

/// Strip a trailing `EMIT CHANGES EVERY <n> ROWS|MS` clause (case-insensitive, outside string
/// literals). Returns the SQL without it and the parsed trigger, if any.
pub(super) fn split_emit(sql: &str) -> Result<(String, Option<Trigger>), String> {
    let lower = sql.to_ascii_lowercase();
    let bytes = lower.as_bytes();
    let is_word = |b: u8| b.is_ascii_alphanumeric() || b == b'_';
    let mut in_str = false;
    let mut at = None;
    let mut i = 0usize;
    while i < bytes.len() {
        if bytes[i] == b'\'' {
            in_str = !in_str;
            i += 1;
            continue;
        }
        if !in_str
            && lower[i..].starts_with("emit")
            && (i == 0 || !is_word(bytes[i - 1]))
            && (i + 4 >= bytes.len() || !is_word(bytes[i + 4]))
        {
            at = Some(i); // the last unquoted `emit` wins (it is a trailing clause)
        }
        i += 1;
    }
    let Some(at) = at else {
        return Ok((sql.to_string(), None));
    };
    let head = sql[..at].trim_end().to_string();
    let trigger = parse_emit(&sql[at..])?;
    Ok((head, Some(trigger)))
}

fn parse_emit(clause: &str) -> Result<Trigger, String> {
    let toks: Vec<String> = clause.split_whitespace().map(|s| s.to_ascii_lowercase()).collect();
    let shape = "`EMIT CHANGES EVERY <n> ROWS` or `EMIT CHANGES EVERY <n> MS`";
    if toks.len() < 2 || toks[0] != "emit" || toks[1] != "changes" {
        return Err(format!("unrecognised EMIT clause — use {shape}"));
    }
    if toks.len() == 2 {
        return Err(format!("`EMIT CHANGES` needs a cadence: {shape}"));
    }
    if toks.len() != 5 || toks[2] != "every" {
        return Err(format!("EMIT clause: expected {shape}"));
    }
    let n: u64 = toks[3]
        .parse()
        .map_err(|_| format!("EMIT cadence `{}` is not a whole number", toks[3]))?;
    match toks[4].as_str() {
        "rows" | "row" => Ok(Trigger::EveryRows(n)),
        "ms" | "milliseconds" | "millisecond" => Ok(Trigger::EveryMs(n as i64)),
        other => Err(format!("EMIT cadence unit `{other}` — use ROWS or MS")),
    }
}

/// Attach a trigger to the plan's windowed aggregate (the 5a updating aggregate). The trigger is
/// valid only on a windowed (`TUMBLE`/`HOP`) aggregate — the operator that early-fires.
pub(super) fn attach_trigger(plan: Plan, trigger: Trigger) -> Result<Plan, String> {
    match plan {
        Plan::Sink { input, name } => Ok(Plan::Sink {
            input: Box::new(attach_trigger(*input, trigger)?),
            name,
        }),
        Plan::Aggregate {
            input,
            time_column,
            window,
            group_by,
            pre,
            aggs,
            post,
            having,
            trigger: _,
        } => {
            if matches!(window, Win::Session { .. }) {
                return Err("EMIT CHANGES is supported on windowed aggregates (TUMBLE / HOP), not sessions".into());
            }
            Ok(Plan::Aggregate {
                input,
                time_column,
                window,
                group_by,
                pre,
                aggs,
                post,
                having,
                trigger: Some(trigger),
            })
        }
        _ => Err("EMIT CHANGES needs a windowed GROUP BY aggregate (`GROUP BY <keys>, TUMBLE(ts, INTERVAL …)`)".into()),
    }
}