bb-ir 0.3.6

Foundation IR types for the bytesandbrains framework — prost-generated ONNX + `bb.core` proto bindings.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

//! Foundation polymorphism plumbing shared by `bb-dsl` (authoring)
//! and `bb-runtime` (dispatch).

use std::any::Any;

/// Marker for engine-owned component instances. Blanket impl covers
/// every `Any + Send + Sync`.
pub trait ErasedComponent: Any + Send + Sync {}

impl<T: Any + Send + Sync> ErasedComponent for T {}

/// Dyn-safe downcast surface. No blanket impl — `Box<dyn AnyComponent>`
/// would otherwise shadow per-type vtables. `bb::Concrete` derive
/// emits the impl.
pub trait AnyComponent: ErasedComponent {
    /// Downcast view - immutable.
    fn as_any(&self) -> &dyn Any;

    /// Downcast view - mutable.
    fn as_any_mut(&mut self) -> &mut dyn Any;
}

/// Component-package origin tag. Surfaces in introspection +
/// telemetry.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum ComponentPackage {
    /// Shipped in the bytesandbrains crate family.
    Framework,

    /// Shipped by the application author. Default.
    Application,
}

/// Author-declared sibling dependency at a named slot. Compiler
/// verifies role match; runtime reaches it via
/// `RuntimeResourceRef::dependency::<T>(slot)`.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct DependencyDecl {
    /// PascalCase role identifier. Plain string so `bb-ir` stays
    /// free of the `ComponentRole` enum.
    pub role: &'static str,

    /// Slot name in the compiler's binding spec.
    pub slot: &'static str,
}

/// Error variants surfaced by `ConcreteComponent::restore`.
#[derive(Debug)]
pub enum RestoreError {
    /// Deserialization failed at the framework's bincode boundary.
    Malformed(bincode::Error),

    /// Impl-specific restore failure.
    Custom(String),
}

impl std::fmt::Display for RestoreError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Malformed(e) => write!(f, "malformed component state bytes: {e}"),
            Self::Custom(m) => write!(f, "component restore failed: {m}"),
        }
    }
}

impl std::error::Error for RestoreError {}

/// Monomorphized `T::serialize` captured at derive-codegen time.
pub type SerializeFn = fn(&dyn ErasedComponent) -> Vec<u8>;

/// Monomorphized `T::restore`; used by snapshot/resume.
pub type RestoreFn = fn(&[u8]) -> Result<Box<dyn ErasedComponent>, RestoreError>;

/// Errors surfaced by `ConstructFn`.
#[derive(Debug)]
pub struct ConstructError {
    /// `TYPE_NAME` of the concrete being constructed.
    pub type_name: &'static str,
    /// Downcast miss or `T::new` error stringified.
    pub detail: String,
}

impl std::fmt::Display for ConstructError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "construct {}: {}", self.type_name, self.detail)
    }
}

impl std::error::Error for ConstructError {}

/// Per-type constructor. Downcasts `&dyn Any` → `&Config` and calls
/// `T::new`. Install looks it up by `TYPE_NAME`.
pub type ConstructFn = fn(&dyn Any) -> Result<Box<dyn ErasedComponent>, ConstructError>;