daemonic_error 1.0.0

//! Core DaemonicClock trait - Unified time interface
//!
//! This trait provides a common interface for both:
//! - Logical clocks (Lamport, Vector, Hybrid)
//! - Physical clocks (MTP, NTP, System)
//!
//! All Daemonic entities use this trait for time access.

use alloc::boxed::Box;
use core::cmp::Ordering;
use crate::{daemonic::glass::Glass, DaemonicError, Observation, TopologySegment};

pub mod types {
	use alloc::boxed::Box;
	// daemonic_clock/src/types.rs
	// Clock type definitions
	use core::fmt::Formatter;
	use alloc::fmt;
	use core::fmt::Display;
	use crate::{const_daemonic_hash, Glass};
	use crate::Observation;
	use core::ops::{Add, Sub};
	use crate::daemonic::daemonic_core::DaemonicClock;
	use crate::daemonic::glass::{GlassStable, Severity};
	use crate::daemonic::topology::TOPOLOGY_ANCHOR;
	use crate::daemonic::TopologySegment;
	
	#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
	pub struct Timestamp {
		/// Logical Clocks are always required at minimum
		/// Todo: At some point, all these fields should be Glassed
		pub logical: u64,
		/// Hardware clock refers to either BIOS time since Unix Epoch or some sort of physical
		/// clock plugged into the machine converted to a Glassed u64
		pub hardware: Option<u64>,
		/// Not in use yet, considered Reserved.
		pub mesh: Option<u64>,
		/// Not in use yet, considered Reserved.
		pub wall: Option<u64>,
	}
	impl Iterator for Timestamp {
		type Item = u64;
		
		fn next(&mut self) -> Option<Self::Item> {
			let x = [self.logical, self.hardware?, self.mesh?, self.wall?];
			// let x =self.logical += 1;
			let mut iter = x.iter();
			let x = iter.next()?;
			Some(*x)
		}
	}
	static DAEMONIC_CLOCK_TOPOLOGY_ANCH0R: TopologySegment = TopologySegment::new("Daemonic::Clock");
	impl Glass<Timestamp> for Timestamp {
		type Anchor = TopologySegment;
		
		fn position(&self) -> &TopologySegment {
			&DAEMONIC_CLOCK_TOPOLOGY_ANCH0R
		}
		
		fn severity(&self) -> Severity {
			Severity::Unknown
		}
		
		fn payload(&self) -> Option<&Timestamp> {
			// Some(&Timestamp {
			// 	logical: self.logical,
			// 	hardware: self.hardware,
			// 	mesh: self.mesh,
			// 	wall: self.wall,
			// })
			unreachable!("Timestamps should always be owned")
		}
		
		fn into_payload(self) -> Option<Timestamp>
			where
				Self: Sized,
				Timestamp: Sized,
		{
			Some(Timestamp {
				logical: self.logical,
				hardware: self.hardware,
				mesh: self.mesh,
				wall: self.wall,
			})
		}
	}
	impl Timestamp {
		/// Create new timestamp from u64
		pub const fn new_logical_clock(value: u64) -> Self {
			Self {
				logical: value,
				hardware: None,
				mesh: None,
				wall: None,
			}
		}
		
		/// Zero timestamp (invalid/broken clock)
		// underneath daemonic core
		pub const fn zerol() -> Self {
			Self {
				logical: 0,
				hardware: None,
				mesh: None,
				wall: None,
			}
		}
		pub const fn zeroh() -> Self {
			Self {
				logical: 0,
				hardware: Some(0u64),
				mesh: None,
				wall: None,
			}
		}
		/// One timestamp (default, zero reserved for broken clock errors)
		pub const fn one() -> Self {
			Self {
				logical: 1,
				hardware: Some(1u64),
				mesh: Some(1u64),
				wall: Some(1u64),
			}
		}
		/// Get raw u64 value
		pub const fn logical_as_u64(self) -> u64 {
			self.logical
		}
		pub const fn hardware_as_u64(self) -> Option<u64> {
			self.hardware
		}
		pub const fn mesh_as_u64(self) -> Option<u64> {
			self.mesh
		}
		pub const fn wall_as_u64(self) -> Option<u64> {
			self.wall
		}
		
		/// Check if logical clock is zero (invalid)
		pub const fn logical_is_zero(self) -> bool {
			self.logical_as_u64() == 0u64
		}
		pub fn hardware_is_zero(self) -> bool {
			self.hardware_as_u64() == Option::from(0u64)
		}
		pub fn wall_is_zero(self) -> bool {
			self.wall_as_u64() == Option::from(0u64)
		}
		pub fn mesh_is_zero(self) -> bool {
			self.mesh_as_u64() == Option::from(0u64)
		}
		
		/// Elapsed ticks since earlier timestamp
		///
		/// Returns: self - earlier (duration in ticks)
		/// Panics: If earlier > self
		pub fn logical_time_elapsed_since(self, earlier: Timestamp) -> u64 {
			assert!(self >= earlier, "earlier must be <= self");
			self.logical - earlier.logical
		}
		
		/// Checked elapsed (returns None if earlier > self)
		pub fn checked_logical_time_elapsed_since(self, earlier: Timestamp) -> Option<u64> {
			if self >= earlier {
				Some(self.logical - earlier.logical)
			} else {
				None
			}
		}
		
		/// Saturating subtraction (returns 0 if would underflow)
		pub fn logical_saturating_sub(self, other: Timestamp) -> u64 {
			self.logical.saturating_sub(other.logical)
		}
	}
	
	// ═══════════════════════════════════════════════════════════════
	// ARITHMETIC OPERATIONS
	// ═══════════════════════════════════════════════════════════════
	
	impl Add<u64> for Timestamp {
		type Output = Timestamp;
		fn add(self, rhs: u64) -> Timestamp {
			let x = self.logical + rhs;
			Timestamp::new_logical_clock(x)
		}
	}
	
	impl Sub for Timestamp {
		type Output = u64;
		fn sub(self, rhs: Timestamp) -> u64 {
			self.logical - rhs.logical
		}
	}
	
	impl Sub<u64> for Timestamp {
		type Output = Timestamp;
		fn sub(self, rhs: u64) -> Timestamp {
			Timestamp::new_logical_clock(self.logical - rhs)
		}
	}
	
	// ═══════════════════════════════════════════════════════════════
	// CONVERSIONS
	// ═══════════════════════════════════════════════════════════════
	
	impl From<u64> for Timestamp {
		fn from(value: u64) -> Self {
			Timestamp::new_logical_clock(value)
		}
	}
	
	impl From<Timestamp> for u64 {
		fn from(ts: Timestamp) -> u64 {
			ts.logical
		}
	}
	
	
	// ═══════════════════════════════════════════════════════════════
	// DURATION (Optional - for future use)
	// ═══════════════════════════════════════════════════════════════
	
	/// DaemonicDuration - Time elapsed between two timestamps
	///
	/// Currently just a u64, but wrapped for type safety.
	#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] // old, needs to be updated
	pub struct DaemonicDuration(u64);
	
	impl DaemonicDuration {
		pub const fn new(ticks: u64) -> Self {
			Self(ticks)
		}
		
		pub const fn zero() -> Self {
			Self(0)
		}
		
		pub const fn as_u64(self) -> u64 {
			self.0
		}
		
		pub const fn is_zero(self) -> bool {
			self.0 == 0
		}
		pub(crate) fn as_secs_f64(&self) -> f64 {
			unimplemented!("Logical Clock ticks cannot be represented as seconds yet")
		}
		pub(crate) fn from_secs(p0: i32) -> DaemonicDuration {
			unimplemented!("Logical Clock ticks cannot be represented as seconds yet")
		}
	}
	
	impl From<u64> for DaemonicDuration {
		fn from(ticks: u64) -> Self {
			DaemonicDuration(ticks)
		}
	}
	
	impl From<DaemonicDuration> for u64 {
		fn from(d: DaemonicDuration) -> u64 {
			d.0
		}
	}
	
	impl Display for DaemonicDuration { // old, needs to be updated
		fn fmt(&self, f: &mut Formatter) -> fmt::Result {
			write!(f, "{} ticks", self.0)
		}
	}
	
	#[cfg(test)]
	mod tests {
		use super::*;
		
		#[test]
		fn test_timestamp_creation() {
			let ts = Timestamp::new_logical_clock(42);
			assert_eq!(ts.logical_as_u64(), 42);
			
			let zero = Timestamp::new_logical_clock(0);
			assert!(zero.logical_is_zero());
			assert_eq!(zero.logical_as_u64(), 0);
		}
		
		#[test]
		fn test_timestamp_arithmetic() {
			let t1 = Timestamp::new_logical_clock(100);
			let t2 = Timestamp::new_logical_clock(200);
			
			// Addition
			assert_eq!(t1 + 50, Timestamp::new_logical_clock(150));
			
			// Subtraction (Timestamp - Timestamp = u64)
			assert_eq!(t2 - t1, 100);
			
			// Subtraction (Timestamp - u64 = Timestamp)
			assert_eq!(t2 - 50, Timestamp::new_logical_clock(150));
		}
		
		#[test]
		fn test_timestamp_elapsed() {
			let t1 = Timestamp::new_logical_clock(100);
			let t2 = Timestamp::new_logical_clock(200);
			
			assert_eq!(t2.logical_time_elapsed_since(t1), 100);
			assert_eq!(t2.checked_logical_time_elapsed_since(t1), Some(100));
			
			// Earlier > later
			assert_eq!(t1.checked_logical_time_elapsed_since(t2), None);
		}
		
		#[test]
		fn test_timestamp_ordering() {
			let t1 = Timestamp::new_logical_clock(100);
			let t2 = Timestamp::new_logical_clock(200);
			
			assert!(t1 < t2);
			assert!(t2 > t1);
			assert_eq!(t1, Timestamp::new_logical_clock(100));
		}
		
		#[test]
		fn test_timestamp_conversions() {
			let value: u64 = 42;
			let ts: Timestamp = value.into();
			let back: u64 = ts.into();
			
			assert_eq!(back, value);
		}
	}
}

use types::*;
static DAEMONIC_CLOCK_TOPOLOGY_SEGMENT: TopologySegment = TopologySegment::new("Daemonic::Clock");
// ═══════════════════════════════════════════════════════════════
// DAEMONIC CLOCK TRAIT
// ═══════════════════════════════════════════════════════════════
/// DaemonicClock - Unified time interface for all Daemonic entities
///
/// This trait abstracts over different clock implementations:
/// - Logical clocks: Lamport, Vector, Hybrid Logical Clock
/// - Physical clocks: MTP (Mesh Temporal Protocol), NTP, System
///
/// All Daemonic entities (Shade, Walker, etc.) use this trait
/// to access time, ensuring consistent temporal semantics across
/// the system regardless of underlying clock implementation.
///
/// # Design Principles
///
/// 1. **Type Safety**: Associated types prevent mixing timestamps
///    from different clock types at compile time.
///
/// 2. **Error Handling**: All operations return `Result<T, DaemonicError>`
///    for unified error handling across the system.
///
/// 3. **Thread Safety**: Must be Send + Sync for use in async contexts.
///
/// 4. **Clone**: Clock references should be cheap to copy (Arc inside).
///
/// # Implementations
///
/// - `LamportClock`: Logical event counter
/// - `MtpClock`: Physical mesh-synchronized time (future)
/// - `HybridClock`: Combines Lamport + MTP for total order (future)
/// Note from current Meph, dated 2026-08-09 0955
/// DaemonicClock being a spec on the Glass trait made sense when i wrote it, Clocks are a form of
/// observation after all, at least in theory but theres a catch to that line of thinking, if so
/// then the clock needs to be under the Observation trait domain, deeper than Glass as a spec.
///
pub trait DaemonicClock<'clock, GLASS: Glass<GLASS> + Iterator>: Clone + 'clock {
	fn new(x: u64) -> Timestamp {
		if x == 0u64 {
			::daemonic_error::daemonic::observation::Observation::<GLASS>::shattered(&DAEMONIC_CLOCK_TOPOLOGY_SEGMENT).with_note(
				"[DAEMONIC ERROR] -> SHATTERED OBSERVATION RETURNED IN CLOCK INPUT\
			Note: 0 is reserved for broken_sword() functionality which is not for new()\
			This function is designed to be used for instantiating a new clock from callsite,\
			not modifying an existing one.\
			\
			New Daemonic Clock constructs can never be 0, else TEMPORAL STACK UNWIND INITIATES\
			Citing: TIME HAS BECOME MEANINGLESS, ALL HELD SYMBOLS TRIGGER DIE IN TRANSIT PREDICATE");
			core::intrinsics::abort();
		} else {
			Timestamp::new_logical_clock(x)
		}
	}
	/// Read current time
	///
	/// Returns: Current timestamp from this clock
	///
	/// # Errors
	///
	/// - `ClockError::Overflow`: Timestamp would overflow
	/// - `ClockError::Unavailable`: Clock not synchronized (physical clocks)
	fn now<C: DaemonicClock<'clock, Timestamp>>(&self) -> Timestamp;
	
	/// Advance clock by one tick
	///
	/// For logical clocks: Increments counter, returns new timestamp
	/// For physical clocks: No-op, returns current wall time
	///
	/// Returns: Timestamp after tick
	///
	/// # Errors
	///
	/// - `ClockError::Overflow`: Would overflow
	#[inline(always)]
	fn tick(&self) -> impl Glass<Timestamp>; // Self is a valid anchor for a clock
	
	/// Synchronize with external timestamp
	///
	/// For logical clocks: max(local, external) + 1 (Lamport rule)
	/// For physical clocks: Adjusts frequency/offset to match
	///
	/// Returns: Timestamp after sync
	///
	/// # Errors
	///
	/// - `ClockError::Overflow`: Would overflow
	/// - `ClockError::InvalidTimestamp`: External timestamp invalid
	/// ***NOTE AND WARNING***: Daemonic Clocks should not sync, and logical
	/// clocks should **NEVER** be fucked with unless theres a reason, and that reason MUST be signed.
	///
	/// Note: Clock drift is expected behavior.
	/// Relativistic physics is blunt about this point in particular, there is no universal clock
	/// or authoritative timestamp, and Faustian axiom #4 and 5 state:
	/// No Privileged Reference frames: Which encompasses temporal reference frames.
	/// Observer equivalence within shared context: Which translates to = `" Every
	/// clock is correct to its own reference frame, and within shared context
	/// all clocks are equal and therefore none can claim authority or correctness
	/// over any other."`
	///
	/// Use this method with caution and knowing.
	/// We fucking told you.
	fn sync(&self, external: Timestamp) -> Timestamp;
	
	// ══ Time Comparison ═══════════════════════════════════════════
	
	/// Compare two timestamps
	///
	/// Returns: Ordering of a vs b
	fn compare(&self, a: Timestamp, b: Timestamp) -> Timestamp;
	
	/// Check if timestamp is zero (invalid/broken)
	fn is_zero(&self, ts: Timestamp) -> bool
		where
			GLASS: Glass<bool>,
	{
		ts.logical_is_zero() // Use Timestamp's method
	}
	
	// ══ DaemonicDuration Operations ═══════════════════════════════════════
	
	/// Calculate duration between two timestamps
	///
	/// Returns: b - a (ticks elapsed)
	///
	/// # Errors
	///
	/// - `ClockError::InvalidDuration`: a > b (negative duration)
	fn duration_between(
		&self,
		a: Timestamp,
		b: Timestamp,
	) -> dyn Glass<DaemonicDuration, Anchor=Self>; // this needs an update from DaemonicDuration, uses std lib shit
	
	// ══ Clock Metadata ════════════════════════════════════════════
	
	/// Get clock type identifier
	fn clock_type<'clocktype>(&self) -> &impl DaemonicClock<GLASS>;
	/// Check if clock is healthy
	///
	/// For logical clocks: Checks for overflow proximity
	/// For physical clocks: Checks sync status
	fn is_healthy(&self) -> bool;
}

// ═══════════════════════════════════════════════════════════════
// EXTENSION TRAITS (Optional capabilities)
// ═══════════════════════════════════════════════════════════════

/// Extension for clocks that support frequency steering
///
/// Implemented by: Physical clocks (MTP, NTP)
/// Not implemented by: Logical clocks (Lamport, Vector)
pub trait SteerableClock<GLASS: Glass<GLASS> + Iterator>: for<'steerableclock> DaemonicClock<'steerableclock, GLASS> {
	/// Set clock frequency adjustment
	///
	/// Parameter: Frequency multiplier (1.0 = normal speed)
	/// Returns: Timestamp when adjustment applied
	fn set_frequency(&self, freq: f64) -> dyn Glass<Timestamp, Anchor=Self>;
	
	/// Get current frequency adjustment
	fn get_frequency(&self) -> dyn Glass<f64, Anchor=Self>; // todo: Frequency should be typed
}

/// Extension for clocks that support stepping (jumping)
///
/// Implemented by: Physical clocks
/// Not implemented by: Logical clocks (would break causality)
pub trait SteppableClock<GLASS: Glass<GLASS> + Iterator>: for<'steppableclock> DaemonicClock<'steppableclock, GLASS> {
	/// Step clock by offset
	///
	/// Warning: Can break causality if used carelessly
	/// Use only for: Initial sync, leap seconds
	fn step(&self, offset: DaemonicDuration) -> dyn Glass<Timestamp, Anchor=Self>;
}

/// Extension for clocks that track uncertainty
///
/// Implemented by: Physical clocks (NTP)
/// Not implemented by: Logical clocks (no uncertainty)
pub trait UncertainClock<GLASS: Glass<GLASS> + Iterator>: for<'uncertainclock> DaemonicClock<'uncertainclock, GLASS> {
	/// Get current time uncertainty estimate
	///
	/// Returns: Maximum error bound on timestamp
	fn uncertainty(&self) -> dyn Glass<DaemonicDuration, Anchor=Self>;
	
	/// Update uncertainty estimate
	///
	/// Used by: Synchronization algorithms
	fn set_uncertainty(&self, uncertainty: DaemonicDuration) -> dyn Glass<(), Anchor=Self>;
}