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
//! Type-erasure guards and shape validation utilities.
//!
//! This module provides runtime validation for type-erased data structures,
//! particularly for validating `NodePartial` updates against `ChannelSpec`
//! definitions. These guards provide clear, actionable error messages when
//! type mismatches occur.
//!
//! # Purpose
//!
//! In workflow systems, data often flows through type-erased containers
//! (like `serde_json::Value` or `Box<dyn Any>`). This module helps catch
//! type errors at runtime boundaries with descriptive diagnostics.
//!
//! # Use Cases
//!
//! - Validating reducer inputs match expected channel types
//! - Checking `NodePartial` updates contain valid data shapes
//! - Runtime schema validation for dynamic workflows
//! - Clear error reporting for configuration mistakes
//!
//! # Future Implementation
//!
//! This module is currently a placeholder. Planned features include:
//!
//! - `TypeGuard` trait for custom validation logic
//! - `ShapeValidator` for JSON schema-like validation
//! - `ChannelTypeChecker` for reducer input validation
//! - Integration with `miette` for rich error diagnostics
//!
//! # Example (Future API)
//!
//! ```rust,ignore
//! use weavegraph::utils::type_guards::{TypeGuard, validate_shape};
//! use serde_json::json;
//!
//! // Define expected shape
//! let expected = ShapeSpec::object()
//! .with_field("messages", ShapeSpec::array(ShapeSpec::string()))
//! .with_field("count", ShapeSpec::number());
//!
//! // Validate at runtime
//! let data = json!({"messages": ["hello"], "count": 42});
//! validate_shape(&data, &expected)?; // Ok
//!
//! let bad_data = json!({"messages": "not an array"});
//! validate_shape(&bad_data, &expected)?;
//! // Error: field 'messages' expected array, found string
//! ```
// Placeholder for future implementation