Skip to main content

vibescript_abi/
sdk.rs

1//! Zero-heap Provider SDK helpers for domain package authors (`const fn` descriptor
2//! constructors, canonical ontology `NQuin48` builders, and checked finite slice I/O).
3
4use crate::descriptor::{
5    FuncDescriptor, OntologicalContract, ParamSpec, ProviderDescriptor, SubNamespaceDescriptor,
6};
7use crate::effects::{
8    AsyncExecutionClass, DeterminismGuarantee, EffectSet, ResourceEnvelope, ReversibilityKind,
9    TargetProfileMask,
10};
11use crate::identity::{q_hash_str, CanonicalIri, StableFuncId};
12use crate::lifecycle::VibeTrap;
13use crate::memory::{BorrowedSliceView, CallerOutputSlice, NQuin48, PrimitiveKind};
14use crate::version::{ContractVersionAxes, SemVer64};
15
16/// Canonical predicate IRI for function preconditions in `static_ontology_nquins()`.
17pub const VIBE_HAS_PRECONDITION_IRI: &str = "https://qualiadb.org/schema/vibe#hasPrecondition";
18
19/// Canonical predicate IRI for function postconditions in `static_ontology_nquins()`.
20pub const VIBE_HAS_POSTCONDITION_IRI: &str = "https://qualiadb.org/schema/vibe#hasPostcondition";
21
22/// Canonical predicate IRI for function invariants in `static_ontology_nquins()`.
23pub const VIBE_PRESERVES_INVARIANT_IRI: &str =
24    "https://qualiadb.org/schema/vibe#preservesInvariant";
25
26/// Default public ontology context IRI for provider contract triples.
27pub const VIBE_PUBLIC_CONTEXT_IRI: &str = "https://qualiadb.org/context/public";
28
29impl FuncDescriptor {
30    /// Compile-time constructor that computes `CanonicalIri`, `schema_hash`, and the
31    /// canonical 32-byte `OntologicalContract::canonical_digest` automatically.
32    #[inline]
33    pub const fn const_new(
34        name: &'static str,
35        canonical_iri_str: &'static str,
36        stable_id: StableFuncId,
37        schema_sig_str: &str,
38        params: &'static [ParamSpec],
39        output_kind: PrimitiveKind,
40        required_output_elems: u32,
41        effects: EffectSet,
42        determinism: DeterminismGuarantee,
43        reversibility: ReversibilityKind,
44        envelope: ResourceEnvelope,
45        pre_span: (u32, u32),
46        post_span: (u32, u32),
47        inv_span: (u32, u32),
48    ) -> Self {
49        let canonical_iri = CanonicalIri::new(canonical_iri_str);
50        let schema_hash = q_hash_str(schema_sig_str);
51        let contract_digest = OntologicalContract::canonical_digest(
52            canonical_iri.fnv1a_hash,
53            stable_id,
54            schema_hash,
55            effects,
56            determinism,
57            reversibility,
58            envelope,
59            pre_span,
60            post_span,
61            inv_span,
62        );
63        Self {
64            name,
65            canonical_iri,
66            stable_id,
67            params,
68            output_kind,
69            required_output_elems,
70            effects,
71            determinism,
72            reversibility,
73            envelope,
74            contract: OntologicalContract {
75                contract_digest,
76                schema_hash,
77                precondition_quin_span: pre_span,
78                postcondition_quin_span: post_span,
79                invariant_quin_span: inv_span,
80            },
81        }
82    }
83
84    /// Compile-time constructor that additionally encodes [`AsyncExecutionClass`] into `envelope.flags`.
85    #[inline]
86    pub const fn const_new_with_async(
87        name: &'static str,
88        canonical_iri_str: &'static str,
89        stable_id: StableFuncId,
90        schema_sig_str: &str,
91        params: &'static [ParamSpec],
92        output_kind: PrimitiveKind,
93        required_output_elems: u32,
94        effects: EffectSet,
95        determinism: DeterminismGuarantee,
96        reversibility: ReversibilityKind,
97        async_class: AsyncExecutionClass,
98        envelope: ResourceEnvelope,
99        pre_span: (u32, u32),
100        post_span: (u32, u32),
101        inv_span: (u32, u32),
102    ) -> Self {
103        Self::const_new(
104            name,
105            canonical_iri_str,
106            stable_id,
107            schema_sig_str,
108            params,
109            output_kind,
110            required_output_elems,
111            effects,
112            determinism,
113            reversibility,
114            envelope.with_async_class(async_class),
115            pre_span,
116            post_span,
117            inv_span,
118        )
119    }
120}
121
122impl ProviderDescriptor {
123    /// Compile-time constructor for a provider descriptor using `ContractVersionAxes::v0_3_default`.
124    #[inline]
125    pub const fn const_new(
126        canonical_iri_str: &'static str,
127        short_alias: &'static str,
128        provider_version: SemVer64,
129        ontology_version: SemVer64,
130        supported_targets: TargetProfileMask,
131        sub_namespaces: &'static [SubNamespaceDescriptor],
132        max_ontology_quins: u32,
133    ) -> Self {
134        Self {
135            canonical_iri: CanonicalIri::new(canonical_iri_str),
136            short_alias,
137            versions: ContractVersionAxes::v0_3_default(provider_version, ontology_version),
138            supported_targets,
139            sub_namespaces,
140            max_ontology_quins,
141        }
142    }
143}
144
145impl NQuin48 {
146    /// Constructs a 5-field parity-sealed precondition `NQuin48` in the public ontology context.
147    #[inline]
148    pub const fn precondition(subject_iri: &str, object_iri: &str, metadata: u64) -> Self {
149        Self::from_parts(
150            q_hash_str(subject_iri),
151            q_hash_str(VIBE_HAS_PRECONDITION_IRI),
152            q_hash_str(object_iri),
153            q_hash_str(VIBE_PUBLIC_CONTEXT_IRI),
154            metadata,
155        )
156    }
157
158    /// Constructs a 5-field parity-sealed postcondition `NQuin48` in the public ontology context.
159    #[inline]
160    pub const fn postcondition(subject_iri: &str, object_iri: &str, metadata: u64) -> Self {
161        Self::from_parts(
162            q_hash_str(subject_iri),
163            q_hash_str(VIBE_HAS_POSTCONDITION_IRI),
164            q_hash_str(object_iri),
165            q_hash_str(VIBE_PUBLIC_CONTEXT_IRI),
166            metadata,
167        )
168    }
169
170    /// Constructs a 5-field parity-sealed invariant `NQuin48` in the public ontology context.
171    #[inline]
172    pub const fn invariant(subject_iri: &str, object_iri: &str, metadata: u64) -> Self {
173        Self::from_parts(
174            q_hash_str(subject_iri),
175            q_hash_str(VIBE_PRESERVES_INVARIANT_IRI),
176            q_hash_str(object_iri),
177            q_hash_str(VIBE_PUBLIC_CONTEXT_IRI),
178            metadata,
179        )
180    }
181}
182
183impl<'a> BorrowedSliceView<'a> {
184    /// Reads the `index`-th `f64` and traps with `VibeTrap::NumericalDomainError` if non-finite.
185    #[inline]
186    pub fn read_finite_f64(&self, index: usize) -> Result<f64, VibeTrap> {
187        let v = self.read_f64_le(index)?;
188        if !v.is_finite() {
189            return Err(VibeTrap::NumericalDomainError);
190        }
191        Ok(v)
192    }
193
194    /// Reads the `index`-th `f32` and traps with `VibeTrap::NumericalDomainError` if non-finite.
195    #[inline]
196    pub fn read_finite_f32(&self, index: usize) -> Result<f32, VibeTrap> {
197        let v = self.read_f32_le(index)?;
198        if !v.is_finite() {
199            return Err(VibeTrap::NumericalDomainError);
200        }
201        Ok(v)
202    }
203
204    /// Reads `N` contiguous finite `f64` values starting at `start_index`.
205    #[inline]
206    pub fn read_finite_f64_array<const N: usize>(
207        &self,
208        start_index: usize,
209    ) -> Result<[f64; N], VibeTrap> {
210        if self.kind() != PrimitiveKind::F64 {
211            return Err(VibeTrap::TypeMismatch);
212        }
213        let mut out = [0.0f64; N];
214        let mut i = 0;
215        while i < N {
216            let idx = start_index
217                .checked_add(i)
218                .ok_or(VibeTrap::SliceBoundsOverflow)?;
219            out[i] = self.read_finite_f64(idx)?;
220            i += 1;
221        }
222        Ok(out)
223    }
224
225    /// Reads `N` contiguous finite `f32` values starting at `start_index`.
226    #[inline]
227    pub fn read_finite_f32_array<const N: usize>(
228        &self,
229        start_index: usize,
230    ) -> Result<[f32; N], VibeTrap> {
231        if self.kind() != PrimitiveKind::F32 {
232            return Err(VibeTrap::TypeMismatch);
233        }
234        let mut out = [0.0f32; N];
235        let mut i = 0;
236        while i < N {
237            let idx = start_index
238                .checked_add(i)
239                .ok_or(VibeTrap::SliceBoundsOverflow)?;
240            out[i] = self.read_finite_f32(idx)?;
241            i += 1;
242        }
243        Ok(out)
244    }
245}
246
247impl<'a> CallerOutputSlice<'a> {
248    /// Atomically appends a slice of `f64` values (little-endian) into the output buffer.
249    #[inline]
250    pub fn push_f64_slice(&mut self, values: &[f64]) -> Result<(), VibeTrap> {
251        if self.kind() != PrimitiveKind::F64 {
252            return Err(VibeTrap::TypeMismatch);
253        }
254        let needed = self
255            .written_elems()
256            .checked_add(values.len())
257            .ok_or(VibeTrap::SliceBoundsOverflow)?;
258        self.ensure_elem_capacity(needed)?;
259        let mut i = 0;
260        while i < values.len() {
261            self.push_f64_le(values[i])?;
262            i += 1;
263        }
264        Ok(())
265    }
266
267    /// Atomically appends a slice of `f32` values (little-endian) into the output buffer.
268    #[inline]
269    pub fn push_f32_slice(&mut self, values: &[f32]) -> Result<(), VibeTrap> {
270        if self.kind() != PrimitiveKind::F32 {
271            return Err(VibeTrap::TypeMismatch);
272        }
273        let needed = self
274            .written_elems()
275            .checked_add(values.len())
276            .ok_or(VibeTrap::SliceBoundsOverflow)?;
277        self.ensure_elem_capacity(needed)?;
278        let mut i = 0;
279        while i < values.len() {
280            self.push_f32_le(values[i])?;
281            i += 1;
282        }
283        Ok(())
284    }
285
286    /// Alias for [`Self::push_f64_slice`].
287    #[inline]
288    pub fn write_f64_slice(&mut self, values: &[f64]) -> Result<(), VibeTrap> {
289        self.push_f64_slice(values)
290    }
291
292    /// Alias for [`Self::push_f32_slice`].
293    #[inline]
294    pub fn write_f32_slice(&mut self, values: &[f32]) -> Result<(), VibeTrap> {
295        self.push_f32_slice(values)
296    }
297}
298
299#[cfg(test)]
300mod wp_abi_001_tests {
301    use super::*;
302    use crate::memory::ResourceHandle;
303    use crate::version::ABI_CRATE_VERSION;
304
305    #[test]
306    fn canonical_digest_has_no_lossy_field_collisions() {
307        let base_env = ResourceEnvelope::hot_zero_heap(100, 64);
308        let d0 = OntologicalContract::canonical_digest(
309            0x11,
310            StableFuncId::new(1, 2),
311            0x22,
312            EffectSet::PURE_COMPUTE,
313            DeterminismGuarantee::DeterministicExact,
314            ReversibilityKind::PureNoState,
315            base_env,
316            (0, 1),
317            (1, 1),
318            (2, 1),
319        );
320        // Varying flags, max_spawned_tasks, or high span bits must alter the SHA-256 digest.
321        let mut env_async = base_env.with_async_class(AsyncExecutionClass::AsyncBoundedTask);
322        let d1 = OntologicalContract::canonical_digest(
323            0x11,
324            StableFuncId::new(1, 2),
325            0x22,
326            EffectSet::PURE_COMPUTE,
327            DeterminismGuarantee::DeterministicExact,
328            ReversibilityKind::PureNoState,
329            env_async,
330            (0, 1),
331            (1, 1),
332            (2, 1),
333        );
334        assert_ne!(d0, d1);
335
336        env_async.max_spawned_tasks = 4;
337        let d2 = OntologicalContract::canonical_digest(
338            0x11,
339            StableFuncId::new(1, 2),
340            0x22,
341            EffectSet::PURE_COMPUTE,
342            DeterminismGuarantee::DeterministicExact,
343            ReversibilityKind::PureNoState,
344            env_async,
345            (0, 1),
346            (1, 1),
347            (2, 1),
348        );
349        assert_ne!(d1, d2);
350
351        let d3 = OntologicalContract::canonical_digest(
352            0x11,
353            StableFuncId::new(1, 2),
354            0x22,
355            EffectSet::PURE_COMPUTE,
356            DeterminismGuarantee::DeterministicExact,
357            ReversibilityKind::PureNoState,
358            base_env,
359            (0x0100_0000, 1),
360            (1, 1),
361            (2, 1),
362        );
363        assert_ne!(d0, d3);
364        assert_eq!(ABI_CRATE_VERSION, SemVer64::release(0, 0, 41));
365    }
366
367    #[test]
368    fn memory_views_roundtrip_all_added_primitive_kinds_and_check_parity() {
369        // u32 / i32
370        let mut buf32 = [0u8; 8];
371        let mut out_u32 = CallerOutputSlice::new(&mut buf32, PrimitiveKind::U32).unwrap();
372        out_u32.push_u32_le(42).unwrap();
373        out_u32.push_u32_le(u32::MAX).unwrap();
374        let v_u32 =
375            BorrowedSliceView::from_raw_bytes(out_u32.written_byte_slice(), PrimitiveKind::U32, 2)
376                .unwrap();
377        assert_eq!(v_u32.read_u32_le(0).unwrap(), 42);
378        assert_eq!(v_u32.read_u32_le(1).unwrap(), u32::MAX);
379
380        let mut buf_i32 = [0u8; 4];
381        let mut out_i32 = CallerOutputSlice::new(&mut buf_i32, PrimitiveKind::I32).unwrap();
382        out_i32.push_i32_le(-77).unwrap();
383        let v_i32 =
384            BorrowedSliceView::from_raw_bytes(out_i32.written_byte_slice(), PrimitiveKind::I32, 1)
385                .unwrap();
386        assert_eq!(v_i32.read_i32_le(0).unwrap(), -77);
387
388        // NQuin48 with parity validation in from_raw_bytes and read_nquin
389        let q = NQuin48::from_parts(1, 2, 3, 4, 5);
390        let mut qbuf = [0u8; 48];
391        let mut qout = CallerOutputSlice::new(&mut qbuf, PrimitiveKind::NQuin48).unwrap();
392        qout.push_nquin(&q).unwrap();
393        let qview =
394            BorrowedSliceView::from_raw_bytes(qout.written_byte_slice(), PrimitiveKind::NQuin48, 1)
395                .unwrap();
396        assert_eq!(qview.read_nquin(0).unwrap(), q);
397
398        qbuf[0] ^= 0xFF;
399        assert_eq!(
400            BorrowedSliceView::from_raw_bytes(&qbuf, PrimitiveKind::NQuin48, 1).unwrap_err(),
401            VibeTrap::InvalidQuinParity
402        );
403
404        // ResourceHandle
405        let h = ResourceHandle::new(0x1234, 7, 3, 9, 11);
406        let mut hbuf = [0u8; 24];
407        let mut hout = CallerOutputSlice::new(&mut hbuf, PrimitiveKind::ResourceHandle).unwrap();
408        hout.push_resource_handle(&h).unwrap();
409        let hview = BorrowedSliceView::from_raw_bytes(
410            hout.written_byte_slice(),
411            PrimitiveKind::ResourceHandle,
412            1,
413        )
414        .unwrap();
415        assert_eq!(hview.read_resource_handle(0).unwrap(), h);
416
417        // Utf8Bytes
418        let mut sbuf = [0u8; 16];
419        let mut sout = CallerOutputSlice::new(&mut sbuf, PrimitiveKind::Utf8Bytes).unwrap();
420        sout.push_utf8_str("vibescript").unwrap();
421        let sview = BorrowedSliceView::from_raw_bytes(
422            sout.written_byte_slice(),
423            PrimitiveKind::Utf8Bytes,
424            10,
425        )
426        .unwrap();
427        assert_eq!(sview.read_utf8_str().unwrap(), "vibescript");
428    }
429}