daemonic_error 1.0.0

// Bitflag constants
const HOLDING:         u16 = 1 << 0;
const CONTAINABLE:     u16 = 1 << 1;
const SHOULD_CONTINUE: u16 = 1 << 2;
const HAS_REPAIR:      u16 = 1 << 3;
const RETRY:           u16 = 1 << 4;
const EXPECTED:        u16 = 1 << 5;
const RECONSTRUCTIBLE: u16 = 1 << 6;
const ASSESSED:        u16 = 1 << 7;
const RESERVED_9:      u16 = 1 << 8;
const RESERVED_10:      u16 = 1 << 9;
const RESERVED_11:      u16 = 1 << 10;
const RESERVED_12:      u16 = 1 << 11;
const RESERVED_13:      u16 = 1 << 12;
const RESERVED_14:      u16 = 1 << 13;
const RESERVED_15:      u16 = 1 << 14;
const RESERVED_16:      u16 = 1 << 15;
#[derive(Clone, Copy, Debug)]
pub struct GlassFlags {
	///# `GlassFlags`
	///
	/// `GlassFlags` is a compact bitfield describing the current capabilities, state, and handling requirements associated with a `Glass` value.
	///
	/// The low eight bits are currently assigned semantic meaning. The remaining eight bits are reserved for future use.
	///
	/// ## Bit Layout
	/// ```ascii
	/// | Bit |      Mask | Name              | Meaning                                                                     |
	/// | --: | --------: | ----------------- | --------------------------------------------------------------------------- |
	/// |   0 |  `1 << 0` | `HOLDING`         | The associated state currently holds a value or reference.                  |
	/// |   1 |  `1 << 1` | `CONTAINABLE`     | The associated state may be contained by the enclosing structure.           |
	/// |   2 |  `1 << 2` | `SHOULD_CONTINUE` | Processing may/should continue after the current observation or transition. |
	/// |   3 |  `1 << 3` | `HAS_REPAIR`      | A repair mechanism is available for the associated state.                   |
	/// |   4 |  `1 << 4` | `RETRY`           | The current operation may be retried.                                       |
	/// |   5 |  `1 << 5` | `EXPECTED`        | The current state or result was expected by the governing operation.        |
	/// |   6 |  `1 << 6` | `RECONSTRUCTIBLE` | The associated state can be reconstructed from available information.       |
	/// |   7 |  `1 << 7` | `ASSESSED`        | The associated state has undergone assessment.                              |
	/// |   8 |  `1 << 8` | `RESERVED_9`      | Reserved for future semantics.                                              |
	/// |   9 |  `1 << 9` | `RESERVED_10`     | Reserved for future semantics.                                              |
	/// |  10 | `1 << 10` | `RESERVED_11`     | Reserved for future semantics.                                              |
	/// |  11 | `1 << 11` | `RESERVED_12`     | Reserved for future semantics.                                              |
	/// |  12 | `1 << 12` | `RESERVED_13`     | Reserved for future semantics.                                              |
	/// |  13 | `1 << 13` | `RESERVED_14`     | Reserved for future semantics.                                              |
	/// |  14 | `1 << 14` | `RESERVED_15`     | Reserved for future semantics.                                              |
	/// |  15 | `1 << 15` | `RESERVED_16`     | Reserved for future semantics.                                              |
	/// --------------------------------------------------------------------------------------------------------------------|
	/// ```
	/// ## Reserved Bits
	///
	/// Bits `8..=15` are reserved.
	///
	/// Reserved bits MUST remain semantically undefined until assigned. Implementations should not depend on their current zero-value state as an enduring semantic guarantee.
	///
	/// Future assignments should document:
	///
	/// * the bit position and mask;
	/// * the state represented by the flag;
	/// * interactions with existing flags;
	/// * whether the flag is observational, operational, or both;
	/// * whether the flag may be mutated after assessment;
	/// * compatibility requirements for serialized or persisted flag values.
	///
	/// ## Repair Enclosure
	///
	/// `GlassFlags` currently provides an optional repair enclosure:
	///
	/// ```rust
	/// repair: Option<fn() -> ()>,
	/// ```
	///
	/// The representation is provisional.
	///
	/// The intended shape of the repair mechanism is **TBD**. The current unit-returning function is therefore a structural placeholder rather than the final repair contract.
	///
	/// In particular, `HAS_REPAIR` should be treated as the semantic indication that repair is available; the concrete function representation should not yet be considered part of the stable interface.
	///
	/// ## Representation
	///
	/// ```rust
	/// pub struct GlassFlags {
	///     /// Bitfield containing the state and capability flags.
	///     bits: u16,
	///
	///     /// Optional repair enclosure.
	///     ///
	///     /// The concrete repair representation is provisional and currently
	///     /// stubbed as a unit-returning function.
	///     repair: Option<fn() -> ()>,
	/// }
	/// ```
	///
	/// The `u16` representation provides sixteen independent flag positions while keeping the flag state compact and directly maskable.
	///
	/// At present:
	///
	/// * **8 bits are defined** (`0..=7`);
	/// * **8 bits are reserved** (`8..=15`);
	/// * `repair` is an associated optional enclosure whose final representation remains undefined.
	bits: u16,
	// repair enclosure — shape is TBD, stubbed as unit for now
	repair: Option<fn() -> ()>,
}

impl GlassFlags {
	// ══ CONSTRUCTORS (preset defaults per state) ═══════════
	pub const fn stable_defaults() -> Self {
		GlassFlags {
			bits: 0,
			repair: None,
		}
	}
	/// Cracked defaults: holding, should_continue. Light error.
	pub const fn cracked_defaults() -> Self {
		GlassFlags {
			bits: HOLDING | SHOULD_CONTINUE | CONTAINABLE,
			repair: None,
		}
	}
	
	/// Fractured defaults: NOT should_continue. Medium error.
	pub const fn fractured_defaults() -> Self {
		GlassFlags {
			bits: 0,
			repair: None,
		}
	}
	pub const fn opaque_defaults() -> Self {
		GlassFlags {
			bits: 0,
			repair: None,
		}
	}
	pub const fn paradox_defaults() -> Self {
		GlassFlags {
			bits: 0,
			repair: None,
		}
	}
	/// Drift defaults: retry enabled, not should_continue.
	pub const fn drift_defaults() -> Self {
		GlassFlags {
			bits: RETRY,
			repair: None,
		}
	}
	pub const fn echo_defaults() -> Self {
		GlassFlags {
			bits: 0,
			repair: None,
		}
	}
	
	/// Shattered defaults: not expected, not reconstructible.
	pub const fn shattered_defaults() -> Self {
		GlassFlags {
			bits: 0,
			repair: None,
		}
	}
	
	/// Unknown defaults: not assessed, not should_continue.
	pub const fn unknown_defaults() -> Self {
		GlassFlags {
			bits: 0,
			repair: None,
		}
	}
	pub const fn warped_defaults() -> Self {
		GlassFlags {
			bits: 0,
			repair: None,
		}
	}
	
	/// Terminal states: no flags, no repair. Ever.
	pub const fn terminal() -> Self {
		GlassFlags {
			bits: 0,
			repair: None,
		}
	}
	
	// ══ PUBLIC FLAG SETTERS (for users at call sites) ══════
	
	pub fn set_holding(mut self, val: bool) -> Self {
		if val { self.bits |= HOLDING; } else { self.bits &= !HOLDING; }
		self
	}
	
	pub fn set_containable(mut self, val: bool) -> Self {
		if val { self.bits |= CONTAINABLE; } else { self.bits &= !CONTAINABLE; }
		self
	}
	
	pub fn set_should_continue(mut self, val: bool) -> Self {
		if val { self.bits |= SHOULD_CONTINUE; } else { self.bits &= !SHOULD_CONTINUE; }
		self
	}
	
	pub fn set_retry(mut self, val: bool) -> Self {
		if val { self.bits |= RETRY; } else { self.bits &= !RETRY; }
		self
	}
	
	pub fn set_expected(mut self, val: bool) -> Self {
		if val { self.bits |= EXPECTED; } else { self.bits &= !EXPECTED; }
		self
	}
	
	pub fn set_reconstructible(mut self, val: bool) -> Self {
		if val { self.bits |= RECONSTRUCTIBLE; } else { self.bits &= !RECONSTRUCTIBLE; }
		self
	}
	
	pub fn set_repair<GLASS>(mut self, repair_fn: fn() -> ()) -> Self {
		self.repair = Some(repair_fn);
		self.bits |= HAS_REPAIR;
		self
	}
	
	// ══ READERS (for branch(), inherent, no bounds) ════════
	// These are pub(crate) — branch() and internals read them.
	// Consumers use the setters. Internals read the results.
	
	pub fn is_holding(&self) -> bool {
		self.bits & HOLDING != 0
	}
	
	pub fn is_containable(&self) -> bool {
		self.bits & CONTAINABLE != 0
	}
	
	pub fn should_continue(&self) -> bool {
		self.bits & SHOULD_CONTINUE != 0
	}
	
	pub fn has_repair(&self) -> bool {
		self.bits & HAS_REPAIR != 0
	}
	
	pub fn should_retry(&self) -> bool {
		self.bits & RETRY != 0
	}
	
	pub fn is_expected(&self) -> bool {
		self.bits & EXPECTED != 0
	}
	
	pub fn is_reconstructible(&self) -> bool {
		self.bits & RECONSTRUCTIBLE != 0
	}
	
	pub fn is_assessed(&self) -> bool {
		self.bits & ASSESSED != 0
	}
}
// pub struct Cracked<GLASS> {
// 	position: &'static TopologySegment,
// 	severity: Severity,
// 	tier: ObservationTier,
// 	annotation: Annotation,
// 	temporal: Temporal,
// 	payload: Option<GLASS>,
// 	flags: GlassFlags,          // ← one field. All behavior.
// }
//
// impl<GLASS> Cracked<GLASS> {
// 	pub fn new(payload: Option<GLASS>, position: &'static TopologySegment) -> Self {
// 		Cracked {
// 			position,
// 			severity: Severity::Cracked,
// 			tier: ObservationTier::Composed,
// 			annotation: Annotation::None,
// 			temporal: Temporal::Current,
// 			payload,
// 			flags: GlassFlags::cracked_defaults(),
// 		}
// 	}
//
// 	/// Expose flags for builder-pattern modification at call site.
// 	pub fn with_flags(mut self, flags: GlassFlags) -> Self {
// 		self.flags = flags;
// 		self
// 	}
//
// 	/// Direct flag access for branch().
// 	pub(crate) fn flags(&self) -> &GlassFlags {
// 		&self.flags
// 	}
// }