use std::{
cmp::Ordering,
collections::{BTreeMap, BTreeSet},
fmt,
sync::Arc,
};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use crate::{
ComparisonExtensionMetadata, PrimitiveValue, TemporalAxis, TemporalPoint, WindowHistory,
WindowSegment, WindowTag,
};
mod rows;
use rows::RowAccumulator;
pub use rows::*;
mod comparators;
use comparators::*;
mod finality;
use finality::*;
#[non_exhaustive]
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum Comparator {
Overlap,
Residual,
Missing,
Coverage,
Gap,
SymmetricDifference,
Containment,
LeadLag {
transition: LeadLagTransition,
axis: TemporalAxis,
tolerance_magnitude: i64,
},
AsOf {
direction: AsOfDirection,
axis: TemporalAxis,
tolerance_magnitude: i64,
},
}
impl Comparator {
pub fn parse(value: &str) -> Option<Self> {
Self::parse_result(value).ok()
}
pub fn parse_result(value: &str) -> Result<Self, ComparatorParseError> {
match value {
"overlap" => Ok(Self::Overlap),
"residual" => Ok(Self::Residual),
"missing" => Ok(Self::Missing),
"coverage" => Ok(Self::Coverage),
"gap" => Ok(Self::Gap),
"symmetric-difference" => Ok(Self::SymmetricDifference),
"containment" => Ok(Self::Containment),
_ => parse_parameterized_comparator(value)
.ok_or_else(|| ComparatorParseError(value.to_owned())),
}
}
#[must_use]
pub fn declaration(&self) -> String {
match self {
Self::Overlap => "overlap".to_owned(),
Self::Residual => "residual".to_owned(),
Self::Missing => "missing".to_owned(),
Self::Coverage => "coverage".to_owned(),
Self::Gap => "gap".to_owned(),
Self::SymmetricDifference => "symmetric-difference".to_owned(),
Self::Containment => "containment".to_owned(),
Self::LeadLag {
transition,
axis,
tolerance_magnitude,
} => {
format!(
"lead-lag:{}:{}:{tolerance_magnitude}",
lead_lag_transition_name(transition),
temporal_axis_name(*axis)
)
}
Self::AsOf {
direction,
axis,
tolerance_magnitude,
} => format!(
"asof:{}:{}:{tolerance_magnitude}",
as_of_direction_name(direction),
temporal_axis_name(*axis)
),
}
}
}
#[derive(Clone, Debug, Eq, thiserror::Error, PartialEq)]
#[error("unsupported comparator declaration '{0}'")]
pub struct ComparatorParseError(String);
fn temporal_axis_name(axis: TemporalAxis) -> &'static str {
match axis {
TemporalAxis::ProcessingPosition => "position",
TemporalAxis::Timestamp => "timestamp",
}
}
fn lead_lag_transition_name(transition: &LeadLagTransition) -> &'static str {
match transition {
LeadLagTransition::Start => "start",
LeadLagTransition::End => "end",
}
}
fn as_of_direction_name(direction: &AsOfDirection) -> &'static str {
match direction {
AsOfDirection::Previous => "previous",
AsOfDirection::Next => "next",
AsOfDirection::Nearest => "nearest",
}
}
#[non_exhaustive]
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum AgainstSelection {
Sources(Vec<String>),
Cohort {
name: String,
sources: Vec<String>,
activity: CohortActivity,
},
}
type SelectorPredicate = Arc<dyn Fn(&crate::WindowRecord) -> bool + Send + Sync>;
#[derive(Clone)]
enum ComparisonSelectorKind {
Any,
WindowName(String),
Key(String),
Source(String),
Sources(Vec<String>),
Partition(String),
PositionRange {
start_inclusive: i64,
end_exclusive: Option<i64>,
},
TimeRange {
start_inclusive: i64,
end_exclusive: Option<i64>,
},
Runtime(SelectorPredicate),
And(Box<ComparisonSelectorKind>, Box<ComparisonSelectorKind>),
Or(Box<ComparisonSelectorKind>, Box<ComparisonSelectorKind>),
}
impl fmt::Debug for ComparisonSelectorKind {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Any => formatter.write_str("Any"),
Self::WindowName(value) => formatter.debug_tuple("WindowName").field(value).finish(),
Self::Key(value) => formatter.debug_tuple("Key").field(value).finish(),
Self::Source(value) => formatter.debug_tuple("Source").field(value).finish(),
Self::Sources(value) => formatter.debug_tuple("Sources").field(value).finish(),
Self::Partition(value) => formatter.debug_tuple("Partition").field(value).finish(),
Self::PositionRange {
start_inclusive,
end_exclusive,
} => formatter
.debug_struct("PositionRange")
.field("start_inclusive", start_inclusive)
.field("end_exclusive", end_exclusive)
.finish(),
Self::TimeRange {
start_inclusive,
end_exclusive,
} => formatter
.debug_struct("TimeRange")
.field("start_inclusive", start_inclusive)
.field("end_exclusive", end_exclusive)
.finish(),
Self::Runtime(_) => formatter.write_str("Runtime(<predicate>)"),
Self::And(left, right) => formatter
.debug_tuple("And")
.field(left)
.field(right)
.finish(),
Self::Or(left, right) => formatter
.debug_tuple("Or")
.field(left)
.field(right)
.finish(),
}
}
}
impl ComparisonSelectorKind {
fn matches(&self, window: &crate::WindowRecord) -> bool {
match self {
Self::Any => true,
Self::WindowName(window_name) => window.window_name() == window_name,
Self::Key(key) => window.key() == key,
Self::Source(source) => window.source() == Some(source.as_str()),
Self::Sources(sources) => sources
.iter()
.any(|source| window.source() == Some(source.as_str())),
Self::Partition(partition) => window.partition() == Some(partition.as_str()),
Self::PositionRange {
start_inclusive,
end_exclusive,
} => {
let start = window.start();
start.axis() == TemporalAxis::ProcessingPosition
&& start.magnitude() >= *start_inclusive
&& end_exclusive.is_none_or(|end| start.magnitude() < end)
}
Self::TimeRange {
start_inclusive,
end_exclusive,
} => {
let start = window.start();
start.axis() == TemporalAxis::Timestamp
&& start.magnitude() >= *start_inclusive
&& end_exclusive.is_none_or(|end| start.magnitude() < end)
}
Self::Runtime(predicate) => predicate(window),
Self::And(left, right) => left.matches(window) && right.matches(window),
Self::Or(left, right) => left.matches(window) || right.matches(window),
}
}
}
#[derive(Clone, Debug)]
pub struct ComparisonSelector {
pub(crate) name: String,
pub description: String,
pub is_serializable: bool,
pub cohort_activity: Option<CohortActivity>,
pub cohort_sources: Vec<String>,
kind: ComparisonSelectorKind,
}
impl PartialEq for ComparisonSelector {
fn eq(&self, other: &Self) -> bool {
self.name == other.name
&& self.description == other.description
&& self.is_serializable == other.is_serializable
&& self.cohort_activity == other.cohort_activity
&& self.cohort_sources == other.cohort_sources
}
}
impl ComparisonSelector {
#[must_use]
pub fn serializable(name: impl Into<String>, description: impl Into<String>) -> Self {
Self {
name: name.into(),
description: description.into(),
is_serializable: true,
cohort_activity: None,
cohort_sources: Vec::new(),
kind: ComparisonSelectorKind::Any,
}
}
#[must_use]
pub fn for_window_name(window_name: impl Into<String>) -> Self {
let window_name = window_name.into();
Self {
name: format!("window:{window_name}"),
description: format!("window name = {window_name}"),
is_serializable: true,
cohort_activity: None,
cohort_sources: Vec::new(),
kind: ComparisonSelectorKind::WindowName(window_name),
}
}
#[must_use]
pub fn for_key(key: impl Into<String>) -> Self {
let key = key.into();
Self {
name: format!("key:{key}"),
description: format!("key = {key}"),
is_serializable: true,
cohort_activity: None,
cohort_sources: Vec::new(),
kind: ComparisonSelectorKind::Key(key),
}
}
#[must_use]
pub fn for_source(source: impl Into<String>) -> Self {
let source = source.into();
Self {
name: format!("source:{source}"),
description: format!("source = {source}"),
is_serializable: true,
cohort_activity: None,
cohort_sources: Vec::new(),
kind: ComparisonSelectorKind::Source(source),
}
}
#[must_use]
pub fn for_sources(sources: impl IntoIterator<Item = impl Into<String>>) -> Self {
Self::for_sources_core(sources, None)
}
#[must_use]
pub fn for_cohort_sources(
sources: impl IntoIterator<Item = impl Into<String>>,
activity: CohortActivity,
) -> Self {
Self::for_sources_core(sources, Some(activity))
}
fn for_sources_core(
sources: impl IntoIterator<Item = impl Into<String>>,
activity: Option<CohortActivity>,
) -> Self {
let sources = sources.into_iter().map(Into::into).collect::<Vec<_>>();
let name = format!("sources:{}", sources.join(","));
let description = format!("source in [{}]", sources.join(", "));
Self {
name,
description,
is_serializable: true,
cohort_activity: activity,
cohort_sources: sources.clone(),
kind: ComparisonSelectorKind::Sources(sources),
}
}
#[must_use]
pub fn for_partition(partition: impl Into<String>) -> Self {
let partition = partition.into();
Self {
name: format!("partition:{partition}"),
description: format!("partition = {partition}"),
is_serializable: true,
cohort_activity: None,
cohort_sources: Vec::new(),
kind: ComparisonSelectorKind::Partition(partition),
}
}
pub fn for_position_range(
start_inclusive: i64,
end_exclusive: Option<i64>,
) -> Result<Self, ComparisonSelectorError> {
if end_exclusive.is_some_and(|end| end < start_inclusive) {
return Err(ComparisonSelectorError::RangeEndBeforeStart);
}
let end_label = end_exclusive.map_or_else(|| "*".to_owned(), |end| end.to_string());
Ok(Self {
name: format!("position:{start_inclusive}..{end_label}"),
description: format!("start position in [{start_inclusive}, {end_label})"),
is_serializable: true,
cohort_activity: None,
cohort_sources: Vec::new(),
kind: ComparisonSelectorKind::PositionRange {
start_inclusive,
end_exclusive,
},
})
}
pub fn for_time_range(
start_inclusive: i64,
end_exclusive: Option<i64>,
) -> Result<Self, ComparisonSelectorError> {
if end_exclusive.is_some_and(|end| end < start_inclusive) {
return Err(ComparisonSelectorError::RangeEndBeforeStart);
}
let end_label = end_exclusive.map_or_else(|| "*".to_owned(), |end| end.to_string());
Ok(Self {
name: format!("time:{start_inclusive}..{end_label}"),
description: format!("start time in [{start_inclusive}, {end_label})"),
is_serializable: true,
cohort_activity: None,
cohort_sources: Vec::new(),
kind: ComparisonSelectorKind::TimeRange {
start_inclusive,
end_exclusive,
},
})
}
#[must_use]
pub fn runtime_only(
name: impl Into<String>,
description: impl Into<String>,
predicate: impl Fn(&crate::WindowRecord) -> bool + Send + Sync + 'static,
) -> Self {
Self {
name: name.into(),
description: description.into(),
is_serializable: false,
cohort_activity: None,
cohort_sources: Vec::new(),
kind: ComparisonSelectorKind::Runtime(Arc::new(predicate)),
}
}
#[must_use]
pub fn with_name(mut self, name: impl Into<String>) -> Self {
self.name = name.into();
self
}
#[must_use]
pub fn and(self, other: Self) -> Self {
Self {
name: format!("{}&{}", self.name, other.name),
description: format!("({}) and ({})", self.description, other.description),
is_serializable: self.is_serializable && other.is_serializable,
cohort_activity: None,
cohort_sources: Vec::new(),
kind: ComparisonSelectorKind::And(Box::new(self.kind), Box::new(other.kind)),
}
}
#[must_use]
pub fn or(self, other: Self) -> Self {
Self {
name: format!("{}|{}", self.name, other.name),
description: format!("({}) or ({})", self.description, other.description),
is_serializable: self.is_serializable && other.is_serializable,
cohort_activity: None,
cohort_sources: Vec::new(),
kind: ComparisonSelectorKind::Or(Box::new(self.kind), Box::new(other.kind)),
}
}
#[must_use]
pub fn matches(&self, window: &crate::WindowRecord) -> bool {
self.kind.matches(window)
}
pub(crate) fn export_expression(&self) -> serde_json::Value {
fn encode(kind: &ComparisonSelectorKind) -> serde_json::Value {
match kind {
ComparisonSelectorKind::Any => serde_json::json!({"kind": "any"}),
ComparisonSelectorKind::WindowName(value) => {
serde_json::json!({"kind": "windowName", "value": value})
}
ComparisonSelectorKind::Key(value) => {
serde_json::json!({"kind": "key", "value": value})
}
ComparisonSelectorKind::Source(value) => {
serde_json::json!({"kind": "source", "value": value})
}
ComparisonSelectorKind::Sources(values) => {
serde_json::json!({"kind": "sources", "values": values})
}
ComparisonSelectorKind::Partition(value) => {
serde_json::json!({"kind": "partition", "value": value})
}
ComparisonSelectorKind::PositionRange {
start_inclusive,
end_exclusive,
} => serde_json::json!({
"kind": "positionRange",
"startInclusive": start_inclusive,
"endExclusive": end_exclusive
}),
ComparisonSelectorKind::TimeRange {
start_inclusive,
end_exclusive,
} => serde_json::json!({
"kind": "timeRange",
"startInclusive": start_inclusive,
"endExclusive": end_exclusive
}),
ComparisonSelectorKind::Runtime(_) => serde_json::json!({"kind": "runtime"}),
ComparisonSelectorKind::And(left, right) => serde_json::json!({
"kind": "and",
"left": encode(left),
"right": encode(right)
}),
ComparisonSelectorKind::Or(left, right) => serde_json::json!({
"kind": "or",
"left": encode(left),
"right": encode(right)
}),
}
}
encode(&self.kind)
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
pub enum ComparisonSelectorError {
#[error("selector range end cannot be earlier than the start")]
RangeEndBeforeStart,
}
#[non_exhaustive]
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum CohortActivity {
Any,
All,
None,
AtLeast {
count: usize,
},
AtMost {
count: usize,
},
Exactly {
count: usize,
},
}
impl CohortActivity {
#[must_use]
pub const fn name(&self) -> &'static str {
match self {
Self::Any => "any",
Self::All => "all",
Self::None => "none",
Self::AtLeast { .. } => "at-least",
Self::AtMost { .. } => "at-most",
Self::Exactly { .. } => "exactly",
}
}
#[must_use]
pub const fn count(&self) -> Option<usize> {
match self {
Self::Any | Self::All | Self::None => None,
Self::AtLeast { count } | Self::AtMost { count } | Self::Exactly { count } => {
Some(*count)
}
}
}
#[must_use]
pub fn is_active(&self, active_count: usize, member_count: usize) -> bool {
match self {
Self::Any => active_count >= 1,
Self::All => active_count == member_count,
Self::None => active_count == 0,
Self::AtLeast { count } => active_count >= *count,
Self::AtMost { count } => active_count <= *count,
Self::Exactly { count } => active_count == *count,
}
}
}
#[derive(Clone, Debug, PartialEq)]
pub struct WindowFilter {
pub name: String,
pub value: PrimitiveValue,
}
#[derive(Clone, Debug, PartialEq)]
pub struct ComparisonScope {
pub window_name: Option<String>,
pub key: Option<String>,
pub partition: Option<String>,
pub time_axis: crate::TemporalAxis,
pub segment_filters: Vec<WindowFilter>,
pub tag_filters: Vec<WindowFilter>,
}
impl Default for ComparisonScope {
fn default() -> Self {
Self::all()
}
}
impl ComparisonScope {
#[must_use]
pub fn all() -> Self {
Self {
window_name: None,
key: None,
partition: None,
time_axis: crate::TemporalAxis::ProcessingPosition,
segment_filters: Vec::new(),
tag_filters: Vec::new(),
}
}
#[must_use]
pub fn window(window_name: impl Into<String>) -> Self {
Self {
window_name: Some(window_name.into()),
..Self::all()
}
}
#[must_use]
pub const fn on_event_time(mut self) -> Self {
self.time_axis = crate::TemporalAxis::Timestamp;
self
}
#[must_use]
pub const fn on_position(mut self) -> Self {
self.time_axis = crate::TemporalAxis::ProcessingPosition;
self
}
#[must_use]
pub fn key(mut self, key: impl Into<String>) -> Self {
self.key = Some(key.into());
self
}
#[must_use]
pub fn partition(mut self, partition: impl Into<String>) -> Self {
self.partition = Some(partition.into());
self
}
#[must_use]
pub fn segment(mut self, name: impl Into<String>, value: impl Into<PrimitiveValue>) -> Self {
self.segment_filters.push(WindowFilter {
name: name.into(),
value: value.into(),
});
self
}
#[must_use]
pub fn tag(mut self, name: impl Into<String>, value: impl Into<PrimitiveValue>) -> Self {
self.tag_filters.push(WindowFilter {
name: name.into(),
value: value.into(),
});
self
}
}
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ComparisonNullTimestampPolicy {
Reject,
Exclude,
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ComparisonNormalizationPolicy {
pub require_closed_windows: bool,
pub use_half_open_ranges: bool,
pub time_axis: crate::TemporalAxis,
pub open_window_policy: OpenWindowPolicy,
pub open_window_horizon: Option<crate::TemporalPoint>,
pub null_timestamp_policy: ComparisonNullTimestampPolicy,
pub coalesce_adjacent_windows: bool,
pub duplicate_window_policy: ComparisonDuplicateWindowPolicy,
pub known_at: Option<crate::TemporalPoint>,
}
impl Default for ComparisonNormalizationPolicy {
fn default() -> Self {
Self::default_policy()
}
}
impl ComparisonNormalizationPolicy {
#[must_use]
pub fn default_policy() -> Self {
Self {
require_closed_windows: false,
use_half_open_ranges: true,
time_axis: crate::TemporalAxis::ProcessingPosition,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
known_at: None,
}
}
#[must_use]
pub fn require_closed() -> Self {
Self::default_policy()
}
#[must_use]
pub fn clip_open_windows_to(horizon: crate::TemporalPoint) -> Self {
Self {
require_closed_windows: false,
time_axis: horizon.axis(),
open_window_policy: OpenWindowPolicy::ClipToHorizon,
open_window_horizon: Some(horizon),
..Self::default_policy()
}
}
#[must_use]
pub fn event_time() -> Self {
Self {
time_axis: crate::TemporalAxis::Timestamp,
..Self::default_policy()
}
}
#[must_use]
pub const fn rejecting_missing_event_time(mut self) -> Self {
self.null_timestamp_policy = ComparisonNullTimestampPolicy::Reject;
self
}
#[must_use]
pub const fn excluding_missing_event_time(mut self) -> Self {
self.null_timestamp_policy = ComparisonNullTimestampPolicy::Exclude;
self
}
#[must_use]
pub fn with_known_at(mut self, point: crate::TemporalPoint) -> Self {
self.known_at = Some(point);
self
}
#[must_use]
pub const fn coalescing_adjacent_windows(mut self) -> Self {
self.coalesce_adjacent_windows = true;
self
}
#[must_use]
pub const fn rejecting_duplicate_windows(mut self) -> Self {
self.duplicate_window_policy = ComparisonDuplicateWindowPolicy::Reject;
self
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ComparisonOutputOptions {
pub include_aligned_segments: bool,
pub include_explain_data: bool,
}
impl Default for ComparisonOutputOptions {
fn default() -> Self {
Self::default_options()
}
}
impl ComparisonOutputOptions {
#[must_use]
pub const fn default_options() -> Self {
Self {
include_aligned_segments: true,
include_explain_data: true,
}
}
}
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq)]
pub struct ComparisonPlan {
pub name: String,
pub(crate) target_source: String,
pub(crate) against: AgainstSelection,
pub(crate) target_selector: Option<ComparisonSelector>,
pub(crate) against_selectors: Vec<ComparisonSelector>,
pub(crate) scope_window: Option<String>,
pub(crate) scope_key: Option<String>,
pub(crate) scope_partition: Option<String>,
pub(crate) scope_segments: Vec<WindowFilter>,
pub(crate) scope_tags: Vec<WindowFilter>,
pub(crate) comparators: Vec<Comparator>,
pub(crate) require_closed_windows: bool,
pub(crate) use_half_open_ranges: bool,
pub(crate) time_axis: TemporalAxis,
pub(crate) null_timestamp_policy: ComparisonNullTimestampPolicy,
pub(crate) known_at: Option<crate::TemporalPoint>,
pub(crate) open_window_policy: OpenWindowPolicy,
pub(crate) open_window_horizon: Option<crate::TemporalPoint>,
pub(crate) coalesce_adjacent_windows: bool,
pub(crate) duplicate_window_policy: ComparisonDuplicateWindowPolicy,
pub(crate) output: ComparisonOutputOptions,
pub(crate) strict: bool,
}
impl ComparisonPlan {
#[must_use]
pub fn new(
name: impl Into<String>,
target_source: impl Into<String>,
against: AgainstSelection,
comparators: Vec<Comparator>,
) -> Self {
Self {
name: name.into(),
target_source: target_source.into(),
against,
target_selector: None,
against_selectors: Vec::new(),
scope_window: None,
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators,
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: ComparisonOutputOptions::default_options(),
strict: false,
}
}
#[must_use]
pub fn with_scope_window(mut self, window_name: Option<String>) -> Self {
self.scope_window = window_name;
self
}
#[must_use]
pub fn with_require_closed_windows(mut self, require_closed_windows: bool) -> Self {
self.require_closed_windows = require_closed_windows;
self
}
#[must_use]
pub fn with_open_window_policy(
mut self,
policy: OpenWindowPolicy,
horizon: Option<TemporalPoint>,
) -> Self {
self.open_window_policy = policy;
self.open_window_horizon = horizon;
self
}
#[must_use]
pub fn with_strict(mut self, strict: bool) -> Self {
self.strict = strict;
self
}
pub(crate) fn effective_target_selector(&self) -> ComparisonSelector {
self.target_selector
.clone()
.unwrap_or_else(|| ComparisonSelector::for_source(self.target_source.clone()))
}
pub(crate) fn effective_against_selectors(&self) -> Vec<ComparisonSelector> {
if !self.against_selectors.is_empty() {
return self.against_selectors.clone();
}
match &self.against {
AgainstSelection::Sources(sources) => sources
.iter()
.cloned()
.map(ComparisonSelector::for_source)
.collect(),
AgainstSelection::Cohort {
name,
sources,
activity,
} => vec![
ComparisonSelector::for_cohort_sources(sources.clone(), activity.clone())
.with_name(name.clone()),
],
}
}
#[must_use]
pub fn is_serializable(&self) -> bool {
self.effective_target_selector().is_serializable
&& self
.effective_against_selectors()
.iter()
.all(|selector| selector.is_serializable)
}
#[must_use]
pub fn validate(&self) -> Vec<ComparisonDiagnostic> {
let mut diagnostics = Vec::new();
if self.name.trim().is_empty() {
diagnostics.push(plan_diagnostic("MissingName", DiagnosticSeverity::Error));
}
if self.target_selector.is_none() && self.target_source.trim().is_empty() {
diagnostics.push(plan_diagnostic("MissingTarget", DiagnosticSeverity::Error));
}
let against = self.effective_against_selectors();
if against.is_empty() {
diagnostics.push(plan_diagnostic("MissingAgainst", DiagnosticSeverity::Error));
}
if self.comparators.is_empty() {
diagnostics.push(plan_diagnostic(
"MissingComparator",
DiagnosticSeverity::Error,
));
}
if self
.scope_window
.as_deref()
.is_some_and(|value| value.trim().is_empty())
{
diagnostics.push(plan_diagnostic("EmptyScope", DiagnosticSeverity::Error));
}
let mut comparator_declarations = BTreeSet::new();
for comparator in &self.comparators {
let declaration = comparator.declaration();
if !comparator_declarations.insert(declaration) {
diagnostics.push(plan_diagnostic(
"DuplicateComparator",
DiagnosticSeverity::Error,
));
}
if matches!(
comparator,
Comparator::LeadLag {
tolerance_magnitude,
..
} | Comparator::AsOf {
tolerance_magnitude,
..
} if *tolerance_magnitude < 0
) {
diagnostics.push(plan_diagnostic(
"NegativeTolerance",
DiagnosticSeverity::Error,
));
}
}
if let Some(selector) = &self.target_selector
&& selector.name.trim().is_empty()
{
diagnostics.push(plan_diagnostic(
"EmptyTargetSelectorName",
DiagnosticSeverity::Error,
));
}
if let Some(selector) = &self.target_selector
&& !self.target_source.trim().is_empty()
&& self.target_source != selector.name
{
diagnostics.push(plan_diagnostic(
"ContradictoryTargetSelection",
DiagnosticSeverity::Error,
));
}
if !self.against_selectors.is_empty()
&& (!matches!(&self.against, AgainstSelection::Sources(sources) if sources.is_empty()))
{
diagnostics.push(plan_diagnostic(
"ContradictoryAgainstSelection",
DiagnosticSeverity::Error,
));
}
if self.against_selectors.is_empty() {
match &self.against {
AgainstSelection::Sources(sources) => {
validate_source_list(sources, false, &mut diagnostics);
}
AgainstSelection::Cohort {
name,
sources,
activity,
} => {
if name.trim().is_empty() {
diagnostics.push(plan_diagnostic(
"EmptyCohortName",
DiagnosticSeverity::Error,
));
}
validate_source_list(sources, true, &mut diagnostics);
if activity.count().is_some_and(|count| count > sources.len()) {
diagnostics.push(plan_diagnostic(
"InvalidCohortCount",
DiagnosticSeverity::Error,
));
}
if matches!(activity, CohortActivity::AtLeast { count: 0 }) {
diagnostics.push(plan_diagnostic(
"InvalidCohortCount",
DiagnosticSeverity::Error,
));
}
}
}
}
let mut selector_names = BTreeSet::new();
for selector in self
.target_selector
.iter()
.chain(self.against_selectors.iter())
{
if selector.name.trim().is_empty() {
diagnostics.push(plan_diagnostic(
"EmptySelectorName",
DiagnosticSeverity::Error,
));
}
if !selector_names.insert(selector.name.as_str()) {
diagnostics.push(plan_diagnostic(
"DuplicateSelectorName",
DiagnosticSeverity::Error,
));
}
}
validate_filters(&self.scope_segments, "Segment", &mut diagnostics);
validate_filters(&self.scope_tags, "Tag", &mut diagnostics);
if !self.use_half_open_ranges {
diagnostics.push(plan_diagnostic(
"UnsupportedRangeSemantics",
DiagnosticSeverity::Error,
));
}
if let Some(horizon) = &self.open_window_horizon
&& horizon.axis() != self.time_axis
{
diagnostics.push(plan_diagnostic(
"HorizonAxisMismatch",
DiagnosticSeverity::Error,
));
}
if self.open_window_horizon.is_some()
&& self.open_window_policy != OpenWindowPolicy::ClipToHorizon
{
diagnostics.push(plan_diagnostic(
"UnusedOpenWindowHorizon",
DiagnosticSeverity::Error,
));
}
diagnostics
}
}
fn plan_diagnostic(code: &str, severity: DiagnosticSeverity) -> ComparisonDiagnostic {
ComparisonDiagnostic {
code: code.to_owned(),
severity,
}
}
fn validate_source_list(
sources: &[String],
cohort: bool,
diagnostics: &mut Vec<ComparisonDiagnostic>,
) {
if sources.is_empty() {
diagnostics.push(plan_diagnostic(
if cohort {
"EmptyCohort"
} else {
"EmptyAgainstSources"
},
DiagnosticSeverity::Error,
));
}
let mut seen = BTreeSet::<&str>::new();
for source in sources {
if source.trim().is_empty() {
diagnostics.push(plan_diagnostic("EmptySource", DiagnosticSeverity::Error));
}
if !seen.insert(source.as_str()) {
diagnostics.push(plan_diagnostic(
"DuplicateSource",
DiagnosticSeverity::Error,
));
}
}
}
fn validate_filters(
filters: &[WindowFilter],
kind: &str,
diagnostics: &mut Vec<ComparisonDiagnostic>,
) {
let mut names = BTreeSet::new();
for filter in filters {
if filter.name.trim().is_empty() {
diagnostics.push(plan_diagnostic(
&format!("Empty{kind}FilterName"),
DiagnosticSeverity::Error,
));
}
if !names.insert(filter.name.as_str()) {
diagnostics.push(plan_diagnostic(
&format!("Duplicate{kind}FilterName"),
DiagnosticSeverity::Error,
));
}
}
}
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum OpenWindowPolicy {
RequireClosed,
ClipToHorizon,
}
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ComparisonDuplicateWindowPolicy {
Preserve,
Reject,
}
#[non_exhaustive]
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
struct SegmentRef<'a> {
start: crate::TemporalPoint,
end: crate::TemporalPoint,
record_id: &'a str,
record_ids: Vec<String>,
source: Option<&'a str>,
}
#[derive(Clone, Debug, Eq, PartialEq)]
struct AlignedSegment {
start: i64,
end: i64,
axis: TemporalAxis,
clock: Option<String>,
target_record_ids: Vec<String>,
against_record_ids: Vec<String>,
against_is_active: bool,
against_active_sources: Vec<String>,
}
#[derive(Clone, Debug, Eq, PartialEq)]
struct TransitionPoint<'a> {
record_id: &'a str,
point: crate::TemporalPoint,
}
type GroupKey = (String, String, Option<String>, TemporalAxis, Option<String>);
type GroupWindows<'a> = (Vec<SegmentRef<'a>>, Vec<SegmentRef<'a>>);
struct ResultArtifacts {
comparator_summaries: Vec<ComparatorSummary>,
coverage_summaries: Vec<CoverageSummary>,
lead_lag_summaries: Vec<LeadLagSummary>,
row_finalities: Vec<ComparisonRowFinality>,
extension_metadata: Vec<ComparisonExtensionMetadata>,
rows: ComparisonRows,
}
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct WindowArtifact {
#[serde(rename = "recordId")]
pub record_id: String,
#[serde(rename = "windowName")]
pub window_name: String,
pub key: String,
pub source: Option<String>,
pub partition: Option<String>,
#[serde(rename = "startPosition")]
pub start_position: i64,
#[serde(rename = "endPosition")]
pub end_position: Option<i64>,
#[serde(rename = "knownAtPosition")]
pub known_at_position: Option<i64>,
#[serde(rename = "isOpen")]
pub is_open: bool,
pub segments: Vec<WindowSegment>,
pub tags: Vec<WindowTag>,
}
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct ExcludedWindowRecord {
#[serde(rename = "recordId")]
pub record_id: String,
pub reason: String,
#[serde(rename = "diagnosticCode")]
pub diagnostic_code: Option<String>,
pub window: WindowArtifact,
}
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct NormalizedWindowRecord {
#[serde(rename = "recordId")]
pub record_id: String,
#[serde(rename = "recordIds")]
pub record_ids: Vec<String>,
#[serde(rename = "selectorName")]
pub selector_name: String,
pub side: ComparisonSide,
pub range: crate::TemporalRange,
#[serde(rename = "isProvisional")]
pub is_provisional: bool,
pub segments: Vec<WindowSegment>,
pub window: WindowArtifact,
}
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct PreparedComparison {
#[serde(skip)]
pub(crate) plan: ComparisonPlan,
pub(crate) diagnostics: Vec<ComparisonDiagnostic>,
#[serde(rename = "selectedWindows")]
pub(crate) selected_windows: Vec<WindowArtifact>,
#[serde(rename = "excludedWindows")]
pub(crate) excluded_windows: Vec<ExcludedWindowRecord>,
#[serde(rename = "normalizedWindows")]
pub(crate) normalized_windows: Vec<NormalizedWindowRecord>,
}
impl PreparedComparison {
#[must_use]
pub fn diagnostics(&self) -> &[ComparisonDiagnostic] {
&self.diagnostics
}
#[must_use]
pub fn selected_windows(&self) -> &[WindowArtifact] {
&self.selected_windows
}
#[must_use]
pub fn excluded_windows(&self) -> &[ExcludedWindowRecord] {
&self.excluded_windows
}
#[must_use]
pub fn normalized_windows(&self) -> &[NormalizedWindowRecord] {
&self.normalized_windows
}
}
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct AlignedSegmentArtifact {
#[serde(rename = "segmentId")]
pub segment_id: String,
#[serde(rename = "windowName")]
pub window_name: String,
pub key: String,
pub partition: Option<String>,
pub range: RowRange,
#[serde(rename = "targetRecordIds")]
pub target_record_ids: Vec<String>,
#[serde(rename = "againstRecordIds")]
pub against_record_ids: Vec<String>,
#[serde(rename = "againstIsActive")]
pub against_is_active: bool,
#[serde(rename = "againstActiveSources")]
pub against_active_sources: Vec<String>,
}
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct AlignedComparison {
pub segments: Vec<AlignedSegmentArtifact>,
}
#[must_use]
pub fn compare(history: &WindowHistory, plan: &ComparisonPlan) -> ComparisonResult {
execute_compare(history, plan, None)
}
#[must_use]
pub fn compare_live(
history: &WindowHistory,
plan: &ComparisonPlan,
evaluation_horizon: crate::TemporalPoint,
) -> ComparisonResult {
execute_compare(history, plan, Some(evaluation_horizon))
}
#[must_use]
pub fn prepare(history: &WindowHistory, plan: &ComparisonPlan) -> PreparedComparison {
prepare_internal(history, plan, None)
}
#[must_use]
pub fn prepare_live(
history: &WindowHistory,
plan: &ComparisonPlan,
evaluation_horizon: crate::TemporalPoint,
) -> PreparedComparison {
prepare_internal(history, plan, Some(evaluation_horizon))
}
#[must_use]
pub fn align(prepared: &PreparedComparison) -> AlignedComparison {
align_internal(prepared)
}
fn execute_compare(
history: &WindowHistory,
plan: &ComparisonPlan,
live_horizon_override: Option<crate::TemporalPoint>,
) -> ComparisonResult {
let structural_diagnostics = plan.validate();
if structural_diagnostics
.iter()
.any(|diagnostic| diagnostic.severity == DiagnosticSeverity::Error)
{
return invalid_result(plan, structural_diagnostics);
}
let mut diagnostics = structural_diagnostics;
let prepared = prepare_internal(history, plan, live_horizon_override.clone());
diagnostics.extend(prepared.diagnostics.clone());
diagnostics.extend(runtime_critic_diagnostics(
plan,
&prepared,
live_horizon_override.clone(),
));
if diagnostics
.iter()
.any(|diagnostic| diagnostic.severity == DiagnosticSeverity::Error)
{
let mut result = materialize_result(
plan,
&plan.name,
false,
diagnostics,
ResultArtifacts {
comparator_summaries: Vec::new(),
coverage_summaries: Vec::new(),
lead_lag_summaries: Vec::new(),
row_finalities: Vec::new(),
extension_metadata: Vec::new(),
rows: ComparisonRows::default(),
},
);
result.known_at = plan.known_at.as_ref().map(row_point_from_temporal_point);
result.evaluation_horizon = live_horizon_override
.as_ref()
.or(plan.open_window_horizon.as_ref())
.map(row_point_from_temporal_point);
if plan.output.include_explain_data {
result.prepared = Some(serde_json::to_value(prepared).expect("prepared artifact"));
}
return result;
}
let aligned = align_internal(&prepared);
let groups = group_normalized_windows(&prepared);
let mut rows = RowAccumulator::default();
let mut comparator_summaries = Vec::new();
let mut lead_lag_summaries = Vec::new();
for comparator in &plan.comparators {
let row_count = match comparator {
Comparator::Overlap => {
let emitted = build_overlap_rows(&aligned);
let count = emitted.len();
rows.overlap.extend(emitted);
count
}
Comparator::Residual => {
let emitted = build_residual_rows(&aligned);
let count = emitted.len();
rows.residual.extend(emitted);
count
}
Comparator::Missing => {
let emitted = build_missing_rows(&aligned);
let count = emitted.len();
rows.missing.extend(emitted);
count
}
Comparator::Coverage => {
let emitted = build_coverage_rows(&aligned);
let count = emitted.len();
rows.coverage.extend(emitted);
count
}
Comparator::Gap => {
let emitted = build_gap_rows(&aligned);
let count = emitted.len();
rows.gap.extend(emitted);
count
}
Comparator::SymmetricDifference => {
let emitted = build_symmetric_difference_rows(&aligned);
let count = emitted.len();
rows.symmetric_difference.extend(emitted);
count
}
Comparator::Containment => {
let emitted = build_containment_rows(&aligned, &prepared);
let count = emitted.len();
rows.containment.extend(emitted);
count
}
Comparator::LeadLag {
transition,
axis,
tolerance_magnitude,
} => {
let (emitted, summary) =
build_lead_lag_rows(&groups, transition.clone(), *axis, *tolerance_magnitude);
let count = emitted.len();
rows.lead_lag.extend(emitted);
lead_lag_summaries.push(summary);
count
}
Comparator::AsOf {
direction,
axis,
tolerance_magnitude,
} => {
let (emitted, extra_diagnostics) =
build_as_of_rows(&groups, direction.clone(), *axis, *tolerance_magnitude);
let count = emitted.len();
rows.as_of.extend(emitted);
diagnostics.extend(extra_diagnostics);
count
}
};
comparator_summaries.push(ComparatorSummary {
comparator_name: comparator.declaration(),
row_count,
});
}
let provisional_record_ids = prepared
.normalized_windows
.iter()
.filter(|window| window.is_provisional)
.map(|window| window.record_id.clone())
.collect::<BTreeSet<_>>();
let rows = rows.into_shared();
let coverage_summaries = build_coverage_summaries(&rows.coverage);
let row_finalities = build_row_finalities(&rows, &provisional_record_ids);
let mut result = materialize_result(
plan,
&plan.name,
!diagnostics
.iter()
.any(|diagnostic| diagnostic.severity == DiagnosticSeverity::Error),
diagnostics,
ResultArtifacts {
comparator_summaries,
coverage_summaries,
lead_lag_summaries,
row_finalities,
extension_metadata: build_extension_metadata(&aligned, plan),
rows,
},
);
result.known_at = plan.known_at.as_ref().map(row_point_from_temporal_point);
result.evaluation_horizon = live_horizon_override
.as_ref()
.or(plan.open_window_horizon.as_ref())
.map(row_point_from_temporal_point);
if plan.output.include_explain_data {
result.prepared = Some(serde_json::to_value(prepared).expect("prepared artifact"));
}
if plan.output.include_aligned_segments {
result.aligned = Some(serde_json::to_value(aligned).expect("aligned artifact"));
}
result
}
fn invalid_result(
plan: &ComparisonPlan,
diagnostics: Vec<ComparisonDiagnostic>,
) -> ComparisonResult {
let mut result = materialize_result(
plan,
&plan.name,
false,
diagnostics,
ResultArtifacts {
comparator_summaries: Vec::new(),
coverage_summaries: Vec::new(),
lead_lag_summaries: Vec::new(),
row_finalities: Vec::new(),
extension_metadata: Vec::new(),
rows: ComparisonRows::default(),
},
);
result.known_at = plan.known_at.as_ref().map(row_point_from_temporal_point);
result.evaluation_horizon = plan
.open_window_horizon
.as_ref()
.map(row_point_from_temporal_point);
result
}
fn parse_parameterized_comparator(value: &str) -> Option<Comparator> {
let parts: Vec<&str> = value.split(':').collect();
match parts.as_slice() {
["lead-lag", transition, axis, tolerance] => Some(Comparator::LeadLag {
transition: parse_lead_lag_transition(transition)?,
axis: parse_temporal_axis(axis)?,
tolerance_magnitude: parse_non_negative_i64(tolerance)?,
}),
["asof", direction, axis, tolerance] => Some(Comparator::AsOf {
direction: parse_as_of_direction(direction)?,
axis: parse_temporal_axis(axis)?,
tolerance_magnitude: parse_non_negative_i64(tolerance)?,
}),
_ => None,
}
}
fn runtime_critic_diagnostics(
plan: &ComparisonPlan,
prepared: &PreparedComparison,
live_horizon_override: Option<crate::TemporalPoint>,
) -> Vec<ComparisonDiagnostic> {
let severity = if plan.strict {
DiagnosticSeverity::Error
} else {
DiagnosticSeverity::Warning
};
let mut diagnostics = Vec::new();
if !plan.is_serializable() {
push_diagnostic_once(
&mut diagnostics,
"RuntimeNonSerializablePlan",
severity.clone(),
);
}
if plan.scope_window.is_none() {
push_diagnostic_once(&mut diagnostics, "BroadSelector", severity.clone());
}
if plan.known_at.is_none()
&& plan
.comparators
.iter()
.any(|item| matches!(item, Comparator::AsOf { .. }))
{
push_diagnostic_once(&mut diagnostics, "FutureLeakageRisk", severity.clone());
}
if plan.open_window_policy == OpenWindowPolicy::ClipToHorizon
&& plan.open_window_horizon.is_none()
&& live_horizon_override.is_none()
{
push_diagnostic_once(
&mut diagnostics,
"LiveFinalityWithoutHorizon",
severity.clone(),
);
}
if prepared
.excluded_windows
.iter()
.any(|window| window.diagnostic_code.as_deref() == Some("OpenWindowsWithoutPolicy"))
{
push_diagnostic_once(&mut diagnostics, "UnboundedOpenDuration", severity.clone());
}
if let (Some(horizon), Some(known_at)) =
(plan.open_window_horizon.as_ref(), plan.known_at.as_ref())
&& horizon.axis() == TemporalAxis::Timestamp
&& known_at.axis() == TemporalAxis::Timestamp
&& horizon.clock() != known_at.clock()
{
push_diagnostic_once(&mut diagnostics, "MixedClockRisk", severity);
}
diagnostics
}
fn parse_temporal_axis(value: &str) -> Option<TemporalAxis> {
match value {
"position" | "ProcessingPosition" => Some(TemporalAxis::ProcessingPosition),
"timestamp" | "Timestamp" => Some(TemporalAxis::Timestamp),
_ => None,
}
}
fn parse_lead_lag_transition(value: &str) -> Option<LeadLagTransition> {
match value {
"start" | "Start" => Some(LeadLagTransition::Start),
"end" | "End" => Some(LeadLagTransition::End),
_ => None,
}
}
fn parse_as_of_direction(value: &str) -> Option<AsOfDirection> {
match value {
"previous" | "Previous" => Some(AsOfDirection::Previous),
"next" | "Next" => Some(AsOfDirection::Next),
"nearest" | "Nearest" => Some(AsOfDirection::Nearest),
_ => None,
}
}
fn parse_non_negative_i64(value: &str) -> Option<i64> {
let parsed = value.parse::<i64>().ok()?;
(parsed >= 0).then_some(parsed)
}
fn materialize_result(
plan: &ComparisonPlan,
plan_name: &str,
is_valid: bool,
diagnostics: Vec<ComparisonDiagnostic>,
artifacts: ResultArtifacts,
) -> ComparisonResult {
ComparisonResult {
schema: "spanfold.comparison.result".to_owned(),
schema_version: 0,
artifact: "result".to_owned(),
plan: plan.clone(),
plan_name: plan_name.to_owned(),
is_valid,
diagnostics,
prepared: None,
aligned: None,
known_at: None,
evaluation_horizon: None,
comparator_summaries: artifacts.comparator_summaries,
coverage_summaries: artifacts.coverage_summaries,
overlap_rows: Arc::clone(&artifacts.rows.overlap),
residual_rows: Arc::clone(&artifacts.rows.residual),
missing_rows: Arc::clone(&artifacts.rows.missing),
coverage_rows: Arc::clone(&artifacts.rows.coverage),
gap_rows: Arc::clone(&artifacts.rows.gap),
symmetric_difference_rows: Arc::clone(&artifacts.rows.symmetric_difference),
containment_rows: Arc::clone(&artifacts.rows.containment),
lead_lag_rows: Arc::clone(&artifacts.rows.lead_lag),
lead_lag_summaries: artifacts.lead_lag_summaries,
as_of_rows: Arc::clone(&artifacts.rows.as_of),
row_finalities: artifacts.row_finalities,
extension_metadata: artifacts.extension_metadata,
rows: artifacts.rows,
}
}
fn build_coverage_summaries(rows: &[CoverageRow]) -> Vec<CoverageSummary> {
let mut grouped: BTreeMap<(String, String, Option<String>), (i128, i128)> = BTreeMap::new();
for row in rows {
let entry = grouped
.entry((
row.window_name.clone(),
row.key.clone(),
row.partition.clone(),
))
.or_insert((0, 0));
entry.0 += i128::from(row.target_magnitude);
entry.1 += i128::from(row.covered_magnitude);
}
grouped
.into_iter()
.map(
|((window_name, key, partition), (target_magnitude, covered_magnitude))| {
CoverageSummary {
window_name,
key,
partition,
target_magnitude: target_magnitude as f64,
target_magnitude_exact: target_magnitude,
covered_magnitude: covered_magnitude as f64,
covered_magnitude_exact: covered_magnitude,
coverage_ratio: if target_magnitude == 0 {
0.0
} else {
covered_magnitude as f64 / target_magnitude as f64
},
}
},
)
.collect()
}
fn build_extension_metadata(
aligned: &AlignedComparison,
plan: &ComparisonPlan,
) -> Vec<ComparisonExtensionMetadata> {
let AgainstSelection::Cohort {
activity, sources, ..
} = &plan.against
else {
return Vec::new();
};
aligned
.segments
.iter()
.enumerate()
.map(|(index, segment)| ComparisonExtensionMetadata {
extension_id: "spanfold.cohort".to_owned(),
key: format!("segment[{index}]"),
value: serde_json::json!({
"rule": activity.name(),
"required": required_activity_count(activity, sources.len()),
"activeCount": segment.against_active_sources.len(),
"isActive": segment.against_is_active,
"activeSources": segment.against_active_sources,
})
.to_string(),
})
.collect()
}
fn required_activity_count(activity: &CohortActivity, member_count: usize) -> usize {
match activity {
CohortActivity::Any => 1,
CohortActivity::All => member_count,
CohortActivity::None => 0,
CohortActivity::AtLeast { count }
| CohortActivity::AtMost { count }
| CohortActivity::Exactly { count } => *count,
}
}
fn prepare_internal(
history: &WindowHistory,
plan: &ComparisonPlan,
live_horizon_override: Option<crate::TemporalPoint>,
) -> PreparedComparison {
let structural_diagnostics = plan.validate();
if structural_diagnostics
.iter()
.any(|diagnostic| diagnostic.severity == DiagnosticSeverity::Error)
{
return PreparedComparison {
plan: plan.clone(),
diagnostics: structural_diagnostics,
selected_windows: Vec::new(),
excluded_windows: Vec::new(),
normalized_windows: Vec::new(),
};
}
let mut diagnostics = structural_diagnostics;
let mut selected_windows = Vec::new();
let mut excluded_windows = Vec::new();
let mut normalized_windows = Vec::new();
let mut candidates = history
.closed_windows()
.iter()
.map(RawWindowRef::Closed)
.collect::<Vec<_>>();
candidates.extend(history.open_windows().iter().map(RawWindowRef::Open));
candidates.sort_by(|left, right| {
(
left.window_name(),
left.key(),
left.source().unwrap_or(""),
left.partition().unwrap_or(""),
left.start_position(),
left.end_position().unwrap_or(i64::MAX),
left.record_id(),
)
.cmp(&(
right.window_name(),
right.key(),
right.source().unwrap_or(""),
right.partition().unwrap_or(""),
right.start_position(),
right.end_position().unwrap_or(i64::MAX),
right.record_id(),
))
});
let target_selector = plan.effective_target_selector();
let target_selector_name = if plan.target_selector.is_some() {
target_selector.name.as_str()
} else {
"target"
};
let against_selectors = plan.effective_against_selectors();
let use_explicit_against_selector_names = !plan.against_selectors.is_empty();
for candidate in candidates {
let window = to_window_artifact(&candidate);
let record = candidate.to_window_record();
let known_at_point = candidate.known_at_point().unwrap_or_else(|| {
candidate
.end_point()
.unwrap_or_else(|| candidate.start_point())
});
if let Some(known_at) = plan.known_at.as_ref()
&& !matches!(
known_at_point.try_cmp(known_at),
Ok(Ordering::Less | Ordering::Equal)
)
{
excluded_windows.push(ExcludedWindowRecord {
record_id: window.record_id.clone(),
reason: "Window was not available at the configured known-at point.".to_owned(),
diagnostic_code: Some("FutureWindowExcluded".to_owned()),
window,
});
diagnostics.push(ComparisonDiagnostic {
code: "FutureWindowExcluded".to_owned(),
severity: DiagnosticSeverity::Warning,
});
continue;
}
if let Some(scope_window) = &plan.scope_window
&& candidate.window_name() != scope_window
{
excluded_windows.push(ExcludedWindowRecord {
record_id: window.record_id.clone(),
reason: "Window is outside the comparison scope.".to_owned(),
diagnostic_code: None,
window,
});
continue;
}
if let Some(scope_key) = &plan.scope_key
&& candidate.key() != scope_key
{
excluded_windows.push(ExcludedWindowRecord {
record_id: window.record_id.clone(),
reason: "Window is outside the comparison scope.".to_owned(),
diagnostic_code: None,
window,
});
continue;
}
if let Some(scope_partition) = &plan.scope_partition
&& candidate.partition() != Some(scope_partition.as_str())
{
excluded_windows.push(ExcludedWindowRecord {
record_id: window.record_id.clone(),
reason: "Window is outside the comparison scope.".to_owned(),
diagnostic_code: None,
window,
});
continue;
}
if !matches_window_artifact(&window, &plan.scope_segments, &plan.scope_tags) {
excluded_windows.push(ExcludedWindowRecord {
record_id: window.record_id.clone(),
reason: "Window is outside the comparison scope.".to_owned(),
diagnostic_code: None,
window,
});
continue;
}
let is_target = target_selector.matches(&record);
let matching_against_selectors = against_selectors
.iter()
.filter(|selector| selector.matches(&record))
.collect::<Vec<_>>();
if !is_target && matching_against_selectors.is_empty() {
excluded_windows.push(ExcludedWindowRecord {
record_id: window.record_id.clone(),
reason: "Window did not match target or comparison selectors.".to_owned(),
diagnostic_code: None,
window,
});
continue;
}
selected_windows.push(window.clone());
if is_target
&& let Some(normalized) = normalize_candidate(
&candidate,
target_selector_name,
ComparisonSide::Target,
plan,
live_horizon_override.clone(),
&mut diagnostics,
&mut excluded_windows,
)
{
normalized_windows.push(normalized);
}
for selector in matching_against_selectors {
let selector_name = if use_explicit_against_selector_names {
selector.name.as_str()
} else {
"against"
};
if let Some(normalized) = normalize_candidate(
&candidate,
selector_name,
ComparisonSide::Against,
plan,
live_horizon_override.clone(),
&mut diagnostics,
&mut excluded_windows,
) {
normalized_windows.push(normalized);
}
}
}
let normalized_windows =
postprocess_normalized_windows(normalized_windows, plan, &mut diagnostics);
let target_ids = normalized_windows
.iter()
.filter(|window| window.side == ComparisonSide::Target)
.flat_map(|window| window.record_ids.iter().cloned())
.collect::<BTreeSet<_>>();
if normalized_windows.iter().any(|window| {
window.side == ComparisonSide::Against
&& window
.record_ids
.iter()
.any(|record_id| target_ids.contains(record_id))
}) {
push_diagnostic_once(
&mut diagnostics,
"SelfComparison",
DiagnosticSeverity::Error,
);
}
PreparedComparison {
plan: plan.clone(),
diagnostics,
selected_windows,
excluded_windows,
normalized_windows,
}
}
fn postprocess_normalized_windows(
windows: Vec<NormalizedWindowRecord>,
plan: &ComparisonPlan,
diagnostics: &mut Vec<ComparisonDiagnostic>,
) -> Vec<NormalizedWindowRecord> {
let deduplicated = deduplicate_normalized_windows(windows, plan, diagnostics);
if plan.coalesce_adjacent_windows {
coalesce_normalized_windows(deduplicated)
} else {
deduplicated
}
}
fn deduplicate_normalized_windows(
windows: Vec<NormalizedWindowRecord>,
plan: &ComparisonPlan,
diagnostics: &mut Vec<ComparisonDiagnostic>,
) -> Vec<NormalizedWindowRecord> {
let mut seen = BTreeSet::<Vec<u8>>::new();
let mut rows = Vec::new();
for window in windows {
let key = normalized_duplicate_key(&window);
if seen.contains(&key) {
push_diagnostic_once(diagnostics, "DuplicateWindow", DiagnosticSeverity::Warning);
if plan.duplicate_window_policy == ComparisonDuplicateWindowPolicy::Reject {
continue;
}
} else {
seen.insert(key);
}
rows.push(window);
}
rows
}
fn coalesce_normalized_windows(
windows: Vec<NormalizedWindowRecord>,
) -> Vec<NormalizedWindowRecord> {
let mut groups: BTreeMap<Vec<u8>, Vec<NormalizedWindowRecord>> = BTreeMap::new();
for window in windows {
groups
.entry(normalized_coalesce_key(&window))
.or_default()
.push(window);
}
let mut rows = Vec::new();
for mut windows in groups.into_values() {
windows.sort_by(|left, right| {
left.range
.start()
.try_cmp(&right.range.start())
.expect("coalescing groups share a temporal domain")
.then_with(|| {
left.range
.end()
.try_cmp(&right.range.end())
.expect("coalescing groups share a temporal domain")
})
.then_with(|| left.record_id.cmp(&right.record_id))
});
for window in windows {
if let Some(previous) = rows.last_mut()
&& can_coalesce_normalized(previous, &window)
{
previous.range =
crate::TemporalRange::new(previous.range.start(), window.range.end())
.expect("adjacent normalized ranges share an axis");
previous.is_provisional |= window.is_provisional;
previous.record_ids.extend(window.record_ids);
continue;
}
rows.push(window);
}
}
rows
}
fn can_coalesce_normalized(
first: &NormalizedWindowRecord,
second: &NormalizedWindowRecord,
) -> bool {
normalized_coalesce_key(first) == normalized_coalesce_key(second)
&& first.range.end() == second.range.start()
}
fn normalized_duplicate_key(window: &NormalizedWindowRecord) -> Vec<u8> {
serde_json::to_vec(&(
&window.selector_name,
&window.side,
&window.window.window_name,
&window.window.key,
&window.window.source,
&window.window.partition,
&window.range,
&window.segments,
))
.unwrap_or_default()
}
fn normalized_coalesce_key(window: &NormalizedWindowRecord) -> Vec<u8> {
serde_json::to_vec(&(
&window.selector_name,
&window.side,
&window.window.window_name,
&window.window.key,
&window.window.source,
&window.window.partition,
&window.segments,
&window.window.tags,
))
.unwrap_or_default()
}
fn push_diagnostic_once(
diagnostics: &mut Vec<ComparisonDiagnostic>,
code: &str,
severity: DiagnosticSeverity,
) {
if diagnostics.iter().any(|diagnostic| diagnostic.code == code) {
return;
}
diagnostics.push(ComparisonDiagnostic {
code: code.to_owned(),
severity,
});
}
fn align_internal(prepared: &PreparedComparison) -> AlignedComparison {
let groups = group_normalized_windows(prepared);
let mut segments = Vec::new();
for ((window_name, key, partition, axis, clock), (targets, againsts)) in groups {
for segment in aligned_segments(
targets.as_slice(),
againsts.as_slice(),
&prepared.plan.against,
) {
segments.push(AlignedSegmentArtifact {
segment_id: format!("segment[{}]", segments.len()),
window_name: window_name.clone(),
key: key.clone(),
partition: partition.clone(),
range: RowRange {
start: segment.start,
end: segment.end,
axis,
clock: clock.clone(),
},
target_record_ids: segment.target_record_ids,
against_record_ids: segment.against_record_ids,
against_is_active: segment.against_is_active,
against_active_sources: segment.against_active_sources,
});
}
}
AlignedComparison { segments }
}
fn group_normalized_windows(prepared: &PreparedComparison) -> BTreeMap<GroupKey, GroupWindows<'_>> {
let mut groups: BTreeMap<GroupKey, GroupWindows<'_>> = BTreeMap::new();
for normalized in &prepared.normalized_windows {
let group = groups
.entry((
normalized.window.window_name.clone(),
normalized.window.key.clone(),
normalized.window.partition.clone(),
normalized.range.start().axis(),
normalized.range.start().clock().map(str::to_owned),
))
.or_default();
let segment = SegmentRef {
start: normalized.range.start(),
end: normalized.range.end(),
record_id: normalized.record_id.as_str(),
record_ids: normalized.record_ids.clone(),
source: normalized.window.source.as_deref(),
};
match normalized.side {
ComparisonSide::Target => group.0.push(segment),
ComparisonSide::Against => group.1.push(segment),
}
}
groups
}
fn row_point_from_temporal_point(point: &crate::TemporalPoint) -> RowPoint {
RowPoint {
axis: point.axis(),
magnitude: point.magnitude(),
clock: point.clock().map(str::to_owned),
}
}
enum RawWindowRef<'a> {
Closed(&'a crate::ClosedWindow),
Open(&'a crate::OpenWindow),
}
impl RawWindowRef<'_> {
fn record_id(&self) -> &str {
match self {
Self::Closed(window) => window.id.as_str(),
Self::Open(window) => window.id.as_str(),
}
}
fn window_name(&self) -> &str {
match self {
Self::Closed(window) => &window.window_name,
Self::Open(window) => &window.window_name,
}
}
fn key(&self) -> &str {
match self {
Self::Closed(window) => &window.key,
Self::Open(window) => &window.key,
}
}
fn source(&self) -> Option<&str> {
match self {
Self::Closed(window) => window.source.as_deref(),
Self::Open(window) => window.source.as_deref(),
}
}
fn partition(&self) -> Option<&str> {
match self {
Self::Closed(window) => window.partition.as_deref(),
Self::Open(window) => window.partition.as_deref(),
}
}
fn start_position(&self) -> i64 {
self.start_point().magnitude()
}
fn start_point(&self) -> crate::TemporalPoint {
match self {
Self::Closed(window) => window.range.start(),
Self::Open(window) => window.start.clone(),
}
}
fn end_position(&self) -> Option<i64> {
self.end_point().map(|point| point.magnitude())
}
fn end_point(&self) -> Option<crate::TemporalPoint> {
match self {
Self::Closed(window) => Some(window.range.end()),
Self::Open(_) => None,
}
}
fn known_at_point(&self) -> Option<crate::TemporalPoint> {
match self {
Self::Closed(window) => window.known_at.clone(),
Self::Open(window) => window.known_at.clone(),
}
}
fn known_at_position(&self) -> Option<i64> {
self.known_at_point().map(|point| point.magnitude())
}
fn segments(&self) -> &[WindowSegment] {
match self {
Self::Closed(window) => &window.segments,
Self::Open(window) => &window.segments,
}
}
fn tags(&self) -> &[WindowTag] {
match self {
Self::Closed(window) => &window.tags,
Self::Open(window) => &window.tags,
}
}
fn is_open(&self) -> bool {
matches!(self, Self::Open(_))
}
fn to_window_record(&self) -> crate::WindowRecord {
match self {
Self::Closed(window) => crate::WindowRecord::Closed((*window).clone()),
Self::Open(window) => crate::WindowRecord::Open((*window).clone()),
}
}
}
fn to_window_artifact(candidate: &RawWindowRef<'_>) -> WindowArtifact {
WindowArtifact {
record_id: candidate.record_id().to_owned(),
window_name: candidate.window_name().to_owned(),
key: candidate.key().to_owned(),
source: candidate.source().map(str::to_owned),
partition: candidate.partition().map(str::to_owned),
start_position: candidate.start_position(),
end_position: candidate.end_position(),
known_at_position: candidate.known_at_position(),
is_open: candidate.is_open(),
segments: candidate.segments().to_vec(),
tags: candidate.tags().to_vec(),
}
}
fn normalize_candidate(
candidate: &RawWindowRef<'_>,
selector_name: &str,
side: ComparisonSide,
plan: &ComparisonPlan,
live_horizon_override: Option<crate::TemporalPoint>,
diagnostics: &mut Vec<ComparisonDiagnostic>,
excluded_windows: &mut Vec<ExcludedWindowRecord>,
) -> Option<NormalizedWindowRecord> {
let horizon = live_horizon_override.or_else(|| plan.open_window_horizon.clone());
if candidate.start_point().axis() != plan.time_axis {
let window = to_window_artifact(candidate);
let (code, severity) = if plan.time_axis == TemporalAxis::Timestamp {
(
"MissingEventTime",
match plan.null_timestamp_policy {
ComparisonNullTimestampPolicy::Reject => DiagnosticSeverity::Error,
ComparisonNullTimestampPolicy::Exclude => DiagnosticSeverity::Warning,
},
)
} else {
("TemporalAxisMismatch", DiagnosticSeverity::Error)
};
excluded_windows.push(ExcludedWindowRecord {
record_id: window.record_id.clone(),
reason: "Window temporal axis does not match the comparison plan.".to_owned(),
diagnostic_code: Some(code.to_owned()),
window,
});
diagnostics.push(ComparisonDiagnostic {
code: code.to_owned(),
severity,
});
return None;
}
let end_point = match candidate.end_point() {
Some(end) => (end, false),
None => match (
plan.require_closed_windows,
plan.open_window_policy,
horizon,
) {
(true, _, _) | (false, OpenWindowPolicy::RequireClosed, _) => {
let window = to_window_artifact(candidate);
excluded_windows.push(ExcludedWindowRecord {
record_id: window.record_id.clone(),
reason: "Open windows require an explicit clipping policy.".to_owned(),
diagnostic_code: Some("OpenWindowsWithoutPolicy".to_owned()),
window,
});
diagnostics.push(ComparisonDiagnostic {
code: "OpenWindowsWithoutPolicy".to_owned(),
severity: DiagnosticSeverity::Error,
});
return None;
}
(false, OpenWindowPolicy::ClipToHorizon, Some(point))
if point.is_compatible_with(&candidate.start_point())
&& matches!(
point.try_cmp(&candidate.start_point()),
Ok(Ordering::Greater | Ordering::Equal)
) =>
{
(point, true)
}
(false, OpenWindowPolicy::ClipToHorizon, Some(_)) => {
let window = to_window_artifact(candidate);
excluded_windows.push(ExcludedWindowRecord {
record_id: window.record_id.clone(),
reason: "Open-window horizon cannot be earlier than the window start."
.to_owned(),
diagnostic_code: Some("InvalidRangeDuration".to_owned()),
window,
});
diagnostics.push(ComparisonDiagnostic {
code: "InvalidRangeDuration".to_owned(),
severity: DiagnosticSeverity::Error,
});
return None;
}
(false, OpenWindowPolicy::ClipToHorizon, None) => {
let window = to_window_artifact(candidate);
excluded_windows.push(ExcludedWindowRecord {
record_id: window.record_id.clone(),
reason: "Open-window clipping requires an evaluation horizon.".to_owned(),
diagnostic_code: Some("OpenWindowsWithoutPolicy".to_owned()),
window,
});
diagnostics.push(ComparisonDiagnostic {
code: "OpenWindowsWithoutPolicy".to_owned(),
severity: DiagnosticSeverity::Error,
});
return None;
}
},
};
let range = match crate::TemporalRange::new(candidate.start_point(), end_point.0.clone()) {
Ok(range) => range,
Err(error) => {
let window = to_window_artifact(candidate);
excluded_windows.push(ExcludedWindowRecord {
record_id: window.record_id.clone(),
reason: error.to_string(),
diagnostic_code: Some("InvalidTemporalRange".to_owned()),
window,
});
diagnostics.push(ComparisonDiagnostic {
code: "InvalidTemporalRange".to_owned(),
severity: DiagnosticSeverity::Error,
});
return None;
}
};
Some(NormalizedWindowRecord {
record_id: candidate.record_id().to_owned(),
record_ids: vec![candidate.record_id().to_owned()],
selector_name: selector_name.to_owned(),
side,
range,
is_provisional: end_point.1,
segments: candidate.segments().to_vec(),
window: to_window_artifact(candidate),
})
}
fn matches_window_artifact(
window: &WindowArtifact,
segment_filters: &[WindowFilter],
tag_filters: &[WindowFilter],
) -> bool {
segment_filters.iter().all(|filter| {
window
.segments
.iter()
.any(|item| item.name == filter.name && item.value == filter.value)
}) && tag_filters.iter().all(|filter| {
window
.tags
.iter()
.any(|item| item.name == filter.name && item.value == filter.value)
})
}
fn aligned_segments(
targets: &[SegmentRef<'_>],
againsts: &[SegmentRef<'_>],
against_selection: &AgainstSelection,
) -> Vec<AlignedSegment> {
let mut points = Vec::with_capacity((targets.len() + againsts.len()) * 2);
for item in targets {
points.push(item.start.clone());
points.push(item.end.clone());
}
for item in againsts {
points.push(item.start.clone());
points.push(item.end.clone());
}
points.sort_by(|left, right| {
left.try_cmp(right)
.expect("alignment groups share a temporal domain")
});
points.dedup();
let mut target_starts = targets
.iter()
.enumerate()
.map(|(index, item)| (item.start.clone(), index))
.collect::<Vec<_>>();
let mut target_ends = targets
.iter()
.enumerate()
.map(|(index, item)| (item.end.clone(), index))
.collect::<Vec<_>>();
let mut against_starts = againsts
.iter()
.enumerate()
.map(|(index, item)| (item.start.clone(), index))
.collect::<Vec<_>>();
let mut against_ends = againsts
.iter()
.enumerate()
.map(|(index, item)| (item.end.clone(), index))
.collect::<Vec<_>>();
for events in [
&mut target_starts,
&mut target_ends,
&mut against_starts,
&mut against_ends,
] {
events.sort_by(|left, right| {
left.0
.try_cmp(&right.0)
.expect("alignment groups share a temporal domain")
});
}
let mut active_targets = BTreeSet::new();
let mut active_againsts = BTreeSet::new();
let mut target_start_index = 0;
let mut target_end_index = 0;
let mut against_start_index = 0;
let mut against_end_index = 0;
let mut segments = Vec::new();
for pair in points.windows(2) {
let start = pair[0].clone();
let end = pair[1].clone();
if !matches!(start.try_cmp(&end), Ok(Ordering::Less)) {
continue;
}
while target_end_index < target_ends.len()
&& matches!(
target_ends[target_end_index].0.try_cmp(&start),
Ok(Ordering::Less | Ordering::Equal)
)
{
active_targets.remove(&target_ends[target_end_index].1);
target_end_index += 1;
}
while against_end_index < against_ends.len()
&& matches!(
against_ends[against_end_index].0.try_cmp(&start),
Ok(Ordering::Less | Ordering::Equal)
)
{
active_againsts.remove(&against_ends[against_end_index].1);
against_end_index += 1;
}
while target_start_index < target_starts.len()
&& matches!(
target_starts[target_start_index].0.try_cmp(&start),
Ok(Ordering::Less | Ordering::Equal)
)
{
active_targets.insert(target_starts[target_start_index].1);
target_start_index += 1;
}
while against_start_index < against_starts.len()
&& matches!(
against_starts[against_start_index].0.try_cmp(&start),
Ok(Ordering::Less | Ordering::Equal)
)
{
active_againsts.insert(against_starts[against_start_index].1);
against_start_index += 1;
}
let mut target_record_ids = Vec::new();
let mut against_record_ids = Vec::new();
for index in &active_targets {
target_record_ids.extend(targets[*index].record_ids.iter().cloned());
}
for index in &active_againsts {
against_record_ids.extend(againsts[*index].record_ids.iter().cloned());
}
let active_sources = active_againsts
.iter()
.filter_map(|index| againsts[*index].source)
.collect::<BTreeSet<_>>()
.into_iter()
.map(str::to_owned)
.collect::<Vec<_>>();
let against_is_active = match against_selection {
AgainstSelection::Sources(_) => !active_sources.is_empty(),
AgainstSelection::Cohort {
sources, activity, ..
} => activity.is_active(active_sources.len(), sources.len()),
};
segments.push(AlignedSegment {
start: start.magnitude(),
end: end.magnitude(),
axis: start.axis(),
clock: start.clock().map(str::to_owned),
target_record_ids,
against_record_ids,
against_is_active,
against_active_sources: active_sources,
});
}
segments
}
#[cfg(test)]
mod tests {
#![allow(unused_must_use)]
use crate::{WindowHistoryFixture, fixture::ContractFixture};
use super::*;
#[test]
fn selectors_match_windows_and_compose_predicates() {
let window = crate::WindowRecord::Closed(crate::ClosedWindow {
id: crate::WindowRecordId::new("record-1").expect("record id"),
window_name: "DeviceOffline".to_owned(),
key: "device-1".to_owned(),
range: crate::TemporalRange::positions(10, 20).expect("range"),
known_at: None,
source: Some("provider-a".to_owned()),
partition: Some("fleet-a".to_owned()),
segments: Vec::new(),
tags: Vec::new(),
boundary_reason: None,
boundary_changes: Vec::new(),
});
assert!(ComparisonSelector::for_source("provider-a").matches(&window));
assert!(!ComparisonSelector::for_source("provider-b").matches(&window));
assert!(ComparisonSelector::for_window_name("DeviceOffline").matches(&window));
assert!(ComparisonSelector::for_key("device-1").matches(&window));
assert!(ComparisonSelector::for_partition("fleet-a").matches(&window));
assert!(
ComparisonSelector::for_window_name("DeviceOffline")
.and(ComparisonSelector::for_source("provider-a"))
.matches(&window)
);
assert!(
ComparisonSelector::for_source("provider-b")
.or(ComparisonSelector::for_source("provider-a"))
.matches(&window)
);
}
#[test]
fn runtime_selector_is_not_serializable_and_uses_predicate() {
let window = crate::WindowRecord::Closed(crate::ClosedWindow {
id: crate::WindowRecordId::new("record-1").expect("record id"),
window_name: "DeviceOffline".to_owned(),
key: "device-1".to_owned(),
range: crate::TemporalRange::positions(0, 12).expect("range"),
known_at: None,
source: None,
partition: None,
segments: Vec::new(),
tags: Vec::new(),
boundary_reason: None,
boundary_changes: Vec::new(),
});
let selector = ComparisonSelector::runtime_only(
"long-window",
"window duration is longer than ten positions",
|record| {
record
.end()
.is_some_and(|end| end.magnitude() - record.start().magnitude() > 10)
},
);
assert!(selector.matches(&window));
assert!(!selector.is_serializable);
}
#[test]
fn plan_validate_reports_structural_and_selector_diagnostics() {
let history = WindowHistoryFixture::new().build();
let complete = history
.compare("Provider QA")
.target_source("provider-a")
.against_source("provider-b")
.scope_window("DeviceOffline")
.overlap()
.plan()
.clone();
assert!(complete.validate().is_empty());
let missing = history.compare(" ").plan().clone();
let missing_codes = missing
.validate()
.into_iter()
.map(|diagnostic| diagnostic.code)
.collect::<Vec<_>>();
assert!(missing_codes.iter().any(|code| code == "MissingName"));
assert!(missing_codes.iter().any(|code| code == "MissingTarget"));
assert!(missing_codes.iter().any(|code| code == "MissingAgainst"));
assert!(missing_codes.iter().any(|code| code == "MissingComparator"));
let runtime_only = history
.compare("Runtime selector QA")
.target_selector(ComparisonSelector::runtime_only(
"provider-a",
"runtime provider selector",
|_| true,
))
.against_source("provider-b")
.scope_window("DeviceOffline")
.overlap()
.strict()
.plan()
.clone();
assert!(runtime_only.validate().is_empty());
assert!(!runtime_only.is_serializable());
}
#[test]
fn range_selectors_use_half_open_start_ranges() {
let position_window = crate::WindowRecord::Closed(crate::ClosedWindow {
id: crate::WindowRecordId::new("record-1").expect("record id"),
window_name: "DeviceOffline".to_owned(),
key: "device-1".to_owned(),
range: crate::TemporalRange::positions(10, 20).expect("range"),
known_at: None,
source: None,
partition: None,
segments: Vec::new(),
tags: Vec::new(),
boundary_reason: None,
boundary_changes: Vec::new(),
});
let time_window = crate::WindowRecord::Closed(crate::ClosedWindow {
id: crate::WindowRecordId::new("record-2").expect("record id"),
window_name: "DeviceOffline".to_owned(),
key: "device-1".to_owned(),
range: crate::TemporalRange::new(
crate::TemporalPoint::timestamp_ticks(15),
crate::TemporalPoint::timestamp_ticks(20),
)
.expect("range"),
known_at: None,
source: None,
partition: None,
segments: Vec::new(),
tags: Vec::new(),
boundary_reason: None,
boundary_changes: Vec::new(),
});
assert!(
ComparisonSelector::for_position_range(10, Some(20))
.expect("selector")
.matches(&position_window)
);
assert!(
!ComparisonSelector::for_position_range(11, Some(20))
.expect("selector")
.matches(&position_window)
);
assert!(
ComparisonSelector::for_time_range(10, Some(20))
.expect("selector")
.matches(&time_window)
);
assert!(matches!(
ComparisonSelector::for_position_range(20, Some(10)),
Err(ComparisonSelectorError::RangeEndBeforeStart)
));
}
#[test]
fn basic_overlap_fixture_matches_expected_counts() {
let fixture = ContractFixture::parse_json(include_str!(
"../../../../dotnet/tests/Spanfold.Tests/Comparison/Fixtures/basic-overlap.json"
))
.expect("fixture should parse");
let result = compare(fixture.history(), fixture.plan());
assert!(result.is_valid);
assert_eq!(result.comparator_summaries[0].row_count, 1);
assert_eq!(result.comparator_summaries[1].row_count, 1);
assert_eq!(result.comparator_summaries[2].row_count, 2);
assert_eq!(result.overlap_rows[0].range.start, 3);
assert_eq!(result.overlap_rows[0].range.end, 5);
assert_eq!(result.residual_rows[0].range.start, 1);
assert_eq!(result.residual_rows[0].range.end, 3);
}
#[test]
fn coverage_rows_are_segments_and_summary_is_the_grouped_ratio() {
let fixture = ContractFixture::parse_json(include_str!(
"../../../../dotnet/tests/Spanfold.Tests/Comparison/Fixtures/basic-overlap.json"
))
.expect("fixture should parse");
let result = compare(fixture.history(), fixture.plan());
assert_eq!(result.rows.coverage.len(), 2);
assert_eq!(result.rows.coverage[0].target_magnitude, 2);
assert_eq!(result.rows.coverage[0].covered_magnitude, 0);
assert_eq!(result.rows.coverage[1].target_magnitude, 2);
assert_eq!(result.rows.coverage[1].covered_magnitude, 2);
assert_eq!(result.coverage_summaries.len(), 1);
let summary = &result.coverage_summaries[0];
assert_eq!(summary.target_magnitude_exact, 4);
assert_eq!(summary.covered_magnitude_exact, 2);
assert_eq!(summary.coverage_ratio, 0.5);
}
#[test]
fn gap_and_symmetric_difference_match_expected_rows() {
let history = WindowHistoryFixture::new()
.closed_window("DeviceOffline", "device-1", 1, 3, |w| {
w.source("provider-a")
})
.expect("target")
.closed_window("DeviceOffline", "device-1", 5, 7, |w| {
w.source("provider-b")
})
.expect("against")
.build();
let plan = ComparisonPlan {
name: "Provider QA".to_owned(),
target_source: "provider-a".to_owned(),
against: AgainstSelection::Sources(vec!["provider-b".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("DeviceOffline".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Gap, Comparator::SymmetricDifference],
require_closed_windows: false,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
};
let result = compare(&history, &plan);
assert_eq!(result.gap_rows.len(), 1);
assert_eq!(result.gap_rows[0].range.start, 3);
assert_eq!(result.gap_rows[0].range.end, 5);
assert_eq!(result.symmetric_difference_rows.len(), 2);
assert_eq!(
result.symmetric_difference_rows[0].side,
ComparisonSide::Target
);
assert_eq!(
result.symmetric_difference_rows[1].side,
ComparisonSide::Against
);
}
#[test]
fn containment_emits_left_contained_and_right_rows() {
let history = WindowHistoryFixture::new()
.closed_window("DeviceOffline", "device-1", 1, 7, |w| w.source("target"))
.expect("target")
.closed_window("DeviceOffline", "device-1", 3, 5, |w| w.source("container"))
.expect("container")
.build();
let plan = ComparisonPlan {
name: "Containment".to_owned(),
target_source: "target".to_owned(),
against: AgainstSelection::Sources(vec!["container".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("DeviceOffline".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Containment],
require_closed_windows: false,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
};
let result = compare(&history, &plan);
assert_eq!(result.containment_rows.len(), 3);
assert_eq!(
result.containment_rows[0].status,
ContainmentStatus::LeftOverhang
);
assert_eq!(
result.containment_rows[1].status,
ContainmentStatus::Contained
);
assert_eq!(
result.containment_rows[2].status,
ContainmentStatus::RightOverhang
);
}
#[test]
fn lead_lag_and_as_of_emit_expected_rows() {
let history = WindowHistoryFixture::new()
.closed_window("DeviceOffline", "device-1", 1, 4, |w| w.source("target"))
.expect("target")
.closed_window("DeviceOffline", "device-1", 3, 6, |w| {
w.source("comparison")
})
.expect("comparison")
.closed_window("Quote", "selection-1", 10, 11, |w| w.source("trade"))
.expect("trade")
.closed_window("Quote", "selection-1", 7, 20, |w| w.source("quote"))
.expect("quote")
.build();
let lead_lag = compare(
&history,
&ComparisonPlan {
name: "Latency QA".to_owned(),
target_source: "target".to_owned(),
against: AgainstSelection::Sources(vec!["comparison".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("DeviceOffline".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::LeadLag {
transition: LeadLagTransition::Start,
axis: TemporalAxis::ProcessingPosition,
tolerance_magnitude: 5,
}],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
},
);
assert_eq!(lead_lag.lead_lag_rows.len(), 1);
assert_eq!(
lead_lag.lead_lag_rows[0].direction,
LeadLagDirection::TargetLeads
);
assert_eq!(lead_lag.lead_lag_rows[0].delta_magnitude, Some(-2));
assert_eq!(lead_lag.lead_lag_summaries[0].target_lead_count, 1);
let as_of = compare(
&history,
&ComparisonPlan {
name: "Quote at trade".to_owned(),
target_source: "trade".to_owned(),
against: AgainstSelection::Sources(vec!["quote".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("Quote".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::AsOf {
direction: AsOfDirection::Previous,
axis: TemporalAxis::ProcessingPosition,
tolerance_magnitude: 5,
}],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
},
);
assert_eq!(as_of.as_of_rows.len(), 1);
assert_eq!(as_of.as_of_rows[0].status, AsOfMatchStatus::Matched);
assert_eq!(as_of.as_of_rows[0].distance_magnitude, Some(3));
}
#[test]
fn lead_lag_and_as_of_saturate_extreme_temporal_distances() {
let history = WindowHistoryFixture::new()
.closed_window(
"DeviceOffline",
"device-1",
i64::MAX - 1,
i64::MAX,
|window| window.source("target"),
)
.expect("target")
.closed_window(
"DeviceOffline",
"device-1",
i64::MIN,
i64::MIN + 1,
|window| window.source("comparison"),
)
.expect("comparison")
.build();
let plan = ComparisonPlan::new(
"Extreme temporal distance",
"target",
AgainstSelection::Sources(vec!["comparison".to_owned()]),
vec![
Comparator::LeadLag {
transition: LeadLagTransition::Start,
axis: TemporalAxis::ProcessingPosition,
tolerance_magnitude: i64::MAX,
},
Comparator::AsOf {
direction: AsOfDirection::Nearest,
axis: TemporalAxis::ProcessingPosition,
tolerance_magnitude: i64::MAX,
},
],
)
.with_scope_window(Some("DeviceOffline".to_owned()));
let result = compare(&history, &plan);
assert!(result.is_valid);
assert_eq!(result.lead_lag_rows[0].delta_magnitude, Some(i64::MAX));
assert!(result.lead_lag_rows[0].is_within_tolerance);
assert_eq!(result.as_of_rows[0].distance_magnitude, Some(i64::MAX));
assert_eq!(result.as_of_rows[0].status, AsOfMatchStatus::Matched);
}
#[test]
fn timestamp_axis_lead_lag_and_as_of_use_event_time_ranges() {
#[derive(Clone)]
struct QuoteEvent {
selection_id: &'static str,
observed_at: i64,
active: bool,
}
let mut pipeline = crate::for_events::<QuoteEvent>()
.record_windows()
.with_event_time(|event| event.observed_at)
.track_window("Quote", |event| event.selection_id, |event| event.active)
.build()
.expect("valid quote pipeline");
pipeline.ingest(
QuoteEvent {
selection_id: "selection-1",
observed_at: 900,
active: true,
},
Some("quote"),
None,
);
pipeline.ingest(
QuoteEvent {
selection_id: "selection-1",
observed_at: 1_000,
active: true,
},
Some("trade"),
None,
);
pipeline.ingest(
QuoteEvent {
selection_id: "selection-1",
observed_at: 1_100,
active: false,
},
Some("trade"),
None,
);
pipeline.ingest(
QuoteEvent {
selection_id: "selection-1",
observed_at: 1_200,
active: false,
},
Some("quote"),
None,
);
let history = pipeline.history();
let lead_lag = compare(
history,
&ComparisonPlan {
name: "Timestamp latency".to_owned(),
target_source: "trade".to_owned(),
against: AgainstSelection::Sources(vec!["quote".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("Quote".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::LeadLag {
transition: LeadLagTransition::Start,
axis: TemporalAxis::Timestamp,
tolerance_magnitude: 150,
}],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::Timestamp,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
},
);
assert_eq!(lead_lag.lead_lag_rows.len(), 1);
assert_eq!(lead_lag.lead_lag_rows[0].axis, TemporalAxis::Timestamp);
assert_eq!(lead_lag.lead_lag_rows[0].delta_magnitude, Some(100));
assert_eq!(
lead_lag.lead_lag_rows[0].direction,
LeadLagDirection::TargetLags
);
assert!(lead_lag.lead_lag_rows[0].is_within_tolerance);
let as_of = compare(
history,
&ComparisonPlan {
name: "Timestamp quote".to_owned(),
target_source: "trade".to_owned(),
against: AgainstSelection::Sources(vec!["quote".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("Quote".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::AsOf {
direction: AsOfDirection::Previous,
axis: TemporalAxis::Timestamp,
tolerance_magnitude: 150,
}],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::Timestamp,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
},
);
assert_eq!(as_of.as_of_rows.len(), 1);
assert_eq!(as_of.as_of_rows[0].axis, TemporalAxis::Timestamp);
assert_eq!(as_of.as_of_rows[0].status, AsOfMatchStatus::Matched);
assert_eq!(as_of.as_of_rows[0].distance_magnitude, Some(100));
}
#[test]
fn residual_against_all_cohort_requires_every_member_active() {
let history = WindowHistoryFixture::new()
.closed_window("SelectionPriced", "selection-1", 1, 11, |w| {
w.source("source-a")
})
.expect("target")
.closed_window("SelectionPriced", "selection-1", 1, 6, |w| {
w.source("source-b")
})
.expect("b")
.closed_window("SelectionPriced", "selection-1", 6, 11, |w| {
w.source("source-c")
})
.expect("c")
.build();
let result = compare(
&history,
&ComparisonPlan {
name: "cohort all".to_owned(),
target_source: "source-a".to_owned(),
against: AgainstSelection::Cohort {
name: "cohort".to_owned(),
sources: vec!["source-b".to_owned(), "source-c".to_owned()],
activity: CohortActivity::All,
},
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("SelectionPriced".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Residual],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
},
);
let total: i64 = result
.residual_rows
.iter()
.map(|row| row.range.end - row.range.start)
.sum();
assert_eq!(total, 10);
}
#[test]
fn residual_against_threshold_and_none_cohorts_use_activity_rules() {
let threshold_history = WindowHistoryFixture::new()
.closed_window("SelectionPriced", "selection-1", 1, 11, |w| {
w.source("source-a")
})
.expect("target")
.closed_window("SelectionPriced", "selection-1", 1, 11, |w| {
w.source("source-b")
})
.expect("b")
.closed_window("SelectionPriced", "selection-1", 1, 6, |w| {
w.source("source-c")
})
.expect("c")
.closed_window("SelectionPriced", "selection-1", 6, 11, |w| {
w.source("source-d")
})
.expect("d")
.build();
let threshold = compare(
&threshold_history,
&ComparisonPlan {
name: "cohort at least".to_owned(),
target_source: "source-a".to_owned(),
against: AgainstSelection::Cohort {
name: "cohort".to_owned(),
sources: vec![
"source-b".to_owned(),
"source-c".to_owned(),
"source-d".to_owned(),
],
activity: CohortActivity::AtLeast { count: 2 },
},
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("SelectionPriced".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Residual],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
},
);
assert!(threshold.residual_rows.is_empty());
let none_history = WindowHistoryFixture::new()
.closed_window("SelectionPriced", "selection-1", 1, 11, |w| {
w.source("source-a")
})
.expect("target")
.closed_window("SelectionPriced", "selection-1", 1, 6, |w| {
w.source("source-b")
})
.expect("b")
.build();
let none = compare(
&none_history,
&ComparisonPlan {
name: "cohort none".to_owned(),
target_source: "source-a".to_owned(),
against: AgainstSelection::Cohort {
name: "cohort".to_owned(),
sources: vec!["source-b".to_owned(), "source-c".to_owned()],
activity: CohortActivity::None,
},
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("SelectionPriced".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Residual],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
},
);
let total: i64 = none
.residual_rows
.iter()
.map(|row| row.range.end - row.range.start)
.sum();
assert_eq!(total, 5);
}
#[test]
fn live_open_windows_emit_provisional_row_finality() {
let history = WindowHistoryFixture::new()
.open_window("DeviceOffline", "device-1", 1, |w| w.source("provider-a"))
.expect("provider-a")
.closed_window("DeviceOffline", "device-1", 3, 5, |w| {
w.source("provider-b")
})
.expect("provider-b")
.build();
let plan = ComparisonPlan {
name: "Live QA".to_owned(),
target_source: "provider-a".to_owned(),
against: AgainstSelection::Sources(vec!["provider-b".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("DeviceOffline".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Residual],
require_closed_windows: false,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::ClipToHorizon,
open_window_horizon: Some(crate::TemporalPoint::position(10)),
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
};
let result = compare_live(&history, &plan, crate::TemporalPoint::position(10));
assert_eq!(result.residual_rows.len(), 2);
assert!(result.has_provisional_rows());
assert_eq!(result.provisional_row_finalities().len(), 2);
assert_eq!(
result.provisional_row_finalities()[0].finality,
ComparisonFinality::Provisional
);
}
#[test]
fn prepare_excludes_future_windows_at_known_at_position() {
let history = WindowHistoryFixture::new()
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-a").known_at_position(10)
})
.expect("window")
.build();
let plan = ComparisonPlan {
name: "Decision audit".to_owned(),
target_source: "provider-a".to_owned(),
against: AgainstSelection::Sources(vec!["provider-b".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("DeviceOffline".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Overlap],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: Some(crate::TemporalPoint::position(5)),
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
};
let prepared = prepare(&history, &plan);
assert!(prepared.normalized_windows.is_empty());
assert_eq!(prepared.excluded_windows.len(), 1);
assert_eq!(
prepared.excluded_windows[0].diagnostic_code.as_deref(),
Some("FutureWindowExcluded")
);
}
#[test]
fn scope_key_and_partition_filter_selected_windows() {
let history = WindowHistoryFixture::new()
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-a").partition("fleet-a")
})
.expect("target")
.closed_window("DeviceOffline", "device-1", 2, 6, |w| {
w.source("provider-b").partition("fleet-a")
})
.expect("against")
.closed_window("DeviceOffline", "device-2", 1, 5, |w| {
w.source("provider-a").partition("fleet-a")
})
.expect("other key")
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-a").partition("fleet-b")
})
.expect("other partition")
.build();
let plan = ComparisonPlan {
name: "Scoped".to_owned(),
target_source: "provider-a".to_owned(),
against: AgainstSelection::Sources(vec!["provider-b".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("DeviceOffline".to_owned()),
scope_key: Some("device-1".to_owned()),
scope_partition: Some("fleet-a".to_owned()),
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Overlap],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
};
let result = compare(&history, &plan);
assert_eq!(result.overlap_rows.len(), 1);
assert_eq!(result.overlap_rows[0].key, "device-1");
assert_eq!(result.overlap_rows[0].partition.as_deref(), Some("fleet-a"));
assert_eq!(
result.prepared.as_ref().expect("prepared")["selectedWindows"]
.as_array()
.expect("selected windows")
.len(),
2
);
}
#[test]
fn normalization_can_reject_duplicate_windows() {
let history = WindowHistoryFixture::new()
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-a")
})
.expect("target")
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-a")
})
.expect("duplicate target")
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-b")
})
.expect("against")
.build();
let plan = ComparisonPlan {
name: "Duplicate QA".to_owned(),
target_source: "provider-a".to_owned(),
against: AgainstSelection::Sources(vec!["provider-b".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("DeviceOffline".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Overlap],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Reject,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
};
let result = compare(&history, &plan);
assert_eq!(result.overlap_rows.len(), 1);
assert!(
result
.diagnostics
.iter()
.any(|item| item.code == "DuplicateWindow")
);
assert_eq!(result.overlap_rows[0].target_record_ids.len(), 1);
}
#[test]
fn normalization_can_coalesce_adjacent_windows() {
let history = WindowHistoryFixture::new()
.closed_window("DeviceOffline", "device-1", 1, 3, |w| {
w.source("provider-a")
})
.expect("target first")
.closed_window("DeviceOffline", "device-1", 3, 5, |w| {
w.source("provider-a")
})
.expect("target second")
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-b")
})
.expect("against")
.build();
let plan = ComparisonPlan {
name: "Coalesce QA".to_owned(),
target_source: "provider-a".to_owned(),
against: AgainstSelection::Sources(vec!["provider-b".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("DeviceOffline".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Overlap],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: true,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
};
let result = compare(&history, &plan);
assert_eq!(result.overlap_rows.len(), 1);
assert_eq!(result.overlap_rows[0].range.start, 1);
assert_eq!(result.overlap_rows[0].range.end, 5);
assert_eq!(result.overlap_rows[0].target_record_ids.len(), 2);
}
#[test]
fn runtime_critic_warns_for_broad_scope_and_future_leakage_risk() {
let history = WindowHistoryFixture::new()
.closed_window("Quote", "selection-1", 10, 11, |w| w.source("trade"))
.expect("trade")
.closed_window("Quote", "selection-1", 7, 20, |w| w.source("quote"))
.expect("quote")
.build();
let plan = ComparisonPlan {
name: "Runtime critic".to_owned(),
target_source: "trade".to_owned(),
against: AgainstSelection::Sources(vec!["quote".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: None,
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::AsOf {
direction: AsOfDirection::Previous,
axis: TemporalAxis::ProcessingPosition,
tolerance_magnitude: 5,
}],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
};
let result = compare(&history, &plan);
assert!(result.is_valid);
assert!(
result
.warning_diagnostics()
.iter()
.any(|item| item.code == "BroadSelector")
);
assert!(
result
.warning_diagnostics()
.iter()
.any(|item| item.code == "FutureLeakageRisk")
);
}
#[test]
fn runtime_selector_plans_execute_locally_and_emit_warning() {
let history = WindowHistoryFixture::new()
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-a")
})
.expect("target")
.closed_window("DeviceOffline", "device-1", 3, 7, |w| {
w.source("provider-b")
})
.expect("against")
.build();
let result = history
.compare("Runtime selector QA")
.target_selector(ComparisonSelector::runtime_only(
"dynamic-target",
"runtime target predicate",
|window| window.source() == Some("provider-a"),
))
.against_selector(ComparisonSelector::for_source("provider-b"))
.scope_window("DeviceOffline")
.overlap()
.run();
assert!(result.is_valid);
assert_eq!(result.overlap_rows.len(), 1);
assert_eq!(
result.prepared.as_ref().expect("prepared")["normalizedWindows"][0]["selectorName"],
"dynamic-target"
);
assert!(result.diagnostics.iter().any(|diagnostic| {
diagnostic.code == "RuntimeNonSerializablePlan"
&& diagnostic.severity == DiagnosticSeverity::Warning
}));
}
#[test]
fn strict_runtime_selector_plan_blocks_materialization() {
let history = WindowHistoryFixture::new()
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-a")
})
.expect("target")
.closed_window("DeviceOffline", "device-1", 3, 7, |w| {
w.source("provider-b")
})
.expect("against")
.build();
let result = history
.compare("Strict runtime selector QA")
.target_selector(ComparisonSelector::runtime_only(
"dynamic-target",
"runtime target predicate",
|window| window.source() == Some("provider-a"),
))
.against_selector(ComparisonSelector::for_source("provider-b"))
.scope_window("DeviceOffline")
.overlap()
.strict()
.run();
assert!(!result.is_valid);
assert!(result.aligned.is_none());
assert!(result.overlap_rows.is_empty());
assert!(result.diagnostics.iter().any(|diagnostic| {
diagnostic.code == "RuntimeNonSerializablePlan"
&& diagnostic.severity == DiagnosticSeverity::Error
}));
}
#[test]
fn strict_runtime_critic_blocks_rows_and_alignment() {
let history = WindowHistoryFixture::new()
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-a")
})
.expect("target")
.closed_window("DeviceOffline", "device-1", 3, 6, |w| {
w.source("provider-b")
})
.expect("against")
.build();
let plan = ComparisonPlan {
name: "Strict broad".to_owned(),
target_source: "provider-a".to_owned(),
against: AgainstSelection::Sources(vec!["provider-b".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: None,
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Overlap],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: true,
};
let result = compare(&history, &plan);
assert!(!result.is_valid);
assert!(result.aligned.is_none());
assert!(result.overlap_rows.is_empty());
assert!(
result
.error_diagnostics()
.iter()
.any(|item| item.code == "BroadSelector")
);
}
#[test]
fn runtime_critic_reports_unbounded_open_duration() {
let history = WindowHistoryFixture::new()
.open_window("DeviceOffline", "device-1", 1, |w| w.source("provider-a"))
.expect("provider-a")
.build();
let plan = ComparisonPlan {
name: "Open QA".to_owned(),
target_source: "provider-a".to_owned(),
against: AgainstSelection::Sources(vec!["provider-b".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("DeviceOffline".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Overlap],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
};
let result = compare(&history, &plan);
assert!(!result.is_valid);
assert!(
result
.diagnostics
.iter()
.any(|item| item.code == "OpenWindowsWithoutPolicy")
);
assert!(
result
.diagnostics
.iter()
.any(|item| item.code == "UnboundedOpenDuration")
);
}
#[test]
fn runtime_critic_reports_live_finality_without_horizon() {
let history = WindowHistoryFixture::new().build();
let plan = ComparisonPlan {
name: "Live QA".to_owned(),
target_source: "provider-a".to_owned(),
against: AgainstSelection::Sources(vec!["provider-b".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("DeviceOffline".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Overlap],
require_closed_windows: false,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::ClipToHorizon,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
};
let result = compare(&history, &plan);
assert!(result.is_valid);
assert!(
result
.warning_diagnostics()
.iter()
.any(|item| item.code == "LiveFinalityWithoutHorizon")
);
}
#[test]
fn runtime_critic_reports_mixed_timestamp_clocks() {
let history = WindowHistoryFixture::new().build();
let plan = ComparisonPlan {
name: "Clock QA".to_owned(),
target_source: "provider-a".to_owned(),
against: AgainstSelection::Sources(vec!["provider-b".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("DeviceOffline".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Overlap],
require_closed_windows: false,
use_half_open_ranges: true,
time_axis: TemporalAxis::Timestamp,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: Some(crate::TemporalPoint::timestamp_ticks_with_clock(
1, "received",
)),
open_window_policy: OpenWindowPolicy::ClipToHorizon,
open_window_horizon: Some(crate::TemporalPoint::timestamp_ticks_with_clock(
1, "provider",
)),
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
};
let result = compare(&history, &plan);
assert!(result.diagnostics.iter().any(|diagnostic| {
diagnostic.code == "MixedClockRisk"
&& diagnostic.severity == DiagnosticSeverity::Warning
}));
}
#[test]
fn closed_windows_default_known_at_to_close_position() {
let history = WindowHistoryFixture::new()
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-a")
})
.expect("window")
.build();
let plan = ComparisonPlan {
name: "Decision audit".to_owned(),
target_source: "provider-a".to_owned(),
against: AgainstSelection::Sources(vec!["provider-b".to_owned()]),
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("DeviceOffline".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Overlap],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: Some(crate::TemporalPoint::position(4)),
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
};
let prepared = prepare(&history, &plan);
assert!(prepared.normalized_windows.is_empty());
assert_eq!(prepared.excluded_windows.len(), 1);
assert_eq!(
prepared.excluded_windows[0].diagnostic_code.as_deref(),
Some("FutureWindowExcluded")
);
}
#[test]
fn event_time_normalization_excludes_position_only_windows_by_policy() {
let history = WindowHistoryFixture::new()
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-a")
})
.expect("target")
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-b")
})
.expect("against")
.build();
let result = history
.compare("Event-time QA")
.target_source("provider-a")
.against_source("provider-b")
.scope_window("DeviceOffline")
.normalization(
ComparisonNormalizationPolicy::event_time().excluding_missing_event_time(),
)
.overlap()
.run();
assert!(result.is_valid);
assert!(result.overlap_rows.is_empty());
assert!(
result
.diagnostics
.iter()
.any(|diagnostic| diagnostic.code == "MissingEventTime"
&& diagnostic.severity == DiagnosticSeverity::Warning)
);
}
#[test]
fn event_time_normalization_rejects_position_only_windows_by_default() {
let history = WindowHistoryFixture::new()
.closed_window("DeviceOffline", "device-1", 1, 5, |w| {
w.source("provider-a")
})
.expect("target")
.build();
let result = history
.compare("Event-time QA")
.target_source("provider-a")
.against_source("provider-b")
.scope_window("DeviceOffline")
.normalization(ComparisonNormalizationPolicy::event_time())
.overlap()
.run();
assert!(!result.is_valid);
assert!(
result
.diagnostics
.iter()
.any(|diagnostic| diagnostic.code == "MissingEventTime"
&& diagnostic.severity == DiagnosticSeverity::Error)
);
}
#[test]
fn cohort_comparison_emits_extension_metadata_and_parsed_evidence() {
let history = WindowHistoryFixture::new()
.closed_window("SelectionPriced", "selection-1", 1, 11, |w| {
w.source("source-a")
})
.expect("target")
.closed_window("SelectionPriced", "selection-1", 1, 6, |w| {
w.source("source-b")
})
.expect("b")
.closed_window("SelectionPriced", "selection-1", 6, 11, |w| {
w.source("source-c")
})
.expect("c")
.build();
let result = compare(
&history,
&ComparisonPlan {
name: "cohort evidence".to_owned(),
target_source: "source-a".to_owned(),
against: AgainstSelection::Cohort {
name: "cohort".to_owned(),
sources: vec!["source-b".to_owned(), "source-c".to_owned()],
activity: CohortActivity::All,
},
target_selector: None,
against_selectors: Vec::new(),
scope_window: Some("SelectionPriced".to_owned()),
scope_key: None,
scope_partition: None,
scope_segments: Vec::new(),
scope_tags: Vec::new(),
comparators: vec![Comparator::Residual],
require_closed_windows: true,
use_half_open_ranges: true,
time_axis: TemporalAxis::ProcessingPosition,
null_timestamp_policy: ComparisonNullTimestampPolicy::Reject,
known_at: None,
open_window_policy: OpenWindowPolicy::RequireClosed,
open_window_horizon: None,
coalesce_adjacent_windows: false,
duplicate_window_policy: ComparisonDuplicateWindowPolicy::Preserve,
output: crate::ComparisonOutputOptions::default_options(),
strict: false,
},
);
assert!(!result.extension_metadata.is_empty());
let evidence = result.cohort_evidence();
assert_eq!(evidence.len(), 2);
assert!(!evidence[0].is_active);
assert!(!evidence[1].is_active);
}
}