Skip to main content

vibescript_abi/
version.rs

1//! Semantic versioning (`SemVer64`), Cargo-compatible caret/range matching (`SemVerReq`),
2//! and the five independent contract version axes (`ContractVersionAxes`).
3
4/// Packed 64-bit semantic version: `[major: u16][minor: u16][patch: u16][abi_flags: u16]`.
5///
6/// `abi_flags == 0` denotes a stable release. Non-zero `abi_flags` denote pre-release
7/// or target-specific ABI qualifiers and are never matched by stable ranges unless
8/// explicitly requested.
9#[repr(transparent)]
10#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
11pub struct SemVer64(pub u64);
12
13impl SemVer64 {
14    /// Packs `(major, minor, patch, abi_flags)` into a `SemVer64`.
15    #[inline]
16    pub const fn new(major: u16, minor: u16, patch: u16, abi_flags: u16) -> Self {
17        let m = (major as u64) << 48;
18        let n = (minor as u64) << 32;
19        let p = (patch as u64) << 16;
20        let f = abi_flags as u64;
21        Self(m | n | p | f)
22    }
23
24    /// Packs a stable release `(major, minor, patch)` with `abi_flags = 0`.
25    #[inline]
26    pub const fn release(major: u16, minor: u16, patch: u16) -> Self {
27        Self::new(major, minor, patch, 0)
28    }
29
30    /// Major version component (`bits 48..63`).
31    #[inline]
32    pub const fn major(self) -> u16 {
33        (self.0 >> 48) as u16
34    }
35
36    /// Minor version component (`bits 32..47`).
37    #[inline]
38    pub const fn minor(self) -> u16 {
39        ((self.0 >> 32) & 0xFFFF) as u16
40    }
41
42    /// Patch version component (`bits 16..31`).
43    #[inline]
44    pub const fn patch(self) -> u16 {
45        ((self.0 >> 16) & 0xFFFF) as u16
46    }
47
48    /// ABI / pre-release flags (`bits 0..15`).
49    #[inline]
50    pub const fn abi_flags(self) -> u16 {
51        (self.0 & 0xFFFF) as u16
52    }
53
54    /// Returns `true` when `abi_flags == 0` (stable release).
55    #[inline]
56    pub const fn is_stable(self) -> bool {
57        self.abi_flags() == 0
58    }
59
60    /// Compares `(major, minor, patch)` release tuple, ignoring `abi_flags`.
61    #[inline]
62    pub const fn release_key(self) -> u64 {
63        self.0 & 0xFFFF_FFFF_FFFF_0000
64    }
65}
66
67/// Deterministic version requirement evaluated without heap allocation.
68#[repr(C)]
69#[derive(Debug, Clone, Copy, PartialEq, Eq)]
70pub enum SemVerReq {
71    /// Matches any stable version (`abi_flags == 0`).
72    AnyStable,
73    /// Matches exact `(major, minor, patch, abi_flags)`.
74    Exact(SemVer64),
75    /// Cargo caret requirement (`^major.minor.patch`):
76    /// - `^1.2.3` -> `>=1.2.3, <2.0.0`
77    /// - `^0.4.0` -> `>=0.4.0, <0.5.0`
78    /// - `^0.0.3` -> `>=0.0.3, <0.0.4`
79    Caret(SemVer64),
80    /// Cargo tilde requirement (`~major.minor.patch`):
81    /// `>=major.minor.patch, <major.(minor+1).0`.
82    Tilde(SemVer64),
83    /// Explicit half-open release range `[min_inclusive, max_exclusive)`.
84    Range {
85        min_inclusive: SemVer64,
86        max_exclusive: SemVer64,
87    },
88}
89
90impl SemVerReq {
91    /// Evaluates whether `candidate` satisfies this version requirement.
92    #[inline]
93    pub const fn matches(&self, candidate: SemVer64) -> bool {
94        match *self {
95            Self::AnyStable => candidate.is_stable(),
96            Self::Exact(req) => candidate.0 == req.0,
97            Self::Caret(req) => {
98                if candidate.abi_flags() != req.abi_flags() {
99                    return false;
100                }
101                let c_key = candidate.release_key();
102                let r_key = req.release_key();
103                if c_key < r_key {
104                    return false;
105                }
106                if req.major() > 0 {
107                    candidate.major() == req.major()
108                } else if req.minor() > 0 {
109                    candidate.major() == 0 && candidate.minor() == req.minor()
110                } else {
111                    candidate.major() == 0
112                        && candidate.minor() == 0
113                        && candidate.patch() == req.patch()
114                }
115            }
116            Self::Tilde(req) => {
117                if candidate.abi_flags() != req.abi_flags() {
118                    return false;
119                }
120                candidate.major() == req.major()
121                    && candidate.minor() == req.minor()
122                    && candidate.patch() >= req.patch()
123            }
124            Self::Range {
125                min_inclusive,
126                max_exclusive,
127            } => {
128                if !candidate.is_stable() {
129                    return false;
130                }
131                let c_key = candidate.release_key();
132                c_key >= min_inclusive.release_key() && c_key < max_exclusive.release_key()
133            }
134        }
135    }
136}
137
138/// The five independent version axes governing a VibeScript extension provider.
139#[repr(C)]
140#[derive(Debug, Clone, Copy, PartialEq, Eq)]
141pub struct ContractVersionAxes {
142    /// VibeScript language grammar & evaluation semantics version (e.g. `0.1.0`).
143    pub language_version: SemVer64,
144    /// `vibescript-abi` layout & trait surface version (e.g. `0.3.0`).
145    pub abi_version: SemVer64,
146    /// Host capability seam version (e.g. `0.1.0` for `vibe-host-0.1`).
147    pub host_version: SemVer64,
148    /// Domain provider implementation version (matched by `SemVerReq`).
149    pub provider_version: SemVer64,
150    /// Self-describing ontology schema version for this provider.
151    pub ontology_version: SemVer64,
152}
153
154/// Packaged `vibescript-abi` crate release version matching `Cargo.toml` (`0.0.41`).
155///
156/// Distinct from the protocol/contract axis baseline (`language = 0.1.0`, `abi = 0.3.0`,
157/// `host = 0.1.0`) returned by [`ContractVersionAxes::v0_3_default`].
158pub const ABI_CRATE_VERSION: SemVer64 = SemVer64::release(0, 0, 41);
159
160impl ContractVersionAxes {
161    /// Current canonical VibeScript 0.1 + ABI 0.3 contract baseline for a provider at `provider_version`.
162    #[inline]
163    pub const fn v0_3_default(provider_version: SemVer64, ontology_version: SemVer64) -> Self {
164        Self {
165            language_version: SemVer64::release(0, 1, 0),
166            abi_version: SemVer64::release(0, 3, 0),
167            host_version: SemVer64::release(0, 1, 0),
168            provider_version,
169            ontology_version,
170        }
171    }
172
173    /// Verifies that the provider's ABI and language versions are compatible with the host engine.
174    #[inline]
175    pub const fn is_engine_compatible(&self) -> bool {
176        SemVerReq::Caret(SemVer64::release(0, 1, 0)).matches(self.language_version)
177            && SemVerReq::Caret(SemVer64::release(0, 3, 0)).matches(self.abi_version)
178            && SemVerReq::Caret(SemVer64::release(0, 1, 0)).matches(self.host_version)
179    }
180}