Skip to main content

vibescript_abi/
lib.rs

1//! `vibescript-abi` — Lightweight, `#![no_std]`, zero-heap extension ABI,
2//! self-describing ontological contract, and Sentinel lifecycle interface for VibeScript.
3
4#![no_std]
5
6pub mod descriptor;
7pub mod effects;
8pub mod identity;
9pub mod lifecycle;
10pub mod memory;
11pub mod sdk;
12pub mod version;
13
14pub use descriptor::{
15    FuncDescriptor, OntologicalContract, ParamSpec, ProviderDescriptor, SubNamespaceDescriptor,
16    VibeNamespaceProvider,
17};
18pub use effects::{
19    AsyncExecutionClass, DeterminismGuarantee, EffectSet, ExecutionMode, ResourceEnvelope,
20    ReversibilityKind, TargetProfileMask,
21};
22pub use identity::{
23    q_hash, q_hash_str, CanonicalIri, PreparedCallHandle, RegistryGeneration, StableFuncId,
24    VibeOpCode, FNV1A_64_OFFSET_BASIS, FNV1A_64_PRIME,
25};
26pub use lifecycle::{
27    AdmissionRequest, AdmissionTicket, CompletionStatus, ExecutionReceiptHeader, FailureStage,
28    SentinelPolicyGate, VibeTrap,
29};
30pub use memory::{BorrowedSliceView, CallerOutputSlice, NQuin48, PrimitiveKind, ResourceHandle};
31pub use sdk::{
32    VIBE_HAS_POSTCONDITION_IRI, VIBE_HAS_PRECONDITION_IRI, VIBE_PRESERVES_INVARIANT_IRI,
33    VIBE_PUBLIC_CONTEXT_IRI,
34};
35pub use version::{ContractVersionAxes, SemVer64, SemVerReq};
36
37#[cfg(test)]
38mod tests {
39    use super::*;
40
41    #[test]
42    fn nquin48_layout_and_parity() {
43        assert_eq!(core::mem::size_of::<NQuin48>(), 48);
44        assert_eq!(core::mem::align_of::<NQuin48>(), 16);
45        let q = NQuin48::from_parts(11, 22, 33, 44, 55);
46        assert!(q.verify_parity());
47        assert_eq!(q.parity(), 11 ^ 22 ^ 33 ^ 44 ^ 55);
48
49        let mut corrupted = q;
50        corrupted.0[2] ^= 1;
51        assert!(!corrupted.verify_parity());
52    }
53
54    #[test]
55    fn semver64_caret_handles_zero_major_and_zero_minor_correctly() {
56        // ^0.4.0 -> >=0.4.0, <0.5.0
57        let req_0_4 = SemVerReq::Caret(SemVer64::release(0, 4, 0));
58        assert!(!req_0_4.matches(SemVer64::release(0, 3, 9)));
59        assert!(req_0_4.matches(SemVer64::release(0, 4, 0)));
60        assert!(req_0_4.matches(SemVer64::release(0, 4, 9)));
61        assert!(!req_0_4.matches(SemVer64::release(0, 5, 0)));
62        assert!(!req_0_4.matches(SemVer64::release(1, 0, 0)));
63
64        // ^0.0.3 -> ==0.0.3
65        let req_0_0_3 = SemVerReq::Caret(SemVer64::release(0, 0, 3));
66        assert!(!req_0_0_3.matches(SemVer64::release(0, 0, 2)));
67        assert!(req_0_0_3.matches(SemVer64::release(0, 0, 3)));
68        assert!(!req_0_0_3.matches(SemVer64::release(0, 0, 4)));
69        assert!(!req_0_0_3.matches(SemVer64::release(0, 1, 0)));
70
71        // ^1.2.3 -> >=1.2.3, <2.0.0
72        let req_1_2_3 = SemVerReq::Caret(SemVer64::release(1, 2, 3));
73        assert!(!req_1_2_3.matches(SemVer64::release(1, 2, 2)));
74        assert!(req_1_2_3.matches(SemVer64::release(1, 2, 3)));
75        assert!(req_1_2_3.matches(SemVer64::release(1, 9, 0)));
76        assert!(!req_1_2_3.matches(SemVer64::release(2, 0, 0)));
77
78        // Prerelease / abi_flags != 0 rejected by stable range
79        assert!(!req_1_2_3.matches(SemVer64::new(1, 2, 3, 1)));
80    }
81
82    #[test]
83    fn q_hash_matches_canonical_fnv1a_64() {
84        let iri = CanonicalIri::new("https://qualiadb.org/ext/etalon/mechanics/verlet_step");
85        assert!(iri.is_valid());
86        assert_eq!(
87            iri.fnv1a_hash,
88            q_hash(b"https://qualiadb.org/ext/etalon/mechanics/verlet_step")
89        );
90
91        let bad = CanonicalIri::with_explicit_hash("https://qualiadb.org/ext/test", 0xDEAD_BEEF);
92        assert!(!bad.is_valid());
93    }
94
95    #[test]
96    fn vibe_opcode_packs_and_unpacks_cleanly() {
97        let stable = StableFuncId::new(7, 42);
98        let op = VibeOpCode::pack(19, stable);
99        assert_eq!(op.ns_slot(), 19);
100        assert_eq!(op.sub_namespace_id(), 7);
101        assert_eq!(op.func_id(), 42);
102        assert_eq!(op.stable_id(), stable);
103    }
104
105    #[test]
106    fn slice_views_and_output_buffer_enforce_bounds_and_parity() {
107        let mut raw_out = [0u8; 16];
108        let mut out = CallerOutputSlice::new(&mut raw_out, PrimitiveKind::F64).unwrap();
109        assert_eq!(out.capacity_elems(), 2);
110        assert_eq!(
111            out.ensure_elem_capacity(3),
112            Err(VibeTrap::OutputBufferTooSmall)
113        );
114        out.push_f64_le(3.5).unwrap();
115        out.push_f64_le(-1.25).unwrap();
116        assert_eq!(out.push_f64_le(9.0), Err(VibeTrap::OutputBufferTooSmall));
117        assert_eq!(out.written_elems(), 2);
118
119        let view = BorrowedSliceView::from_raw_bytes(out.written_byte_slice(), PrimitiveKind::F64, 2)
120            .unwrap();
121        assert_eq!(view.read_f64_le(0).unwrap(), 3.5);
122        assert_eq!(view.read_f64_le(1).unwrap(), -1.25);
123        assert_eq!(view.read_f64_le(2), Err(VibeTrap::SliceBoundsOverflow));
124    }
125
126    #[test]
127    fn resource_handle_validates_owner_and_generation() {
128        let owner = q_hash_str("https://qualiadb.org/ext/etalon/mechanics");
129        let handle = ResourceHandle::new(owner, 3, 0, 5, 12);
130        assert!(handle.validate(owner, 3, 5).is_ok());
131        assert_eq!(
132            handle.validate(owner ^ 1, 3, 5),
133            Err(VibeTrap::InvalidResourceHandleOwner)
134        );
135        assert_eq!(
136            handle.validate(owner, 3, 6),
137            Err(VibeTrap::StaleResourceHandleGeneration)
138        );
139    }
140
141    #[test]
142    fn execution_receipt_seals_to_parity_valid_nquins() {
143        let receipt = ExecutionReceiptHeader {
144            ticket_id: 101,
145            actor_did_hash: q_hash_str("did:q42:alice"),
146            provider_iri_hash: q_hash_str("https://qualiadb.org/ext/etalon/mechanics"),
147            func_iri_hash: q_hash_str("https://qualiadb.org/ext/etalon/mechanics/verlet_step"),
148            stable_id: StableFuncId::new(0, 1),
149            mode: ExecutionMode::GovernedApplication,
150            status: CompletionStatus::Committed,
151            simulated: false,
152            reserved: [0; 5],
153            policy_generation: 9,
154            registry_generation: RegistryGeneration(2),
155            ticks_consumed: 14,
156            output_bytes_written: 24,
157            trap_code: 0,
158            failure_stage: 0,
159            input_output_fold_hash: 0x1234_5678_9ABC_DEF0,
160            lamport_timestamp: 500,
161        };
162        let quins = receipt.to_audit_nquins();
163        assert!(quins[0].verify_parity());
164        assert!(quins[1].verify_parity());
165    }
166
167    #[test]
168    fn sdk_const_constructors_and_ontology_nquins_verify_5field_parity() {
169        const PARAMS: &[ParamSpec] = &[
170            ParamSpec::slice("vec3", PrimitiveKind::F64, 3, 3),
171            ParamSpec::scalar("scale", PrimitiveKind::F64),
172        ];
173        const FUNC: FuncDescriptor = FuncDescriptor::const_new(
174            "scale_vec3",
175            "https://qualiadb.org/ext/test/math/scale_vec3",
176            StableFuncId::new(0, 1),
177            "(f64[3],f64)->f64[3]",
178            PARAMS,
179            PrimitiveKind::F64,
180            3,
181            EffectSet::PURE_COMPUTE,
182            DeterminismGuarantee::DeterministicTolerance,
183            ReversibilityKind::PureNoState,
184            ResourceEnvelope::hot_zero_heap(16, 24),
185            (0, 1),
186            (1, 1),
187            (2, 1),
188        );
189        const SUBS: &[SubNamespaceDescriptor] = &[SubNamespaceDescriptor {
190            name: "math",
191            sub_id: 0,
192            functions: &[FUNC],
193        }];
194        const PROVIDER: ProviderDescriptor = ProviderDescriptor::const_new(
195            "https://qualiadb.org/ext/test",
196            "tmath",
197            SemVer64::release(0, 2, 1),
198            SemVer64::release(0, 1, 0),
199            TargetProfileMask::ALL_CPU,
200            SUBS,
201            8,
202        );
203        const QUINS: [NQuin48; 3] = [
204            NQuin48::precondition(
205                "https://qualiadb.org/ext/test/math/scale_vec3",
206                "https://qualiadb.org/schema/vibe#FiniteRealInputs",
207                10,
208            ),
209            NQuin48::postcondition(
210                "https://qualiadb.org/ext/test/math/scale_vec3",
211                "https://qualiadb.org/schema/vibe#FiniteRealOutputs",
212                20,
213            ),
214            NQuin48::invariant(
215                "https://qualiadb.org/ext/test/math/scale_vec3",
216                "https://qualiadb.org/schema/vibe#Linearity",
217                30,
218            ),
219        ];
220
221        assert!(PROVIDER.canonical_iri.is_valid());
222        assert!(PROVIDER.versions.is_engine_compatible());
223        assert!(FUNC.canonical_iri.is_valid());
224        assert!(FUNC.contract.validate_spans(QUINS.len()));
225        assert_eq!(
226            FUNC.contract.contract_digest,
227            OntologicalContract::canonical_digest(
228                FUNC.canonical_iri.fnv1a_hash,
229                FUNC.stable_id,
230                q_hash_str("(f64[3],f64)->f64[3]"),
231                FUNC.effects,
232                FUNC.determinism,
233                FUNC.reversibility,
234                FUNC.envelope,
235                (0, 1),
236                (1, 1),
237                (2, 1),
238            )
239        );
240        for q in &QUINS {
241            assert!(q.verify_parity());
242            assert_eq!(
243                q.parity(),
244                q.subject() ^ q.predicate() ^ q.object() ^ q.context() ^ q.metadata()
245            );
246        }
247    }
248
249    #[test]
250    fn sdk_finite_slice_readers_and_writers_reject_non_finite_values() {
251        let mut buf_f64 = [0u8; 24];
252        let mut out_f64 = CallerOutputSlice::new(&mut buf_f64, PrimitiveKind::F64).unwrap();
253        out_f64.push_f64_slice(&[1.25, -2.5, 4.0]).unwrap();
254        assert_eq!(out_f64.written_elems(), 3);
255
256        let view_f64 =
257            BorrowedSliceView::from_raw_bytes(out_f64.written_byte_slice(), PrimitiveKind::F64, 3)
258                .unwrap();
259        assert_eq!(
260            view_f64.read_finite_f64_array::<3>(0).unwrap(),
261            [1.25, -2.5, 4.0]
262        );
263
264        let nan_bytes = f64::NAN.to_le_bytes();
265        let nan_view = BorrowedSliceView::from_raw_bytes(&nan_bytes, PrimitiveKind::F64, 1).unwrap();
266        assert_eq!(
267            nan_view.read_finite_f64(0),
268            Err(VibeTrap::NumericalDomainError)
269        );
270
271        let mut buf_f32 = [0u8; 8];
272        let mut out_f32 = CallerOutputSlice::new(&mut buf_f32, PrimitiveKind::F32).unwrap();
273        out_f32.write_f32_slice(&[0.5f32, 1.5f32]).unwrap();
274        let view_f32 =
275            BorrowedSliceView::from_raw_bytes(out_f32.written_byte_slice(), PrimitiveKind::F32, 2)
276                .unwrap();
277        assert_eq!(view_f32.read_finite_f32_array::<2>(0).unwrap(), [0.5, 1.5]);
278
279        let inf_bytes = f32::INFINITY.to_le_bytes();
280        let inf_view = BorrowedSliceView::from_raw_bytes(&inf_bytes, PrimitiveKind::F32, 1).unwrap();
281        assert_eq!(
282            inf_view.read_finite_f32(0),
283            Err(VibeTrap::NumericalDomainError)
284        );
285    }
286}