vyre_spec/
op_contract.rs

1//! Optional operation-contract metadata shared by signatures and catalogs.
2
3/// Backend capability required by an operation.
4#[derive(Debug, Clone, PartialEq, Eq, Hash, serde::Deserialize, serde::Serialize)]
5pub struct CapabilityId(pub String);
6
7impl CapabilityId {
8    /// Create a capability id from a stable name.
9    #[must_use]
10    pub fn new(name: impl Into<String>) -> Self {
11        Self(name.into())
12    }
13
14    /// Return the stable capability name.
15    #[must_use]
16    pub fn as_str(&self) -> &str {
17        &self.0
18    }
19}
20
21/// Determinism contract for an operation.
22#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Deserialize, serde::Serialize)]
23#[non_exhaustive]
24pub enum DeterminismClass {
25    /// Bit-identical outputs for identical inputs.
26    Deterministic,
27    /// Deterministic except for backend rounding policy.
28    DeterministicModuloRounding,
29    /// Backend scheduling or hardware effects may change results.
30    NonDeterministic,
31}
32
33/// Side-effect class for an operation.
34#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Deserialize, serde::Serialize)]
35#[non_exhaustive]
36pub enum SideEffectClass {
37    /// Pure value computation.
38    Pure,
39    /// Reads memory through explicit operands.
40    ReadsMemory,
41    /// Writes memory through explicit operands.
42    WritesMemory,
43    /// Performs synchronization.
44    Synchronizing,
45    /// Performs atomic memory effects.
46    Atomic,
47}
48
49/// Portable cost hint for planning and diagnostics.
50#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Deserialize, serde::Serialize)]
51#[non_exhaustive]
52pub enum CostHint {
53    /// Cheap scalar or metadata operation.
54    Cheap,
55    /// Medium-cost operation.
56    Medium,
57    /// Expensive operation.
58    Expensive,
59    /// Cost depends on backend or runtime data.
60    Unknown,
61}
62
63/// Optional contract annotations for operation declarations.
64#[derive(Debug, Clone, PartialEq, Eq, Hash, serde::Deserialize, serde::Serialize)]
65pub struct OperationContract {
66    /// Required backend capabilities.
67    #[serde(default)]
68    pub capability_requirements: Option<smallvec::SmallVec<[CapabilityId; 4]>>,
69    /// Determinism class.
70    #[serde(default)]
71    pub determinism: Option<DeterminismClass>,
72    /// Side-effect class.
73    #[serde(default)]
74    pub side_effect: Option<SideEffectClass>,
75    /// Portable cost hint.
76    #[serde(default)]
77    pub cost_hint: Option<CostHint>,
78}
79
80impl OperationContract {
81    /// Empty contract for declarations that have not been annotated yet.
82    #[must_use]
83    pub const fn none() -> Self {
84        Self {
85            capability_requirements: None,
86            determinism: None,
87            side_effect: None,
88            cost_hint: None,
89        }
90    }
91}
92
93impl Default for OperationContract {
94    fn default() -> Self {
95        Self::none()
96    }
97}
vyre_spec/op_contract.rs

vyre_spec/
op_contract.rs
