//! Type-erased, reference-counted smart pointer with runtime borrow checking.

//!

//! # Safety

//!

//! This module provides `RefAny`, a type-erased container similar to `Arc<RefCell<dyn Any>>`,

//! but designed for FFI compatibility and cross-language interoperability.

//!

//! ## Memory Safety Guarantees

//!

//! 1. **Proper Alignment**: Fixed in commit addressing Miri UB - memory is allocated with correct

//!    alignment for the stored type using `Layout::from_size_align()`.

//!

//! 2. **Atomic Reference Counting**: All reference counts use `AtomicUsize` with `SeqCst` ordering,

//!    ensuring thread-safe access and preventing use-after-free.

//!

//! 3. **Runtime Type Safety**: Type IDs are checked before downcasting, preventing invalid pointer

//!    casts that would cause undefined behavior.

//!

//! 4. **Runtime Borrow Checking**: Shared and mutable borrows are tracked at runtime, enforcing

//!    Rust's borrowing rules dynamically (similar to `RefCell`).

//!

//! ## Thread Safety

//!

//! - `RefAny` is `Send`: Can be transferred between threads (data is heap-allocated)

//! - `RefAny` is `Sync`: Can be shared between threads (atomic operations + `&mut self` for

//!   borrows)

//!

//! The `SeqCst` (Sequentially Consistent) memory ordering provides the strongest guarantees:

//! all atomic operations appear in a single global order visible to all threads, preventing

//! race conditions where one thread doesn't see another's reference count updates.

use alloc::boxed::Box;

use alloc::string::String;

use core::{

    alloc::Layout,

    ffi::c_void,

    fmt,

    sync::atomic::{AtomicUsize, Ordering as AtomicOrdering},

};

use azul_css::AzString;

/// C-compatible destructor function type for `RefAny`.

/// Called when the last reference to a `RefAny` is dropped.

pub type RefAnyDestructorType = extern "C" fn(*mut c_void);

// NOTE: JSON serialization/deserialization callback types are defined in azul_layout::json

// The actual types are:

//   RefAnySerializeFnType = extern "C" fn(RefAny) -> Json

//   RefAnyDeserializeFnType = extern "C" fn(Json) -> ResultRefAnyString

// In azul_core, we only store function pointers as usize (0 = not set).

/// Internal reference counting metadata for `RefAny`.

///

/// This struct tracks:

///

/// - How many `RefAny` clones exist (`num_copies`)

/// - How many shared borrows are active (`num_refs`)

/// - How many mutable borrows are active (`num_mutable_refs`)

/// - Memory layout information for correct deallocation

/// - Type information for runtime type checking

///

/// # Thread Safety

///

/// All counters are `AtomicUsize` with `SeqCst` ordering, making them safe to access

/// from multiple threads simultaneously. The strong ordering ensures no thread can

/// observe inconsistent states (e.g., both seeing count=1 during final drop).

#[derive(Debug)]

#[repr(C)]

// `_internal_*` are C-ABI field names exposed in api.json; the `_` prefix is the

// intentional "internal" convention and cannot be renamed without breaking the ABI.

#[allow(clippy::pub_underscore_fields)]

pub struct RefCountInner {

    /// Type-erased pointer to heap-allocated data.

    ///

    /// SAFETY: Must be properly aligned for the stored type (guaranteed by

    /// `Layout::from_size_align` in `new_c`). Never null for non-ZST types.

    ///

    /// This pointer is shared by all `RefAny` clones, so `replace_contents`

    /// updates are visible to all clones.

    pub _internal_ptr: *const c_void,

    /// Number of `RefAny` instances sharing the same data.

    /// When this reaches 0, the data is deallocated.

    pub num_copies: AtomicUsize,

    /// Number of active shared borrows (`Ref<T>`).

    /// While > 0, mutable borrows are forbidden.

    pub num_refs: AtomicUsize,

    /// Number of active mutable borrows (`RefMut<T>`).

    /// While > 0, all other borrows are forbidden.

    pub num_mutable_refs: AtomicUsize,

    /// Size of the stored type in bytes (from `size_of::<T>()`).

    pub _internal_len: usize,

    /// Layout size for deallocation (from `Layout::size()`).

    pub _internal_layout_size: usize,

    /// Required alignment for the stored type (from `align_of::<T>()`).

    /// CRITICAL: Must match the alignment used during allocation to prevent UB.

    pub _internal_layout_align: usize,

    /// Runtime type identifier computed from `TypeId::of::<T>()`.

    /// Used to prevent invalid downcasts.

    pub type_id: u64,

    /// Human-readable type name (e.g., "`MyStruct`") for debugging.

    pub type_name: AzString,

    /// Function pointer to correctly drop the type-erased data.

    /// SAFETY: Must be called with a pointer to data of the correct type.

    pub custom_destructor: extern "C" fn(*mut c_void),

    /// Function pointer to serialize `RefAny` to JSON (0 = not set).

    /// Cast to `RefAnySerializeFnType` (defined in `azul_layout::json`) when called.

    /// Type: extern "C" fn(RefAny) -> Json

    pub serialize_fn: usize,

    /// Function pointer to deserialize JSON to new `RefAny` (0 = not set).

    /// Cast to `RefAnyDeserializeFnType` (defined in `azul_layout::json`) when called.

    /// Type: extern "C" fn(Json) -> `ResultRefAnyString`

    pub deserialize_fn: usize,

    /// Function pointer to an on-update observer (0 = not set).

    /// Cast to `extern "C" fn(*const c_void, usize)` — the (data ptr, byte len)

    /// of the *pre-mutation* data — and fired from `downcast_mut` BEFORE the

    /// mutable borrow is handed out. This is the foundation for undo/redo

    /// snapshots and client/server state sync. Set via `RefAny::set_update_fn`.

    pub update_fn: usize,

}

/// Wrapper around a heap-allocated `RefCountInner`.

///

/// This is the shared metadata that all `RefAny` clones point to.

/// The `RefCount` is responsible for all memory management:

///

/// - `RefCount::clone()` increments `num_copies` in `RefCountInner`

/// - `RefCount::drop()` decrements `num_copies` and, if it reaches 0:

///   1. Frees the `RefCountInner`

///   2. Calls the custom destructor on the data

///   3. Deallocates the data memory

///

/// # Why `run_destructor: bool`

///

/// This flag tracks whether this `RefCount` instance should decrement

/// `num_copies` when dropped. Set to `true` for all clones (including

/// those created by `RefAny::clone()` and `AZ_REFLECT` macros).

/// Set to `false` after the decrement has been performed to prevent

/// double-decrement.

#[derive(Hash, PartialEq, PartialOrd, Ord, Eq)]

#[repr(C)]

pub struct RefCount {

    pub ptr: *const RefCountInner,

    pub run_destructor: bool,

}

impl fmt::Debug for RefCount {

}

impl Clone for RefCount {

    /// Clones the `RefCount` and increments the reference count.

    ///

    /// # Safety

    ///

    /// This is safe because:

    /// - The ptr is valid (created from `Box::into_raw`)

    /// - `num_copies` is atomically incremented with `SeqCst` ordering

    /// - This ensures the `RefCountInner` is not freed while clones exist

        // CRITICAL: Must increment num_copies so the RefCountInner is not freed

        // while this clone exists. The C macros (AZ_REFLECT) use AzRefCount_clone

        // to create Ref/RefMut guards, and those guards must keep the data alive.

            // SAFETY: `ptr` is non-null (checked) and came from `Box::into_raw`

            // in `RefCount::new`; it stays alive as long as any clone exists

            // because every clone increments `num_copies` here.

}

impl Drop for RefCount {

    /// Decrements the reference count when a `RefCount` clone is dropped.

    ///

    /// If this was the last reference (`num_copies` reaches 0), this will also

    /// free the `RefCountInner` and call the custom destructor.

    #[allow(clippy::used_underscore_binding)] // `_`-prefixed fields are an intentional FFI/api.json naming convention; internal access is required

        // Only decrement if run_destructor is true (meaning this is a clone)

        // and the pointer is valid

        // Take the inner pointer and NULL the field before doing anything

        // else. The C ABI reaches this drop via `AzRefCount_delete` →

        // `drop_in_place` on C-owned struct memory, and writes through

        // `&mut self` persist in that memory. Nulling the pointer here

        // (mirroring the `ptr = 0` convention the AZ_REFLECT C macros use

        // for their downcast guards) makes a SECOND delete of the same

        // struct — easy to hit in C example failure paths, and unguarded

        // in pre-0.2.1 copies of azul.h — a safe no-op via the null check

        // above, instead of a double-free of the RefCountInner allocation

        // or a read through a dangling pointer.

        // Atomically decrement and get the PREVIOUS value. `checked_sub`

        // refuses to underflow: an unmatched decrement (e.g. a C caller

        // deleting a byte-copied Ref struct twice) becomes a no-op instead

        // of wrapping `num_copies` to `usize::MAX` and corrupting the

        // reference count for the rest of the process.

        // SAFETY: `inner` is non-null (guarded above) and points to the live

        // `RefCountInner` from `Box::into_raw`; only the atomic field is touched.

            ) {

            }

        };

        // If previous value wasn't 1, other references still exist

        // We're the last reference! Clean up.

        // SAFETY: ptr came from Box::into_raw, and we're the last reference

        // Get the data pointer

        // Handle zero-sized types specially

            // Reconstruct the layout used during allocation. Removed the

            // `unsafe { Layout::from_size_align_unchecked(..) }`: these size/align

            // were produced by a valid `Layout` in `new_c` (`layout.size()` /

            // `layout.align()`), so the safe checked constructor always succeeds

            // and is behaviorally identical here — no unsafe needed.

            )

            // Phase 1: Run the custom destructor

            // Phase 2: Deallocate the memory

            // SAFETY: `data_ptr` was allocated in `new_c` (or `replace_contents`)

            // with exactly this `layout`, and we are the last reference, so no

            // other clone can observe the freed block.

        }

}

/// Debug-friendly snapshot of `RefCountInner` with non-atomic values.

#[derive(Debug, Clone)]

pub(crate) struct RefCountInnerDebug {

    pub(crate) num_copies: usize,

    pub(crate) num_refs: usize,

    pub(crate) num_mutable_refs: usize,

    pub(crate) _internal_len: usize,

    pub(crate) _internal_layout_size: usize,

    pub(crate) _internal_layout_align: usize,

    pub(crate) type_id: u64,

    pub(crate) type_name: AzString,

    pub(crate) custom_destructor: usize,

    /// Serialization function pointer (0 = not set)

    pub(crate) serialize_fn: usize,

    /// Deserialization function pointer (0 = not set)

    pub(crate) deserialize_fn: usize,

}

impl RefCount {

    /// Creates a new `RefCount` by boxing the metadata on the heap.

    ///

    /// # Safety

    ///

    /// Safe because we're creating a new allocation with `Box::new`,

    /// then immediately leaking it with `into_raw` to get a stable pointer.

    /// Dereferences the raw pointer to access the metadata.

    ///

    /// # Safety

    ///

    /// Safe because:

    /// - The pointer is created from `Box::into_raw`, so it's valid and properly aligned

    /// - The lifetime is tied to `&self`, ensuring the pointer is still alive

    /// - Reference counting ensures the data isn't freed while references exist

        // SAFETY: `ptr` is non-null (asserted) and came from `Box::into_raw`; the

        // returned reference is bounded by `&self`, and refcounting keeps the

        // `RefCountInner` alive for at least that long.

    /// Creates a debug snapshot of the current reference counts.

    ///

    /// Loads all atomic values with `SeqCst` ordering to get a consistent view.

    #[allow(clippy::used_underscore_binding)] // `_`-prefixed fields are an intentional FFI/api.json naming convention; internal access is required

    /// Runtime check: can we create a shared borrow?

    ///

    /// Returns `true` if there are no active mutable borrows.

    /// Multiple shared borrows can coexist (like `&T` in Rust).

    ///

    /// # Memory Ordering

    ///

    /// Uses `SeqCst` to ensure we see the most recent state from all threads.

    /// If another thread just released a mutable borrow, we'll see it.

    /// Runtime check: can we create a mutable borrow?

    ///

    /// Returns `true` only if there are ZERO active borrows of any kind.

    /// This enforces Rust's exclusive mutability rule (like `&mut T`).

    ///

    /// # Memory Ordering

    ///

    /// Uses `SeqCst` to ensure we see all recent borrows from all threads.

    /// Both counters must be checked atomically to prevent races.

    /// Increments the shared borrow counter.

    ///

    /// Called when a `Ref<T>` is created. The `Ref::drop` will decrement it.

    ///

    /// # Memory Ordering

    ///

    /// `SeqCst` ensures this increment is visible to all threads before they

    /// try to acquire a mutable borrow (which checks this counter).

    /// Decrements the shared borrow counter.

    ///

    /// Called when a `Ref<T>` is dropped, indicating the borrow is released.

    ///

    /// # Underflow guard

    ///

    /// Saturates at 0: an unmatched decrement — e.g. a C caller running

    /// `FooRef_delete` after a FAILED downcast with a pre-0.2.1 copy of

    /// `azul.h` (whose macro did not skip the decrease), or a plain

    /// double-delete — must not wrap `num_refs` to `usize::MAX`, which

    /// would make `can_be_shared_mut()` return `false` for the rest of

    /// the process (callbacks silently stop mutating state).

    ///

    /// # Memory Ordering

    ///

    /// `SeqCst` ensures this decrement is immediately visible to other threads

    /// waiting to acquire a mutable borrow.

        );

    /// Increments the mutable borrow counter.

    ///

    /// Called when a `RefMut<T>` is created. Should only succeed when this

    /// counter and `num_refs` are both 0.

    ///

    /// # Memory Ordering

    ///

    /// `SeqCst` ensures this increment is visible to all other threads,

    /// blocking them from acquiring any borrow (shared or mutable).

    /// Decrements the mutable borrow counter.

    ///

    /// Called when a `RefMut<T>` is dropped, releasing exclusive access.

    ///

    /// # Underflow guard

    ///

    /// Saturates at 0 (see [`Self::decrease_ref`]): a double

    /// `FooRefMut_delete` from C must not wrap `num_mutable_refs`, which

    /// would corrupt the runtime borrow checker and let a second thread

    /// or timer callback obtain an aliasing mutable borrow.

    ///

    /// # Memory Ordering

    ///

    /// `SeqCst` ensures this decrement is immediately visible, allowing

    /// other threads to acquire borrows.

        );

}

/// RAII guard for a shared borrow of type `T` from a `RefAny`.

///

/// Similar to `std::cell::Ref`, this automatically decrements the borrow

/// counter when dropped, ensuring borrows are properly released.

///

/// # Deref

///

/// Implements `Deref<Target = T>` so you can use it like `&T`.

#[derive(Debug)]

#[repr(C)]

pub struct Ref<'a, T> {

    ptr: &'a T,

    sharing_info: RefCount,

}

impl<T> Drop for Ref<'_, T> {

    /// Automatically releases the shared borrow when the guard goes out of scope.

    ///

    /// # Safety

    ///

    /// Safe because `decrease_ref` uses atomic operations and is designed to be

    /// called exactly once per `Ref` instance.

}

impl<T> core::ops::Deref for Ref<'_, T> {

    type Target = T;

}

/// RAII guard for a mutable borrow of type `T` from a `RefAny`.

///

/// Similar to `std::cell::RefMut`, this automatically decrements the mutable

/// borrow counter when dropped, releasing exclusive access.

///

/// # Deref / `DerefMut`

///

/// Implements both `Deref` and `DerefMut` so you can use it like `&mut T`.

#[derive(Debug)]

#[repr(C)]

pub struct RefMut<'a, T> {

    ptr: &'a mut T,

    sharing_info: RefCount,

}

impl<T> Drop for RefMut<'_, T> {

    /// Automatically releases the mutable borrow when the guard goes out of scope.

    ///

    /// # Safety

    ///

    /// Safe because `decrease_refmut` uses atomic operations and is designed to be

    /// called exactly once per `RefMut` instance.

}

impl<T> core::ops::Deref for RefMut<'_, T> {

    type Target = T;

}

impl<T> core::ops::DerefMut for RefMut<'_, T> {

}

/// Type-erased, reference-counted smart pointer with runtime borrow checking.

///

/// `RefAny` is similar to `Arc<RefCell<dyn Any>>`, providing:

/// - Type erasure (stores any `'static` type)

/// - Reference counting (clones share the same data)

/// - Runtime borrow checking (enforces Rust's borrowing rules at runtime)

/// - FFI compatibility (`#[repr(C)]` and C-compatible API)

///

/// # Thread Safety

///

/// - `Send`: Can be moved between threads (heap-allocated data, atomic counters)

/// - `Sync`: Can be shared between threads (`downcast_ref/mut` require `&mut self`)

///

/// # Memory Safety

///

/// Fixed critical UB bugs in alignment, copy count, and pointer provenance.

/// All operations are verified with Miri to ensure absence of undefined behavior.

///

/// # Usage

///

/// ```rust

/// # use azul_core::refany::RefAny;

/// let data = RefAny::new(42i32);

/// let mut data_clone = data.clone(); // shares the same heap allocation

///

/// // Runtime-checked downcasting with type safety

/// if let Some(value_ref) = data_clone.downcast_ref::<i32>() {

///     assert_eq!(*value_ref, 42);

/// };

///

/// // Runtime-checked mutable borrowing

/// if let Some(mut value_mut) = data_clone.downcast_mut::<i32>() {

///     *value_mut = 100;

/// };

/// ```

#[derive(Debug)]

#[repr(C)]

pub struct RefAny {

    /// Shared metadata: reference counts, type info, destructor, AND data pointer.

    ///

    /// All `RefAny` clones point to the same `RefCountInner` via this field.

    /// The data pointer is stored in `RefCountInner` so all clones see the same

    /// pointer, even after `replace_contents()` is called.

    ///

    /// The `run_destructor` flag on `RefCount` controls whether dropping this

    /// `RefAny` should decrement the reference count and potentially free memory.

    pub sharing_info: RefCount,

    /// Unique ID for this specific clone (root = 0, subsequent clones increment).

    ///

    /// Used to distinguish between the original and clones for debugging.

    pub instance_id: u64,

}

// The comparison traits below are hand-written, NOT derived, and key on

// `sharing_info` ALONE. `instance_id` is deliberately omitted:

//

//     // self.instance_id == other.instance_id   <-- NEVER compare this

//

// `instance_id` is a debug-only counter that `clone()` increments (original = 0,

// first clone = 1, ...). Deriving equality folded it in, so a `RefAny` never

// equaled its own clone even though both point at the same `RefCountInner` — the

// same heap data, same refcount. Equality here means "same data", not "same

// handle"; `sharing_info` (a pointer + flag) already distinguishes unrelated

// instances.

//

// Hash/Ord must key on exactly the same fields as PartialEq or they break their

// own contracts (equal values must hash equally; `cmp() == Equal` must imply

// `==`), so all five delegate to `sharing_info`.

impl PartialEq for RefAny {

}

impl Eq for RefAny {}

impl core::hash::Hash for RefAny {

}

impl PartialOrd for RefAny {

}

impl Ord for RefAny {

}

impl_option!(

    RefAny,

    OptionRefAny,

    copy = false,

    [Debug, Hash, Clone, PartialEq, PartialOrd, Ord, Eq]

);

// AUDIT: unsound-but-required. These `Send`/`Sync` impls are unconditional in

// `T`: a `!Send`/`!Sync` payload moved or shared cross-thread races its own

// internals. This is an INTENTIONAL FFI design constraint — `RefAny` is a

// type-erased C-ABI handle with no way to carry `T: Send + Sync` bounds across

// the boundary, and the framework's threading model keeps a given payload on

// one thread in practice. Left as-is per the audit; do not "fix" by adding

// bounds (it would break the erased FFI type).

//

// SAFETY: RefAny is Send because:

// - The data pointer points to heap memory (can be sent between threads)

// - All shared state (RefCountInner) uses atomic operations

// - No thread-local storage is used

#[allow(clippy::non_send_fields_in_send_ty)] // see SAFETY note above: atomic refcount, no TLS, no cross-thread deref

unsafe impl Send for RefAny {}

// SAFETY: RefAny is Sync because:

// - Methods on `&RefAny` (like `clone`, `get_type_id`) only use atomic operations or

//   read immutable data, which is inherently thread-safe

// - The runtime borrow checker (via `can_be_shared/shared_mut`) uses SeqCst atomics

//

// AUDIT: unsound-but-required (same intentional FFI constraint as `Send` above).

//

// The check-then-increment race that this note described in `downcast_ref/mut`

// is now FIXED (both use atomic `fetch_add`+validate / `compare_exchange`

// acquisition — see those methods). The remaining unsoundness is only the

// unconditional-in-`T` `Sync`, which is required by the erased C-ABI type.

unsafe impl Sync for RefAny {}

impl RefAny {

    /// Creates a new type-erased `RefAny` containing the given value.

    ///

    /// This is the primary way to construct a `RefAny` from Rust code.

    ///

    /// # Type Safety

    ///

    /// Stores the `TypeId` of `T` for runtime type checking during downcasts.

    ///

    /// # Memory Layout

    ///

    /// - Allocates memory on the heap with correct size (`size_of::<T>()`) and alignment

    ///   (`align_of::<T>()`)

    /// - Copies the value into the heap allocation

    /// - Forgets the original value to prevent double-drop

    ///

    /// # Custom Destructor

    ///

    /// Creates a type-specific destructor that:

    /// 1. Copies the data from heap back to stack

    /// 2. Calls `mem::drop` to run `T`'s destructor

    /// 3. The heap memory is freed separately in `RefAny::drop`

    ///

    /// This two-phase destruction ensures proper cleanup even for complex types.

    ///

    /// # Safety

    ///

    /// Safe because:

    /// - `mem::forget` prevents double-drop of the original value

    /// - Type `T` and destructor `<U>` are matched at compile time

    /// - `ptr::copy_nonoverlapping` with count=1 copies exactly one `T`

    ///

    /// # Example

    ///

    /// ```rust

    /// # use azul_core::refany::RefAny;

    /// let mut data = RefAny::new(42i32);

    /// let value = data.downcast_ref::<i32>().unwrap();

    /// assert_eq!(*value, 42);

    /// ```

        /// Type-specific destructor that properly drops the inner value.

        ///

        /// # Safety

        ///

        /// Safe to call ONLY with a pointer that was created by `RefAny::new<U>`.

        /// The type `U` must match the original type `T`.

        ///

        /// # Why Copy to Stack?

        ///

        /// Rust's drop glue expects a value, not a pointer. We copy the data

        /// to the stack so `mem::drop` can run the destructor properly.

        ///

        /// # Critical Fix

        ///

        /// The third argument to `copy_nonoverlapping` is the COUNT (1 element),

        /// not the SIZE in bytes. Using `size_of::<U>()` here would copy

        /// `size_of::<U>()` elements, causing buffer overflow.

            use core::{mem, ptr};

            // The actual drop glue. `U::drop` is arbitrary user code and this

            // function is `extern "C"` (called across the FFI boundary from the

            // C ABI teardown), so a panic escaping here would unwind across that

            // boundary = UB.

            // SAFETY: this fn is only installed by `RefAny::new::<U>`, so `ptr`

            // points to an initialized, properly aligned `U` that no other code

            // still references (we are in the final drop). We move it out exactly

            // once (`count = 1`) and run its drop glue.

                // A ZST has no bytes to move, and `ptr` is not a real pointer to one:

                // `RefAny::new` never allocates for a ZST, and `RefCount::drop`

                // substitutes a 1-byte-aligned dummy. Feeding that to

                // `copy_nonoverlapping` violates its "aligned and non-null"

                // precondition (`[u64; 0]` demands align 8) — UB, and Rust's debug

                // check turns it into a NON-UNWINDING abort that kills the process.

                //

                // A ZST has exactly one value, so conjure it directly and run its drop

                // glue without touching `ptr` at all.

                    // Sound for a ZST (exactly one value, touches no memory); the

                    // size_of == 0 guard is what makes assume_init well-defined here.

                    #[allow(clippy::uninit_assumed_init)]

                // Allocate uninitialized stack space for one `U`

                // Copy 1 element of type U from heap to stack

                    1, // CRITICAL: This is element count, not byte count!

                );

                // Take ownership and run the destructor

            // AUDIT: contain any panic from `U::drop` so it can't unwind across

            // the `extern "C"` boundary. `catch_unwind` needs `std`; `no_std`

            // builds use `panic = "abort"`, where unwinding cannot occur.

            #[cfg(feature = "std")]

            #[cfg(not(feature = "std"))]

            {

                run();

            }

            0, // serialize_fn: not set for Rust types by default

            0, // deserialize_fn: not set for Rust types by default

        );

    /// C-ABI compatible function to create a `RefAny` from raw components.

    ///

    /// This is the low-level constructor used by FFI bindings (C, Python, etc.).

    ///

    /// # Parameters

    ///

    /// - `ptr`: Pointer to the value to store (will be copied)

    /// - `len`: Size of the value in bytes (`size_of::<T>()`)

    /// - `align`: Required alignment in bytes (`align_of::<T>()`)

    /// - `type_id`: Unique identifier for the type (for downcast safety)

    /// - `type_name`: Human-readable type name (for debugging)

    /// - `custom_destructor`: Function to call when the last reference is dropped

    /// - `serialize_fn`: Function pointer for JSON serialization (0 = not set)

    /// - `deserialize_fn`: Function pointer for JSON deserialization (0 = not set)

    ///

    /// # Safety

    ///

    /// Caller must ensure:

    /// - `ptr` points to valid data of size `len` with alignment `align`

    /// - `type_id` uniquely identifies the type

    /// - `custom_destructor` correctly drops the type at `ptr`

    /// - `len` and `align` match the actual type's layout

    /// - If `serialize_fn != 0`, it must be a valid function pointer of type

    ///   `extern "C" fn(RefAny) -> Json`

    /// - If `deserialize_fn != 0`, it must be a valid function pointer of type

    ///   `extern "C" fn(Json) -> ResultRefAnyString`

    ///

    /// # Zero-Sized Types

    ///

    /// Special case: ZSTs use a null pointer but still track the type info

    /// and call the destructor (which may have side effects even for ZSTs).

    ///

    /// # Panics

    ///

    /// Panics if `ptr` is null while `len > 0` (a non-empty value must have a

    /// valid backing pointer).

    #[allow(clippy::used_underscore_binding)] // `_`-prefixed fields are an intentional FFI/api.json naming convention; internal access is required

        use core::ptr;

        // CRITICAL: Validate input pointer for non-ZST types

        // A NULL pointer for a non-zero-sized type would cause UB when copying

                len,

            );

        // Special case: Zero-sized types

        //

        // Calling `alloc(Layout { size: 0, .. })` is UB, so we use a null pointer.

        // The destructor is still called (it may have side effects even for ZSTs).

        } else {

            // CRITICAL FIX: Use the caller-provided alignment, not alignment of [u8]

            //

            // Previous bug: `Layout::for_value(&[u8])` created align=1

            // This caused unaligned references when downcasting to types like i32 (align=4)

            //

            // Fixed: `Layout::from_size_align(len, align)` respects the type's alignment

            // Allocate heap memory with correct alignment

            // SAFETY: `layout` has non-zero size (this branch is `len != 0`), the

            // required precondition for `alloc`; null return is handled below.

            // Handle allocation failure (aborts the program)

            // Copy the data byte-by-byte to the heap

            // SAFETY: Both pointers are valid, non-overlapping, and properly aligned

        };

    /// Returns the raw data pointer for FFI downcasting.

    ///

    /// This is used by the `AZ_REFLECT` macros in C/C++ to access the

    /// type-erased data pointer for downcasting operations.

    ///

    /// # Safety

    ///

    /// The returned pointer must only be dereferenced after verifying

    /// the type ID matches the expected type. Callers are responsible

    /// for proper type safety checks.

    #[allow(clippy::used_underscore_binding)] // `_`-prefixed fields are an intentional FFI/api.json naming convention; internal access is required

    /// Returns the byte length of the type-erased payload behind

    /// [`Self::get_data_ptr`] (`size_of::<T>()` of the stored type;

    /// `0` for ZSTs).

    #[allow(clippy::used_underscore_binding)] // `_`-prefixed fields are an intentional FFI/api.json naming convention; internal access is required

    /// Checks if this is the only `RefAny` instance with no active borrows.

    ///

    /// Returns `true` only if:

    /// - `num_copies == 1` (no clones exist)

    /// - `num_refs == 0` (no shared borrows active)

    /// - `num_mutable_refs == 0` (no mutable borrows active)

    ///

    /// Useful for checking if you have exclusive ownership.

    ///

    /// # Memory Ordering

    ///

    /// Uses `SeqCst` to ensure a consistent view across all three counters.

    /// Attempts to downcast to a shared reference of type `U`.

    ///

    /// Returns `None` if:

    /// - The stored type doesn't match `U` (type safety)

    /// - A mutable borrow is already active (borrow checking)

    /// - The pointer is null AND `U` is not zero-sized (uninitialized). A

    ///   stored ZST has a null pointer *by design* (nothing is allocated) and

    ///   downcasts successfully, via a dangling-but-aligned reference.

    ///

    /// # Type Safety

    ///

    /// Compares `type_id` at runtime before casting. This prevents casting

    /// `*const c_void` to the wrong type, which would be immediate UB.

    ///

    /// # Borrow Checking

    ///

    /// Checks `can_be_shared()` to enforce Rust's borrowing rules:

    /// - Multiple shared borrows are allowed

    /// - Shared and mutable borrows cannot coexist

    ///

    /// # Safety

    ///

    /// The `unsafe` cast is safe because:

    /// - Type ID check ensures `U` matches the stored type

    /// - Memory was allocated with correct alignment for `U`

    /// - Lifetime `'a` is tied to `&'a mut self`, preventing use-after-free

    /// - Reference count is incremented atomically before returning

    ///

    /// # Why `&mut self`?

    ///

    /// Requires `&mut self` to prevent multiple threads from calling this

    /// simultaneously on the same `RefAny`. The borrow checker enforces this.

    /// Clones of the `RefAny` can call this independently (they share data

    /// but have separate runtime borrow tracking).

    #[allow(clippy::used_underscore_binding)] // `_`-prefixed fields are an intentional FFI/api.json naming convention; internal access is required

    #[inline]

        // Runtime type check: prevent downcasting to wrong type

        // AUDIT: ATOMIC shared-borrow acquisition.

        //

        // `RefAny` is `Sync` and clones share one `RefCountInner`, so the old

        // check-then-increment (`can_be_shared()` then `increase_ref()`) raced a

        // concurrent `downcast_mut` on another clone: both could pass their

        // pre-checks and hand out aliasing `&`/`&mut` to the same memory (UB).

        //

        // Fix (mirrors the `compare_exchange` discipline in `replace_contents`):

        // increment `num_refs` FIRST, then validate that no mutable borrow is

        // live. `SeqCst` imposes a single total order, so a writer (which CASes

        // `num_mutable_refs` 0->1 then reads `num_refs`) and this reader (which

        // adds to `num_refs` then reads `num_mutable_refs`) can never both

        // succeed — at least one observes the other's write. Back the increment

        // out on any failure path.

            // A mutable borrow is (being) acquired — release and fail.

        // Get data pointer from shared RefCountInner (stable while we hold the

        // shared borrow: `replace_contents` needs `num_refs == 0` to proceed).

        // A null `_internal_ptr` means either an uninitialized `RefAny` or a ZST:

        // `RefAny::new_c` stores ZSTs with a null pointer (they need no backing

        // allocation). A ZST is a *valid* stored value, so the type check above is

        // authoritative and a `&U` to a ZST dereferences no bytes — only a

        // *non-ZST* null pointer is a genuine failure.

        Some(Ref {

            // SAFETY: type check passed. For a real value `data_ptr` is non-null

            // and correctly aligned; for a ZST (null pointer) we hand out a

            // dangling-but-aligned `NonNull::dangling` reference, valid precisely

            // because it is never dereferenced for bytes.

            ptr: unsafe {

                } else {

                }

            },

        })

    /// Attempts to downcast to a mutable reference of type `U`.

    ///

    /// Returns `None` if:

    /// - The stored type doesn't match `U` (type safety)

    /// - Any borrow is already active (borrow checking)

    /// - The pointer is null AND `U` is not zero-sized (uninitialized). A

    ///   stored ZST has a null pointer *by design* and downcasts successfully,

    ///   via a dangling-but-aligned reference; note that the on-update observer

    ///   is NOT fired for a ZST (there are no bytes for it to snapshot).

    ///

    /// # Type Safety

    ///

    /// Compares `type_id` at runtime before casting, preventing UB.

    ///

    /// # Borrow Checking

    ///

    /// Checks `can_be_shared_mut()` to enforce exclusive mutability:

    /// - No other borrows (shared or mutable) can be active

    /// - This is Rust's `&mut T` rule, enforced at runtime

    ///

    /// # Safety

    ///

    /// The `unsafe` cast is safe because:

    ///

    /// - Type ID check ensures `U` matches the stored type

    /// - Memory was allocated with correct alignment for `U`

    /// - Borrow check ensures no other references exist

    /// - Lifetime `'a` is tied to `&'a mut self`, preventing aliasing

    /// - Mutable reference count is incremented atomically

    ///

    /// # Memory Ordering

    ///

    /// The `increase_refmut()` uses `SeqCst`, ensuring other threads see

    /// this mutable borrow before they try to acquire any borrow.

    #[allow(clippy::used_underscore_binding)] // `_`-prefixed fields are an intentional FFI/api.json naming convention; internal access is required

    #[inline]

        // Runtime type check

        // AUDIT: ATOMIC exclusive-borrow acquisition (mirror `replace_contents`).

        //

        // The old check-then-increment (`can_be_shared_mut()` then

        // `increase_refmut()`) raced concurrent borrows on sibling clones and

        // could hand out an aliasing `&mut` (UB). Instead, `compare_exchange`

        // `num_mutable_refs` 0->1 to atomically take the exclusive slot, THEN

        // verify no shared borrow is live; release + fail otherwise. The CAS

        // both acquires and rejects a second mutable borrow in one step.

        {

            // A shared borrow is live — release the exclusive slot and fail.

        // Get data pointer from shared RefCountInner

        // A null `_internal_ptr` is either an uninitialized `RefAny` or a ZST

        // (stored with a null pointer; see `downcast_ref`). A non-ZST null is a

        // real failure — release the exclusive slot and bail. For a ZST there are

        // no bytes to observe or mutate, so skip the update observer below and

        // hand out a dangling-but-aligned `&mut`, keeping the exclusive borrow.

        // Fire the on-update observer (if registered) BEFORE handing out the

        // mutable borrow: the callback sees the pre-mutation data + its byte

        // length, enabling undo/redo snapshots and client/server state sync.

            // SAFETY: `update_fn` is non-zero (checked) and, per `set_update_fn`'s

            // contract, is a valid `extern "C" fn(*const c_void, usize)`. The

            // round-trip goes through an int-to-pointer CAST (not a direct

            // usize->fn transmute): a transmuted integer carries no provenance,

            // which is UB to call (Miri rejects it); the cast re-acquires it.

            // AUDIT: the observer is a host-provided `extern "C"` fn. A Rust

            // panic escaping it would unwind across the FFI boundary (UB), so

            // contain it. `catch_unwind` needs `std`; `no_std` builds use

            // `panic = "abort"` where no unwinding can occur.

            #[cfg(feature = "std")]

            {

            }

            #[cfg(not(feature = "std"))]

            {

                cb(data_ptr, len);

            }

    /// Computes a runtime type ID from Rust's `TypeId`.

    ///

    /// Rust's `TypeId` is not `#[repr(C)]` and can't cross FFI boundaries.

    /// This function converts it to a `u64` by treating it as a byte array.

    ///

    /// # Safety

    ///

    /// Safe because:

    /// - `TypeId` is a valid type with a stable layout

    /// - We only read from it, never write

    /// - The slice lifetime is bounded by the function scope

    ///

    /// # Implementation

    ///

    /// Treats the `TypeId` as bytes and sums them with bit shifts to create

    /// a unique (but not cryptographically secure) hash.

    #[inline]

        use core::{any::TypeId, mem};

        // SAFETY: TypeId is a valid type, we're only reading it

            )

        };

        // AUDIT: fold ALL bytes of the `TypeId` (16 on current toolchains),

        // not just the first 8. This u64 is the ONLY runtime type guard used by

        // `downcast_*`; dropping the high 8 bytes let two distinct types whose

        // `TypeId`s differ only in their upper half collide, permitting a

        // wrong-type downcast (UB). An FxHash-style rotate+multiply mixes every

        // byte into the result and is deterministic within a process run (which

        // is all `TypeId` itself guarantees).

    /// Checks if the stored type matches the given type ID.

    /// Returns the stored type ID.

    /// Returns the human-readable type name for debugging.

    /// Returns the current reference count (number of `RefAny` clones sharing this data).

    ///

    /// This is useful for debugging and metadata purposes.

    /// Returns the serialize function pointer (0 = not set).

    /// 

    /// This is used for JSON serialization of `RefAny` contents.

    /// Returns the deserialize function pointer (0 = not set).

    /// 

    /// This is used for JSON deserialization to create a new `RefAny`.

    /// Sets the serialize function pointer.

    ///

    /// # Safety

    ///

    /// The caller must ensure the function pointer is valid and has the correct

    /// signature: `extern "C" fn(RefAny) -> Json`

    ///

    /// **Known issue:** `&mut self` is exclusive to this clone, not to the shared

    /// `RefCountInner`. Concurrent calls via different clones are a data race

    /// because `serialize_fn` is a plain `usize`, not atomic.

        // FIXME: &mut self is exclusive to this clone only, not to the shared

        // RefCountInner — concurrent calls via different clones are a data race.

        // SAFETY: `inner` came from `Box::into_raw` and is live (we hold `self`).

    /// Sets the deserialize function pointer.

    ///

    /// # Safety

    ///

    /// The caller must ensure the function pointer is valid and has the correct

    /// signature: `extern "C" fn(Json) -> ResultRefAnyString`

    ///

    /// **Known issue:** `&mut self` is exclusive to this clone, not to the shared

    /// `RefCountInner`. Concurrent calls via different clones are a data race

    /// because `deserialize_fn` is a plain `usize`, not atomic.

        // FIXME: &mut self is exclusive to this clone only, not to the shared

        // RefCountInner — concurrent calls via different clones are a data race.

        // SAFETY: `inner` came from `Box::into_raw` and is live (we hold `self`).

    /// Registers an on-update observer (`0` = unset). It is fired from

    /// [`Self::downcast_mut`] with the (data ptr, byte len) of the *pre-mutation*

    /// data, just before the mutable borrow is handed out — the foundation for

    /// undo/redo snapshots and client/server state sync.

    ///

    /// # Safety

    ///

    /// If `update_fn != 0` it must be a valid `extern "C" fn(*const c_void, usize)`.

    /// Same shared-`RefCountInner` caveat as [`Self::set_serialize_fn`]: `&mut self`

    /// is exclusive to this clone, not to the shared inner.

        // SAFETY: `inner` came from `Box::into_raw` and is live (we hold `self`).