From 52ffc72f37ea1210fdb55688dadb8e7f1a46c246 Mon Sep 17 00:00:00 2001 From: ZZJJWarth <2678328250@qq.com> Date: Sun, 25 Oct 2026 16:28:00 +0800 Subject: [PATCH 1/3] feat(chronos): add device clock model estimation Device timestamps need a versioned conversion to reference time. Add a deterministic model estimator with bounded observation windows, drift and uncertainty limits, counter wrap handling, and generation-aware resets. Support step and bounded slew updates and preserve retained model identity when refreshing a later generation after a fault. Validate 32 model tests, including the retained-model regression, and workspace format, clippy, build and tests. Assisted-by: Codex:gpt-6 --- Cargo.lock | 8 + Cargo.toml | 1 + system/chronos/Cargo.toml | 10 + system/chronos/README.md | 20 +- system/chronos/src/core.rs | 937 ++++++++++++++++++++++++++++++++ system/chronos/src/lib.rs | 14 + system/chronos/src/model.rs | 411 ++++++++++++++ system/chronos/src/snapshot.rs | 48 ++ system/chronos/tests/core.rs | 943 +++++++++++++++++++++++++++++++++ 9 files changed, 2378 insertions(+), 14 deletions(-) create mode 100644 system/chronos/Cargo.toml create mode 100644 system/chronos/src/core.rs create mode 100644 system/chronos/src/lib.rs create mode 100644 system/chronos/src/model.rs create mode 100644 system/chronos/src/snapshot.rs create mode 100644 system/chronos/tests/core.rs diff --git a/Cargo.lock b/Cargo.lock index 0b79b3c58..e63698fe9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3185,6 +3185,14 @@ dependencies = [ "walkdir", ] +[[package]] +name = "robonix-chronos" +version = "1.1.0-beta.1" +dependencies = [ + "serde", + "thiserror 2.0.18", +] + [[package]] name = "robonix-chronos-clock" version = "1.1.0" diff --git a/Cargo.toml b/Cargo.toml index b7565868d..59f5e0dfb 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -14,6 +14,7 @@ members = [ "system/atlas", "system/chronos/clock", + "system/chronos", "system/executor", "system/liaison", "system/pilot", diff --git a/system/chronos/Cargo.toml b/system/chronos/Cargo.toml new file mode 100644 index 000000000..93d34f96d --- /dev/null +++ b/system/chronos/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "robonix-chronos" +version.workspace = true +edition.workspace = true +license.workspace = true +description = "Robonix Chronos clock-domain models" + +[dependencies] +serde.workspace = true +thiserror.workspace = true diff --git a/system/chronos/README.md b/system/chronos/README.md index d5440976d..e81562973 100644 --- a/system/chronos/README.md +++ b/system/chronos/README.md @@ -1,19 +1,11 @@ -# Chronos — unified time +# Chronos -One of the 12 Robonix system components. Provides a single monotonic -time source plus PTP / IEEE-1588 alignment between hardware (lidar, -camera, IMU, chassis odometry) and the runtime. +`robonix-chronos` provides `ChronosCore`: a deterministic device-to-reference clock model library. Register a clock domain and policy, submit paired `ClockObservation` values, then query status, model coefficients or conversions. It does not read host clocks or run a process. -**Status — v0.1 stub.** Not yet implemented. +The core bounds its observation window, checks integer conversion overflow, tracks reference/device generations, and handles wrap, outliers, holdover and reset. Model updates support step and bounded slew. -For now, components read system wall time / per-sensor timestamps -directly. Scene / mapping fuse multimodal data on their own. Chronos -will absorb that responsibility in v0.2. +Refreshing a new generation preserves retained models from earlier generations; their freshness cannot be computed from the new observations. -When implemented, Chronos will: +Outlier checks include the configured drift allowance over steady time since the last accepted observation, so permitted rate changes and observations within holdover uncertainty can update the model. Larger residuals remain rejected. -- expose a single `time/now` capability returning a monotonic, machine- - global time stamp consistent with sensor headers, -- run a PTP master/slave loop (1588v2) to discipline NIC clocks across - the body's compute units, -- emit drift / sync-quality metrics to [vitals](../vitals/). +Run `cargo test -p robonix-chronos --test core`. diff --git a/system/chronos/src/core.rs b/system/chronos/src/core.rs new file mode 100644 index 000000000..50b635334 --- /dev/null +++ b/system/chronos/src/core.rs @@ -0,0 +1,937 @@ +// SPDX-License-Identifier: MulanPSL-2.0 + +use std::collections::{HashMap, VecDeque}; + +use crate::model::{ + ChronosError, ClockDomainDescriptor, ClockDomainPolicy, ClockModel, ClockObservation, + ConversionResult, DomainState, DomainStatus, ModelUpdatePolicy, PARTS_PER_BILLION, + divide_rounded, +}; + +#[derive(Debug, Clone)] +struct Sample { + device_timestamp_ns: i64, + reference_timestamp_ns: i64, + uncertainty_ns: u64, +} + +#[derive(Debug, Clone)] +struct DomainRecord { + descriptor: ClockDomainDescriptor, + policy: ClockDomainPolicy, + generation: u64, + reference_generation: u64, + model_version: u64, + state: DomainState, + reason: String, + samples: VecDeque, + model: Option, + fitted_uncertainty_ns: u64, + wrap_offset_ns: i128, + last_raw_device_ns: Option, + last_reference_ns: Option, + last_seen_sequence_id: Option, + last_seen_steady_ns: Option, + last_observation_steady_ns: Option, + accepted_observations: u64, + rejected_observations: u64, +} + +/// In-process registry and model estimator for device clock domains. +#[derive(Debug, Clone)] +pub struct ChronosCore { + domains: HashMap, + reference_generation: u64, + reference_available: bool, +} + +impl Default for ChronosCore { + fn default() -> Self { + Self { + domains: HashMap::new(), + reference_generation: 1, + reference_available: true, + } + } +} + +impl ChronosCore { + /// Construct an empty core without reading any operating-system clock. + pub fn new() -> Self { + Self::default() + } + + /// Return the generation of the reference clock used by all domain models. + pub fn reference_generation(&self) -> u64 { + self.reference_generation + } + + /// Apply a reference generation and restart fitting for every device domain. + /// + /// Equal generations are idempotent. Older or zero generations are + /// rejected. The last estimate remains available with its old reference + /// identity while the reset is committed atomically across all domains. + pub fn update_reference_generation(&mut self, generation: u64) -> Result<(), ChronosError> { + if generation == 0 || generation < self.reference_generation { + return Err(ChronosError::ReferenceGenerationOutOfOrder { + current: self.reference_generation, + received: generation, + }); + } + if generation == self.reference_generation { + return Ok(()); + } + let mut reset_domains = self.domains.clone(); + for record in reset_domains.values_mut() { + begin_new_generation(record, true)?; + record.reference_generation = generation; + record.reason = "reference generation changed; retaining previous model".to_string(); + } + self.domains = reset_domains; + self.reference_generation = generation; + Ok(()) + } + + /// Store reference availability as an orthogonal quality dimension. + /// + /// Domain state and diagnostics are retained across reference outages. + /// Status and conversion queries overlay unavailable reference quality + /// without mutating the fitted model or hiding an existing domain fault. + pub fn update_reference_availability(&mut self, available: bool) -> Result<(), ChronosError> { + if available == self.reference_available { + return Ok(()); + } + let mut updated = self.domains.clone(); + for record in updated.values_mut() { + record.model_version = record + .model_version + .checked_add(1) + .ok_or(ChronosError::Overflow)?; + if let Some(model) = record.model.as_mut() { + model.model_version = model + .model_version + .checked_add(1) + .ok_or(ChronosError::Overflow)?; + } + } + self.domains = updated; + self.reference_available = available; + Ok(()) + } + + /// Register a domain after validating its static facts and quality policy. + pub fn register( + &mut self, + descriptor: ClockDomainDescriptor, + policy: ClockDomainPolicy, + ) -> Result { + descriptor.validate()?; + policy.validate()?; + if self.domains.contains_key(&descriptor.domain_id) { + return Err(ChronosError::DuplicateDomain(descriptor.domain_id)); + } + let domain_id = descriptor.domain_id.clone(); + let record = DomainRecord { + descriptor, + policy, + generation: 1, + reference_generation: self.reference_generation, + model_version: 0, + state: DomainState::Initializing, + reason: "collecting observations".to_string(), + samples: VecDeque::new(), + model: None, + fitted_uncertainty_ns: 0, + wrap_offset_ns: 0, + last_raw_device_ns: None, + last_reference_ns: None, + last_seen_sequence_id: None, + last_seen_steady_ns: None, + last_observation_steady_ns: None, + accepted_observations: 0, + rejected_observations: 0, + }; + self.domains.insert(domain_id.clone(), record); + self.status(&domain_id, 0) + } + + /// Remove a domain and all models and observations associated with it. + pub fn unregister(&mut self, domain_id: &str) -> Result<(), ChronosError> { + self.domains + .remove(domain_id) + .map(|_| ()) + .ok_or_else(|| ChronosError::UnknownDomain(domain_id.to_string())) + } + + /// Start a new generation after a confirmed device restart or reference change. + pub fn reset(&mut self, domain_id: &str) -> Result { + let record = self + .domains + .get_mut(domain_id) + .ok_or_else(|| ChronosError::UnknownDomain(domain_id.to_string()))?; + begin_new_generation(record, false)?; + Ok(status_from_record( + domain_id, + record, + 0, + self.reference_available, + )) + } + + /// Validate and incorporate one paired observation into a domain model. + /// + /// Device or reference time regression starts a new generation unless the + /// device regression matches the descriptor's declared counter wrap. + pub fn observe( + &mut self, + domain_id: &str, + observation: ClockObservation, + ) -> Result { + if !self.reference_available { + return Err(ChronosError::ReferenceUnavailable); + } + let record = self + .domains + .get_mut(domain_id) + .ok_or_else(|| ChronosError::UnknownDomain(domain_id.to_string()))?; + if let Err(error) = validate_observation_order(record, &observation) { + record.rejected_observations = record.rejected_observations.saturating_add(1); + return Err(error); + } + if let Err(error) = validate_observation_value(record, &observation) { + record.rejected_observations = record.rejected_observations.saturating_add(1); + record.last_seen_sequence_id = Some(observation.sequence_id); + record.last_seen_steady_ns = Some(observation.steady_received_ns); + return Err(error); + } + let reset = observation_requires_reset(record, &observation); + let mut candidate = record.clone(); + if reset { + begin_new_generation(&mut candidate, false)?; + } + let normalized_device = + match normalize_observation(&mut candidate, observation.device_timestamp_ns) { + Ok(value) => value, + Err(error) => { + mark_fault(record, &observation); + return Err(error); + } + }; + let outlier = match is_outlier(&candidate, normalized_device, &observation) { + Ok(value) => value, + Err(error) => { + mark_fault(record, &observation); + return Err(error); + } + }; + if outlier { + let predicted = match candidate + .model + .as_ref() + .expect("outlier checks require a model") + .extrapolate_normalized(normalized_device) + { + Ok(value) => value, + Err(error) => { + mark_fault(record, &observation); + return Err(error); + } + }; + let residual_ns = + match absolute_difference(predicted, observation.reference_timestamp_ns) { + Ok(value) => value, + Err(error) => { + mark_fault(record, &observation); + return Err(error); + } + }; + record.rejected_observations = record.rejected_observations.saturating_add(1); + record.last_seen_sequence_id = Some(observation.sequence_id); + record.last_seen_steady_ns = Some(observation.steady_received_ns); + let limit_ns = outlier_limit(&candidate, &observation)?; + return Err(ChronosError::ObservationOutlier { + residual_ns, + limit_ns, + }); + } + if let Err(error) = + accept_observation(&mut candidate, normalized_device, observation.clone()) + { + mark_fault(record, &observation); + return Err(error); + } + if let Err(error) = update_model(&mut candidate) { + mark_fault(record, &observation); + return Err(error); + } + *record = candidate; + Ok(status_from_record( + domain_id, + record, + record.last_observation_steady_ns.unwrap_or(0), + self.reference_available, + )) + } + + /// Return an owned model with current reference quality applied. + pub fn model(&self, domain_id: &str) -> Result { + let mut model = self.stored_model(domain_id)?.clone(); + if !self.reference_available { + if model.state != DomainState::Fault { + model.state = DomainState::Unsynced; + } + model.uncertainty_ns = u64::MAX; + } + Ok(model) + } + + /// Borrow coefficients without applying orthogonal reference quality. + fn stored_model(&self, domain_id: &str) -> Result<&ClockModel, ChronosError> { + let record = self + .domains + .get(domain_id) + .ok_or_else(|| ChronosError::UnknownDomain(domain_id.to_string()))?; + record + .model + .as_ref() + .ok_or(ChronosError::ModelUnavailable(record.state)) + } + + /// Convert a timestamp with the latest model and return its exact identity. + pub fn convert( + &self, + domain_id: &str, + device_timestamp_ns: i64, + ) -> Result { + let mut result = self.stored_model(domain_id)?.convert(device_timestamp_ns)?; + if !self.reference_available { + if result.state != DomainState::Fault { + result.state = DomainState::Unsynced; + } + result.uncertainty_ns = u64::MAX; + } + Ok(result) + } + + /// Return current status with age measured only against monotonic input. + pub fn status( + &self, + domain_id: &str, + now_steady_ns: u64, + ) -> Result { + let record = self + .domains + .get(domain_id) + .ok_or_else(|| ChronosError::UnknownDomain(domain_id.to_string()))?; + if record + .last_seen_steady_ns + .is_some_and(|last| now_steady_ns < last) + { + return Err(ChronosError::ObservationOutOfOrder); + } + Ok(status_from_record( + domain_id, + record, + now_steady_ns, + self.reference_available, + )) + } + + /// Advance mature domains through holdover and unsynchronized states. + /// + /// Uncertainty grows from the fitted value using the configured drift + /// bound. Each externally visible change produces a new model version. + pub fn refresh(&mut self, now_steady_ns: u64) -> Result<(), ChronosError> { + if self + .domains + .values() + .filter_map(|record| record.last_seen_steady_ns) + .any(|last| now_steady_ns < last) + { + return Err(ChronosError::ObservationOutOfOrder); + } + let mut refreshed = self.domains.clone(); + for record in refreshed.values_mut() { + refresh_record(record, now_steady_ns)?; + } + self.domains = refreshed; + Ok(()) + } +} + +/// Require strictly increasing sequence and monotonic receipt values. +fn validate_observation_order( + record: &DomainRecord, + observation: &ClockObservation, +) -> Result<(), ChronosError> { + let sequence_is_old = record + .last_seen_sequence_id + .is_some_and(|sequence| observation.sequence_id <= sequence); + let steady_is_old = record + .last_seen_steady_ns + .is_some_and(|steady| observation.steady_received_ns <= steady); + if sequence_is_old || steady_is_old { + return Err(ChronosError::ObservationOutOfOrder); + } + Ok(()) +} + +/// Distinguish declared counter wrap from a reset or reference regression. +fn observation_requires_reset(record: &DomainRecord, observation: &ClockObservation) -> bool { + let device_reset = record.last_raw_device_ns.is_some_and(|last| { + if observation.device_timestamp_ns >= last { + return false; + } + let regression = i128::from(last) - i128::from(observation.device_timestamp_ns); + record + .descriptor + .wrap_period_ns + .is_none_or(|period| regression <= i128::from(period) / 2) + }); + let reference_reset = record + .last_reference_ns + .is_some_and(|last| observation.reference_timestamp_ns < last); + device_reset || reference_reset +} + +/// Clear generation-specific history while optionally retaining a stale model. +fn begin_new_generation(record: &mut DomainRecord, retain_model: bool) -> Result<(), ChronosError> { + record.generation = record + .generation + .checked_add(1) + .ok_or(ChronosError::Overflow)?; + if retain_model { + if let Some(model) = record.model.as_mut() { + model.model_version = model + .model_version + .checked_add(1) + .ok_or(ChronosError::Overflow)?; + model.state = DomainState::Unsynced; + } + } else { + record.model = None; + } + record.model_version = 0; + record.state = DomainState::Reset; + record.reason = "clock reset or time regression".to_string(); + record.samples.clear(); + record.fitted_uncertainty_ns = 0; + record.wrap_offset_ns = 0; + record.last_raw_device_ns = None; + record.last_reference_ns = None; + record.last_seen_sequence_id = None; + record.last_observation_steady_ns = None; + Ok(()) +} + +/// Require wrapping counters to use their declared canonical raw range. +fn validate_observation_value( + record: &DomainRecord, + observation: &ClockObservation, +) -> Result<(), ChronosError> { + if let Some(period) = record.descriptor.wrap_period_ns + && (observation.device_timestamp_ns < 0 || observation.device_timestamp_ns >= period as i64) + { + return Err(ChronosError::InvalidObservation( + "device timestamp is outside the declared wrap period".to_string(), + )); + } + if let (Some(period), Some(previous_steady)) = ( + record.descriptor.wrap_period_ns, + record.last_observation_steady_ns, + ) { + let elapsed = observation.steady_received_ns - previous_steady; + let maximum_rate = 1_000_000 + u128::from(record.policy.max_drift_ppm); + let ambiguous_after = (u128::from(period) * 1_000_000).div_ceil(maximum_rate * 2); + if u128::from(elapsed) >= ambiguous_after { + return Err(ChronosError::InvalidObservation( + "counter wrap is ambiguous after observation gap; reset the domain".into(), + )); + } + } + if record + .last_raw_device_ns + .is_some_and(|last| observation.device_timestamp_ns == last) + { + return Err(ChronosError::InvalidObservation( + "device timestamp repeats the previous observation".to_string(), + )); + } + Ok(()) +} + +/// Extend a declared wrapping counter into a generation-local signed timeline. +fn normalize_observation(record: &mut DomainRecord, raw: i64) -> Result { + if let (Some(last), Some(period)) = + (record.last_raw_device_ns, record.descriptor.wrap_period_ns) + && raw < last + && i128::from(last) - i128::from(raw) > i128::from(period) / 2 + { + record.wrap_offset_ns = record + .wrap_offset_ns + .checked_add(i128::from(period)) + .ok_or(ChronosError::Overflow)?; + } + let normalized = i128::from(raw) + .checked_add(record.wrap_offset_ns) + .ok_or(ChronosError::Overflow)?; + i64::try_from(normalized).map_err(|_| ChronosError::Overflow) +} + +/// Reject only clear residual violations from an already usable model. +fn is_outlier( + record: &DomainRecord, + normalized_device_ns: i64, + observation: &ClockObservation, +) -> Result { + if !matches!(record.state, DomainState::Tracking | DomainState::Holdover) { + return Ok(false); + } + let Some(model) = record.model.as_ref() else { + return Ok(false); + }; + let predicted = model.extrapolate_normalized(normalized_device_ns)?; + let residual = absolute_difference(predicted, observation.reference_timestamp_ns)?; + Ok(residual > outlier_limit(record, observation)?) +} + +fn outlier_limit( + record: &DomainRecord, + observation: &ClockObservation, +) -> Result { + let elapsed_ns = record + .last_observation_steady_ns + .map_or(0, |last| observation.steady_received_ns - last); + // Policy bounds absolute drift; residuals are relative to the fitted rate. + let rate_bound_ppb = u128::from(record.policy.max_drift_ppm) * 1_000 + + record + .model + .as_ref() + .map_or(0, |model| u128::from(model.rate_adjust_ppb.unsigned_abs())); + // A windowed fit may still lag the latest accepted sample during a rate change. + let latest_residual = match (record.model.as_ref(), record.samples.back()) { + (Some(model), Some(sample)) => absolute_difference( + model.extrapolate_normalized(sample.device_timestamp_ns)?, + sample.reference_timestamp_ns, + )?, + _ => 0, + }; + Ok(record + .policy + .max_residual_ns + .saturating_add(record.fitted_uncertainty_ns.max(latest_residual)) + .saturating_add(drift_allowance_ns(elapsed_ns, rate_bound_ppb)) + .saturating_add(observation.uncertainty_ns)) +} + +fn drift_allowance_ns(elapsed_ns: u64, rate_bound_ppb: u128) -> u64 { + let growth = u128::from(elapsed_ns) + .saturating_mul(rate_bound_ppb) + .div_ceil(1_000_000_000); + u64::try_from(growth).unwrap_or(u64::MAX) +} + +/// Store one accepted sample and its ordering boundary before fitting. +fn accept_observation( + record: &mut DomainRecord, + normalized_device_ns: i64, + observation: ClockObservation, +) -> Result<(), ChronosError> { + record.samples.push_back(Sample { + device_timestamp_ns: normalized_device_ns, + reference_timestamp_ns: observation.reference_timestamp_ns, + uncertainty_ns: observation.uncertainty_ns, + }); + while record.samples.len() > record.policy.observation_window { + record.samples.pop_front(); + } + record.last_raw_device_ns = Some(observation.device_timestamp_ns); + record.last_reference_ns = Some(observation.reference_timestamp_ns); + record.last_seen_sequence_id = Some(observation.sequence_id); + record.last_seen_steady_ns = Some(observation.steady_received_ns); + record.last_observation_steady_ns = Some(observation.steady_received_ns); + record.accepted_observations = record + .accepted_observations + .checked_add(1) + .ok_or(ChronosError::Overflow)?; + Ok(()) +} + +/// Make an internal processing failure visible without committing staged samples. +fn mark_fault(record: &mut DomainRecord, observation: &ClockObservation) { + record.state = DomainState::Fault; + record.reason = "clock model processing failed".to_string(); + record.model_version = record.model_version.saturating_add(1); + record.rejected_observations = record.rejected_observations.saturating_add(1); + record.last_seen_sequence_id = Some(observation.sequence_id); + record.last_seen_steady_ns = Some(observation.steady_received_ns); + if let Some(model) = record.model.as_mut() { + model.state = DomainState::Fault; + model.model_version = if model.generation == record.generation + && model.reference_generation == record.reference_generation + { + record.model_version + } else { + model.model_version.saturating_add(1) + }; + } +} + +/// Fit or update an affine model once the domain has enough observations. +fn update_model(record: &mut DomainRecord) -> Result<(), ChronosError> { + if record.samples.len() < record.policy.minimum_observations { + if record.state != DomainState::Reset { + record.state = DomainState::Initializing; + record.reason = "collecting observations".to_string(); + } + return Ok(()); + } + let mut fit = fit_samples(&record.samples)?; + fit.uncertainty_ns = fit + .uncertainty_ns + .saturating_add(record.descriptor.resolution_ns); + let drift_limit_ppb = i128::from(record.policy.max_drift_ppm) + .checked_mul(1_000) + .ok_or(ChronosError::Overflow)?; + let next_version = record + .model_version + .checked_add(1) + .ok_or(ChronosError::Overflow)?; + let mut model = build_model(record, &fit, next_version, DomainState::Tracking)?; + apply_model_update_policy( + record.policy.model_update, + record.model.as_ref(), + &mut model, + &mut fit, + )?; + let quality_ok = i128::from(fit.rate_adjust_ppb).abs() <= drift_limit_ppb + && fit.uncertainty_ns <= record.policy.max_uncertainty_ns; + let state = if quality_ok { + DomainState::Tracking + } else { + DomainState::Unsynced + }; + model.state = state; + model.uncertainty_ns = fit.uncertainty_ns; + record.state = state; + record.reason = if quality_ok { + "model satisfies clock domain policy".to_string() + } else { + "drift or uncertainty exceeds clock domain policy".to_string() + }; + record.model_version = next_version; + record.fitted_uncertainty_ns = fit.uncertainty_ns; + record.model = Some(model); + Ok(()) +} + +/// Bound the phase correction at the latest sample using elapsed observation steady time. +/// Step uses the fit directly; slew includes its remaining offset in reported uncertainty. +fn apply_model_update_policy( + policy: ModelUpdatePolicy, + previous: Option<&ClockModel>, + next: &mut ClockModel, + fit: &mut Fit, +) -> Result<(), ChronosError> { + let ModelUpdatePolicy::Slew { max_correction_ppm } = policy else { + return Ok(()); + }; + let Some(previous) = previous.filter(|model| { + model.generation == next.generation + && model.reference_generation == next.reference_generation + }) else { + return Ok(()); + }; + let boundary = i128::from(next.latest_raw_device_ns) + .checked_add(i128::from(next.wrap_offset_ns)) + .and_then(|value| i64::try_from(value).ok()) + .ok_or(ChronosError::Overflow)?; + let old_reference = previous.extrapolate_normalized(boundary)?; + let new_reference = next.extrapolate_normalized(boundary)?; + let elapsed = next + .last_observation_steady_ns + .checked_sub(previous.last_observation_steady_ns) + .ok_or(ChronosError::ObservationOutOfOrder)?; + let budget = i128::from(elapsed) + .checked_mul(i128::from(max_correction_ppm)) + .ok_or(ChronosError::Overflow)? + / 1_000_000; + let requested = i128::from(new_reference) - i128::from(old_reference); + let correction = requested.clamp(-budget, budget) - requested; + if correction != 0 { + let correction = i64::try_from(correction).map_err(|_| ChronosError::Overflow)?; + next.residual_offset_ns = next + .residual_offset_ns + .checked_add(correction) + .ok_or(ChronosError::Overflow)?; + fit.residual_offset_ns = next.residual_offset_ns; + fit.uncertainty_ns = fit.uncertainty_ns.saturating_add(correction.unsigned_abs()); + } + Ok(()) +} + +#[derive(Debug)] +struct Fit { + device_anchor_ns: i64, + reference_anchor_ns: i64, + rate_adjust_ppb: i64, + residual_offset_ns: i64, + uncertainty_ns: u64, +} + +/// Fit centered least squares without converting epoch-sized values to floats. +fn fit_samples(samples: &VecDeque) -> Result { + let first = samples.front().expect("fitting requires observations"); + let count = samples.len() as f64; + let mut sum_x = 0.0; + let mut sum_y = 0.0; + for sample in samples { + sum_x += + (i128::from(sample.device_timestamp_ns) - i128::from(first.device_timestamp_ns)) as f64; + sum_y += (i128::from(sample.reference_timestamp_ns) + - i128::from(first.reference_timestamp_ns)) as f64; + } + let mean_x = sum_x / count; + let mean_y = sum_y / count; + let mut covariance = 0.0; + let mut variance = 0.0; + for sample in samples { + let x = + (i128::from(sample.device_timestamp_ns) - i128::from(first.device_timestamp_ns)) as f64; + let y = (i128::from(sample.reference_timestamp_ns) + - i128::from(first.reference_timestamp_ns)) as f64; + covariance += (x - mean_x) * (y - mean_y); + variance += (x - mean_x) * (x - mean_x); + } + if variance == 0.0 { + return Err(ChronosError::InvalidObservation( + "device observations do not advance".to_string(), + )); + } + finish_fit(samples, first, covariance / variance) +} + +/// Convert the floating-point slope into a centered integer clock model. +fn finish_fit(samples: &VecDeque, first: &Sample, slope: f64) -> Result { + if !slope.is_finite() { + return Err(ChronosError::Overflow); + } + let rate = ((slope - 1.0) * PARTS_PER_BILLION as f64).round(); + if !(i64::MIN as f64..=i64::MAX as f64).contains(&rate) { + return Err(ChronosError::Overflow); + } + let rate_adjust_ppb = rate as i64; + let mut residual_sum = 0_i128; + for sample in samples { + let delta = i128::from(sample.device_timestamp_ns) + .checked_sub(i128::from(first.device_timestamp_ns)) + .ok_or(ChronosError::Overflow)?; + let predicted = predict_from_first(first, delta, rate_adjust_ppb, 0)?; + residual_sum = residual_sum + .checked_add(i128::from(sample.reference_timestamp_ns) - i128::from(predicted)) + .ok_or(ChronosError::Overflow)?; + } + let residual_offset = divide_rounded(residual_sum, samples.len() as i128); + let residual_offset_ns = i64::try_from(residual_offset).map_err(|_| ChronosError::Overflow)?; + let mut residual_square_sum = 0.0; + let mut input_uncertainty = 0; + for sample in samples { + let delta = i128::from(sample.device_timestamp_ns) + .checked_sub(i128::from(first.device_timestamp_ns)) + .ok_or(ChronosError::Overflow)?; + let predicted = predict_from_first(first, delta, rate_adjust_ppb, residual_offset_ns)?; + let residual = absolute_difference(predicted, sample.reference_timestamp_ns)?; + residual_square_sum += (residual as f64).powi(2); + input_uncertainty = input_uncertainty.max(sample.uncertainty_ns); + } + let rms = (residual_square_sum / samples.len() as f64).sqrt().ceil() as u64; + Ok(Fit { + device_anchor_ns: first.device_timestamp_ns, + reference_anchor_ns: first.reference_timestamp_ns, + rate_adjust_ppb, + residual_offset_ns, + uncertainty_ns: input_uncertainty.saturating_add(rms), + }) +} + +/// Evaluate a fitted rate from the first paired observation using integers. +fn predict_from_first( + first: &Sample, + delta: i128, + rate_adjust_ppb: i64, + residual_offset_ns: i64, +) -> Result { + let rate = divide_rounded( + delta + .checked_mul(i128::from(rate_adjust_ppb)) + .ok_or(ChronosError::Overflow)?, + PARTS_PER_BILLION, + ); + let predicted = i128::from(first.reference_timestamp_ns) + .checked_add(delta) + .and_then(|value| value.checked_add(rate)) + .and_then(|value| value.checked_add(i128::from(residual_offset_ns))) + .ok_or(ChronosError::Overflow)?; + i64::try_from(predicted).map_err(|_| ChronosError::Overflow) +} + +/// Materialize a fitted model with a bounded future validity interval. +fn build_model( + record: &DomainRecord, + fit: &Fit, + model_version: u64, + state: DomainState, +) -> Result { + let first = record.samples.front().expect("model requires observations"); + let latest = record.samples.back().expect("model requires observations"); + let validity_extension = record + .policy + .tracking_timeout_ns + .saturating_add(record.policy.holdover_duration_ns); + let (valid_from, extension) = if let Some(period) = record.descriptor.wrap_period_ns { + let half_period = (period / 2).max(1); + let unambiguous_margin = half_period.saturating_sub(1); + ( + i128::from(latest.device_timestamp_ns) - i128::from(unambiguous_margin), + validity_extension.min(unambiguous_margin), + ) + } else { + (i128::from(first.device_timestamp_ns), validity_extension) + }; + let valid_from = valid_from.max(i128::from(first.device_timestamp_ns)); + let valid_until = i128::from(latest.device_timestamp_ns) + .saturating_add(i128::from(extension)) + .min(i128::from(i64::MAX)); + Ok(ClockModel { + domain_id: record.descriptor.domain_id.clone(), + generation: record.generation, + reference_generation: record.reference_generation, + model_version, + device_anchor_ns: fit.device_anchor_ns, + reference_anchor_ns: fit.reference_anchor_ns, + rate_adjust_ppb: fit.rate_adjust_ppb, + residual_offset_ns: fit.residual_offset_ns, + uncertainty_ns: fit.uncertainty_ns, + valid_from_device_ns: i64::try_from(valid_from).map_err(|_| ChronosError::Overflow)?, + valid_until_device_ns: i64::try_from(valid_until).map_err(|_| ChronosError::Overflow)?, + sample_count: record.samples.len() as u64, + state, + last_observation_steady_ns: record.last_observation_steady_ns.unwrap_or(0), + latest_raw_device_ns: record.last_raw_device_ns.unwrap_or(fit.device_anchor_ns), + wrap_period_ns: record.descriptor.wrap_period_ns, + wrap_offset_ns: i64::try_from(record.wrap_offset_ns).map_err(|_| ChronosError::Overflow)?, + }) +} + +/// Apply freshness and holdover limits to one mature domain. +fn refresh_record(record: &mut DomainRecord, now_steady_ns: u64) -> Result<(), ChronosError> { + // New-generation observations cannot describe a retained model's freshness. + if record.model.as_ref().is_some_and(|model| { + model.generation != record.generation + || model.reference_generation != record.reference_generation + }) { + return Ok(()); + } + if !matches!( + record.state, + DomainState::Tracking | DomainState::Holdover | DomainState::Unsynced | DomainState::Fault + ) { + return Ok(()); + } + let Some(last) = record.last_observation_steady_ns else { + return Ok(()); + }; + let age = now_steady_ns - last; + if age <= record.policy.tracking_timeout_ns { + return Ok(()); + } + let holdover_age = age - record.policy.tracking_timeout_ns; + let drift_growth = drift_allowance_ns( + holdover_age, + u128::from(record.policy.max_drift_ppm) * 1_000, + ); + let uncertainty = record.fitted_uncertainty_ns.saturating_add(drift_growth); + let next_state = match record.state { + DomainState::Fault => DomainState::Fault, + DomainState::Unsynced => DomainState::Unsynced, + _ if holdover_age <= record.policy.holdover_duration_ns + && uncertainty <= record.policy.max_uncertainty_ns => + { + DomainState::Holdover + } + _ => DomainState::Unsynced, + }; + if record.state != next_state + || record + .model + .as_ref() + .is_some_and(|model| model.uncertainty_ns != uncertainty) + { + record.model_version = record + .model_version + .checked_add(1) + .ok_or(ChronosError::Overflow)?; + record.state = next_state; + record.reason = match next_state { + DomainState::Holdover => "observations are stale; using bounded holdover".to_string(), + DomainState::Unsynced => { + "observations are stale; estimate uncertainty is unbounded by policy".to_string() + } + DomainState::Fault => "clock model processing failed; retaining estimate".to_string(), + _ => unreachable!("freshness refresh only produces degraded states"), + }; + if let Some(model) = record.model.as_mut() { + model.model_version = record.model_version; + model.state = next_state; + model.uncertainty_ns = uncertainty; + } + } + Ok(()) +} + +/// Build a status snapshot without changing model or state. +fn status_from_record( + domain_id: &str, + record: &DomainRecord, + now_steady_ns: u64, + reference_available: bool, +) -> DomainStatus { + let mut status = DomainStatus { + domain_id: domain_id.to_string(), + generation: record.generation, + reference_generation: record.reference_generation, + model_version: record.model_version, + state: record.state, + accepted_observations: record.accepted_observations, + rejected_observations: record.rejected_observations, + last_observation_age_ns: record + .last_observation_steady_ns + .map(|last| now_steady_ns.saturating_sub(last)), + uncertainty_ns: record + .model + .as_ref() + .filter(|model| { + model.generation == record.generation + && model.reference_generation == record.reference_generation + }) + .map(|model| model.uncertainty_ns), + reason: record.reason.clone(), + }; + if !reference_available { + if status.state != DomainState::Fault { + status.state = DomainState::Unsynced; + } + status.uncertainty_ns = status.uncertainty_ns.map(|_| u64::MAX); + status.reason = format!( + "reference clock is unavailable; domain status: {}", + record.reason + ); + } + status +} + +/// Compute an absolute signed timestamp difference without overflowing i64. +fn absolute_difference(left: i64, right: i64) -> Result { + let difference = (i128::from(left) - i128::from(right)).abs(); + u64::try_from(difference).map_err(|_| ChronosError::Overflow) +} diff --git a/system/chronos/src/lib.rs b/system/chronos/src/lib.rs new file mode 100644 index 000000000..5ba05fce6 --- /dev/null +++ b/system/chronos/src/lib.rs @@ -0,0 +1,14 @@ +// SPDX-License-Identifier: MulanPSL-2.0 + +//! Deterministic device-to-reference clock models. + +mod core; +mod model; +pub use core::ChronosCore; +pub use model::{ + ChronosError, ClockDomainDescriptor, ClockDomainPolicy, ClockModel, ClockObservation, + ConversionResult, DomainState, DomainStatus, ModelUpdatePolicy, +}; + +mod snapshot; +pub use snapshot::ClockModelParametersSnapshot; diff --git a/system/chronos/src/model.rs b/system/chronos/src/model.rs new file mode 100644 index 000000000..b2bc123ab --- /dev/null +++ b/system/chronos/src/model.rs @@ -0,0 +1,411 @@ +// SPDX-License-Identifier: MulanPSL-2.0 + +use serde::Deserialize; +use thiserror::Error; + +pub(crate) const PARTS_PER_BILLION: i128 = 1_000_000_000; + +/// Keep configured and observed domain identities within the same wire limits. +pub(crate) fn validate_domain_id(domain_id: &str) -> Result<(), &'static str> { + if domain_id.is_empty() || domain_id.len() > 128 || domain_id.trim() != domain_id { + return Err("domain_id must contain 1..128 bytes without surrounding whitespace"); + } + Ok(()) +} + +/// Synchronization state of one device clock domain. +#[repr(u8)] +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum DomainState { + Initializing = 0, + Tracking = 1, + Holdover = 2, + Reset = 3, + Unsynced = 4, + Fault = 5, +} + +/// Static facts needed by the pure core to interpret a device clock domain. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ClockDomainDescriptor { + pub domain_id: String, + pub resolution_ns: u64, + pub wrap_period_ns: Option, +} + +impl ClockDomainDescriptor { + /// Reject identities and units that cannot produce an unambiguous model. + pub fn validate(&self) -> Result<(), ChronosError> { + validate_domain_id(&self.domain_id) + .map_err(|reason| ChronosError::InvalidDomain(reason.into()))?; + if self.resolution_ns == 0 { + return Err(ChronosError::InvalidDomain( + "resolution_ns must be positive".to_string(), + )); + } + if let Some(period) = self.wrap_period_ns + && (!(2..=i64::MAX as u64).contains(&period)) + { + return Err(ChronosError::InvalidDomain( + "wrap_period_ns must fit a signed timestamp and contain at least two values" + .to_string(), + )); + } + Ok(()) + } +} + +/// How fitted offset corrections are published within one clock generation. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)] +#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)] +pub enum ModelUpdatePolicy { + /// Publish new coefficients immediately, allowing forward or backward corrections. + Step {}, + /// Bound offset correction per observation by elapsed steady time; rates remain fitted. + Slew { max_correction_ppm: u64 }, +} + +impl Default for ModelUpdatePolicy { + fn default() -> Self { + Self::Step {} + } +} + +/// Per-domain limits used for model maturity, freshness, quality and offset correction. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ClockDomainPolicy { + pub minimum_observations: usize, + pub observation_window: usize, + pub max_drift_ppm: u64, + pub max_residual_ns: u64, + pub tracking_timeout_ns: u64, + pub holdover_duration_ns: u64, + pub max_uncertainty_ns: u64, + pub model_update: ModelUpdatePolicy, +} + +impl ClockDomainPolicy { + /// Reject limits that would prevent model fitting or bounded holdover. + pub fn validate(&self) -> Result<(), ChronosError> { + if self.minimum_observations < 2 { + return Err(ChronosError::InvalidPolicy( + "minimum_observations must be at least two".to_string(), + )); + } + if self.observation_window < self.minimum_observations { + return Err(ChronosError::InvalidPolicy( + "observation_window must cover minimum_observations".to_string(), + )); + } + if self.max_residual_ns == 0 || self.max_uncertainty_ns == 0 { + return Err(ChronosError::InvalidPolicy( + "residual and uncertainty limits must be positive".to_string(), + )); + } + if let ModelUpdatePolicy::Slew { max_correction_ppm } = self.model_update + && !(1..=1_000_000).contains(&max_correction_ppm) + { + return Err(ChronosError::InvalidPolicy( + "slew max_correction_ppm must be between 1 and 1000000".to_string(), + )); + } + Ok(()) + } +} + +/// One paired device/reference observation, timestamped by a monotonic clock. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ClockObservation { + pub sequence_id: u64, + pub device_timestamp_ns: i64, + pub reference_timestamp_ns: i64, + pub uncertainty_ns: u64, + pub steady_received_ns: u64, +} + +/// Immutable, versioned affine relationship between one device clock and the reference. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ClockModel { + pub(crate) domain_id: String, + pub(crate) generation: u64, + pub(crate) reference_generation: u64, + pub(crate) model_version: u64, + pub(crate) device_anchor_ns: i64, + pub(crate) reference_anchor_ns: i64, + pub(crate) rate_adjust_ppb: i64, + pub(crate) residual_offset_ns: i64, + pub(crate) uncertainty_ns: u64, + pub(crate) valid_from_device_ns: i64, + pub(crate) valid_until_device_ns: i64, + pub(crate) sample_count: u64, + pub(crate) state: DomainState, + pub(crate) last_observation_steady_ns: u64, + pub(crate) latest_raw_device_ns: i64, + pub(crate) wrap_period_ns: Option, + pub(crate) wrap_offset_ns: i64, +} + +impl ClockModel { + /// Return the clock domain represented by this model. + pub fn domain_id(&self) -> &str { + &self.domain_id + } + + /// Return the generation that invalidates models from earlier resets. + pub fn generation(&self) -> u64 { + self.generation + } + + /// Return the reference-clock generation used to fit this model. + pub fn reference_generation(&self) -> u64 { + self.reference_generation + } + + /// Return the monotonically increasing model version within a generation. + pub fn model_version(&self) -> u64 { + self.model_version + } + + /// Return the device anchor used by the affine relationship. + pub fn device_anchor_ns(&self) -> i64 { + self.device_anchor_ns + } + + /// Return the reference anchor used by the affine relationship. + pub fn reference_anchor_ns(&self) -> i64 { + self.reference_anchor_ns + } + + /// Return the signed frequency correction in parts per billion. + pub fn rate_adjust_ppb(&self) -> i64 { + self.rate_adjust_ppb + } + + /// Return the residual offset applied after the anchor and rate terms. + pub fn residual_offset_ns(&self) -> i64 { + self.residual_offset_ns + } + + /// Return the model uncertainty in nanoseconds. + pub fn uncertainty_ns(&self) -> u64 { + self.uncertainty_ns + } + + /// Return the first normalized device timestamp covered by the model. + pub fn valid_from_device_ns(&self) -> i64 { + self.valid_from_device_ns + } + + /// Return the final normalized device timestamp covered by the model. + pub fn valid_until_device_ns(&self) -> i64 { + self.valid_until_device_ns + } + + /// Return the number of observations represented by the current fit. + pub fn sample_count(&self) -> u64 { + self.sample_count + } + + /// Return the synchronization state attached to this model version. + pub fn state(&self) -> DomainState { + self.state + } + + /// Return when the last accepted observation reached the core. + pub fn last_observation_steady_ns(&self) -> u64 { + self.last_observation_steady_ns + } + + /// Return the latest raw counter used to select an unambiguous wrap epoch. + pub fn latest_raw_device_ns(&self) -> i64 { + self.latest_raw_device_ns + } + + /// Return the declared raw counter period, if the device clock wraps. + pub fn wrap_period_ns(&self) -> Option { + self.wrap_period_ns + } + + /// Return the generation-local offset applied before affine conversion. + pub fn wrap_offset_ns(&self) -> i64 { + self.wrap_offset_ns + } + + /// Convert whenever the retained coefficients define an unambiguous value. + /// + /// Synchronization state and validity are reported with the estimate rather + /// than used as quality gates. Wrapping clocks remain bounded to the range + /// in which a raw counter can be assigned to one unambiguous wrap epoch. + /// Extrapolation outside a non-wrapping model's validity reports unbounded + /// uncertainty rather than presenting the estimate as policy-bounded. + pub fn convert(&self, device_timestamp_ns: i64) -> Result { + let normalized = self.normalize_device_timestamp(device_timestamp_ns)?; + let within_validity = normalized >= i128::from(self.valid_from_device_ns) + && normalized <= i128::from(self.valid_until_device_ns); + if self.wrap_period_ns.is_some() && !within_validity { + return Err(ChronosError::TimestampOutsideModel); + } + let delta = normalized - i128::from(self.device_anchor_ns); + let rate = divide_rounded( + delta + .checked_mul(i128::from(self.rate_adjust_ppb)) + .ok_or(ChronosError::Overflow)?, + PARTS_PER_BILLION, + ); + let reference = i128::from(self.reference_anchor_ns) + .checked_add(delta) + .and_then(|value| value.checked_add(rate)) + .and_then(|value| value.checked_add(i128::from(self.residual_offset_ns))) + .ok_or(ChronosError::Overflow)?; + Ok(ConversionResult { + reference_timestamp_ns: i64::try_from(reference).map_err(|_| ChronosError::Overflow)?, + generation: self.generation, + reference_generation: self.reference_generation, + model_version: self.model_version, + uncertainty_ns: if within_validity { + self.uncertainty_ns + } else { + u64::MAX + }, + state: self.state, + within_validity, + last_observation_steady_ns: self.last_observation_steady_ns, + }) + } + + /// Map a raw counter near the latest observation into the model generation. + fn normalize_device_timestamp(&self, raw: i64) -> Result { + if let Some(period) = self.wrap_period_ns + && (raw < 0 || raw >= period as i64) + { + return Err(ChronosError::InvalidObservation( + "device timestamp is outside the declared wrap period".to_string(), + )); + } + let mut normalized = i128::from(raw) + .checked_add(i128::from(self.wrap_offset_ns)) + .ok_or(ChronosError::Overflow)?; + if let Some(period) = self.wrap_period_ns { + let period = i128::from(period); + let difference = i128::from(raw) - i128::from(self.latest_raw_device_ns); + if period % 2 == 0 && difference.abs() == period / 2 { + return Err(ChronosError::TimestampOutsideModel); + } + if difference < -(period / 2) { + normalized = normalized + .checked_add(period) + .ok_or(ChronosError::Overflow)?; + } else if difference > period / 2 { + normalized = normalized + .checked_sub(period) + .ok_or(ChronosError::Overflow)?; + } + } + Ok(normalized) + } + + /// Evaluate a normalized timestamp without applying validity or state gates. + pub(crate) fn extrapolate_normalized(&self, normalized: i64) -> Result { + let delta = i128::from(normalized) - i128::from(self.device_anchor_ns); + let rate = divide_rounded( + delta + .checked_mul(i128::from(self.rate_adjust_ppb)) + .ok_or(ChronosError::Overflow)?, + PARTS_PER_BILLION, + ); + let reference = i128::from(self.reference_anchor_ns) + .checked_add(delta) + .and_then(|value| value.checked_add(rate)) + .and_then(|value| value.checked_add(i128::from(self.residual_offset_ns))) + .ok_or(ChronosError::Overflow)?; + i64::try_from(reference).map_err(|_| ChronosError::Overflow) + } +} + +/// Result of a model conversion, carrying the exact model identity used. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ConversionResult { + pub reference_timestamp_ns: i64, + pub generation: u64, + pub reference_generation: u64, + pub model_version: u64, + pub uncertainty_ns: u64, + pub state: DomainState, + pub within_validity: bool, + pub last_observation_steady_ns: u64, +} + +/// Current synchronization status independent of whether a model is available. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct DomainStatus { + pub domain_id: String, + pub generation: u64, + pub reference_generation: u64, + pub model_version: u64, + pub state: DomainState, + pub accepted_observations: u64, + pub rejected_observations: u64, + pub last_observation_age_ns: Option, + pub uncertainty_ns: Option, + pub reason: String, +} + +/// Errors produced by domain validation, observation processing, and conversion. +#[derive(Debug, Error, Clone, PartialEq, Eq)] +pub enum ChronosError { + #[error("unknown clock domain '{0}'")] + UnknownDomain(String), + #[error("clock domain '{0}' is already registered")] + DuplicateDomain(String), + #[error("invalid clock domain: {0}")] + InvalidDomain(String), + #[error("invalid clock domain policy: {0}")] + InvalidPolicy(String), + #[error("observation sequence or monotonic receipt time is not newer")] + ObservationOutOfOrder, + #[error("reference generation is not newer: current {current}, received {received}")] + ReferenceGenerationOutOfOrder { current: u64, received: u64 }, + #[error("reference clock is unavailable")] + ReferenceUnavailable, + #[error("invalid clock observation: {0}")] + InvalidObservation(String), + #[error("observation residual {residual_ns} ns exceeds {limit_ns} ns")] + ObservationOutlier { residual_ns: u64, limit_ns: u64 }, + #[error("clock model is not available in state {0:?}")] + ModelUnavailable(DomainState), + #[error("timestamp is outside the model validity interval")] + TimestampOutsideModel, + #[error("timestamp arithmetic overflow")] + Overflow, +} + +/// Divide with nearest-integer rounding; exact half values round away from zero. +pub(crate) fn divide_rounded(numerator: i128, denominator: i128) -> i128 { + let quotient = numerator / denominator; + let remainder = numerator % denominator; + if remainder == 0 { + return quotient; + } + let magnitude = remainder.abs().saturating_mul(2); + if magnitude >= denominator.abs() { + quotient + numerator.signum() * denominator.signum() + } else { + quotient + } +} + +#[cfg(test)] +mod tests { + use super::divide_rounded; + + #[test] + /// Signed half values use the same nearest-integer rule in both directions. + fn integer_rounding_is_symmetric_at_half_values() { + assert_eq!(divide_rounded(1, 2), 1); + assert_eq!(divide_rounded(-1, 2), -1); + assert_eq!(divide_rounded(3, 2), 2); + assert_eq!(divide_rounded(-3, 2), -2); + assert_eq!(divide_rounded(1, 3), 0); + assert_eq!(divide_rounded(-1, 3), 0); + } +} diff --git a/system/chronos/src/snapshot.rs b/system/chronos/src/snapshot.rs new file mode 100644 index 000000000..890b37272 --- /dev/null +++ b/system/chronos/src/snapshot.rs @@ -0,0 +1,48 @@ +// SPDX-License-Identifier: MulanPSL-2.0 + +use crate::model::{ClockModel, DomainState}; + +/// Versioned affine coefficients that consumers can evaluate locally. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ClockModelParametersSnapshot { + pub generation: u64, + pub reference_generation: u64, + pub model_version: u64, + pub state: DomainState, + pub device_anchor_ns: i64, + pub reference_anchor_ns: i64, + pub rate_adjust_ppb: i64, + pub residual_offset_ns: i64, + pub uncertainty_ns: u64, + pub valid_from_device_ns: i64, + pub valid_until_device_ns: i64, + pub sample_count: u64, + pub last_observation_steady_ns: u64, + pub latest_raw_device_ns: i64, + pub wrap_period_ns: Option, + pub wrap_offset_ns: i64, +} + +impl From<&ClockModel> for ClockModelParametersSnapshot { + /// Copy every coefficient and wrap-normalization input needed locally. + fn from(model: &ClockModel) -> Self { + Self { + generation: model.generation(), + reference_generation: model.reference_generation(), + model_version: model.model_version(), + state: model.state(), + device_anchor_ns: model.device_anchor_ns(), + reference_anchor_ns: model.reference_anchor_ns(), + rate_adjust_ppb: model.rate_adjust_ppb(), + residual_offset_ns: model.residual_offset_ns(), + uncertainty_ns: model.uncertainty_ns(), + valid_from_device_ns: model.valid_from_device_ns(), + valid_until_device_ns: model.valid_until_device_ns(), + sample_count: model.sample_count(), + last_observation_steady_ns: model.last_observation_steady_ns(), + latest_raw_device_ns: model.latest_raw_device_ns(), + wrap_period_ns: model.wrap_period_ns(), + wrap_offset_ns: model.wrap_offset_ns(), + } + } +} diff --git a/system/chronos/tests/core.rs b/system/chronos/tests/core.rs new file mode 100644 index 000000000..aec10abc4 --- /dev/null +++ b/system/chronos/tests/core.rs @@ -0,0 +1,943 @@ +// SPDX-License-Identifier: MulanPSL-2.0 + +use robonix_chronos::{ + ChronosCore, ChronosError, ClockDomainDescriptor, ClockDomainPolicy, + ClockModelParametersSnapshot, ClockObservation, DomainState, ModelUpdatePolicy, +}; + +/// Build the common descriptor while varying declared counter wrap behavior. +fn descriptor(wrap_period_ns: Option) -> ClockDomainDescriptor { + ClockDomainDescriptor { + domain_id: "camera_clock".to_string(), + resolution_ns: 1, + wrap_period_ns, + } +} + +/// Build policy limits shared by core behavior tests. +fn policy() -> ClockDomainPolicy { + ClockDomainPolicy { + minimum_observations: 3, + observation_window: 8, + max_drift_ppm: 500, + max_residual_ns: 2_000, + tracking_timeout_ns: 1_000_000_000, + holdover_duration_ns: 3_000_000_000, + max_uncertainty_ns: 2_000_000, + model_update: ModelUpdatePolicy::Step {}, + } +} + +/// Build one paired observation with a deterministic sequence and receipt time. +fn observation(sequence: u64, device: i64, reference: i64, steady: u64) -> ClockObservation { + ClockObservation { + sequence_id: sequence, + device_timestamp_ns: device, + reference_timestamp_ns: reference, + uncertainty_ns: 100, + steady_received_ns: steady, + } +} + +/// Apply Chronos's nearest-integer, half-away-from-zero division rule. +fn divide_rounded(numerator: i128, denominator: i128) -> i128 { + let quotient = numerator / denominator; + let remainder = numerator % denominator; + let twice = remainder.abs() * 2; + if twice < denominator { + quotient + } else if numerator.is_negative() { + quotient - 1 + } else { + quotient + 1 + } +} + +/// Reconstruct one local conversion using only published model parameters. +fn convert_published(model: &ClockModelParametersSnapshot, raw: i64) -> i64 { + let mut normalized = i128::from(raw) + i128::from(model.wrap_offset_ns); + if let Some(period) = model.wrap_period_ns { + let period = i128::from(period); + let difference = i128::from(raw) - i128::from(model.latest_raw_device_ns); + if difference < -(period / 2) { + normalized += period; + } else if difference > period / 2 { + normalized -= period; + } + } + let delta = normalized - i128::from(model.device_anchor_ns); + let rate = divide_rounded(delta * i128::from(model.rate_adjust_ppb), 1_000_000_000); + i64::try_from( + i128::from(model.reference_anchor_ns) + delta + rate + i128::from(model.residual_offset_ns), + ) + .unwrap() +} + +/// Feed exact samples for a clock whose signed rate correction is known. +fn tracking_core(rate_adjust_ppb: i64) -> ChronosCore { + let mut core = ChronosCore::new(); + core.register(descriptor(None), policy()).unwrap(); + for sequence in 1..=4 { + let device = sequence as i64 * 1_000_000_000; + let correction = device * rate_adjust_ppb / 1_000_000_000; + core.observe( + "camera_clock", + observation( + sequence, + device, + 10_000_000_000 + device + correction, + sequence, + ), + ) + .unwrap(); + } + core +} + +/// Fit a signed-rate model across one declared counter wrap. +fn wrapping_tracking_core(rate_adjust_ppb: i64) -> ChronosCore { + let mut core = ChronosCore::new(); + core.register(descriptor(Some(1_000_000)), policy()) + .unwrap(); + for (sequence, raw, normalized) in [ + (1, 700_000, 700_000), + (2, 800_000, 800_000), + (3, 900_000, 900_000), + (4, 20_000, 1_020_000), + ] { + let correction = divide_rounded( + i128::from(normalized) * i128::from(rate_adjust_ppb), + 1_000_000_000, + ); + core.observe( + "camera_clock", + observation( + sequence, + raw, + 10_000_000 + normalized + i64::try_from(correction).unwrap(), + sequence, + ), + ) + .unwrap(); + } + core +} + +/// Select an in-range raw value whose signed rate term must be rounded. +fn raw_requiring_rounding( + model: &robonix_chronos::ClockModel, + published: &ClockModelParametersSnapshot, + candidates: impl Iterator, +) -> i64 { + candidates + .filter(|raw| model.convert(*raw).is_ok()) + .find(|raw| { + let normalized = i128::from(*raw) + i128::from(published.wrap_offset_ns); + let delta = normalized - i128::from(published.device_anchor_ns); + let remainder = (delta * i128::from(published.rate_adjust_ppb)) % 1_000_000_000; + remainder.abs() * 2 > 1_000_000_000 + }) + .expect("test model must expose a value with a non-trivial fractional rate term") +} + +#[test] +/// Both oscillator directions must retain their signed frequency correction. +fn estimates_positive_and_negative_drift() { + let fast = tracking_core(125_000); + assert_eq!( + fast.model("camera_clock").unwrap().rate_adjust_ppb(), + 125_000 + ); + + let slow = tracking_core(-80_000); + assert_eq!( + slow.model("camera_clock").unwrap().rate_adjust_ppb(), + -80_000 + ); +} + +#[test] +/// Published coefficients reproduce non-integral positive and negative drift. +fn published_parameters_preserve_conversion_rounding() { + for rate_adjust_ppb in [125_000, -80_000] { + let core = tracking_core(rate_adjust_ppb); + let model = core.model("camera_clock").unwrap(); + let published = ClockModelParametersSnapshot::from(&model); + let raw = raw_requiring_rounding( + &model, + &published, + published.device_anchor_ns..=published.device_anchor_ns + 20_000, + ); + assert_eq!( + convert_published(&published, raw), + model.convert(raw).unwrap().reference_timestamp_ns + ); + + let wrapping = wrapping_tracking_core(rate_adjust_ppb); + let model = wrapping.model("camera_clock").unwrap(); + let published = ClockModelParametersSnapshot::from(&model); + let raw = raw_requiring_rounding(&model, &published, 0..=20_000); + assert_eq!( + convert_published(&published, raw), + model.convert(raw).unwrap().reference_timestamp_ns + ); + } +} + +#[test] +/// Conversion carries the generation and version of the model that was used. +fn converts_with_versioned_checked_model() { + let core = tracking_core(125_000); + let converted = core.convert("camera_clock", 4_500_000_000).unwrap(); + assert_eq!(converted.reference_timestamp_ns, 14_500_562_500); + assert_eq!(converted.generation, 1); + assert_eq!(converted.reference_generation, 1); + assert!(converted.model_version >= 1); + assert_eq!(converted.state, DomainState::Tracking); + assert!(converted.within_validity); + assert_eq!(converted.last_observation_steady_ns, 4); +} + +#[test] +fn accepts_and_fits_rate_change_within_drift_policy() { + for (initial_rate, rate) in [ + (0, -400_000), + (0, 400_000), + (400_000, -400_000), + (-400_000, 400_000), + ] { + let mut core = ChronosCore::new(); + core.register(descriptor(None), policy()).unwrap(); + for sequence in 1..=16 { + let device = sequence as i64 * 500_000_000; + let correction = (device.min(2_000_000_000) * initial_rate + + (device - 2_000_000_000).max(0) * rate) + / 1_000_000_000; + let status = core + .observe( + "camera_clock", + observation( + sequence, + device, + 10_000_000_000 + device + correction, + device as u64, + ), + ) + .unwrap(); + if sequence >= 3 { + assert_eq!(status.state, DomainState::Tracking); + } + } + assert_eq!(core.model("camera_clock").unwrap().rate_adjust_ppb(), rate); + } +} + +#[test] +fn outlier_gate_includes_rounded_elapsed_drift_allowance() { + // The 500,000,001 ns gap permits 250,001 ns of drift at 500 ppm. + let limit_ns = 2_000 + 101 + 250_001 + 100; + for residual_ns in [limit_ns, limit_ns + 1] { + let mut core = tracking_core(0); + let result = core.observe( + "camera_clock", + observation(5, 5_000_000_000, 15_000_000_000 + residual_ns, 500_000_005), + ); + if residual_ns == limit_ns { + assert_eq!(result.unwrap().state, DomainState::Tracking); + } else { + assert_eq!( + result.unwrap_err(), + ChronosError::ObservationOutlier { + residual_ns: residual_ns as u64, + limit_ns: limit_ns as u64, + } + ); + } + } +} + +#[test] +fn holdover_observation_within_grown_uncertainty_restores_tracking() { + let mut core = tracking_core(0); + core.refresh(2_000_000_004).unwrap(); + let status = core.status("camera_clock", 2_000_000_004).unwrap(); + assert_eq!(status.state, DomainState::Holdover); + assert!(status.uncertainty_ns.unwrap() > 3_000); + let recovered = core + .observe( + "camera_clock", + observation(5, 6_000_000_001, 16_000_003_001, 2_000_000_005), + ) + .unwrap(); + assert_eq!(recovered.state, DomainState::Tracking); + assert_eq!(recovered.accepted_observations, 5); + assert_eq!(recovered.rejected_observations, 0); +} + +#[test] +/// A mature model rejects a large residual without replacing its model version. +fn rejects_obvious_outlier_without_replacing_model() { + let mut core = tracking_core(0); + let version = core.model("camera_clock").unwrap().model_version(); + let error = core + .observe( + "camera_clock", + observation(5, 5_000_000_000, 99_000_000_000, 5), + ) + .unwrap_err(); + assert!(matches!(error, ChronosError::ObservationOutlier { .. })); + assert_eq!(core.model("camera_clock").unwrap().model_version(), version); + assert_eq!( + core.status("camera_clock", 5) + .unwrap() + .rejected_observations, + 1 + ); +} + +#[test] +/// An undeclared device-time regression invalidates the previous generation. +fn device_regression_starts_a_new_generation() { + let mut core = tracking_core(0); + let status = core + .observe("camera_clock", observation(5, 10, 20_000_000_010, 5)) + .unwrap(); + assert_eq!(status.generation, 2); + assert_eq!(status.state, DomainState::Reset); + assert!(matches!( + core.model("camera_clock"), + Err(ChronosError::ModelUnavailable(DomainState::Reset)) + )); +} + +#[test] +/// A restarted sequence requires explicit reset so late samples stay rejected. +fn implicit_reset_rejects_restarted_sequence() { + let mut core = tracking_core(0); + assert_eq!( + core.observe("camera_clock", observation(0, 10, 20_000_000_010, 5)), + Err(ChronosError::ObservationOutOfOrder) + ); + assert_eq!(core.status("camera_clock", 5).unwrap().generation, 1); +} + +#[test] +/// A declared counter wrap extends time without changing generation. +fn declared_counter_wrap_keeps_the_generation() { + let mut core = ChronosCore::new(); + core.register(descriptor(Some(1_000)), policy()).unwrap(); + core.observe("camera_clock", observation(1, 800, 10_000, 1)) + .unwrap(); + core.observe("camera_clock", observation(2, 900, 10_100, 2)) + .unwrap(); + let status = core + .observe("camera_clock", observation(3, 20, 10_220, 3)) + .unwrap(); + assert_eq!(status.generation, 1); + assert_eq!(status.state, DomainState::Tracking); + assert_eq!( + core.convert("camera_clock", 30) + .unwrap() + .reference_timestamp_ns, + 10_230 + ); + let model = core.model("camera_clock").unwrap(); + let published = ClockModelParametersSnapshot::from(&model); + assert_eq!(published.wrap_period_ns, Some(1_000)); + assert_eq!(published.latest_raw_device_ns, 20); + assert_eq!(published.wrap_offset_ns, 1_000); + assert_eq!(convert_published(&published, 30), 10_230); +} + +#[test] +/// Stale models remain calculable while reporting degraded quality. +fn stale_observations_enter_holdover_then_unsynced() { + let mut core = tracking_core(0); + core.refresh(2_000_000_004).unwrap(); + let holdover = core.status("camera_clock", 2_000_000_004).unwrap(); + assert_eq!(holdover.state, DomainState::Holdover); + assert!(holdover.uncertainty_ns.unwrap() > 100); + + core.refresh(4_000_000_005).unwrap(); + let unsynced = core.status("camera_clock", 4_000_000_005).unwrap(); + assert_eq!(unsynced.state, DomainState::Unsynced); + let estimate = core.convert("camera_clock", 4_000_000_000).unwrap(); + assert_eq!(estimate.state, DomainState::Unsynced); + assert!(estimate.within_validity); + + let previous_uncertainty = estimate.uncertainty_ns; + core.refresh(5_000_000_005).unwrap(); + assert!( + core.convert("camera_clock", 4_000_000_000) + .unwrap() + .uncertainty_ns + > previous_uncertainty + ); + + let extrapolated = core.convert("camera_clock", 9_000_000_000).unwrap(); + assert!(!extrapolated.within_validity); + assert_eq!(extrapolated.uncertainty_ns, u64::MAX); +} + +#[test] +/// Reference loss retains conversion coefficients with explicit bad quality. +fn unavailable_reference_degrades_and_recovers_model() { + let mut core = tracking_core(0); + let tracking_version = core.model("camera_clock").unwrap().model_version(); + core.update_reference_availability(false).unwrap(); + core.refresh(2_000_000_004).unwrap(); + + let status = core.status("camera_clock", 2_000_000_004).unwrap(); + assert_eq!(status.state, DomainState::Unsynced); + assert_eq!(status.uncertainty_ns, Some(u64::MAX)); + let estimate = core.convert("camera_clock", 4_500_000_000).unwrap(); + assert_eq!(estimate.state, DomainState::Unsynced); + assert_eq!(estimate.uncertainty_ns, u64::MAX); + let unavailable_model = core.model("camera_clock").unwrap(); + assert_eq!(unavailable_model.state(), DomainState::Unsynced); + assert_eq!(unavailable_model.uncertainty_ns(), u64::MAX); + assert!(unavailable_model.model_version() > tracking_version); + assert_eq!( + core.observe( + "camera_clock", + observation(5, 5_000_000_000, 15_000_000_000, 5), + ), + Err(ChronosError::ReferenceUnavailable) + ); + + core.update_reference_availability(true).unwrap(); + let recovered_version = core.model("camera_clock").unwrap().model_version(); + assert!(recovered_version > unavailable_model.model_version()); + let recovered = core + .observe( + "camera_clock", + observation(5, 5_000_000_000, 15_000_000_000, 5), + ) + .unwrap(); + assert_eq!(recovered.state, DomainState::Tracking); + assert_ne!(recovered.uncertainty_ns, Some(u64::MAX)); +} + +#[test] +/// Duplicate sequences and decreasing monotonic receipt times are rejected. +fn ordering_uses_sequence_and_monotonic_receipt_time() { + let mut core = ChronosCore::new(); + core.register(descriptor(None), policy()).unwrap(); + core.observe("camera_clock", observation(1, 10, 20, 10)) + .unwrap(); + assert_eq!( + core.observe("camera_clock", observation(1, 11, 21, 11)), + Err(ChronosError::ObservationOutOfOrder) + ); + assert_eq!( + core.observe("camera_clock", observation(2, 11, 21, 9)), + Err(ChronosError::ObservationOutOfOrder) + ); +} + +#[test] +/// Removing a domain also removes its status and model history. +fn unregister_removes_domain_state() { + let mut core = ChronosCore::new(); + core.register(descriptor(None), policy()).unwrap(); + core.unregister("camera_clock").unwrap(); + assert_eq!( + core.status("camera_clock", 0), + Err(ChronosError::UnknownDomain("camera_clock".to_string())) + ); +} + +#[test] +/// A new reference generation retains the old estimate with explicit identity. +fn reference_generation_resets_registered_domains() { + let mut core = tracking_core(0); + assert_eq!(core.reference_generation(), 1); + core.update_reference_generation(2).unwrap(); + assert_eq!(core.reference_generation(), 2); + let reset = core.status("camera_clock", 4).unwrap(); + assert_eq!(reset.generation, 2); + assert_eq!(reset.reference_generation, 2); + assert_eq!(reset.state, DomainState::Reset); + assert_eq!(reset.uncertainty_ns, None); + let estimate = core.convert("camera_clock", 4_500_000_000).unwrap(); + assert_eq!(estimate.generation, 1); + assert_eq!(estimate.reference_generation, 1); + assert_eq!(estimate.state, DomainState::Unsynced); + core.update_reference_generation(2).unwrap(); + assert_eq!(core.status("camera_clock", 4).unwrap().generation, 2); + assert!(matches!( + core.update_reference_generation(1), + Err(ChronosError::ReferenceGenerationOutOfOrder { .. }) + )); +} + +#[test] +/// Confirmed reset creates a generation before accepting restarted counters. +fn explicit_reset_allows_device_sequence_to_restart() { + let mut core = tracking_core(0); + let reset = core.reset("camera_clock").unwrap(); + assert_eq!(reset.generation, 2); + assert_eq!(reset.state, DomainState::Reset); + + let status = core + .observe("camera_clock", observation(0, 10, 20_000_000_010, 10)) + .unwrap(); + assert_eq!(status.generation, 2); + assert_eq!(status.state, DomainState::Reset); +} + +#[test] +/// A rejected first sample after wrap must not consume the wrap transition. +fn rejected_wrap_sample_does_not_advance_wrap_epoch() { + let mut core = ChronosCore::new(); + let mut wrap_policy = policy(); + wrap_policy.max_residual_ns = 5; + core.register(descriptor(Some(1_000)), wrap_policy).unwrap(); + core.observe("camera_clock", observation(1, 700, 10_000, 1)) + .unwrap(); + core.observe("camera_clock", observation(2, 800, 10_100, 2)) + .unwrap(); + core.observe("camera_clock", observation(3, 900, 10_200, 3)) + .unwrap(); + + assert!(matches!( + core.observe("camera_clock", observation(4, 20, 99_999, 4)), + Err(ChronosError::ObservationOutlier { .. }) + )); + let status = core + .observe("camera_clock", observation(5, 30, 10_330, 5)) + .unwrap(); + assert_eq!(status.generation, 1); + assert_eq!( + core.convert("camera_clock", 40) + .unwrap() + .reference_timestamp_ns, + 10_340 + ); +} + +#[test] +/// Rejected inputs still consume their ordering identity to prevent replay. +fn rejected_observation_advances_input_ordering_boundary() { + let mut core = tracking_core(0); + assert!(matches!( + core.observe( + "camera_clock", + observation(5, 5_000_000_000, 99_000_000_000, 5), + ), + Err(ChronosError::ObservationOutlier { .. }) + )); + assert_eq!( + core.observe( + "camera_clock", + observation(5, 5_000_000_001, 15_000_000_001, 6), + ), + Err(ChronosError::ObservationOutOfOrder) + ); + assert_eq!( + core.status("camera_clock", 6) + .unwrap() + .rejected_observations, + 2 + ); + assert_eq!( + core.status("camera_clock", 4), + Err(ChronosError::ObservationOutOfOrder) + ); +} + +#[test] +/// Repeated device timestamps are rejected as input, not treated as core faults. +fn repeated_device_timestamp_is_rejected_without_fault() { + let mut core = tracking_core(0); + let version = core.model("camera_clock").unwrap().model_version(); + assert!(matches!( + core.observe( + "camera_clock", + observation(5, 4_000_000_000, 14_000_000_000, 5), + ), + Err(ChronosError::InvalidObservation(_)) + )); + let status = core.status("camera_clock", 5).unwrap(); + assert_eq!(status.state, DomainState::Tracking); + assert_eq!(status.model_version, version); +} + +#[test] +/// Wrapping conversion rejects noncanonical and exact-half-period timestamps. +fn wrapping_conversion_rejects_ambiguous_inputs() { + let mut core = ChronosCore::new(); + core.register(descriptor(Some(1_000)), policy()).unwrap(); + core.observe("camera_clock", observation(1, 700, 10_000, 1)) + .unwrap(); + core.observe("camera_clock", observation(2, 800, 10_100, 2)) + .unwrap(); + core.observe("camera_clock", observation(3, 900, 10_200, 3)) + .unwrap(); + assert!(matches!( + core.convert("camera_clock", 1_400), + Err(ChronosError::InvalidObservation(_)) + )); + assert_eq!( + core.convert("camera_clock", 400), + Err(ChronosError::TimestampOutsideModel) + ); +} + +#[test] +/// Reported uncertainty cannot be finer than the declared clock resolution. +fn declared_resolution_bounds_model_uncertainty() { + let mut core = ChronosCore::new(); + let mut coarse = descriptor(None); + coarse.resolution_ns = 1_000_000; + core.register(coarse, policy()).unwrap(); + for sequence in 1..=3 { + core.observe( + "camera_clock", + observation( + sequence, + sequence as i64 * 1_000, + sequence as i64 * 1_000, + sequence, + ), + ) + .unwrap(); + } + assert!(core.model("camera_clock").unwrap().uncertainty_ns() >= 1_000_000); +} + +#[test] +/// Refitting a long observation window always covers its newest sample. +fn model_validity_always_contains_the_latest_observation() { + let mut core = ChronosCore::new(); + let mut short = policy(); + short.observation_window = 10; + short.tracking_timeout_ns = 10; + short.holdover_duration_ns = 10; + core.register(descriptor(None), short).unwrap(); + for sequence in 1..=6 { + let timestamp = sequence as i64 * 1_000; + core.observe( + "camera_clock", + observation(sequence, timestamp, timestamp, sequence), + ) + .unwrap(); + } + assert_eq!( + core.convert("camera_clock", 6_000) + .unwrap() + .reference_timestamp_ns, + 6_000 + ); +} + +#[test] +/// Failed fitting does not commit its sample and is visible through FAULT. +fn fitting_failure_is_atomic_and_visible_as_fault() { + let mut core = ChronosCore::new(); + let mut two_samples = policy(); + two_samples.minimum_observations = 2; + core.register(descriptor(Some(i64::MAX as u64)), two_samples) + .unwrap(); + core.observe("camera_clock", observation(1, i64::MAX - 100, 10_000, 1)) + .unwrap(); + core.observe("camera_clock", observation(2, 0, 10_100, 2)) + .unwrap(); + assert!(matches!( + core.observe("camera_clock", observation(3, i64::MAX - 50, 10_150, 3),), + Err(ChronosError::Overflow) + )); + let fault = core.status("camera_clock", 3).unwrap(); + assert_eq!(fault.state, DomainState::Fault); + assert_eq!(fault.accepted_observations, 2); + assert_eq!(fault.rejected_observations, 1); + assert_eq!( + core.convert("camera_clock", 0).unwrap().state, + DomainState::Fault + ); + + core.update_reference_availability(false).unwrap(); + let unavailable = core.status("camera_clock", 3).unwrap(); + assert_eq!(unavailable.state, DomainState::Fault); + assert!(unavailable.reason.contains("clock model processing failed")); + assert_eq!( + core.convert("camera_clock", 0).unwrap().uncertainty_ns, + u64::MAX + ); + core.update_reference_availability(true).unwrap(); + let recovered = core.status("camera_clock", 3).unwrap(); + assert_eq!(recovered.state, DomainState::Fault); + assert_eq!(recovered.reason, "clock model processing failed"); +} + +#[test] +fn refresh_preserves_a_retained_model_after_a_new_generation_fault() { + let mut core = ChronosCore::new(); + let mut limits = policy(); + limits.tracking_timeout_ns = 10; + core.register(descriptor(Some(i64::MAX as u64)), limits) + .unwrap(); + for sequence in 1..=3 { + core.observe( + "camera_clock", + observation( + sequence, + sequence as i64 * 10, + sequence as i64 * 10, + sequence, + ), + ) + .unwrap(); + } + core.update_reference_generation(2).unwrap(); + core.observe("camera_clock", observation(4, i64::MAX - 100, 10_000, 4)) + .unwrap(); + core.observe("camera_clock", observation(5, 0, 10_100, 5)) + .unwrap(); + assert!(matches!( + core.observe("camera_clock", observation(6, i64::MAX - 50, 10_150, 6)), + Err(ChronosError::Overflow) + )); + let retained = core.model("camera_clock").unwrap(); + assert_eq!(retained.reference_generation(), 1); + assert_eq!(retained.state(), DomainState::Fault); + + core.refresh(10_000).unwrap(); + + assert_eq!(core.model("camera_clock").unwrap(), retained); + assert_eq!( + core.status("camera_clock", 10_000).unwrap().state, + DomainState::Fault + ); +} + +#[test] +/// Step permits a new fit to correct an older model's forward bias without an artificial offset. +fn step_model_updates_allow_backward_correction() { + let mut core = ChronosCore::new(); + let mut permissive = policy(); + permissive.minimum_observations = 3; + permissive.observation_window = 3; + permissive.max_drift_ppm = 1_000_000; + permissive.max_residual_ns = 1_000; + permissive.max_uncertainty_ns = 1_000_000; + core.register(descriptor(None), permissive).unwrap(); + core.observe("camera_clock", observation(1, 0, 0, 1)) + .unwrap(); + core.observe("camera_clock", observation(2, 100, 100, 2)) + .unwrap(); + core.observe("camera_clock", observation(3, 200, 200, 3)) + .unwrap(); + let old_boundary = core + .convert("camera_clock", 300) + .unwrap() + .reference_timestamp_ns; + + core.observe("camera_clock", observation(4, 300, 250, 4)) + .unwrap(); + let new_boundary = core + .convert("camera_clock", 300) + .unwrap() + .reference_timestamp_ns; + assert!(new_boundary < old_boundary); + assert_eq!(new_boundary, 258); +} + +/// Seed an identity model with permissive fitting limits and a selected update mode. +fn update_policy_core(mode: ModelUpdatePolicy, wrap: Option) -> ChronosCore { + let mut core = ChronosCore::new(); + let mut limits = policy(); + limits.observation_window = 3; + limits.max_drift_ppm = if wrap.is_some() { 500_000 } else { 1_000_000 }; + limits.model_update = mode; + core.register(descriptor(wrap), limits).unwrap(); + for (sequence, device) in [(1, 0), (2, 100), (3, 200)] { + core.observe( + "camera_clock", + observation(sequence, device, device, sequence * 100), + ) + .unwrap(); + } + core +} + +#[test] +/// Both correction directions are bounded by elapsed steady time, including intervals too short to permit a one-nanosecond correction. +fn slew_limits_positive_and_negative_corrections() { + for (reference, elapsed, expected) in [ + (250, 100, 290), + (350, 100, 310), + (250, 200, 280), + (250, 1, 300), + (250, 500, 258), + ] { + let mut core = update_policy_core( + ModelUpdatePolicy::Slew { + max_correction_ppm: 100_000, + }, + None, + ); + core.observe( + "camera_clock", + observation(4, 300, reference, 300 + elapsed), + ) + .unwrap(); + let converted = core.convert("camera_clock", 300).unwrap(); + assert_eq!(converted.reference_timestamp_ns, expected); + let mut raw = update_policy_core(ModelUpdatePolicy::Step {}, None); + raw.observe( + "camera_clock", + observation(4, 300, reference, 300 + elapsed), + ) + .unwrap(); + let fitted = raw.convert("camera_clock", 300).unwrap(); + assert_eq!( + converted.uncertainty_ns, + fitted.uncertainty_ns + expected.abs_diff(fitted.reference_timestamp_ns) + ); + } +} + +#[test] +/// Stable observations consume the remaining offset until the published model reaches the fit. +fn slew_converges_after_transient_samples_leave_window() { + let mut core = update_policy_core( + ModelUpdatePolicy::Slew { + max_correction_ppm: 100_000, + }, + None, + ); + for sequence in 4..=20 { + let device = (sequence as i64 - 1) * 100; + core.observe( + "camera_clock", + observation(sequence, device, device - 50, sequence * 100), + ) + .unwrap(); + } + assert_eq!( + core.convert("camera_clock", 1900) + .unwrap() + .reference_timestamp_ns, + 1850 + ); +} + +#[test] +/// A wrap uses the same normalized boundary as conversion when applying the correction limit. +fn slew_corrects_across_declared_wrap() { + let mut core = update_policy_core( + ModelUpdatePolicy::Slew { + max_correction_ppm: 100_000, + }, + Some(400), + ); + core.observe("camera_clock", observation(4, 300, 300, 400)) + .unwrap(); + core.observe("camera_clock", observation(5, 0, 350, 500)) + .unwrap(); + assert_eq!( + core.convert("camera_clock", 0) + .unwrap() + .reference_timestamp_ns, + 390 + ); +} + +#[test] +/// New device and reference generations start with the raw fit instead of smoothing old offsets. +fn slew_does_not_bridge_resets() { + for reference_reset in [false, true] { + let mut core = update_policy_core( + ModelUpdatePolicy::Slew { + max_correction_ppm: 1, + }, + None, + ); + if reference_reset { + core.update_reference_generation(2).unwrap(); + } else { + core.reset("camera_clock").unwrap(); + } + for sequence in 1..=3 { + let device = sequence as i64 * 100; + core.observe( + "camera_clock", + observation(sequence, device, device + 500, 400 + sequence * 100), + ) + .unwrap(); + } + assert_eq!( + core.convert("camera_clock", 300) + .unwrap() + .reference_timestamp_ns, + 800 + ); + } +} + +#[test] +/// Remaining slew bias degrades quality until successive corrections bring it within policy. +fn slew_reports_unsynced_until_offset_recovers() { + let mut core = ChronosCore::new(); + let mut limits = policy(); + limits.observation_window = 3; + limits.max_drift_ppm = 1_000_000; + limits.max_uncertainty_ns = 125; + limits.model_update = ModelUpdatePolicy::Slew { + max_correction_ppm: 100_000, + }; + core.register(descriptor(None), limits).unwrap(); + for sequence in 1..=3 { + let device = (sequence as i64 - 1) * 100; + core.observe( + "camera_clock", + observation(sequence, device, device, sequence * 100), + ) + .unwrap(); + } + assert_eq!( + core.status("camera_clock", 300).unwrap().state, + DomainState::Tracking + ); + core.observe("camera_clock", observation(4, 300, 250, 400)) + .unwrap(); + assert_eq!( + core.status("camera_clock", 400).unwrap().state, + DomainState::Unsynced + ); + for sequence in 5..=20 { + let device = (sequence as i64 - 1) * 100; + core.observe( + "camera_clock", + observation(sequence, device, device - 50, sequence * 100), + ) + .unwrap(); + } + assert_eq!( + core.status("camera_clock", 2000).unwrap().state, + DomainState::Tracking + ); +} + +#[test] +/// Missed counter cycles cannot silently corrupt the normalized timeline; explicit reset recovers. +fn wrapping_observation_gap_requires_reset() { + let mut core = ChronosCore::new(); + core.register(descriptor(Some(1000)), policy()).unwrap(); + core.observe("camera_clock", observation(1, 800, 800, 1)) + .unwrap(); + let invalid = core + .observe("camera_clock", observation(2, 850, 1850, 1001)) + .unwrap_err(); + assert!(invalid.to_string().contains("ambiguous")); + assert_eq!( + core.status("camera_clock", 1001) + .unwrap() + .accepted_observations, + 1 + ); + core.reset("camera_clock").unwrap(); + core.observe("camera_clock", observation(3, 850, 1850, 1002)) + .unwrap(); +} From 961141525fd75149e78c0d6eabccba101c8fae92 Mon Sep 17 00:00:00 2001 From: ZZJJWarth <2678328250@qq.com> Date: Tue, 3 Nov 2026 20:45:22 +0800 Subject: [PATCH 2/3] fix(chronos): reject overflowing fitted rates Reject the floating-point upper boundary before converting fitted rates to signed coefficients. Document and test that a newer reference generation resets Fault while availability recovery preserves it. --- system/chronos/README.md | 4 ++++ system/chronos/src/core.rs | 4 +++- system/chronos/tests/core.rs | 40 ++++++++++++++++++++++++++++++++++++ 3 files changed, 47 insertions(+), 1 deletion(-) diff --git a/system/chronos/README.md b/system/chronos/README.md index e81562973..3c55ccb9a 100644 --- a/system/chronos/README.md +++ b/system/chronos/README.md @@ -4,8 +4,12 @@ The core bounds its observation window, checks integer conversion overflow, tracks reference/device generations, and handles wrap, outliers, holdover and reset. Model updates support step and bounded slew. +Fitted rates outside the signed coefficient range are rejected, including a floating-point rate that rounds to the exclusive upper boundary. + Refreshing a new generation preserves retained models from earlier generations; their freshness cannot be computed from the new observations. +A strictly newer reference generation clears `Fault` to `Reset` and replaces its diagnostic reason. A retained model becomes `Unsynced` with its old generation identity until refitting. Equal-generation updates are idempotent, and reference availability recovery preserves `Fault`. + Outlier checks include the configured drift allowance over steady time since the last accepted observation, so permitted rate changes and observations within holdover uncertainty can update the model. Larger residuals remain rejected. Run `cargo test -p robonix-chronos --test core`. diff --git a/system/chronos/src/core.rs b/system/chronos/src/core.rs index 50b635334..690760124 100644 --- a/system/chronos/src/core.rs +++ b/system/chronos/src/core.rs @@ -71,6 +71,8 @@ impl ChronosCore { /// Equal generations are idempotent. Older or zero generations are /// rejected. The last estimate remains available with its old reference /// identity while the reset is committed atomically across all domains. + /// A newer generation clears Fault to Reset; the retained model becomes + /// Unsynced. Availability recovery alone preserves Fault. pub fn update_reference_generation(&mut self, generation: u64) -> Result<(), ChronosError> { if generation == 0 || generation < self.reference_generation { return Err(ChronosError::ReferenceGenerationOutOfOrder { @@ -717,7 +719,7 @@ fn finish_fit(samples: &VecDeque, first: &Sample, slope: f64) -> Result< return Err(ChronosError::Overflow); } let rate = ((slope - 1.0) * PARTS_PER_BILLION as f64).round(); - if !(i64::MIN as f64..=i64::MAX as f64).contains(&rate) { + if !(i64::MIN as f64..i64::MAX as f64).contains(&rate) { return Err(ChronosError::Overflow); } let rate_adjust_ppb = rate as i64; diff --git a/system/chronos/tests/core.rs b/system/chronos/tests/core.rs index aec10abc4..185ac7a17 100644 --- a/system/chronos/tests/core.rs +++ b/system/chronos/tests/core.rs @@ -668,6 +668,25 @@ fn fitting_failure_is_atomic_and_visible_as_fault() { let recovered = core.status("camera_clock", 3).unwrap(); assert_eq!(recovered.state, DomainState::Fault); assert_eq!(recovered.reason, "clock model processing failed"); + + core.update_reference_generation(1).unwrap(); + let unchanged = core.status("camera_clock", 3).unwrap(); + assert_eq!(unchanged.state, DomainState::Fault); + assert_eq!(unchanged.reason, recovered.reason); + + core.update_reference_generation(2).unwrap(); + let reset = core.status("camera_clock", 3).unwrap(); + assert_eq!(reset.state, DomainState::Reset); + assert_eq!(reset.generation, 2); + assert_eq!(reset.reference_generation, 2); + assert_eq!( + reset.reason, + "reference generation changed; retaining previous model" + ); + let retained = core.convert("camera_clock", 0).unwrap(); + assert_eq!(retained.state, DomainState::Unsynced); + assert_eq!(retained.generation, 1); + assert_eq!(retained.reference_generation, 1); } #[test] @@ -941,3 +960,24 @@ fn wrapping_observation_gap_requires_reset() { core.observe("camera_clock", observation(3, 850, 1850, 1002)) .unwrap(); } + +#[test] +fn fitting_rejects_a_rate_rounded_to_the_signed_upper_boundary() { + let mut core = ChronosCore::new(); + let mut limits = policy(); + limits.minimum_observations = 2; + core.register(descriptor(None), limits).unwrap(); + core.observe("camera_clock", observation(1, 0, 0, 1)) + .unwrap(); + assert_eq!( + core.observe( + "camera_clock", + observation(2, 1_000_000, 9_223_372_037_854_777, 2), + ), + Err(ChronosError::Overflow) + ); + assert_eq!( + core.status("camera_clock", 2).unwrap().state, + DomainState::Fault + ); +} From 58d187e4fc3b3f89aa7a72388de1f1b1c817487a Mon Sep 17 00:00:00 2001 From: ZZJJWarth <2678328250@qq.com> Date: Fri, 13 Nov 2026 19:03:57 +0800 Subject: [PATCH 3/3] fix(chronos): align the lockfile with the workspace version The workspace now uses version 1.1.0. Refresh the Chronos lockfile entry so locked builds resolve the rebased workspace without updating it. --- Cargo.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Cargo.lock b/Cargo.lock index e63698fe9..82da4c6c6 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3187,7 +3187,7 @@ dependencies = [ [[package]] name = "robonix-chronos" -version = "1.1.0-beta.1" +version = "1.1.0" dependencies = [ "serde", "thiserror 2.0.18",