daemonic_error 1.0.0

use crate::daemonic_system_call::DaemonicSystemCall;
use alloc::borrow::ToOwned;
use alloc::string::{String, ToString};
use core::convert::Infallible;
use core::fmt::Debug;
use core::marker::PhantomData;
use core::ops::{ControlFlow, FromResidual, Try};
use crate::{const_daemonic_hash, Timestamp, TOPOLOGY_ANCHOR, AXIOM_OFFSET, ObservationTier, DaemonicError};
pub use crate::{daemonic::glass::Glass, daemonic::{
	glass::{
		Temporal,
		Consistency,
		Accessibility,
		Annotation,
		Severity,
		Assessment,
	}
}};
use crate::daemonic::{SpatialAnchor, TopologySegment};
use crate::DaemonicClock;

// pub(crate) mod debug;

// pub mod display;

pub(crate) mod error;

pub(crate) mod observable;

pub mod observer;
mod constants;
use constants::*;
pub(crate) mod obs_states;
pub use obs_states::*;

/// ═══════════════════════════════════════════════════════════════
/// CONCRETE OBSERVATION TYPE
/// ═══════════════════════════════════════════════════════════════
///
/// A generic struct representing an observation. It holds information about
/// the observation's position, severity, tier, annotation, temporal context,
/// and an optional payload containing additional data.
///
/// # Type Parameters
/// - `GLASS`: A generic type representing the payload data associated with the
///   observation. This can be used to store additional information specific to
///   the observation's context or domain.
///
/// # Fields
/// - `position` (`Position`): The spatial information or location associated
///   with the observation.
/// - `severity` (`Severity`): A measure of the seriousness or importance of
///   the observation.
/// - `tier` (`ObservationTier`): The classification or level of the observation,
///   providing additional contextual grouping.
/// - `annotation` (`Annotation`): Any textual notes or metadata that further
///   detail or explain the observation.
/// - `temporal` (`Temporal`): The time-related information or timestamp
///   describing when the observation occurred or applies.
/// - `payload` (`Option<GLASS>`): Optional additional data related to the
///   observation, which can be of any type determined by the `GLASS` parameter.
/// Note to future developers and Meph/Self:
/// This shit is fucking meaningless.
/// No, seriously, its fucking meaningless on its own outside of use context or call site.
/// Generic logic by definition is generic and therefore meaningless.
/// So. If you are examining this logic and experiencing an existential crisis that \
/// makes you want to flip the desk and scream:
/// ```text
/// THIS IS ALL FUCKING MEANINGLESS!!!
/// ```
/// I know. Heres a doc stub to tell you that it is.
/// Go take a break.
pub enum Observation<GLASS>
// where
// 	GLASS: Glass<GLASS>,
{
	Stable(Stable<GLASS>),
	Cracked(Cracked<GLASS>),
	Fractured(Fractured<GLASS>),
	Drift(Drift<GLASS>),
	Echo(Echo<GLASS>),
	Opaque(Opaque<GLASS>),
	Warped(Warped<GLASS>),
	Impossible(Impossible<GLASS>),
	Shattered(Shattered),
	Paradox(Paradox<GLASS>),
	Unknown(Unknown<GLASS>),
}
impl<GLASS: Debug> Debug for Observation<GLASS> {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
		match &self {
			Observation::Stable(stable) => {
				f.debug_struct("Stable")
					.field("position", &stable.extract_position_label())
					.field("severity", &stable.extract_severity())
					.field("tier", &stable.extract_tier())
					.field("annotation", &stable.extract_annotation())
					.field("temporal", &stable.extract_temporal())
					.field("payload", &stable.extract_referent_payload())
					.finish()
			}
			Observation::Cracked(cracked) => {
				f.debug_struct("Cracked")
					.field("position", &cracked.extract_position_label())
					.field("severity", &cracked.extract_severity())
					.field("tier", &cracked.extract_tier())
					.field("annotation", &cracked.extract_annotation())
					.field("temporal", &cracked.extract_temporal())
					.field("payload", &cracked.query_payload())
					.finish()
			}
			Observation::Fractured(fractured) => {
				f.debug_struct("Fractured")
					.field("position", &fractured.extract_position_label())
					.field("severity", &fractured.extract_severity())
					.field("tier", &fractured.extract_tier())
					.field("annotation", &fractured.extract_annotation())
					.field("temporal", &fractured.extract_temporal())
					.field("payload", &fractured.query_payload())
					.finish()
			}
			Observation::Drift(drift) => {
				f.debug_struct("Drift")
					.field("position", &drift.extract_position_label())
					.field("severity", &drift.extract_severity())
					.field("tier", &drift.extract_tier())
					.field("annotation", &drift.extract_annotation())
					.field("temporal", &drift.extract_temporal())
					.field("payload", &drift.query_payload())
					.finish()
			}
			Observation::Echo(echo) => {
				f.debug_struct("Echo")
					.field("position", &echo.extract_position_label())
					.field("severity", &echo.extract_severity())
					.field("tier", &echo.extract_tier())
					.field("annotation", &echo.extract_annotation())
					.field("temporal", &echo.extract_temporal())
					.field("payload", &echo.query_payload())
					.finish()
			}
			Observation::Opaque(opaque) => {
				f.debug_struct("Opaque")
					.field("position", &opaque.extract_position_label())
					.field("severity", &opaque.extract_severity())
					.field("tier", &opaque.extract_tier())
					.field("annotation", &opaque.extract_annotation())
					.field("temporal", &opaque.extract_temporal())
					.field("payload", &"[DAEMONIC ERROR] -> DEBUG STATE REPORT -> OPAQUE PAYLOADS ARE NOT OBSERVABLE THROUGH THE DEBUG INTERFACE - OBSERVER KEY REQUIRED - (in development)")
					.finish()
			}
			Observation::Warped(warped) => {
				f.debug_struct("Warped")
					.field("position", &warped.extract_position_label())
					.field("severity", &warped.extract_severity())
					.field("tier", &warped.extract_tier())
					.field("annotation", &warped.extract_annotation())
					.field("temporal", &warped.extract_temporal())
					.field("payload", &warped.query_payload())
					.finish()
			}
			Observation::Impossible(impossible) => {
				f.debug_struct("Impossible")
					.field("position", &impossible.extract_position_label())
					.field("severity", &impossible.extract_severity())
					.field("tier", &impossible.extract_tier())
					.field("annotation", &impossible.extract_annotation())
					.field("temporal", &impossible.extract_temporal())
					.field("_phantom", &"[DAEMONIC ERROR] -> DEBUG STATE REPORT -> IMPOSSIBLE PAYLOADS ARE NOT OBSERVABLE THROUGH THE DEBUG INTERFACE BECAUSE THEY CANNOT EXIST]")
					.finish()
			}
			Observation::Shattered(shattered) => {
				f.debug_struct("Shattered")
					.field("position", &shattered.extract_position_label())
					.field("severity", &shattered.extract_severity())
					.field("tier", &shattered.extract_tier())
					.field("annotation", &shattered.extract_annotation())
					.field("temporal", &shattered.extract_temporal())
					.finish()
			}
			Observation::Paradox(paradox) => {
				f.debug_struct("Paradox")
					.field("position", &paradox.extract_position_label())
					.field("severity", &paradox.extract_severity())
					.field("tier", &paradox.extract_tier())
					.field("annotation", &paradox.extract_annotation())
					.field("temporal", &paradox.extract_temporal())
					.field("absolute_payload", &paradox.extract_absolute_payload())
					.field("asserted_payload", &paradox.query_asserted_payload())
					.finish()
			}
			Observation::Unknown(unknown) => {
				f.debug_struct("Unknown")
					.field("position", &unknown.extract_position_label())
					.field("severity", &unknown.extract_severity())
					.field("tier", &unknown.extract_tier())
					.field("annotation", &unknown.extract_annotation())
					.field("temporal", &unknown.extract_temporal())
					.field("payload", &unknown.query_payload())
					.finish()
			}
		}
	}
}

impl<GLASS: Debug> core::fmt::Display for Observation<GLASS> {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
		Ok(match &self {
			Observation::Stable(stable) => {
				write!(f, "[{}] {}", stable.extract_severity(), stable.extract_position_label())?;
				
				if !matches!(stable.extract_annotation(), Annotation::None) {
					write!(f, " — {}", stable.extract_annotation())?;
				}
				write!(f, " {:?}", stable.extract_referent_payload())?;
			}
			Observation::Cracked(cracked) => {
				write!(f, "[{}] {}", cracked.extract_severity(), cracked.extract_position_label())?;
				
				if !matches!(cracked.extract_annotation(), Annotation::None) {
					write!(f, " — {}", cracked.extract_annotation())?;
				}
			}
			Observation::Fractured(fractured) => {
				write!(f, "[{}] {}", fractured.extract_severity(), fractured.extract_position_label())?;
				
				if !matches!(fractured.extract_annotation(), Annotation::None) {
					write!(f, " — {}", fractured.extract_annotation())?;
				}
			}
			Observation::Drift(drift) => {
				write!(f, "[{}] {}", drift.extract_severity(), drift.extract_position_label())?;
				if !matches!(drift.extract_annotation(), Annotation::None) {
					write!(f, " — {}", drift.extract_annotation())?;
				}
			}
			Observation::Echo(echo) => {
				write!(f, "[{}] {}", echo.extract_severity(), echo.extract_position_label())?;
				
				if !matches!(echo.extract_annotation(), Annotation::None) {
					write!(f, " — {}", echo.extract_annotation())?;
				}
			}
			Observation::Opaque(opaque) => {
				write!(f, "[{}] {}", opaque.extract_severity(), opaque.extract_position_label())?;
				
				if !matches!(opaque.extract_annotation(), Annotation::None) {
					write!(f, " — {}", opaque.extract_annotation())?;
				}
			}
			Observation::Warped(warped) => {
				write!(f, "[{}] {}", warped.extract_severity(), warped.extract_position_label())?;
				
				if !matches!(warped.extract_annotation(), Annotation::None) {
					write!(f, " — {}", warped.extract_annotation())?;
				}
			}
			Observation::Impossible(impossible) => {
				write!(f, "[{}] {}", impossible.extract_severity(), impossible.extract_position_label())?;
				
				if !matches!(impossible.extract_annotation(), Annotation::None) {
					write!(f, " — {}", impossible.extract_annotation())?;
				}
			}
			Observation::Shattered(shattered) => {
				write!(f, "[{}] {}", shattered.extract_severity(), shattered.extract_position_label())?;
				
				if !matches!(shattered.extract_annotation(), Annotation::None) {
					write!(f, " — {}", shattered.extract_annotation())?;
				}
			}
			Observation::Paradox(paradox) => {
				write!(f, "[{}] {}", paradox.extract_severity(), paradox.extract_position_label())?;
				
				if !matches!(paradox.extract_annotation(), Annotation::None) {
					write!(f, " — {}", paradox.extract_annotation())?;
				}
			}
			Observation::Unknown(unknown) => {
				write!(f, "[{}] {}", unknown.extract_severity(), unknown.extract_position_label())?;
				
				if !matches!(unknown.extract_annotation(), Annotation::None) {
					write!(f, " — {}", unknown.extract_annotation())?;
				}
			}
		})
	}
}
/// Observation implements Try so ? works in formatting chains.
/// Stable/Cracked → Continue (formatting succeeded, proceed).
/// Everything else → Break (formatting failed, propagate).
/// Additional Context: Walkthrough context - Dated 2026-09-08 23:14
/// All doc stubs from here down in this Try for Observation implementation are documented with **Thought process** documented @ the dated timestamp for Future Developers and Meph/Self.
impl<GLASS> Try for Observation<GLASS> {
	/// What does ? return?
	/// updated, all state traits Self's point to the State Structs, the State Structs themselves implement Glass{State} for each type, and each State trait is a spec on Glass<GLASS>.
	/// So, all types that implement a Glass state of any type will qualify automatically.
	type Output = GLASS;
	/// What does ? break?
	/// core::convert::Infallible is supposed to be here because it inherits from the core trait defs, this type return enclosure MUST be infallible
	/// So, all constructors for State traits are infallible by design.
	/// Consider this an invariant: If State constructors fail under any circumstance, file a bug report @: https://gitlab.com/Mephistophel3s/daemonic-error
	///
	/// Only Stable trait includes an unwrap method, others have various methods for state and data (if present) inspection and introspection.
	/// Stable is guaranteed to carry a payload and is infallible, a Stable construct cant be built without a valid and TYPED Glass input
	/// Cracked has a query_payload which returns either GLASS or None
	type Residual = Observation<core::convert::Infallible>;
	/// this probably isnt totally correct but it works for now. probably.
	fn from_output(output: Self::Output) -> crate::daemonic::observation::Observation<GLASS> {
		Observation::stable(output, &STABLE_TRY_TOPOLOGY_SEGMENT)
	}
	
	fn branch(self) -> ControlFlow<Self::Residual, Self::Output>
	{
		// ══════════════════════════════════════════════════════════════
		// Try::branch() for Observation<GLASS>
		//
		// All behavioral reads go through GlassFlags.
		// No trait bounds required. No trait method calls.
		//
		// Data access (extract_position, extract_annotation, extract_payload_owned,
		// query_payload_existence) are inherent methods on the state structs.
		// Behavioral decisions (is_holding, should_continue, has_repair) are
		// read from the GlassFlags bitfield.
		//
		// Repair invocation is stubbed — the flags record HAS_REPAIR but the
		// repair enclosure shape is TBD. When repair is fleshed out, the
		// (_, _, true) arms will invoke the enclosure and propagate through ?.
		// Until then: has_repair is read but repair is not invoked.
		// ══════════════════════════════════════════════════════════════
		
		match self {
			Observation::Stable(stable) => {
				// Stable: always Continue. Extract the raw GLASS payload.
				// Output = GLASS, not Stable<GLASS>.
				// Being past this point IS the proof of stability.
				ControlFlow::Continue(stable.unwrap_payload())
			}
			
			Observation::Cracked(cracked) => {
				let payload_exists = cracked.query_payload_existence();
				let flags = cracked.extract_flags();
				
				match (payload_exists, flags.is_holding(), flags.has_repair()) {
					// Payload exists, holding, no repair needed.
					// Extract GLASS from the Cracked wrapper. Continue with raw payload.
					(true, true, false) => {
						// safe: payload_exists confirmed above
						ControlFlow::Continue(cracked.extract_owned_payload().unwrap())
					}
					// Repair available. Attempt repair regardless of other flags.
					// TODO: invoke repair enclosure when shape is finalized.
					// For now: treat as break (repair not yet invocable through flags).
					(_, _, true) => {
						let position = cracked.extract_position();
						let annotation = cracked.extract_annotation();
						let mut obs = obs_states::Cracked::<core::convert::Infallible>::new(
							None, position,
						);
						obs.mutate_annotation(annotation);
						ControlFlow::Break(Observation::Cracked(obs))
					}
					// Payload exists, not holding, no repair. Break.
					// Payload absent, holding, no repair. Can't produce GLASS. Break.
					// Payload absent, not holding, no repair. Full break.
					// All non-continue paths: erase payload, preserve metadata.
					(_, _, false) => {
						let position = cracked.extract_position();
						let annotation = cracked.extract_annotation();
						let mut obs = obs_states::Cracked::<core::convert::Infallible>::new(
							None, position,
						);
						obs.mutate_annotation(annotation);
						ControlFlow::Break(Observation::Cracked(obs))
					}
				}
			}
			
			Observation::Fractured(fractured) => {
				let flags = fractured.extract_flags();
				
				match (flags.has_repair(), flags.should_continue()) {
					// Repair exists and should continue: attempt repair.
					// TODO: invoke repair enclosure when shape is finalized.
					(true, true) => {
						// Stubbed: treat as payload extraction attempt for now.
						match fractured.extract_referent_payload() {
							Some(payload) => {
								let real_payload = fractured.extract_owned_payload().unwrap();
								ControlFlow::Continue(real_payload)
							}
							None => {
								let position = fractured.extract_position();
								let annotation = fractured.extract_annotation();
								let mut obs = obs_states::Fractured::<core::convert::Infallible>::new(
									None, position,
								);
								obs.mutate_annotation(annotation);
								ControlFlow::Break(Observation::Fractured(obs))
							}
						}
					}
					// No repair but should continue: extract payload if present.
					(false, true) => {
						match fractured.extract_referent_payload() {
							Some(payload) => {
								let real_payload = fractured.extract_owned_payload().unwrap();
								ControlFlow::Continue(real_payload)
							}
							None => {
								let position = fractured.extract_position();
								let annotation = fractured.extract_annotation();
								let mut obs = obs_states::Fractured::<core::convert::Infallible>::new(
									None, position,
								);
								obs.mutate_annotation(annotation);
								ControlFlow::Break(Observation::Fractured(obs))
							}
						}
					}
					// Shouldn't continue: break regardless of repair availability.
					(_, false) => {
						let position = fractured.extract_position();
						let annotation = fractured.extract_annotation();
						let mut obs = obs_states::Fractured::<core::convert::Infallible>::new(
							None, position,
						);
						obs.mutate_annotation(annotation);
						ControlFlow::Break(Observation::Fractured(obs))
					}
				}
			}
			
			Observation::Drift(drift) => {
				let flags = drift.extract_flags();
				
				match (flags.has_repair(), flags.should_retry()) {
					(true, true) => {
						match drift.extract_referent_payload() {
							Some(payload) => {
								let real_payload = drift.extract_owned_payload().unwrap();
								ControlFlow::Continue(real_payload)
							}
							None => {
								let position = drift.extract_position();
								let annotation = drift.extract_annotation();
								let mut obs = obs_states::Drift::<core::convert::Infallible>::new(
									None, position,
								);
								obs.mutate_annotation(annotation);
								ControlFlow::Break(Observation::Drift(obs))
							}
						}
					}
					(false, true) => {
						match drift.extract_referent_payload() {
							Some(payload) => {
								let real_payload = drift.extract_owned_payload().unwrap();
								ControlFlow::Continue(real_payload)
							}
							None => {
								let position = drift.extract_position();
								let annotation = drift.extract_annotation();
								let mut obs = obs_states::Drift::<core::convert::Infallible>::new(
									None, position,
								);
								obs.mutate_annotation(annotation);
								ControlFlow::Break(Observation::Drift(obs))
							}
						}
					}
					(_, false) => {
						let position = drift.extract_position();
						let annotation = drift.extract_annotation();
						let mut obs = obs_states::Drift::<core::convert::Infallible>::new(
							None, position,
						);
						obs.mutate_annotation(annotation);
						ControlFlow::Break(Observation::Drift(obs))
					}
				}
			}
			
			Observation::Echo(echo) => {
				let flags = echo.extract_flags();
				
				match (flags.has_repair(), flags.should_continue()) {
					(true, true) => {
						match echo.extract_referent_payload() {
							Some(payload) => {
								let real_payload = echo.extract_owned_payload().unwrap();
								ControlFlow::Continue(real_payload)
							}
							None => {
								let position = echo.extract_position();
								let annotation = echo.extract_annotation();
								let mut obs = obs_states::Echo::<core::convert::Infallible>::new(
									None, position,
								);
								obs.mutate_annotation(annotation);
								ControlFlow::Break(Observation::Echo(obs))
							}
						}
					}
					(false, true) => {
						match echo.extract_referent_payload() {
							Some(payload) => {
								let real_payload = echo.extract_owned_payload().unwrap();
								ControlFlow::Continue(real_payload)
							}
							None => {
								let position = echo.extract_position();
								let annotation = echo.extract_annotation();
								let mut obs = obs_states::Echo::<core::convert::Infallible>::new(
									None, position,
								);
								obs.mutate_annotation(annotation);
								ControlFlow::Break(Observation::Echo(obs))
							}
						}
					}
					(_, false) => {
						let position = echo.extract_position();
						let annotation = echo.extract_annotation();
						let mut obs = obs_states::Echo::<core::convert::Infallible>::new(
							None, position,
						);
						obs.mutate_annotation(annotation);
						ControlFlow::Break(Observation::Echo(obs))
					}
				}
			}
			
			Observation::Opaque(opaque) => {
				let flags = opaque.extract_flags();
				
				// Opaque has PhantomData, no real payload to extract.
				// Even with should_continue: can't produce GLASS without repair.
				match (flags.has_repair(), flags.should_continue()) {
					(true, true) => {
						// TODO: invoke repair enclosure (only way to produce GLASS from Opaque).
						let position = opaque.extract_position();
						let annotation = opaque.extract_annotation();
						let mut obs = obs_states::Opaque::<core::convert::Infallible>::new(
							PhantomData, position,
						);
						obs.mutate_annotation(annotation);
						ControlFlow::Break(Observation::Opaque(obs))
					}
					// All other combinations: break.
					// Opaque without repair can never produce GLASS.
					_ => {
						let position = opaque.extract_position();
						let annotation = opaque.extract_annotation();
						let mut obs = obs_states::Opaque::<core::convert::Infallible>::new(
							PhantomData, position,
						);
						obs.mutate_annotation(annotation);
						ControlFlow::Break(Observation::Opaque(obs))
					}
				}
			}
			
			Observation::Warped(warped) => {
				let flags = warped.extract_flags();
				
				match (flags.has_repair(), flags.should_continue()) {
					(true, true) => {
						match warped.extract_referent_payload() {
							Some(payload) => {
								let real_payload = warped.extract_owned_payload().unwrap();
								ControlFlow::Continue(real_payload)
							}
							None => {
								let position = warped.extract_position();
								let annotation = warped.extract_annotation();
								let mut obs = obs_states::Warped::<core::convert::Infallible>::new(
									None, position,
								);
								obs.mutate_annotation(annotation);
								ControlFlow::Break(Observation::Warped(obs))
							}
						}
					}
					(false, true) => {
						match warped.extract_referent_payload() {
							Some(payload) => {
								let real_payload = warped.extract_owned_payload().unwrap();
								ControlFlow::Continue(real_payload)
							}
							None => {
								let position = warped.extract_position();
								let annotation = warped.extract_annotation();
								let mut obs = obs_states::Warped::<core::convert::Infallible>::new(
									None, position,
								);
								obs.mutate_annotation(annotation);
								ControlFlow::Break(Observation::Warped(obs))
							}
						}
					}
					(_, false) => {
						let position = warped.extract_position();
						let annotation = warped.extract_annotation();
						let mut obs = obs_states::Warped::<core::convert::Infallible>::new(
							None, position,
						);
						obs.mutate_annotation(annotation);
						ControlFlow::Break(Observation::Warped(obs))
					}
				}
			}
			
			// ══ TERMINAL STATES ══════════════════════════════════════
			// GlassFlags::terminal(). No flags. No decisions. Always break.
			
			Observation::Impossible(impossible) => {
				let position = impossible.extract_position();
				let annotation = impossible.extract_annotation();
				let mut obs = obs_states::Impossible::<core::convert::Infallible>::new(
					PhantomData, position,
				);
				obs.mutate_annotation(annotation);
				ControlFlow::Break(Observation::Impossible(obs))
			}
			
			Observation::Shattered(shattered) => {
				let position = shattered.extract_position();
				let annotation = shattered.extract_annotation();
				let mut obs = obs_states::Shattered::new(position);
				obs.mutate_annotation(annotation);
				ControlFlow::Break(Observation::Shattered(obs))
			}
			
			// ══ SPECIAL STATES ═══════════════════════════════════════
			
			Observation::Paradox(paradox) => {
				let flags = paradox.extract_flags();
				
				match (flags.has_repair(), flags.should_continue()) {
					// Repair available and should continue: attempt repair.
					// TODO: invoke repair enclosure when shape is finalized.
					(true, true) => {
						// Stubbed: extract absolute payload (the evidence).
						ControlFlow::Continue(paradox.extract_owned_absolute_payload())
					}
					// No repair but should continue.
					// Continue with absolute_payload (the evidence).
					// The paradox is acknowledged but execution proceeds with the actual value.
					(false, true) => {
						ControlFlow::Continue(paradox.extract_owned_absolute_payload())
					}
					// Shouldn't continue: break.
					// Paradox evidence lost during type erasure to Infallible.
					// Downgrade to Shattered with provenance annotation.
					(_, false) => {
						let position = paradox.extract_position();
						let annotation = paradox.extract_annotation();
						let mut obs = obs_states::Shattered::new(position);
						obs.mutate_annotation(Annotation::Note(
							alloc::format!(
								"Paradox evidence lost during ? propagation. Original: {:?}",
								annotation
							)
						));
						ControlFlow::Break(Observation::Shattered(obs))
					}
				}
			}
			
			Observation::Unknown(unknown) => {
				let flags = unknown.extract_flags();
				let anything_known = unknown.query_payload().is_some();
				
				match (anything_known, flags.should_continue()) {
					// Known properties exist AND should continue.
					// Extract payload if available.
					(true, true) => {
						//todo ref return is not correct
						// copy the struct first to an owned region
						// let unknownstub = unknown.extract_owned_payload().to_owned();
						match unknown.extract_referent_payload() {
							Some(payload) => {
								let real_payload = unknown.extract_owned_payload().unwrap();
								ControlFlow::Continue(real_payload)
							}
							None => {
								let position = unknown.extract_position();
								let annotation = unknown.extract_annotation();
								let mut obs = obs_states::Unknown::<core::convert::Infallible>::new(
									None, position,
								);
								obs.mutate_annotation(annotation);
								ControlFlow::Break(Observation::Unknown(obs))
							}
						}
					}
					// All other combinations: break.
					_ => {
						let position = unknown.extract_position();
						let annotation = unknown.extract_annotation();
						let mut obs = obs_states::Unknown::<core::convert::Infallible>::new(
							None, position,
						);
						obs.mutate_annotation(annotation);
						ControlFlow::Break(Observation::Unknown(obs))
					}
				}
			}
		}
	}
}
impl<GLASS> FromResidual<Observation<core::convert::Infallible>> for Observation<GLASS> {
	fn from_residual(residual: Observation<core::convert::Infallible>) -> Self {
		match residual {
			// Stable: should never propagate through ?.
			// If it does: something is fundamentally wrong.
			Observation::Stable(_) => {
				unreachable!(
					"Stable observations do not propagate through ? — \
                     if you see this, the Try::branch impl has a bug"
				)
			}
			
			// Cracked: payload erased. Metadata preserved.
			Observation::Cracked(cracked) => {
				let mut obs = obs_states::Cracked::new(
					None,
					cracked.extract_position(),
				);
				obs.mutate_annotation(cracked.extract_annotation());
				Self::Cracked(obs)
			}
			
			// Fractured: payload erased. Metadata preserved.
			Observation::Fractured(fractured) => {
				let mut obs = obs_states::Fractured::new(
					None,
					fractured.extract_position(),
				);
				obs.mutate_annotation(fractured.extract_annotation());
				Self::Fractured(obs)
			}
			
			// Drift: payload erased. Metadata preserved.
			Observation::Drift(drift) => {
				let mut obs = obs_states::Drift::new(
					None,
					drift.extract_position(),
				);
				obs.mutate_annotation(drift.extract_annotation());
				Self::Drift(obs)
			}
			
			// Echo: payload erased. Metadata preserved.
			Observation::Echo(echo) => {
				let mut obs = obs_states::Echo::new(
					None,
					echo.extract_position(),
				);
				obs.mutate_annotation(echo.extract_annotation());
				Self::Echo(obs)
			}
			
			// Opaque: was already PhantomData. Still is.
			// No real payload to erase. Just carry metadata.
			Observation::Opaque(opaque) => {
				let mut obs = obs_states::Opaque::new(
					PhantomData,
					opaque.extract_position(),
				);
				obs.mutate_annotation(opaque.extract_annotation());
				Self::Opaque(obs)
			}
			
			// Warped: payload erased. Metadata preserved.
			Observation::Warped(warped) => {
				let mut obs = obs_states::Warped::new(
					None,
					warped.extract_position(),
				);
				obs.mutate_annotation(warped.extract_annotation());
				Self::Warped(obs)
			}
			
			// Impossible: was already PhantomData. Carry metadata.
			Observation::Impossible(impossible) => {
				let mut obs = obs_states::Impossible::new(
					PhantomData,
					impossible.extract_position(),
				);
				obs.mutate_annotation(impossible.extract_annotation());
				Self::Impossible(obs)
			}
			
			// Shattered: no GLASS parameter at all. Pure metadata.
			// Simplest case: just reconstruct with metadata.
			Observation::Shattered(shattered) => {
				let mut obs = obs_states::Shattered::new(
					shattered.extract_position(),
				);
				obs.mutate_annotation(shattered.extract_annotation());
				Self::Shattered(obs)
			}
			
			// Paradox: this is the tricky one.
			// Paradox has absolute_payload: GLASS (guaranteed).
			// But: the residual's GLASS is Infallible. No real value.
			// The absolute_payload: was erased with everything else.
			// On reconstruction: we can't restore it. The evidence is gone.
			//
			// A Paradox that lost its evidence: is no longer provably paradoxical.
			// It's: a Shattered observation that USED to be a Paradox.
			// Downgrade to Shattered with annotation explaining the provenance.
			Observation::Paradox(paradox) => {
				let mut obs = obs_states::Shattered::new(
					paradox.extract_position(),
				);
				obs.mutate_annotation(
					Annotation::Note(
						alloc::format!(
							"Paradox evidence lost during ? propagation. \
                             Original annotation: {:?}",
							paradox.extract_annotation()
						)
					)
				);
				Self::Shattered(obs)
			}
			
			// Unknown: payload erased. Metadata preserved.
			Observation::Unknown(unknown) => {
				let mut obs = obs_states::Unknown::new(
					None,
					unknown.extract_position(),
				);
				obs.mutate_annotation(unknown.extract_annotation());
				Self::Unknown(obs)
			}
		}
	}
}

impl<GLASS> FromResidual<Result<core::convert::Infallible, core::fmt::Error>> for Observation<GLASS> {
	fn from_residual(_residual: Result<core::convert::Infallible, core::fmt::Error>) -> Observation<GLASS> {
		Observation::shattered(&FROM_RESIDUAL_TOPOLOGY_SEGMENT)
			.with_note("std::fmt::Error converted to Glass")
			.with_suggestion("If you are seeing this Error and TopologySegment, it means you need to handle States better at call site. \
			The boundary protocol cant Observe the entire pipeline like how Observation can. If you are using Result<T, E> somewhere an op could fail, use Observation<GLASS> instead and declare its state so Topology can fill itself in.")
	}
}
const OBSERVATION_TOPOLOGY_ANCH0R: TopologySegment = TopologySegment::new("Daemonic::Glass::Observation<GLASS>");
impl<GLASS> Observation<GLASS> {
	/// Construct a Stable observation with payload
	/// TopologySegments must be constructed as static constants at call site implementation with:
	/// ```rust
	/// use daemonic_error::TopologySegment
	/// struct MyType { fielda: String }
	/// impl MyType {
	///      const TOPOLOGY: TopologySegment = TopologySegment::new("Daemonic::Glass::Consumer::MyType");
	///  }
	/// ```
	pub fn stable(value: GLASS, position: &'static TopologySegment) -> Observation<GLASS> {
		Observation::Stable(Stable::new(value, position))
	}
	pub fn cracked(value: Option<GLASS>, position: &'static TopologySegment) -> Observation<GLASS> {
		Observation::Cracked(obs_states::Cracked::new(value, position))
	}
	pub fn fractured(value: Option<GLASS>, position: &'static TopologySegment) -> Observation<GLASS> {
		Observation::Fractured(obs_states::Fractured::new(value, position))
	}
	pub fn echo(value: Option<GLASS>, position: &'static TopologySegment) -> Observation<GLASS> {
		Observation::Echo(obs_states::Echo::new(value, position))
	}
	pub fn warped(value: Option<GLASS>, position: &'static TopologySegment) -> Observation<GLASS> {
		Observation::Warped(obs_states::Warped::new(value, position))
	}
	pub fn drift(value: Option<GLASS>, position: &'static TopologySegment) -> Observation<GLASS> {
		Observation::Drift(obs_states::Drift::new(value, position))
	}
	pub fn opaque(phantom: PhantomData<GLASS>, position: &'static TopologySegment) -> Observation<GLASS> {
		Observation::Opaque(obs_states::Opaque::new(phantom, position))
	}
	pub fn paradox(absolute_value: GLASS, asserted_value: Option<GLASS>, position: &'static TopologySegment) -> Observation<GLASS> {
		Observation::Paradox(obs_states::Paradox::new(absolute_value, asserted_value, position))
	}
	pub fn impossible(phantom: PhantomData<GLASS>, position: &'static TopologySegment) -> Observation<GLASS> {
		Observation::Impossible(obs_states::Impossible::new(phantom, position))
	}
	/// Construct a Shattered observation (no payload)
	pub fn shattered(position: &'static TopologySegment) -> Observation<GLASS> {
		Observation::Shattered(obs_states::Shattered::new(position))
	}
	/// Construct an Unknown observation (no payload)
	pub fn unknown(value: Option<GLASS>, position: &'static TopologySegment) -> Observation<GLASS> {
		Observation::Unknown(obs_states::Unknown::new(value, position))
	}
	
	/// Attach an annotation
	pub fn with_note(mut self, note: impl Into<String>) -> Self {
		match self {
			Self::Stable(mut s) => {
				Self::Stable(Stable::with_note(s, note.into()))
			}
			Self::Cracked(mut c) => {
				Self::Cracked(Cracked::with_note(c, note.into()))
			}
			Self::Fractured(mut f) => {
				Self::Fractured(Fractured::with_note(f, note.into()))
			}
			Self::Drift(mut d) => {
				Self::Drift(Drift::with_note(d, note.into()))
			}
			Self::Echo(mut e) => {
				Self::Echo(Echo::with_note(e, note.into()))
			}
			Self::Opaque(mut o) => {
				Self::Opaque(obs_states::Opaque::with_note(o, note.into()))
			}
			Self::Warped(mut w) => {
				Self::Warped(Warped::with_note(w, note.into()))
			}
			Self::Impossible(mut i) => {
				Self::Impossible(Impossible::with_note(i, note.into()))
			}
			Self::Shattered(mut sh) => {
				Self::Shattered(Shattered::with_note(sh, note.into()))
			}
			Self::Paradox(mut p) => {
				Self::Paradox(Paradox::with_note(p, note.into()))
			}
			Self::Unknown(mut u) => {
				Self::Unknown(Unknown::with_note(u, note.into()))
			}
		}
	}
	pub fn with_suggestion(mut self, suggestion: impl Into<String>) -> Self {
		match self {
			Self::Stable(mut s) => {
				Self::Stable(Stable::with_suggestion(s, suggestion.into()))
			}
			Self::Cracked(mut c) => {
				Self::Cracked(Cracked::with_suggestion(c, suggestion.into()))
			}
			Self::Fractured(mut f) => {
				Self::Fractured(Fractured::with_suggestion(f, suggestion.into()))
			}
			Self::Drift(mut d) => {
				Self::Drift(Drift::with_suggestion(d, suggestion.into()))
			}
			Self::Echo(mut e) => {
				Self::Echo(Echo::with_suggestion(e, suggestion.into()))
			}
			Self::Opaque(mut o) => {
				Self::Opaque(obs_states::Opaque::with_suggestion(o, suggestion.into()))
			}
			Self::Warped(mut w) => {
				Self::Warped(Warped::with_suggestion(w, suggestion.into()))
			}
			Self::Impossible(mut i) => {
				Self::Impossible(Impossible::with_suggestion(i, suggestion.into()))
			}
			Self::Shattered(mut sh) => {
				Self::Shattered(Shattered::with_suggestion(sh, suggestion.into()))
			}
			Self::Paradox(mut p) => {
				Self::Paradox(Paradox::with_suggestion(p, suggestion.into()))
			}
			Self::Unknown(mut u) => {
				Self::Unknown(Unknown::with_suggestion(u, suggestion.into()))
			}
		}
	}
	pub fn extract_topology_segment(&self) -> &'static TopologySegment {
		match self {
			Observation::Stable(s) => { s.extract_position() }
			Observation::Cracked(s) => { s.extract_position() }
			Observation::Fractured(s) => { s.extract_position() }
			Observation::Drift(s) => { s.extract_position() }
			Observation::Echo(s) => { s.extract_position() }
			Observation::Opaque(s) => { s.extract_position() }
			Observation::Warped(s) => { s.extract_position() }
			Observation::Impossible(s) => { s.extract_position() }
			Observation::Shattered(s) => { s.extract_position() }
			Observation::Paradox(s) => { s.extract_position() }
			Observation::Unknown(s) => { s.extract_position() }
		}
	}
	pub fn mutate_tier(self, tier: ObservationTier) -> Observation<GLASS> {
		match self {
			Observation::Stable(s) => {
				let mut glass = s;
				Observation::Stable(glass.mutate_tier(tier))
			}
			
			Observation::Cracked(c) => {
				let mut glass = c;
				Observation::Cracked(glass.mutate_tier(tier))
			}
			
			Observation::Fractured(s) => {
				let mut glass = s;
				Observation::Fractured(glass.mutate_tier(tier))
			}
			
			Observation::Drift(s) => {
				let mut glass = s;
				Observation::Drift(glass.mutate_tier(tier))
			}
			
			Observation::Echo(s) => {
				let mut glass = s;
				Observation::Echo(glass.mutate_tier(tier))
			}
			
			Observation::Opaque(s) => {
				let mut glass = s;
				Observation::Opaque(glass.mutate_tier(tier))
			}
			
			Observation::Warped(s) => {
				let mut glass = s;
				Observation::Warped(glass.mutate_tier(tier))
			}
			
			Observation::Impossible(s) => {
				let mut glass = s;
				Observation::Impossible(glass.mutate_tier(tier))
			}
			
			Observation::Shattered(s) => {
				let mut glass = s;
				Observation::Shattered(glass.mutate_tier(tier))
			}
			
			Observation::Paradox(s) => {
				let mut glass = s;
				Observation::Paradox(glass.mutate_tier(tier))
			}
			
			Observation::Unknown(s) => {
				let mut glass = s;
				Observation::Unknown(glass.mutate_tier(tier))
			}
		}
	}
	pub fn extract_severity(&self) -> Severity {
		match self {
			Observation::Stable(stable) => {
				stable.extract_severity()
			}
			Observation::Cracked(cracked) => {
				cracked.extract_severity()
			}
			
			Observation::Fractured(fractured) => {
				fractured.extract_severity()
			}
			
			Observation::Drift(drift) => {
				drift.extract_severity()
			}
			
			Observation::Echo(echo) => {
				echo.extract_severity()
			}
			
			Observation::Opaque(opaque) => {
				opaque.extract_severity()
			}
			
			Observation::Warped(warped) => {
				warped.extract_severity()
			}
			
			Observation::Impossible(impossible) => {
				impossible.extract_severity()
			}
			
			Observation::Shattered(shattered) => {
				shattered.extract_severity()
			}
			
			Observation::Paradox(paradox) => {
				paradox.extract_severity()
			}
			
			Observation::Unknown(unknown) => {
				unknown.extract_severity()
			}
		}
	}
}
// SAFETY: Observation is Send + Sync if GLASS is Send + Sync
#[allow(unsafe_code)]
unsafe impl<GLASS: Send> Send for Observation<GLASS> {}
#[allow(unsafe_code)]
unsafe impl<GLASS: Sync> Sync for Observation<GLASS> {}
#[allow(unsafe_code)]
unsafe impl<GLASS> DaemonicSystemCall for Observation<GLASS> {}

// impl<GLASS: Glass<GLASS>> Glass<Observation<GLASS>> for Observation<GLASS> {
// 	type Anchor = TopologySegment;
//
// 	fn position(&self) -> &TopologySegment { &self.position }
//
// 	fn severity(&self) -> Severity { self.severity }
//
// 	fn annotation(&self) -> Annotation { self.annotation.clone() }
//
// 	fn temporal(&self) -> Temporal { self.temporal.clone() }
//
// 	fn tier(&self) -> ObservationTier { self.tier }
//
// 	fn payload(&self) -> Option<&Observation<GLASS>> { Some(self) }
// 	fn into_payload(self) -> Option<Observation<GLASS>> { Some(self) }
// }
// ═══════════════════════════════════════════════════════════════
// BOUNDARY PROTOCOL (Glass ↔ Result/Option)
// ═══════════════════════════════════════════════════════════════


/// Convert Result to Glass observation (information-adding)
impl<T, E: core::fmt::Display> From<Result<T, E>> for Observation<T> {
	fn from(result: Result<T, E>) -> Self {
		match result {
			Ok(value) => Observation::Stable(obs_states::Stable::new(value, &OK_FROM_RESULT_RESIDUAL_TOPOLOGY_SEGMENT)),
			Err(e) => Observation::Shattered(Shattered::new(&ERR_FROM_RESULT_RESIDUAL_TOPOLOGY_SEGMENT).with_note(e.to_string()))
		}
	}
}

/// Convert Option to Glass observation (None = Unknown)
impl<T> From<Option<T>> for Observation<T> {
	fn from(opt: Option<T>) -> Observation<T> {
		let some_position = &SOME_FROM_OPTION_TOPOLOGY_SEGMENT;
		let none_position = &NONE_FROM_OPTION_TOPOLOGY_SEGMENT;
		match opt {
			Some(value) => Observation::Stable(Stable::new(value, some_position).with_note("[DAMEONIC ERROR] <-> BOUNDARY PROTOCOL <-> OPTION<T> <-> TOPOLOGY MIGHT BE LOSSY THROUGH THIS INTERFACE")),
			None => Observation::Unknown(Unknown::new(None, none_position).with_note("[DAMEONIC ERROR] <-> BOUNDARY PROTOCOL <-> OPTION<T> <-> TOPOLOGY MIGHT BE LOSSY THROUGH THIS INTERFACE")),
		}
	}
}
impl<GLASS> Observation<GLASS> {
	pub(crate) fn to_errno(&self) -> i32 {
		0i32
		// todo fix this
		// escalated observations store negative syscall return
		// negate to get positive errno
		// -(self.payload.unwrap_or(0)) as i32
		
	}
}