plexor_core/erasure/mod.rs
1// Copyright 2025 Alecks Gates
2//
3// This Source Code Form is subject to the terms of the Mozilla Public
4// License, v. 2.0. If a copy of the MPL was not distributed with this
5// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6
7//! # Type Erasure Module
8//!
9//! This module provides the mechanisms for bridging type-agnostic transport layers
10//! with type-specific processing logic.
11//!
12//! ## Rationale for `unsafe` Transmutes
13//!
14//! Plexor uses `unsafe` transmutes as a fundamental architectural requirement to achieve
15//! a "Universal Plexus" capable of routing an infinite variety of user-defined types.
16//!
17//! This is particularly important for **External Ganglia** (e.g., ZMQ, HTTP, WebSockets).
18//! In these cases:
19//! 1. Data arrives from the network as a raw byte stream.
20//! 2. The system identifies the message type at runtime via a string-based name (topic).
21//! 3. The system must then locate the corresponding type-erased `Synapse` and restore
22//! its concrete Rust types to decode the bytes and trigger the appropriate `Reactants`.
23//!
24//! Because these types are not known at compile time by the transport layer, and the
25//! standard `Any` trait has limitations in restoring complex generic types across
26//! trait boundaries, we use `TypeId` verification to ensure runtime safety before
27//! using `unsafe` transmutes to restore the type-specific pointers. This avoids
28//! the performance penalties of reflection while overcoming the constraints of the
29//! type system.
30
31pub mod error;
32pub mod neuron;
33pub mod payload;
34pub mod reactant;
35pub mod synapse;