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}