Skip to main content

vibescript_abi/
identity.rs

1//! Canonical IRI hashing (`q_hash` FNV-1a 64-bit), provider-scoped stable function IDs,
2//! and generational prepared runtime dispatch handles (`VibeOpCode`, `PreparedCallHandle`).
3
4/// 64-bit FNV-1a offset basis used across QualiaDB (`qualia_core_db::q_hash`) and `vibe`.
5pub const FNV1A_64_OFFSET_BASIS: u64 = 0xcbf2_9ce4_8422_2325;
6
7/// 64-bit FNV-1a prime used across QualiaDB (`qualia_core_db::q_hash`) and `vibe`.
8pub const FNV1A_64_PRIME: u64 = 0x0000_0100_0000_01b3;
9
10/// Compile-time and runtime 64-bit FNV-1a hash over raw bytes (`q_hash`).
11#[inline]
12pub const fn q_hash(bytes: &[u8]) -> u64 {
13    let mut hash = FNV1A_64_OFFSET_BASIS;
14    let mut i = 0;
15    while i < bytes.len() {
16        hash ^= bytes[i] as u64;
17        hash = hash.wrapping_mul(FNV1A_64_PRIME);
18        i += 1;
19    }
20    hash
21}
22
23/// Compile-time and runtime 64-bit FNV-1a hash over a UTF-8 string slice.
24#[inline]
25pub const fn q_hash_str(s: &str) -> u64 {
26    q_hash(s.as_bytes())
27}
28
29/// Globally stable semantic identifier pairing an immutable IRI with its `q_hash`.
30#[repr(C)]
31#[derive(Debug, Clone, Copy, PartialEq, Eq)]
32pub struct CanonicalIri {
33    /// Canonical UTF-8 IRI (e.g. `"https://qualiadb.org/ext/etalon/sim/xpbd_step"`).
34    pub iri: &'static str,
35    /// Precomputed 64-bit FNV-1a hash (`q_hash_str(iri)`).
36    pub fnv1a_hash: u64,
37}
38
39impl CanonicalIri {
40    /// Constructs a `CanonicalIri` and computes its `q_hash` at compile time.
41    #[inline]
42    pub const fn new(iri: &'static str) -> Self {
43        Self {
44            iri,
45            fnv1a_hash: q_hash_str(iri),
46        }
47    }
48
49    /// Constructs a `CanonicalIri` with an explicit hash (verified during registration).
50    #[inline]
51    pub const fn with_explicit_hash(iri: &'static str, fnv1a_hash: u64) -> Self {
52        Self { iri, fnv1a_hash }
53    }
54
55    /// Verifies that the stored `fnv1a_hash` matches `q_hash_str(self.iri)` and the IRI is non-empty.
56    #[inline]
57    pub const fn is_valid(&self) -> bool {
58        !self.iri.is_empty() && self.fnv1a_hash == q_hash_str(self.iri)
59    }
60}
61
62/// Provider-scoped stable function identifier (`sub_namespace_id`, `func_id`).
63///
64/// Unlike process-local registry slots, `StableFuncId` is immutable within a
65/// provider major/minor release and independent of provider registration order.
66#[repr(C)]
67#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
68pub struct StableFuncId {
69    /// Sub-namespace index within the provider (e.g. `0 = kinematics`, `1 = dynamics`).
70    pub sub_namespace_id: u16,
71    /// Function index within the sub-namespace.
72    pub func_id: u16,
73}
74
75impl StableFuncId {
76    /// Creates a new `StableFuncId`.
77    #[inline]
78    pub const fn new(sub_namespace_id: u16, func_id: u16) -> Self {
79        Self {
80            sub_namespace_id,
81            func_id,
82        }
83    }
84
85    /// Packs `(sub_namespace_id, func_id)` into a `u32`.
86    #[inline]
87    pub const fn to_u32(self) -> u32 {
88        ((self.sub_namespace_id as u32) << 16) | (self.func_id as u32)
89    }
90
91    /// Unpacks a `u32` into `StableFuncId`.
92    #[inline]
93    pub const fn from_u32(packed: u32) -> Self {
94        Self {
95            sub_namespace_id: (packed >> 16) as u16,
96            func_id: (packed & 0xFFFF) as u16,
97        }
98    }
99}
100
101/// Process-local 64-bit prepared dispatch handle: `[ns_slot: u32][sub_id: u16][func_id: u16]`.
102///
103/// **Important**: `VibeOpCode` is a process-local runtime handle bound to a
104/// `RegistryGeneration`. It is never persisted as a canonical semantic ID and
105/// never written into `NQuin.predicate[0..7]` (`SlgOpcode`).
106#[repr(transparent)]
107#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
108pub struct VibeOpCode(pub u64);
109
110impl VibeOpCode {
111    /// Packs a registry slot and `StableFuncId` into a `VibeOpCode`.
112    #[inline]
113    pub const fn pack(ns_slot: u32, stable_id: StableFuncId) -> Self {
114        let upper = (ns_slot as u64) << 32;
115        let lower = stable_id.to_u32() as u64;
116        Self(upper | lower)
117    }
118
119    /// Extracts the registry provider slot (`bits 32..63`).
120    #[inline]
121    pub const fn ns_slot(self) -> u32 {
122        (self.0 >> 32) as u32
123    }
124
125    /// Extracts the sub-namespace ID (`bits 16..31`).
126    #[inline]
127    pub const fn sub_namespace_id(self) -> u16 {
128        ((self.0 >> 16) & 0xFFFF) as u16
129    }
130
131    /// Extracts the function ID (`bits 0..15`).
132    #[inline]
133    pub const fn func_id(self) -> u16 {
134        (self.0 & 0xFFFF) as u16
135    }
136
137    /// Extracts the `StableFuncId`.
138    #[inline]
139    pub const fn stable_id(self) -> StableFuncId {
140        StableFuncId {
141            sub_namespace_id: self.sub_namespace_id(),
142            func_id: self.func_id(),
143        }
144    }
145}
146
147/// Monotonic generation counter of the extension registry.
148///
149/// Incremented on every provider registration or unload so stale `PreparedCallHandle`s
150/// fail closed in $O(1)$ before dispatch.
151#[repr(transparent)]
152#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
153pub struct RegistryGeneration(pub u32);
154
155impl RegistryGeneration {
156    /// Initial generation before any registration.
157    pub const INITIAL: Self = Self(1);
158
159    /// Returns the next generation, saturating at `u32::MAX`.
160    #[inline]
161    pub const fn next(self) -> Self {
162        Self(self.0.saturating_add(1))
163    }
164}
165
166/// Prepared call token produced during the cold `Prepare` stage and consumed in $O(1)$
167/// during the hot `Admit -> Execute` stages.
168#[repr(C)]
169#[derive(Debug, Clone, Copy, PartialEq, Eq)]
170pub struct PreparedCallHandle {
171    /// Packed `O(1)` dispatch slot (`[ns_slot: u32][sub_id: u16][func_id: u16]`).
172    pub opcode: VibeOpCode,
173    /// Registry generation at preparation time; must equal current registry generation on dispatch.
174    pub registry_generation: RegistryGeneration,
175    /// Reserved alignment padding.
176    pub reserved: u32,
177    /// Canonical `q_hash` of the provider namespace IRI.
178    pub provider_iri_hash: u64,
179    /// Canonical `q_hash` of the function IRI.
180    pub func_iri_hash: u64,
181    /// Full 32-byte SHA-256 ontological contract digest bound at preparation time.
182    pub contract_digest: [u8; 32],
183}