Skip to main content

vibescript_abi/
descriptor.rs

1//! Self-describing ontological contract (`OntologicalContract`), function/provider
2//! descriptors (`FuncDescriptor`, `ProviderDescriptor`), and `VibeNamespaceProvider`.
3
4use crate::effects::{
5    AsyncExecutionClass, DeterminismGuarantee, EffectSet, ResourceEnvelope, ReversibilityKind,
6    TargetProfileMask,
7};
8use crate::identity::{CanonicalIri, StableFuncId};
9use crate::lifecycle::VibeTrap;
10use crate::memory::{BorrowedSliceView, CallerOutputSlice, NQuin48, PrimitiveKind};
11use crate::version::ContractVersionAxes;
12
13/// Self-describing ontological contract attached to an extension function.
14///
15/// Combines a full 32-byte SHA-256 contract digest with a 64-bit `q_hash` schema
16/// fingerprint and slice spans into the provider's `static_ontology_nquins()` table.
17#[repr(C)]
18#[derive(Debug, Clone, Copy, PartialEq, Eq)]
19pub struct OntologicalContract {
20    /// Full 32-byte SHA-256 digest of the canonical function contract.
21    pub contract_digest: [u8; 32],
22    /// 64-bit `q_hash` of the parameter/return schema signature.
23    pub schema_hash: u64,
24    /// `(start, len)` span in `static_ontology_nquins()` encoding preconditions.
25    pub precondition_quin_span: (u32, u32),
26    /// `(start, len)` span in `static_ontology_nquins()` encoding postconditions.
27    pub postcondition_quin_span: (u32, u32),
28    /// `(start, len)` span in `static_ontology_nquins()` encoding conservation/invariants.
29    pub invariant_quin_span: (u32, u32),
30}
31
32impl OntologicalContract {
33    /// Verifies that all `(start, len)` spans lie within `total_ontology_quins`.
34    #[inline]
35    pub const fn validate_spans(&self, total_ontology_quins: usize) -> bool {
36        let total = total_ontology_quins as u64;
37        let pre_end =
38            (self.precondition_quin_span.0 as u64) + (self.precondition_quin_span.1 as u64);
39        let post_end =
40            (self.postcondition_quin_span.0 as u64) + (self.postcondition_quin_span.1 as u64);
41        let inv_end = (self.invariant_quin_span.0 as u64) + (self.invariant_quin_span.1 as u64);
42        pre_end <= total && post_end <= total && inv_end <= total
43    }
44
45    /// Computes a deterministic 32-byte SHA-256 canonical contract digest at compile time
46    /// from all fields of the function's identity, schema hash, effects, envelope, and ontology spans.
47    #[inline]
48    pub const fn canonical_digest(
49        func_iri_hash: u64,
50        stable_id: StableFuncId,
51        schema_hash: u64,
52        effects: EffectSet,
53        determinism: DeterminismGuarantee,
54        reversibility: ReversibilityKind,
55        envelope: ResourceEnvelope,
56        pre_span: (u32, u32),
57        post_span: (u32, u32),
58        inv_span: (u32, u32),
59    ) -> [u8; 32] {
60        let mut msg = [0u8; 82];
61        // Domain tag "VS03CNTR"
62        let domain = *b"VS03CNTR";
63        let f_iri = func_iri_hash.to_le_bytes();
64        let s_id = stable_id.to_u32().to_le_bytes();
65        let sch = schema_hash.to_le_bytes();
66        let eff = effects.0.to_le_bytes();
67        let det = determinism as u8;
68        let rev = reversibility as u8;
69        let max_ticks = envelope.max_ticks.to_le_bytes();
70        let max_scratch = envelope.max_scratch_bytes.to_le_bytes();
71        let max_vram = envelope.max_vram_bytes.to_le_bytes();
72        let max_out = envelope.max_output_bytes.to_le_bytes();
73        let max_tasks = envelope.max_spawned_tasks.to_le_bytes();
74        let flags = envelope.flags.to_le_bytes();
75        let pre0 = pre_span.0.to_le_bytes();
76        let pre1 = pre_span.1.to_le_bytes();
77        let post0 = post_span.0.to_le_bytes();
78        let post1 = post_span.1.to_le_bytes();
79        let inv0 = inv_span.0.to_le_bytes();
80        let inv1 = inv_span.1.to_le_bytes();
81
82        let mut pos = 0;
83        let mut i = 0;
84        while i < 8 { msg[pos] = domain[i]; pos += 1; i += 1; }
85        i = 0; while i < 8 { msg[pos] = f_iri[i]; pos += 1; i += 1; }
86        i = 0; while i < 4 { msg[pos] = s_id[i]; pos += 1; i += 1; }
87        i = 0; while i < 8 { msg[pos] = sch[i]; pos += 1; i += 1; }
88        i = 0; while i < 4 { msg[pos] = eff[i]; pos += 1; i += 1; }
89        msg[pos] = det; pos += 1;
90        msg[pos] = rev; pos += 1;
91        i = 0; while i < 8 { msg[pos] = max_ticks[i]; pos += 1; i += 1; }
92        i = 0; while i < 4 { msg[pos] = max_scratch[i]; pos += 1; i += 1; }
93        i = 0; while i < 4 { msg[pos] = max_vram[i]; pos += 1; i += 1; }
94        i = 0; while i < 4 { msg[pos] = max_out[i]; pos += 1; i += 1; }
95        i = 0; while i < 2 { msg[pos] = max_tasks[i]; pos += 1; i += 1; }
96        i = 0; while i < 2 { msg[pos] = flags[i]; pos += 1; i += 1; }
97        i = 0; while i < 4 { msg[pos] = pre0[i]; pos += 1; i += 1; }
98        i = 0; while i < 4 { msg[pos] = pre1[i]; pos += 1; i += 1; }
99        i = 0; while i < 4 { msg[pos] = post0[i]; pos += 1; i += 1; }
100        i = 0; while i < 4 { msg[pos] = post1[i]; pos += 1; i += 1; }
101        i = 0; while i < 4 { msg[pos] = inv0[i]; pos += 1; i += 1; }
102        i = 0; while i < 4 { msg[pos] = inv1[i]; pos += 1; i += 1; }
103        debug_assert!(pos == 82);
104
105        sha256_const(&msg)
106    }
107}
108
109const SHA256_INIT: [u32; 8] = [
110    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
111    0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
112];
113
114const SHA256_K: [u32; 64] = [
115    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
116    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
117    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
118    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
119    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
120    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
121    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
122    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
123];
124
125const fn sha256_compress(mut state: [u32; 8], block: &[u8; 64]) -> [u32; 8] {
126    let mut w = [0u32; 64];
127    let mut i = 0;
128    while i < 16 {
129        let j = i * 4;
130        w[i] = u32::from_be_bytes([block[j], block[j + 1], block[j + 2], block[j + 3]]);
131        i += 1;
132    }
133    while i < 64 {
134        let s0 = w[i - 15].rotate_right(7) ^ w[i - 15].rotate_right(18) ^ (w[i - 15] >> 3);
135        let s1 = w[i - 2].rotate_right(17) ^ w[i - 2].rotate_right(19) ^ (w[i - 2] >> 10);
136        w[i] = w[i - 16].wrapping_add(s0).wrapping_add(w[i - 7]).wrapping_add(s1);
137        i += 1;
138    }
139
140    let mut a = state[0];
141    let mut b = state[1];
142    let mut c = state[2];
143    let mut d = state[3];
144    let mut e = state[4];
145    let mut f = state[5];
146    let mut g = state[6];
147    let mut h = state[7];
148
149    i = 0;
150    while i < 64 {
151        let s1 = e.rotate_right(6) ^ e.rotate_right(11) ^ e.rotate_right(25);
152        let ch = (e & f) ^ ((!e) & g);
153        let temp1 = h.wrapping_add(s1).wrapping_add(ch).wrapping_add(SHA256_K[i]).wrapping_add(w[i]);
154        let s0 = a.rotate_right(2) ^ a.rotate_right(13) ^ a.rotate_right(22);
155        let maj = (a & b) ^ (a & c) ^ (b & c);
156        let temp2 = s0.wrapping_add(maj);
157
158        h = g;
159        g = f;
160        f = e;
161        e = d.wrapping_add(temp1);
162        d = c;
163        c = b;
164        b = a;
165        a = temp1.wrapping_add(temp2);
166        i += 1;
167    }
168
169    state[0] = state[0].wrapping_add(a);
170    state[1] = state[1].wrapping_add(b);
171    state[2] = state[2].wrapping_add(c);
172    state[3] = state[3].wrapping_add(d);
173    state[4] = state[4].wrapping_add(e);
174    state[5] = state[5].wrapping_add(f);
175    state[6] = state[6].wrapping_add(g);
176    state[7] = state[7].wrapping_add(h);
177    state
178}
179
180/// Pure `#![no_std]` compile-time SHA-256 over arbitrary slices.
181pub(crate) const fn sha256_const(data: &[u8]) -> [u8; 32] {
182    let mut state = SHA256_INIT;
183    let mut offset = 0;
184    while offset + 64 <= data.len() {
185        let mut block = [0u8; 64];
186        let mut i = 0;
187        while i < 64 {
188            block[i] = data[offset + i];
189            i += 1;
190        }
191        state = sha256_compress(state, &block);
192        offset += 64;
193    }
194
195    let rem = data.len() - offset;
196    let mut tail = [0u8; 64];
197    let mut i = 0;
198    while i < rem {
199        tail[i] = data[offset + i];
200        i += 1;
201    }
202    tail[rem] = 0x80;
203    if rem >= 56 {
204        state = sha256_compress(state, &tail);
205        tail = [0u8; 64];
206    }
207    let bit_len = (data.len() as u64) * 8;
208    let len_bytes = bit_len.to_be_bytes();
209    i = 0;
210    while i < 8 {
211        tail[56 + i] = len_bytes[i];
212        i += 1;
213    }
214    state = sha256_compress(state, &tail);
215
216    let mut out = [0u8; 32];
217    let mut j = 0;
218    while j < 8 {
219        let be = state[j].to_be_bytes();
220        out[j * 4] = be[0];
221        out[j * 4 + 1] = be[1];
222        out[j * 4 + 2] = be[2];
223        out[j * 4 + 3] = be[3];
224        j += 1;
225    }
226    out
227}
228
229/// Parameter specification for an extension function.
230#[repr(C)]
231#[derive(Debug, Clone, Copy, PartialEq, Eq)]
232pub struct ParamSpec {
233    /// Parameter name (UTF-8 static identifier).
234    pub name: &'static str,
235    /// Element primitive kind expected in the corresponding `BorrowedSliceView`.
236    pub kind: PrimitiveKind,
237    /// Minimum element count required (`1` for scalar, `N` for fixed vector/tuple).
238    pub min_elems: u32,
239    /// Maximum element count permitted (`u32::MAX` for unbounded slice within envelope).
240    pub max_elems: u32,
241}
242
243impl ParamSpec {
244    /// Scalar parameter (`min_elems = 1`, `max_elems = 1`).
245    #[inline]
246    pub const fn scalar(name: &'static str, kind: PrimitiveKind) -> Self {
247        Self {
248            name,
249            kind,
250            min_elems: 1,
251            max_elems: 1,
252        }
253    }
254
255    /// Bounded slice parameter (`min_elems..=max_elems`).
256    #[inline]
257    pub const fn slice(
258        name: &'static str,
259        kind: PrimitiveKind,
260        min_elems: u32,
261        max_elems: u32,
262    ) -> Self {
263        Self {
264            name,
265            kind,
266            min_elems,
267            max_elems,
268        }
269    }
270}
271
272/// Static descriptor for a single extension function.
273#[repr(C)]
274#[derive(Debug, Clone, Copy, PartialEq, Eq)]
275pub struct FuncDescriptor {
276    /// Short function name within its sub-namespace (e.g. `"verlet_step"`).
277    pub name: &'static str,
278    /// Globally unique canonical IRI + `q_hash`.
279    pub canonical_iri: CanonicalIri,
280    /// Provider-scoped stable `(sub_namespace_id, func_id)`.
281    pub stable_id: StableFuncId,
282    /// Static parameter specifications.
283    pub params: &'static [ParamSpec],
284    /// Output element primitive kind written to `CallerOutputSlice`.
285    pub output_kind: PrimitiveKind,
286    /// Exact or worst-case number of output elements required per call.
287    pub required_output_elems: u32,
288    /// Declared effect bitmask.
289    pub effects: EffectSet,
290    /// Declared determinism guarantee.
291    pub determinism: DeterminismGuarantee,
292    /// Declared reversibility / undo classification.
293    pub reversibility: ReversibilityKind,
294    /// Worst-case resource envelope enforced at admission and runtime.
295    pub envelope: ResourceEnvelope,
296    /// Self-describing ontological contract and `NQuin48` span offsets.
297    pub contract: OntologicalContract,
298}
299
300impl FuncDescriptor {
301    /// Returns the synchronous vs bounded-async execution classification encoded in `envelope.flags`.
302    #[inline]
303    pub const fn async_class(&self) -> AsyncExecutionClass {
304        self.envelope.async_class()
305    }
306}
307
308/// Static descriptor for a sub-namespace within a provider.
309#[repr(C)]
310#[derive(Debug, Clone, Copy, PartialEq, Eq)]
311pub struct SubNamespaceDescriptor {
312    /// Sub-namespace name (e.g. `"kinematics"`).
313    pub name: &'static str,
314    /// Immutable sub-namespace ID (`matches StableFuncId::sub_namespace_id`).
315    pub sub_id: u16,
316    /// Functions exported by this sub-namespace.
317    pub functions: &'static [FuncDescriptor],
318}
319
320/// Top-level descriptor for a VibeScript extension provider.
321#[repr(C)]
322#[derive(Debug, Clone, Copy, PartialEq, Eq)]
323pub struct ProviderDescriptor {
324    /// Canonical namespace IRI + `q_hash` (e.g. `"https://qualiadb.org/ext/etalon/mechanics"`).
325    pub canonical_iri: CanonicalIri,
326    /// Default short import alias (e.g. `"mech"`).
327    pub short_alias: &'static str,
328    /// Five independent version axes (`language`, `abi`, `host`, `provider`, `ontology`).
329    pub versions: ContractVersionAxes,
330    /// Supported execution target profiles.
331    pub supported_targets: TargetProfileMask,
332    /// Exported sub-namespaces.
333    pub sub_namespaces: &'static [SubNamespaceDescriptor],
334    /// Maximum allowed ontology `NQuin48` records for this provider.
335    pub max_ontology_quins: u32,
336}
337
338/// Trait implemented by zero-heap VibeScript extension providers (`crates/vibe`, `etalon`, `qualia-core-db`).
339pub trait VibeNamespaceProvider: Sync {
340    /// Returns the provider's static metadata and function catalog.
341    fn descriptor(&self) -> &'static ProviderDescriptor;
342
343    /// Returns the provider's static, compile-time sealed `NQuin48` ontology triples.
344    fn static_ontology_nquins(&self) -> &'static [NQuin48];
345
346    /// Executes the function identified by `stable_id` using caller-supplied input/output slices.
347    ///
348    /// Returns the number of logical ticks consumed on success, or a deterministic `VibeTrap`.
349    fn call(
350        &self,
351        stable_id: StableFuncId,
352        inputs: &[BorrowedSliceView<'_>],
353        output: &mut CallerOutputSlice<'_>,
354    ) -> Result<u64, VibeTrap>;
355}