irys 0.2.0

//! # irys — Compile-Time Trait Reflection for Rust
//!
//! **Automatically discover which traits a type implements at compile time, without per-type annotation.**
//!
//! ```rust
//! use irys::*;
//! use std::fmt;
//!
//! // 1. Define a capability (marker struct + what trait object it maps to)
//! struct DisplayCap;
//! impl Capability for DisplayCap {
//!     type Handle = dyn fmt::Display;
//! }
//!
//! // 2. Register it (one-time, blanket — covers ALL types that implement Display)
//! register_capability! {
//!     slot = 0,
//!     cap = DisplayCap,
//!     trait_bound = fmt::Display,
//! }
//!
//! // 3. Reflect any value — capabilities are detected automatically
//! let envelope = reflect!("hello world");
//! assert!(envelope.has::<DisplayCap>());
//!
//! let display = envelope.get::<DisplayCap>().unwrap();
//! assert_eq!(format!("{}", display), "hello world");
//! ```
//!
//! ## Why irys?
//!
//! Every existing reflection system in Rust requires **per-type registration**:
//!
//! | System | Registration cost | Trait discovery? |
//! |--------|-------------------|-----------------|
//! | **irys** | **1 per trait** (blanket covers all types) | Yes, automatic |
//! | `bevy_reflect` | 1 per type + 1 per type×trait | Partial (explicit `#[reflect(Trait)]`) |
//! | `typetag` | 1 per type×trait | No (serde only) |
//! | `inventory`/`linkme` | 1 per type | No |
//! | `std::any::Any` | None | No (downcast only) |
//!
//! With irys, you register a capability **once** and it automatically applies to every type
//! that satisfies the trait bound — past, present, and future. No derives, no proc macros,
//! no per-type boilerplate.
//!
//! ## Core Concepts
//!
//! ### Capabilities
//!
//! A **capability** is a marker struct that maps to a trait object type. It answers the
//! question "can this value do X?":
//!
//! ```rust,ignore
//! struct SerializeCap;
//! impl Capability for SerializeCap {
//!     type Handle = dyn erased_serde::Serialize;
//! }
//! ```
//!
//! ### Registries
//!
//! A **registry** is a namespace for capabilities. It isolates your capability slots from
//! other libraries so they can't collide:
//!
//! ```rust
//! # use irys::*;
//! # use std::fmt;
//! struct MyRegistry;
//!
//! # struct DebugCap;
//! # impl Capability for DebugCap { type Handle = dyn fmt::Debug; }
//! register_capability! {
//!     registry = MyRegistry,
//!     slot = 0,  // slot 0 in YOUR registry — no conflict with anyone else's slot 0
//!     cap = DebugCap,
//!     trait_bound = fmt::Debug,
//! }
//! ```
//!
//! When no registry is specified, [`DefaultRegistry`] is used.
//!
//! ### Slots
//!
//! Each capability occupies a **slot** (a number) within a registry. The slot determines
//! which compile-time probe fires during reflection. Two capabilities at the same slot
//! in the same registry will produce a compile error — this is intentional collision
//! detection.
//!
//! You only probe the slots you use. 5 capabilities? Probe 5 slots. This means compile
//! time scales with what YOU care about, not what exists in the ecosystem.
//!
//! ### Envelopes — The Ownership Model
//!
//! irys follows the same ownership model as `Vec<T>` / `&[T]` / `&mut [T]`:
//!
//! | Type | Created by | Access |
//! |------|-----------|--------|
//! | [`Envelope`] | [`reflect!`] | Full ownership: get, get_mut, into_data |
//! | [`EnvelopeRef`] | [`reflect_ref!`] or [`Envelope::as_ref`] | Shared: get, data |
//! | [`EnvelopeMut`] | [`reflect_mut!`] or [`Envelope::as_mut`] | Mutable: get, get_mut, data_mut |
//!
//! ```rust
//! # use irys::*;
//! # use std::fmt;
//! # struct DisplayCap;
//! # impl Capability for DisplayCap { type Handle = dyn fmt::Display; }
//! # register_capability! { slot = 0, cap = DisplayCap, trait_bound = fmt::Display }
//! // Owned — consumes the value
//! let envelope = reflect!(42i32);
//!
//! // Shared borrow — value remains available
//! let value = 42i32;
//! let envelope_ref = reflect_ref!(&value);
//! assert_eq!(value, 42); // still usable
//!
//! // Mutable borrow — can mutate through capabilities
//! # trait Resettable { fn reset(&mut self); }
//! # struct ResettableCap;
//! # impl Capability for ResettableCap { type Handle = dyn Resettable; }
//! # register_capability! { slot = 1, cap = ResettableCap, trait_bound = Resettable }
//! # struct Counter { count: u32 }
//! # impl Resettable for Counter { fn reset(&mut self) { self.count = 0; } }
//! let mut counter = Counter { count: 99 };
//! {
//!     let mut env = reflect_mut!(&mut counter);
//!     env.get_mut::<ResettableCap>().unwrap().reset();
//! }
//! assert_eq!(counter.count, 0); // mutated in place
//! ```
//!
//! Conversions work like you'd expect:
//! - `envelope.as_ref()` → `EnvelopeRef` (borrows the envelope's map, zero-cost)
//! - `envelope.as_mut()` → `EnvelopeMut` (borrows the envelope's map, zero-cost)
//! - `envelope_mut.as_ref()` → `EnvelopeRef` (downgrade to shared)
//!
//! ## Registries & Slot Ranges
//!
//! By default, `reflect!` probes the [`DefaultRegistry`] for 256 slots. You can customize
//! which registries and how many slots to probe:
//!
//! ```rust
//! # use irys::*;
//! # struct CoreRegistry;
//! # struct ObsRegistry;
//! # let value = 42i32;
//! let envelope = reflect!(value, [
//!     { registry: CoreRegistry, slots: 0..5 },
//!     { registry: ObsRegistry, slots: 0..3 },
//! ]);
//! ```
//!
//! This gives you precise control over compile-time cost: only probe the slots you actually
//! use. If you have 5 capabilities, probe 5 slots — not 256.
//!
//! Registries probed later **override** earlier ones for the same capability (last-write-wins).
//! This gives you natural override/specialization semantics without language-level specialization.
//!
//! ## The `Reflectable` Trait
//!
//! For generic code that needs to work with reflected values, implement [`Reflectable`].
//! The [`impl_reflectable!`] macro does this in one line:
//!
//! ```rust
//! # use irys::*;
//! # struct MyRegistry;
//! struct MyEvent { data: String }
//!
//! impl_reflectable!(MyEvent, [{ registry: MyRegistry, slots: 0..10 }]);
//!
//! // Generic code can accept anything Reflectable
//! fn publish(event: impl Reflectable) {
//!     let envelope = event.reflect();
//!     // route based on capabilities...
//! }
//!
//! // Also works with borrowed access
//! fn inspect(event: &impl Reflectable) {
//!     let envelope_ref = event.reflect_ref();
//!     // read-only capability access...
//! }
//! ```
//!
//! This is analogous to how `bevy_reflect` uses `#[derive(Reflect)]` — but here it's
//! a one-line macro invocation with no proc macros.
//!
//! ## Common Patterns
//!
//! ### Cloning an Envelope
//!
//! `Envelope` can't implement `Clone` directly (the inner value is type-erased). Instead,
//! register `Clone` as a capability, then use [`caps()`](Envelope::caps) +
//! [`from_raw()`](Envelope::from_raw) to reconstruct:
//!
//! ```rust
//! # use irys::*;
//! use std::any::Any;
//!
//! trait DynClone: Send + Sync {
//!     fn clone_boxed(&self) -> Box<dyn Any + Send + Sync>;
//! }
//!
//! impl<T: Clone + Send + Sync + 'static> DynClone for T {
//!     fn clone_boxed(&self) -> Box<dyn Any + Send + Sync> {
//!         Box::new(self.clone())
//!     }
//! }
//!
//! struct CloneCap;
//! impl Capability for CloneCap {
//!     type Handle = dyn DynClone;
//! }
//!
//! register_capability! {
//!     slot = 0,
//!     cap = CloneCap,
//!     trait_bound = DynClone,
//! }
//!
//! // Clone an envelope:
//! # #[derive(Clone)] struct MyData(i32);
//! let envelope = reflect!(MyData(42));
//! let cloned_data = envelope.get::<CloneCap>().unwrap().clone_boxed();
//! let cloned_envelope = Envelope::from_raw(cloned_data, envelope.caps().clone());
//! ```
//!
//! The capability map clone is cheap (just `Arc` refcount bumps internally). If the map
//! doesn't match the data type (e.g., after calling `from_raw` with wrong data),
//! `get()` safely returns `None` — no panics.
//!
//! ### Event Bus Routing
//!
//! Route heterogeneous events based on discovered capabilities:
//!
//! ```rust,ignore
//! use std::sync::{mpsc, Arc};
//!
//! fn router(rx: mpsc::Receiver<Arc<Envelope>>) {
//!     while let Ok(envelope) = rx.recv() {
//!         if let Some(prio) = envelope.get::<PriorityCap>() {
//!             if prio.is_critical() {
//!                 escalate(&envelope);
//!             }
//!         }
//!         if envelope.has::<SerializeCap>() {
//!             persist(&envelope);
//!         }
//!     }
//! }
//! ```
//!
//! ### Composing with Other Reflection Libraries
//!
//! irys can wrap other reflection systems as capabilities:
//!
//! ```rust,ignore
//! struct ReflectCap;
//! impl Capability for ReflectCap {
//!     type Handle = dyn bevy_reflect::Reflect;
//! }
//!
//! register_capability! {
//!     slot = 0,
//!     cap = ReflectCap,
//!     trait_bound = bevy_reflect::Reflect,
//! }
//!
//! // Now any type implementing Reflect is automatically detected
//! // irys handles discovery, bevy_reflect handles structural introspection
//! ```
//!
//! ## How It Works
//!
//! irys uses a technique called **autoref specialization** combined with **const generics**
//! to achieve compile-time trait detection on stable Rust. Here's the mechanism:
//!
//! 1. **`register_capability!`** generates two impls for each capability:
//!    - An inherent-like impl on `Probe<T, Registry, N>` with a trait bound (`T: MyTrait`)
//!    - A blanket trait impl on `&Probe<T, Registry, N>` with no bound (the fallback)
//!
//! 2. **`reflect!`** expands (via `seq!`) into a loop calling `.probe()` for each slot.
//!    Rust's method resolution prefers the inherent impl when the bound is satisfied,
//!    falling back to the trait impl (which is a no-op) when it's not.
//!
//! 3. **The compiler resolves this statically** — there's no runtime branching. For
//!    capabilities a type doesn't have, the optimizer eliminates the no-op entirely.
//!
//! 4. **Registries** are just type parameters on `Probe`, giving each namespace its own
//!    set of inherent impls that can't collide with other registries.
//!
//! The result: zero runtime cost for undetected capabilities, and the entire detection
//! happens at compile time.
//!
//! ## Limitations
//!
//! - **Concrete types only at the `reflect!()` call site**: The autoref trick requires the
//!   compiler to see the concrete type. In generic functions where `T` is abstract, use the
//!   [`Reflectable`] trait pattern (implement `Reflectable` on concrete types, then bound
//!   generic code with `T: Reflectable`). This is the same constraint every Rust reflection
//!   library has — bevy_reflect requires `#[derive(Reflect)]` on concrete types too.
//!
//! - **Capabilities only propagate downward**: A `reflect!()` call can only detect
//!   capabilities whose `register_capability!` was visible at compile time — i.e., defined
//!   in the same crate or in a dependency. If crate A calls `reflect!()` and crate B
//!   (which depends on A) registers a new capability, crate A will NOT see it. This is a
//!   fundamental consequence of Rust's compilation model: upstream crates are compiled
//!   before downstream crates exist.
//!
//!   **Workarounds**: Have the upstream crate accept a pre-constructed [`Envelope`], a
//!   `fn() -> Envelope`, or a type implementing [`Reflectable`]. This pushes the `reflect!()`
//!   call to the downstream crate where all capabilities are visible.
//!
//! - **Slot management is manual**: You pick slot numbers. The compiler catches collisions
//!   (same registry + same slot = compile error), but you manage the allocation. Use
//!   registries to isolate your slots from other libraries.
//!
//! - **`unsafe` internally**: Fat pointer transport between type-erased closures requires
//!   `transmute_copy`. This is sound (trait object fat pointer layout is guaranteed) but
//!   the code does contain `unsafe` blocks internally. The public API is fully safe.

use std::any::{Any, TypeId};
use std::borrow::Cow;
use std::collections::HashMap;
use std::marker::PhantomData;
use std::sync::Arc;

pub use seq_macro::seq;

/// The default registry used when no registry is specified in [`register_capability!`] or [`reflect!`].
///
/// All capabilities registered without an explicit `registry = ...` go into this registry.
/// The default `reflect!(value)` call probes this registry for slots 0..256.
pub struct DefaultRegistry;

/// A capability defines what trait object a type can be cast to.
///
/// Implement this on a marker struct to define a new capability:
///
/// ```rust,ignore
/// # use irys::Capability;
/// struct SerializeCap;
/// impl Capability for SerializeCap {
///     type Handle = dyn erased_serde::Serialize; // or your own bridge trait
/// }
/// ```
///
/// The `Handle` type is the trait object you'll get back from [`Envelope::get`].
pub trait Capability: 'static {
    /// The trait object type this capability provides access to.
    type Handle: ?Sized + 'static;
}

#[derive(Clone)]
struct CastFn {
    cast_ref: Arc<dyn Fn(&dyn Any) -> Option<[usize; 2]> + Send + Sync>,
    cast_mut: Arc<dyn Fn(&mut dyn Any) -> Option<[usize; 2]> + Send + Sync>,
}

/// Storage for detected capabilities and their type-erased cast functions.
///
/// You typically don't interact with this directly — it's created internally by [`reflect!`]
/// and stored inside [`Envelope`].
#[derive(Clone)]
pub struct CapabilityMap {
    entries: HashMap<TypeId, CastFn>,
}

impl CapabilityMap {
    pub fn new() -> Self {
        Self { entries: HashMap::new() }
    }

    pub fn insert_cast<C: Capability>(
        &mut self,
        cast_ref: impl Fn(&dyn Any) -> Option<&C::Handle> + Send + Sync + 'static,
        cast_mut: impl Fn(&mut dyn Any) -> Option<&mut C::Handle> + Send + Sync + 'static,
    ) {
        self.entries.insert(TypeId::of::<C>(), CastFn {
            cast_ref: Arc::new(move |any| {
                let handle: &C::Handle = cast_ref(any)?;
                Some(unsafe { std::mem::transmute_copy::<&C::Handle, [usize; 2]>(&handle) })
            }),
            cast_mut: Arc::new(move |any| {
                let handle: &mut C::Handle = cast_mut(any)?;
                Some(unsafe { std::mem::transmute_copy::<&mut C::Handle, [usize; 2]>(&handle) })
            }),
        });
    }

    pub fn has<C: Capability>(&self) -> bool {
        self.entries.contains_key(&TypeId::of::<C>())
    }

    pub fn len(&self) -> usize {
        self.entries.len()
    }

    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }

    fn get_ref<C: Capability>(&self, data: &dyn Any) -> Option<[usize; 2]> {
        let cast_fn = self.entries.get(&TypeId::of::<C>())?;
        (cast_fn.cast_ref)(data)
    }

    fn get_mut<C: Capability>(&self, data: &mut dyn Any) -> Option<[usize; 2]> {
        let cast_fn = self.entries.get(&TypeId::of::<C>())?;
        (cast_fn.cast_mut)(data)
    }
}

/// A reflected value with its discovered capabilities (owned).
///
/// Created by [`reflect!`], an `Envelope` wraps the original value and provides
/// capability-based access to trait objects. This is the owned variant — analogous to
/// `Vec<T>`. For borrowed access, see [`EnvelopeRef`] and [`EnvelopeMut`].
///
/// # Conversions
///
/// Like `Vec<T>` → `&[T]` / `&mut [T]`:
/// - [`Envelope::as_ref`] → [`EnvelopeRef`]
/// - [`Envelope::as_mut`] → [`EnvelopeMut`]
///
/// # Thread Safety
///
/// `Envelope` is `Send + Sync` (the inner value is `Box<dyn Any + Send + Sync>`).
/// For shared access across threads, wrap in `Arc<Envelope>`.
pub struct Envelope {
    data: Box<dyn Any + Send + Sync>,
    caps: CapabilityMap,
}

impl Envelope {
    pub fn from_parts(data: impl Any + Send + Sync, caps: CapabilityMap) -> Self {
        Self { data: Box::new(data), caps }
    }

    /// Construct an envelope from a pre-boxed value and a capability map.
    ///
    /// This is useful for reconstructing an envelope after cloning the inner value
    /// via a `DynClone` capability. If the capability map doesn't match the boxed type,
    /// `get()` will safely return `None` rather than panicking.
    pub fn from_raw(data: Box<dyn Any + Send + Sync>, caps: CapabilityMap) -> Self {
        Self { data, caps }
    }

    /// Get a shared reference to the capability map.
    pub fn caps(&self) -> &CapabilityMap {
        &self.caps
    }

    /// Borrow this envelope as an [`EnvelopeRef`] (read-only access).
    pub fn as_ref(&self) -> EnvelopeRef<'_> {
        EnvelopeRef { data: &*self.data, caps: Cow::Borrowed(&self.caps) }
    }

    /// Borrow this envelope as an [`EnvelopeMut`] (read + mutable trait access).
    pub fn as_mut(&mut self) -> EnvelopeMut<'_> {
        EnvelopeMut { data: &mut *self.data, caps: Cow::Borrowed(&self.caps) }
    }

    /// Get a shared reference to the capability's trait object.
    ///
    /// Returns `None` if the wrapped type doesn't implement the capability's trait bound.
    pub fn get<C: Capability>(&self) -> Option<&C::Handle> {
        let fat = self.caps.get_ref::<C>(&*self.data)?;
        unsafe { Some(&*std::mem::transmute_copy::<[usize; 2], *const C::Handle>(&fat)) }
    }

    /// Get a mutable reference to the capability's trait object.
    ///
    /// Returns `None` if the wrapped type doesn't implement the capability's trait bound.
    pub fn get_mut<C: Capability>(&mut self) -> Option<&mut C::Handle> {
        let fat = self.caps.get_mut::<C>(&mut *self.data)?;
        unsafe { Some(&mut *std::mem::transmute_copy::<[usize; 2], *mut C::Handle>(&fat)) }
    }

    /// Check whether this envelope's value has a given capability.
    pub fn has<C: Capability>(&self) -> bool {
        self.caps.has::<C>()
    }

    /// Get a shared reference to the underlying concrete type.
    ///
    /// Returns `None` if `T` doesn't match the actual stored type.
    pub fn data<T: 'static>(&self) -> Option<&T> {
        self.data.downcast_ref()
    }

    /// Get a mutable reference to the underlying concrete type.
    ///
    /// Returns `None` if `T` doesn't match the actual stored type.
    pub fn data_mut<T: 'static>(&mut self) -> Option<&mut T> {
        self.data.downcast_mut()
    }

    /// Consume the envelope and recover the original value.
    ///
    /// Returns `None` if `T` doesn't match the actual stored type.
    pub fn into_data<T: 'static>(self) -> Option<T> {
        self.data.downcast().ok().map(|b| *b)
    }

    /// The number of capabilities detected on this value.
    pub fn capability_count(&self) -> usize {
        self.caps.len()
    }
}

/// A borrowed reflected value with read-only capability access.
///
/// Created by [`reflect_ref!`] or [`Envelope::as_ref`]. Analogous to `&[T]`.
/// Provides shared access to capabilities without consuming the original value.
///
/// # Example
///
/// ```rust
/// # use irys::*;
/// # use std::fmt;
/// # struct DisplayCap;
/// # impl Capability for DisplayCap { type Handle = dyn fmt::Display; }
/// # register_capability! { slot = 0, cap = DisplayCap, trait_bound = fmt::Display }
/// let value = 42i32;
/// let envelope_ref = reflect_ref!(&value);
/// assert!(envelope_ref.has::<DisplayCap>());
/// // value is still available here
/// assert_eq!(value, 42);
/// ```
pub struct EnvelopeRef<'a> {
    data: &'a dyn Any,
    caps: Cow<'a, CapabilityMap>,
}

impl<'a> EnvelopeRef<'a> {
    pub fn from_parts(data: &'a dyn Any, caps: CapabilityMap) -> Self {
        Self { data, caps: Cow::Owned(caps) }
    }

    /// Get a shared reference to the capability map.
    pub fn caps(&self) -> &CapabilityMap {
        &self.caps
    }

    /// Get a shared reference to the capability's trait object.
    ///
    /// Returns `None` if the wrapped type doesn't implement the capability's trait bound.
    pub fn get<C: Capability>(&self) -> Option<&C::Handle> {
        let fat = self.caps.get_ref::<C>(self.data)?;
        unsafe { Some(&*std::mem::transmute_copy::<[usize; 2], *const C::Handle>(&fat)) }
    }

    /// Check whether this envelope's value has a given capability.
    pub fn has<C: Capability>(&self) -> bool {
        self.caps.has::<C>()
    }

    /// Get a shared reference to the underlying concrete type.
    ///
    /// Returns `None` if `T` doesn't match the actual stored type.
    pub fn data<T: 'static>(&self) -> Option<&T> {
        self.data.downcast_ref()
    }

    /// The number of capabilities detected on this value.
    pub fn capability_count(&self) -> usize {
        self.caps.len()
    }
}

/// A mutably borrowed reflected value with read + write capability access.
///
/// Created by [`reflect_mut!`] or [`Envelope::as_mut`]. Analogous to `&mut [T]`.
/// Provides mutable access to capabilities without consuming the original value.
///
/// # Example
///
/// ```rust
/// # use irys::*;
/// # use std::fmt;
/// # trait Resettable { fn reset(&mut self); fn value(&self) -> String; }
/// # struct ResettableCap;
/// # impl Capability for ResettableCap { type Handle = dyn Resettable; }
/// # register_capability! { slot = 0, cap = ResettableCap, trait_bound = Resettable }
/// # struct Counter { count: u32 }
/// # impl Resettable for Counter { fn reset(&mut self) { self.count = 0; } fn value(&self) -> String { format!("{}", self.count) } }
/// let mut value = Counter { count: 42 };
/// let mut envelope_mut = reflect_mut!(&mut value);
/// envelope_mut.get_mut::<ResettableCap>().unwrap().reset();
/// assert_eq!(value.count, 0);
/// ```
pub struct EnvelopeMut<'a> {
    data: &'a mut dyn Any,
    caps: Cow<'a, CapabilityMap>,
}

impl<'a> EnvelopeMut<'a> {
    pub fn from_parts(data: &'a mut dyn Any, caps: CapabilityMap) -> Self {
        Self { data, caps: Cow::Owned(caps) }
    }

    /// Get a shared reference to the capability map.
    pub fn caps(&self) -> &CapabilityMap {
        &self.caps
    }

    /// Downgrade to a read-only [`EnvelopeRef`].
    pub fn as_ref(&self) -> EnvelopeRef<'_> {
        EnvelopeRef { data: self.data, caps: Cow::Borrowed(&self.caps) }
    }

    /// Get a shared reference to the capability's trait object.
    ///
    /// Returns `None` if the wrapped type doesn't implement the capability's trait bound.
    pub fn get<C: Capability>(&self) -> Option<&C::Handle> {
        let fat = self.caps.get_ref::<C>(self.data)?;
        unsafe { Some(&*std::mem::transmute_copy::<[usize; 2], *const C::Handle>(&fat)) }
    }

    /// Get a mutable reference to the capability's trait object.
    ///
    /// Returns `None` if the wrapped type doesn't implement the capability's trait bound.
    pub fn get_mut<C: Capability>(&mut self) -> Option<&mut C::Handle> {
        let fat = self.caps.get_mut::<C>(self.data)?;
        unsafe { Some(&mut *std::mem::transmute_copy::<[usize; 2], *mut C::Handle>(&fat)) }
    }

    /// Check whether this envelope's value has a given capability.
    pub fn has<C: Capability>(&self) -> bool {
        self.caps.has::<C>()
    }

    /// Get a shared reference to the underlying concrete type.
    ///
    /// Returns `None` if `T` doesn't match the actual stored type.
    pub fn data<T: 'static>(&self) -> Option<&T> {
        self.data.downcast_ref()
    }

    /// Get a mutable reference to the underlying concrete type.
    ///
    /// Returns `None` if `T` doesn't match the actual stored type.
    pub fn data_mut<T: 'static>(&mut self) -> Option<&mut T> {
        self.data.downcast_mut()
    }

    /// The number of capabilities detected on this value.
    pub fn capability_count(&self) -> usize {
        self.caps.len()
    }
}

/// Trait for types that know how to reflect themselves.
///
/// Provides owned, shared, and mutable reflection — analogous to how
/// `Any` provides `downcast`, `downcast_ref`, and `downcast_mut`.
///
/// # Manual Implementation
///
/// ```rust
/// # use irys::*;
/// struct MyEvent { data: String }
///
/// impl Reflectable for MyEvent {
///     fn reflect(self) -> Envelope { reflect!(self) }
///     fn reflect_ref(&self) -> EnvelopeRef<'_> { reflect_ref!(&*self) }
///     fn reflect_mut(&mut self) -> EnvelopeMut<'_> { reflect_mut!(&mut *self) }
/// }
/// ```
///
/// # Using the Helper Macro
///
/// ```rust
/// # use irys::*;
/// struct MyEvent { data: String }
///
/// impl_reflectable!(MyEvent);
///
/// // With custom registries:
/// # struct MyRegistry;
/// struct OtherEvent;
/// impl_reflectable!(OtherEvent, [{ registry: MyRegistry, slots: 0..5 }]);
/// ```
pub trait Reflectable: Send + Sync + 'static {
    fn reflect(self) -> Envelope;
    fn reflect_ref(&self) -> EnvelopeRef<'_>;
    fn reflect_mut(&mut self) -> EnvelopeMut<'_>;
}

/// Implement [`Reflectable`] for a type with minimal boilerplate.
///
/// # Basic Usage (DefaultRegistry, 256 slots)
///
/// ```rust
/// # use irys::*;
/// struct MyEvent { data: String }
/// impl_reflectable!(MyEvent);
/// ```
///
/// # Custom Registries
///
/// ```rust
/// # use irys::*;
/// # struct CoreReg;
/// # struct ObsReg;
/// struct MyEvent;
/// impl_reflectable!(MyEvent, [
///     { registry: CoreReg, slots: 0..5 },
///     { registry: ObsReg, slots: 0..3 },
/// ]);
/// ```
#[macro_export]
macro_rules! impl_reflectable {
    ($ty:ty) => {
        $crate::impl_reflectable!($ty, [{ registry: $crate::DefaultRegistry, slots: 0..256 }]);
    };
    ($ty:ty, [$($registries:tt)*]) => {
        impl $crate::Reflectable for $ty {
            fn reflect(self) -> $crate::Envelope {
                $crate::reflect!(self, [$($registries)*])
            }
            fn reflect_ref(&self) -> $crate::EnvelopeRef<'_> {
                $crate::reflect_ref!(&*self, [$($registries)*])
            }
            fn reflect_mut(&mut self) -> $crate::EnvelopeMut<'_> {
                $crate::reflect_mut!(&mut *self, [$($registries)*])
            }
        }
    };
}

#[doc(hidden)]
pub struct Probe<'a, T, Registry, const N: u64>(pub &'a T, PhantomData<Registry>);

impl<'a, T, R, const N: u64> Probe<'a, T, R, N> {
    #[inline(always)]
    pub fn new(val: &'a T) -> Self {
        Self(val, PhantomData)
    }
}

#[doc(hidden)]
pub trait HasCap<Marker, Registry, const N: u64> {
    fn probe(&self, caps: &mut CapabilityMap);
}

#[doc(hidden)]
pub trait NoCap<Registry, const N: u64> {
    fn probe(&self, _caps: &mut CapabilityMap) {}
}

impl<T, R, const N: u64> NoCap<R, N> for &Probe<'_, T, R, N> {}

#[doc(hidden)]
#[macro_export]
macro_rules! probe_slot {
    ($msg:expr, $caps:expr, $registry:ty, $n:literal) => {{
        use $crate::HasCap as _;
        use $crate::NoCap as _;
        (&$crate::Probe::<_, $registry, $n>::new($msg)).probe($caps);
    }};
}

/// Reflect a value, automatically detecting which capabilities it supports.
///
/// Consumes the value and returns an owned [`Envelope`].
///
/// # Basic Usage
///
/// ```rust
/// # use irys::*;
/// # use std::fmt;
/// # struct DisplayCap;
/// # impl Capability for DisplayCap { type Handle = dyn fmt::Display; }
/// # register_capability! { slot = 0, cap = DisplayCap, trait_bound = fmt::Display }
/// // Probes DefaultRegistry, slots 0..256
/// let envelope = reflect!(42i32);
/// assert!(envelope.has::<DisplayCap>());
/// ```
///
/// # Custom Registries & Ranges
///
/// ```rust
/// # use irys::*;
/// # struct MyRegistry;
/// # let value = 42i32;
/// let envelope = reflect!(value, [
///     { registry: MyRegistry, slots: 0..10 },
/// ]);
/// ```
///
/// # Multiple Registries
///
/// ```rust
/// # use irys::*;
/// # struct CoreReg;
/// # struct ObsReg;
/// # let value = 42i32;
/// let envelope = reflect!(value, [
///     { registry: CoreReg, slots: 0..5 },
///     { registry: ObsReg, slots: 0..3 },
/// ]);
/// ```
///
/// Registries probed later override earlier ones for the same capability (last-write-wins).
#[macro_export]
macro_rules! reflect {
    ($($args:tt)*) => { $crate::__reflect_internal!(@owned $($args)*) };
}

/// Reflect a shared reference, detecting capabilities without consuming the value.
///
/// Returns an [`EnvelopeRef`] with read-only access to capabilities.
/// The original value remains available after the call.
///
/// # Example
///
/// ```rust
/// # use irys::*;
/// # use std::fmt;
/// # struct DisplayCap;
/// # impl Capability for DisplayCap { type Handle = dyn fmt::Display; }
/// # register_capability! { slot = 0, cap = DisplayCap, trait_bound = fmt::Display }
/// let value = 42i32;
/// let envelope_ref = reflect_ref!(&value);
/// assert!(envelope_ref.has::<DisplayCap>());
/// assert_eq!(value, 42); // value is still usable
/// ```
#[macro_export]
macro_rules! reflect_ref {
    ($($args:tt)*) => { $crate::__reflect_internal!(@ref $($args)*) };
}

/// Reflect a mutable reference, detecting capabilities with mutable access.
///
/// Returns an [`EnvelopeMut`] with read + write access to capabilities.
/// The original value remains available after the envelope is dropped.
///
/// # Example
///
/// ```rust
/// # use irys::*;
/// # trait Resettable { fn reset(&mut self); }
/// # struct ResettableCap;
/// # impl Capability for ResettableCap { type Handle = dyn Resettable; }
/// # register_capability! { slot = 0, cap = ResettableCap, trait_bound = Resettable }
/// # struct Counter { count: u32 }
/// # impl Resettable for Counter { fn reset(&mut self) { self.count = 0; } }
/// let mut value = Counter { count: 99 };
/// {
///     let mut envelope_mut = reflect_mut!(&mut value);
///     envelope_mut.get_mut::<ResettableCap>().unwrap().reset();
/// }
/// assert_eq!(value.count, 0);
/// ```
#[macro_export]
macro_rules! reflect_mut {
    ($($args:tt)*) => { $crate::__reflect_internal!(@mut $($args)*) };
}

#[doc(hidden)]
#[macro_export]
macro_rules! __reflect_internal {
    // === Explicit registries — normalize binding, then probe + finish ===
    (@owned $msg:expr, [$($registries:tt)*]) => {{
        let msg = $msg;
        $crate::__reflect_core!(@owned, msg, &msg, [$($registries)*])
    }};
    (@ref & $msg:expr, [$($registries:tt)*]) => {{
        let msg = &$msg;
        $crate::__reflect_core!(@ref, msg, msg, [$($registries)*])
    }};
    (@mut &mut $msg:expr, [$($registries:tt)*]) => {{
        let msg = &mut $msg;
        $crate::__reflect_core!(@mut, msg, &*msg, [$($registries)*])
    }};

    // === No registries specified — default registry fallback ===
    (@owned $msg:expr) => {
        $crate::__reflect_internal!(@owned $msg, [{ registry: $crate::DefaultRegistry, slots: 0..256 }])
    };
    (@ref & $msg:expr) => {
        $crate::__reflect_internal!(@ref & $msg, [{ registry: $crate::DefaultRegistry, slots: 0..256 }])
    };
    (@mut &mut $msg:expr) => {
        $crate::__reflect_internal!(@mut &mut $msg, [{ registry: $crate::DefaultRegistry, slots: 0..256 }])
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules! __reflect_core {
    (@$mode:ident, $msg:ident, $probe:expr, [$({ registry: $registry:ty, slots: $start:literal..$end:literal }),* $(,)?]) => {{
        let mut caps = $crate::CapabilityMap::new();
        $( $crate::seq!(N in $start..$end { $crate::probe_slot!($probe, &mut caps, $registry, N); }); )*
        $crate::__reflect_finish!(@$mode $msg, caps)
    }};
}

#[doc(hidden)]
#[macro_export]
macro_rules! __reflect_finish {
    (@owned $msg:ident, $caps:ident) => {
        $crate::Envelope::from_parts($msg, $caps)
    };
    (@ref $msg:ident, $caps:ident) => {
        $crate::EnvelopeRef::from_parts($msg as &dyn std::any::Any, $caps)
    };
    (@mut $msg:ident, $caps:ident) => {
        $crate::EnvelopeMut::from_parts($msg as &mut dyn std::any::Any, $caps)
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules! __reflect_probe {
    ($msg:expr, [$({ registry: $registry:ty, slots: $start:literal..$end:literal }),* $(,)?]) => {{
        let mut caps = $crate::CapabilityMap::new();
        $(
            $crate::seq!(N in $start..$end {
                $crate::probe_slot!($msg, &mut caps, $registry, N);
            });
        )*
        caps
    }};
}

/// Register a capability so that [`reflect!`] can detect it on any type satisfying the trait bound.
///
/// This is a **blanket registration** — it applies to ALL types that implement the given trait,
/// not just one specific type. Register once, works everywhere.
///
/// Fields can be provided in **any order**. The `registry` field is optional (defaults to
/// [`DefaultRegistry`]).
///
/// # Basic Usage (DefaultRegistry)
///
/// ```rust
/// # use irys::*;
/// # use std::fmt;
/// struct DisplayCap;
/// impl Capability for DisplayCap {
///     type Handle = dyn fmt::Display;
/// }
///
/// register_capability! {
///     slot = 0,
///     cap = DisplayCap,
///     trait_bound = fmt::Display,
/// }
/// ```
///
/// # Custom Registry
///
/// ```rust
/// # use irys::*;
/// # use std::fmt;
/// struct MyRegistry;
///
/// # struct DebugCap;
/// # impl Capability for DebugCap { type Handle = dyn fmt::Debug; }
/// register_capability! {
///     registry = MyRegistry,
///     slot = 0,
///     cap = DebugCap,
///     trait_bound = fmt::Debug,
/// }
/// ```
///
/// # Compound Trait Bounds
///
/// ```rust
/// # use irys::*;
/// # use std::fmt;
/// # struct SendDebugCap;
/// # impl Capability for SendDebugCap { type Handle = dyn fmt::Debug + Send + Sync; }
/// register_capability! {
///     slot = 0,
///     cap = SendDebugCap,
///     trait_bound = fmt::Debug + Send + Sync,
/// }
/// ```
///
/// # Any Field Order
///
/// ```rust
/// # use irys::*;
/// # use std::fmt;
/// # struct DebugCap;
/// # impl Capability for DebugCap { type Handle = dyn fmt::Debug; }
/// register_capability! {
///     trait_bound = fmt::Debug,
///     cap = DebugCap,
///     slot = 0,
/// }
/// ```
///
/// # Slot Collisions
///
/// Two capabilities at the same slot in the same registry will produce a **compile error**
/// (duplicate inherent method). This is intentional — it prevents silent conflicts.
#[macro_export]
macro_rules! register_capability {
    ($($input:tt)*) => {
        $crate::__register_cap_parse! { [] @rest [$($input)*] }
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules! __register_cap_parse {
    // === Terminal: no more tokens ===
    ([$($parsed:tt)*] @rest []) => {
        $crate::__register_cap_emit! { $($parsed)* }
    };

    // Peel: registry
    ([$($parsed:tt)*] @rest [registry = $registry:ty, $($rest:tt)*]) => {
        $crate::__register_cap_parse! { [$($parsed)* @registry [$registry]] @rest [$($rest)*] }
    };

    // Peel: slot
    ([$($parsed:tt)*] @rest [slot = $slot:literal, $($rest:tt)*]) => {
        $crate::__register_cap_parse! { [$($parsed)* @slot [$slot]] @rest [$($rest)*] }
    };

    // Peel: cap
    ([$($parsed:tt)*] @rest [cap = $cap:ty, $($rest:tt)*]) => {
        $crate::__register_cap_parse! { [$($parsed)* @cap [$cap]] @rest [$($rest)*] }
    };

    // Peel: trait_bound (freeform — munch until next keyword)
    ([$($parsed:tt)*] @rest [trait_bound = $($rest:tt)+]) => {
        $crate::__register_cap_munch! { @target trait_bound @parsed [$($parsed)*] @accum [] @rest [$($rest)+] }
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules! __register_cap_munch {
    // Hit ", <keyword> =" — done, store and continue
    (@target $target:ident @parsed [$($parsed:tt)*] @accum [$($accum:tt)*] @rest [, registry = $($rest:tt)*]) => {
        $crate::__register_cap_parse! { [$($parsed)* @$target [$($accum)*]] @rest [registry = $($rest)*] }
    };
    (@target $target:ident @parsed [$($parsed:tt)*] @accum [$($accum:tt)*] @rest [, slot = $($rest:tt)*]) => {
        $crate::__register_cap_parse! { [$($parsed)* @$target [$($accum)*]] @rest [slot = $($rest)*] }
    };
    (@target $target:ident @parsed [$($parsed:tt)*] @accum [$($accum:tt)*] @rest [, cap = $($rest:tt)*]) => {
        $crate::__register_cap_parse! { [$($parsed)* @$target [$($accum)*]] @rest [cap = $($rest)*] }
    };
    (@target $target:ident @parsed [$($parsed:tt)*] @accum [$($accum:tt)*] @rest [, trait_bound = $($rest:tt)*]) => {
        $crate::__register_cap_parse! { [$($parsed)* @$target [$($accum)*]] @rest [trait_bound = $($rest)*] }
    };

    // End of input
    (@target $target:ident @parsed [$($parsed:tt)*] @accum [$($accum:tt)*] @rest []) => {
        $crate::__register_cap_parse! { [$($parsed)* @$target [$($accum)*]] @rest [] }
    };
    (@target $target:ident @parsed [$($parsed:tt)*] @accum [$($accum:tt)*] @rest [,]) => {
        $crate::__register_cap_parse! { [$($parsed)* @$target [$($accum)*]] @rest [] }
    };

    // Munch one token
    (@target $target:ident @parsed $parsed:tt @accum [$($accum:tt)*] @rest [$first:tt $($rest:tt)*]) => {
        $crate::__register_cap_munch! { @target $target @parsed $parsed @accum [$($accum)* $first] @rest [$($rest)*] }
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules! __register_cap_emit {
    ($($input:tt)*) => {
        $crate::__register_cap_norm! {
            @registry [] @slot [] @cap [] @trait_bound []
            @input [$($input)*]
        }
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules! __register_cap_norm {
    // Terminal — all input consumed, emit
    (@registry [$($registry:tt)*] @slot [$slot:literal] @cap [$cap:ty] @trait_bound [$($tb:tt)+]
     @input []) => {
        $crate::__register_cap_final! { @registry [$($registry)*] @slot [$slot] @cap [$cap] @trait_bound [$($tb)+] }
    };

    // Extract each @key [value] pair
    (@registry $r:tt @slot $s:tt @cap $c:tt @trait_bound $tb:tt
     @input [@registry [$($registry:tt)*] $($rest:tt)*]) => {
        $crate::__register_cap_norm! { @registry [$($registry)*] @slot $s @cap $c @trait_bound $tb @input [$($rest)*] }
    };
    (@registry $r:tt @slot $s:tt @cap $c:tt @trait_bound $tb:tt
     @input [@slot [$($slot:tt)*] $($rest:tt)*]) => {
        $crate::__register_cap_norm! { @registry $r @slot [$($slot)*] @cap $c @trait_bound $tb @input [$($rest)*] }
    };
    (@registry $r:tt @slot $s:tt @cap $c:tt @trait_bound $tb:tt
     @input [@cap [$($cap:tt)*] $($rest:tt)*]) => {
        $crate::__register_cap_norm! { @registry $r @slot $s @cap [$($cap)*] @trait_bound $tb @input [$($rest)*] }
    };
    (@registry $r:tt @slot $s:tt @cap $c:tt @trait_bound $tb:tt
     @input [@trait_bound [$($bound:tt)*] $($rest:tt)*]) => {
        $crate::__register_cap_norm! { @registry $r @slot $s @cap $c @trait_bound [$($bound)*] @input [$($rest)*] }
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules! __register_cap_final {
    // No registry — use default
    (@registry [] @slot [$slot:literal] @cap [$cap:ty] @trait_bound [$($bounds:tt)+]) => {
        $crate::__register_cap_final! { @registry [$crate::DefaultRegistry] @slot [$slot] @cap [$cap] @trait_bound [$($bounds)+] }
    };
    // All fields present — emit the impl
    (@registry [$registry:ty] @slot [$slot:literal] @cap [$cap:ty] @trait_bound [$($bounds:tt)+]) => {
        impl<'a, T: $($bounds)+ + 'static> $crate::HasCap<$cap, $registry, $slot>
            for $crate::Probe<'a, T, $registry, $slot>
        {
            fn probe(&self, caps: &mut $crate::CapabilityMap) {
                caps.insert_cast::<$cap>(
                    |any| {
                        let val = any.downcast_ref::<T>()?;
                        Some(val as &<$cap as $crate::Capability>::Handle)
                    },
                    |any| {
                        let val = any.downcast_mut::<T>()?;
                        Some(val as &mut <$cap as $crate::Capability>::Handle)
                    },
                );
            }
        }
    };
}