Skip to main content

qualia_core_db/governance/
webizen_validator.rs

1//! Webizen NQuin Validation Layer
2//!
3//! Provides shape/confidence/domain/structural rule enforcement for NQuins at
4//! ingestion and query time.  Rules are stored as dedicated Q42 blocks and
5//! validated during ingestion via [`WebValidator`].
6//!
7//! A lightweight pattern-matching VM ([`execute_query_program`]) is also
8//! provided for the CLI SPARQL query path; it is distinct from the full
9//! Webizen bytecode engine in [`crate::webizen_bytecode`].
10
11use crate::NQuin;
12use std::collections::HashSet;
13
14const OP_MATCH_SUBJ: u8 = 0x01;
15const OP_MATCH_PRED: u8 = 0x02;
16const OP_MATCH_OBJ: u8 = 0x03;
17
18const OP_BIND_VAR: u8 = 0x10;
19const SLOT_SUBJ: u8 = 0x00;
20const SLOT_PRED: u8 = 0x01;
21const SLOT_OBJ: u8 = 0x02;
22
23const OP_HALT: u8 = 0xFF;
24
25/// Stack-allocated register file for bound variable hashes (max 16 variables).
26#[derive(Debug, Default)]
27struct VmRegisters {
28    values: [u64; 16],
29    bound_flags: u16,
30}
31
32impl VmRegisters {
33    /// Store `value` in register `id` and mark it bound; ids ≥ 16 are
34    /// ignored (the register file is deliberately bounded).
35    fn bind(&mut self, id: u8, value: u64) {
36        if (id as usize) < self.values.len() {
37            self.values[id as usize] = value;
38            self.bound_flags |= 1 << id;
39        }
40    }
41}
42
43/// Execute a query bytecode program against a NQuin dataset.
44///
45/// Opcodes: `MATCH_SUBJ` / `MATCH_PRED` / `MATCH_OBJ` filter the candidate
46/// set; `BIND_VAR` extracts a slot value into a register; `HALT` stops early.
47///
48/// Returns the vector of bound register values on success.
49pub fn execute_query_program(program: &[u8], dataset: &[NQuin]) -> Result<Vec<u64>, &'static str> {
50    let mut pc = 0;
51    let mut registers = VmRegisters::default();
52    let mut candidate_set: Vec<&NQuin> = dataset.iter().collect();
53
54    while pc < program.len() {
55        let opcode = program[pc];
56        pc += 1;
57
58        match opcode {
59            OP_MATCH_SUBJ => {
60                if pc + 8 > program.len() {
61                    return Err("Unexpected EOF in OP_MATCH_SUBJ");
62                }
63                let target_hash = u64::from_le_bytes(program[pc..pc + 8].try_into().unwrap());
64                pc += 8;
65                candidate_set.retain(|quin| quin.subject == target_hash);
66            }
67            OP_MATCH_PRED => {
68                if pc + 8 > program.len() {
69                    return Err("Unexpected EOF in OP_MATCH_PRED");
70                }
71                let target_hash = u64::from_le_bytes(program[pc..pc + 8].try_into().unwrap());
72                pc += 8;
73                candidate_set.retain(|quin| quin.predicate == target_hash);
74            }
75            OP_MATCH_OBJ => {
76                if pc + 8 > program.len() {
77                    return Err("Unexpected EOF in OP_MATCH_OBJ");
78                }
79                let target_hash = u64::from_le_bytes(program[pc..pc + 8].try_into().unwrap());
80                pc += 8;
81                candidate_set.retain(|quin| quin.object == target_hash);
82            }
83            OP_BIND_VAR => {
84                if pc + 2 > program.len() {
85                    return Err("Unexpected EOF in OP_BIND_VAR");
86                }
87                let slot = program[pc];
88                let reg_id = program[pc + 1];
89                pc += 2;
90                if let Some(q) = candidate_set.first() {
91                    let value = match slot {
92                        SLOT_SUBJ => q.subject,
93                        SLOT_PRED => q.predicate,
94                        SLOT_OBJ => q.object,
95                        _ => return Err("Invalid slot identifier"),
96                    };
97                    registers.bind(reg_id, value);
98                }
99            }
100            OP_HALT => break,
101            _ => return Err("Unknown Opcode"),
102        }
103    }
104
105    let mut results = Vec::new();
106    for i in 0..16 {
107        if registers.bound_flags & (1 << i) != 0 {
108            results.push(registers.values[i]);
109        }
110    }
111    Ok(results)
112}
113
114// ── Rule types ────────────────────────────────────────────────────────────────
115
116/// Unique identifier for a [`WebRule`].
117pub type WebRuleId = u64;
118
119/// Classification of a [`WebRule`].
120#[derive(Debug, Clone, Copy, PartialEq, Eq)]
121pub enum WebRuleType {
122    Shape,
123    Confidence,
124    Domain,
125    Structural,
126}
127
128/// A validation rule applied by the [`WebValidator`] to incoming NQuins.
129#[repr(C)]
130#[derive(Debug, Clone)]
131pub struct WebRule {
132    pub rule_id: WebRuleId,
133    pub rule_type: WebRuleType,
134    /// Context this rule applies to; `0` means all contexts.
135    pub context_id: u64,
136    /// Predicate this rule applies to; `0` means all predicates.
137    pub predicate_hash: u64,
138    pub min_confidence: f32,
139    pub required_domain: u64,
140}
141
142impl WebRule {
143    /// A rule matching all contexts and predicates with no confidence
144    /// floor or domain requirement — narrow it with the `with_*`
145    /// builders.
146    pub fn new(rule_id: WebRuleId, rule_type: WebRuleType) -> Self {
147        Self {
148            rule_id,
149            rule_type,
150            context_id: 0,
151            predicate_hash: 0,
152            min_confidence: 0.0,
153            required_domain: 0,
154        }
155    }
156
157    /// Restrict the rule to a single context (`0` keeps it global).
158    pub fn with_context(mut self, context_id: u64) -> Self {
159        self.context_id = context_id;
160        self
161    }
162
163    /// Restrict the rule to a single predicate hash (`0` matches all).
164    pub fn with_predicate(mut self, predicate_hash: u64) -> Self {
165        self.predicate_hash = predicate_hash;
166        self
167    }
168
169    /// Set the minimum confidence a quin must carry for this rule.
170    pub fn with_confidence(mut self, min_confidence: f32) -> Self {
171        self.min_confidence = min_confidence;
172        self
173    }
174
175    /// Require quins to carry domain `required_domain` for this rule.
176    pub fn with_domain(mut self, required_domain: u64) -> Self {
177        self.required_domain = required_domain;
178        self
179    }
180}
181
182/// Outcome of a [`WebValidator::validate`] call.
183#[derive(Debug, Clone, PartialEq, Eq)]
184pub enum WebVerdict {
185    Pass,
186    Fail(String),
187    PassWithWarning(String),
188}
189
190// ── Validator ─────────────────────────────────────────────────────────────────
191
192/// Validates NQuins against a set of [`WebRule`]s before Q42 append.
193pub struct WebValidator {
194    rules: Vec<WebRule>,
195    active_rule_ids: HashSet<WebRuleId>,
196    confidence_threshold: f32,
197}
198
199impl WebValidator {
200    /// Create an empty validator with the default 0.5 confidence
201    /// threshold — `needs_validation` returns false until rules are
202    /// added.
203    pub fn new() -> Self {
204        Self {
205            rules: Vec::new(),
206            active_rule_ids: HashSet::new(),
207            confidence_threshold: 0.5,
208        }
209    }
210
211    /// Override the global confidence floor applied during validation.
212    pub fn set_confidence_threshold(&mut self, threshold: f32) {
213        self.confidence_threshold = threshold;
214    }
215
216    /// Register `rule` and mark its id active for validation.
217    pub fn add_rule(&mut self, rule: WebRule) {
218        self.active_rule_ids.insert(rule.rule_id);
219        self.rules.push(rule);
220    }
221
222    /// Returns `false` when no rules apply, allowing the fast-path to the Q42
223    /// append buffer without invoking the full validator.
224    pub fn needs_validation(&self, quin: &NQuin) -> bool {
225        for rule in &self.rules {
226            if rule.context_id == 0 || rule.context_id == quin.context {
227                if rule.predicate_hash == 0 || rule.predicate_hash == quin.predicate {
228                    return true;
229                }
230            }
231        }
232        false
233    }
234
235    /// Validate a NQuin against all active rules.
236    pub fn validate(&self, quin: &NQuin) -> WebVerdict {
237        let confidence = (quin.metadata & 0xFFFFFFFF) as f32 / u32::MAX as f32;
238
239        if confidence < self.confidence_threshold {
240            return WebVerdict::Fail(format!(
241                "Confidence {} below threshold {}",
242                confidence, self.confidence_threshold
243            ));
244        }
245
246        for rule in &self.rules {
247            if rule.context_id != 0 && rule.context_id != quin.context {
248                continue;
249            }
250            if rule.predicate_hash != 0 && rule.predicate_hash != quin.predicate {
251                continue;
252            }
253
254            match rule.rule_type {
255                WebRuleType::Confidence => {
256                    if confidence < rule.min_confidence {
257                        return WebVerdict::Fail(format!(
258                            "Confidence {} below rule threshold {}",
259                            confidence, rule.min_confidence
260                        ));
261                    }
262                }
263                WebRuleType::Domain => {
264                    if rule.required_domain != 0 && quin.subject != rule.required_domain {
265                        return WebVerdict::Fail("Subject not in required domain".to_string());
266                    }
267                }
268                WebRuleType::Shape | WebRuleType::Structural => {}
269            }
270        }
271
272        WebVerdict::Pass
273    }
274
275    /// Validate an embedded triple (Virtual ID).
276    pub fn validate_embedded_triple(
277        &self,
278        virtual_id: u64,
279        components: &[u64; 3],
280        context_id: u64,
281    ) -> WebVerdict {
282        const TAG_EMBEDDED: u64 = 0x1;
283
284        if virtual_id & TAG_EMBEDDED != TAG_EMBEDDED {
285            return WebVerdict::Fail("Not a Virtual ID".to_string());
286        }
287
288        for rule in &self.rules {
289            if rule.context_id == 0 || rule.context_id == context_id {
290                if let WebRuleType::Structural = rule.rule_type {
291                    if components[0] == 0 || components[1] == 0 || components[2] == 0 {
292                        return WebVerdict::Fail("Embedded triple has zero component".to_string());
293                    }
294                }
295            }
296        }
297
298        WebVerdict::Pass
299    }
300}
301
302impl Default for WebValidator {
303    /// Equivalent to [`WebValidator::new`].
304    fn default() -> Self {
305        Self::new()
306    }
307}
308
309// ── Q42 storage ───────────────────────────────────────────────────────────────
310
311/// Serialises and deserialises [`WebRule`]s to/from NQuin blocks in Q42.
312#[repr(C)]
313#[derive(Debug, Clone)]
314pub struct WebRuleStorage {
315    pub block_id: u64,
316    pub rule_count: u32,
317    pub reserved: u32,
318}
319
320impl WebRuleStorage {
321    const RULE_FLAG: u64 = 0x1 << 62;
322
323    /// Pack each rule into one `NQuin`: `subject` = rule id, `predicate`
324    /// = type tag (high byte) | context low byte, `object` = predicate
325    /// hash, `context` = context id, `metadata` = `RULE_FLAG` |
326    /// confidence bits | domain in the high 32. Parity left 0 — storage
327    /// blocks are verified by flag, not fold.
328    pub fn rules_to_quins(rules: &[WebRule]) -> Vec<NQuin> {
329        rules
330            .iter()
331            .map(|rule| NQuin {
332                subject: rule.rule_id,
333                predicate: (rule.rule_type as u64) << 8 | (rule.context_id & 0xFF),
334                object: rule.predicate_hash,
335                context: rule.context_id,
336                metadata: Self::RULE_FLAG
337                    | ((rule.min_confidence as u64) & 0xFFFFFFFF)
338                    | (rule.required_domain << 32),
339                parity: 0,
340            })
341            .collect()
342    }
343
344    /// Recover rules from quins carrying `RULE_FLAG` in metadata;
345    /// non-rule quins are skipped. Confidence is stored as a `u32`
346    /// fraction (`bits / u32::MAX`) so round-trips lose raw `f32`
347    /// precision — callers needing exact values should re-set them.
348    pub fn quins_to_rules(quins: &[NQuin]) -> Vec<WebRule> {
349        quins
350            .iter()
351            .filter(|q| q.metadata & Self::RULE_FLAG != 0)
352            .map(|q| {
353                let rule_type = match (q.predicate >> 8) % 4 {
354                    0 => WebRuleType::Shape,
355                    1 => WebRuleType::Confidence,
356                    2 => WebRuleType::Domain,
357                    _ => WebRuleType::Structural,
358                };
359                WebRule {
360                    rule_id: q.subject,
361                    rule_type,
362                    context_id: q.context,
363                    predicate_hash: q.object,
364                    min_confidence: (q.metadata & 0xFFFFFFFF) as f32 / u32::MAX as f32,
365                    required_domain: (q.metadata >> 32) & 0x0FFF_FFFF,
366                }
367            })
368            .collect()
369    }
370}
371
372#[cfg(test)]
373mod tests {
374    use super::*;
375
376    #[test]
377    fn rule_creation() {
378        let rule = WebRule::new(123, WebRuleType::Confidence).with_confidence(0.8);
379        assert_eq!(rule.rule_id, 123);
380        assert_eq!(rule.min_confidence, 0.8);
381    }
382
383    #[test]
384    fn validator_no_rules_needs_no_validation() {
385        let validator = WebValidator::new();
386        assert!(!validator.needs_validation(&NQuin {
387            subject: 1,
388            predicate: 2,
389            object: 3,
390            context: 0,
391            metadata: 0,
392            parity: 0
393        }));
394    }
395
396    #[test]
397    fn validator_add_rule_triggers_needs_validation() {
398        let mut validator = WebValidator::new();
399        let rule = WebRule::new(123, WebRuleType::Confidence)
400            .with_predicate(456)
401            .with_context(789);
402        validator.add_rule(rule);
403        let quin = NQuin {
404            subject: 1,
405            predicate: 456,
406            object: 3,
407            context: 789,
408            metadata: 0,
409            parity: 0,
410        };
411        assert!(validator.needs_validation(&quin));
412    }
413
414    #[test]
415    fn validate_pass_high_confidence() {
416        let mut validator = WebValidator::new();
417        validator.set_confidence_threshold(0.5);
418        let quin = NQuin {
419            subject: 1,
420            predicate: 2,
421            object: 3,
422            context: 0,
423            metadata: u32::MAX as u64,
424            parity: 0,
425        };
426        assert_eq!(validator.validate(&quin), WebVerdict::Pass);
427    }
428
429    #[test]
430    fn validate_fail_zero_confidence() {
431        let mut validator = WebValidator::new();
432        validator.set_confidence_threshold(0.5);
433        let quin = NQuin {
434            subject: 1,
435            predicate: 2,
436            object: 3,
437            context: 0,
438            metadata: 0,
439            parity: 0,
440        };
441        assert!(matches!(validator.validate(&quin), WebVerdict::Fail(_)));
442    }
443
444    #[test]
445    fn validate_embedded_triple_pass() {
446        let validator = WebValidator::new();
447        let virtual_id = 0x1 | 0x123456789ABCDEF0;
448        let components = [1u64, 2, 3];
449        assert_eq!(
450            validator.validate_embedded_triple(virtual_id, &components, 0),
451            WebVerdict::Pass
452        );
453    }
454
455    #[test]
456    fn storage_round_trip() {
457        let rules = vec![
458            WebRule::new(123, WebRuleType::Confidence).with_confidence(0.8),
459            WebRule::new(456, WebRuleType::Domain).with_domain(789),
460        ];
461        let quins = WebRuleStorage::rules_to_quins(&rules);
462        assert_eq!(quins.len(), 2);
463        let back = WebRuleStorage::quins_to_rules(&quins);
464        assert_eq!(back.len(), 2);
465    }
466
467    #[test]
468    fn execute_query_program_bind_var() {
469        let quin = NQuin {
470            subject: 0xAABB,
471            predicate: 0xCCDD,
472            object: 0xEEFF,
473            context: 0,
474            metadata: 0,
475            parity: 0,
476        };
477        // MATCH_SUBJ 0xAABB, then BIND_VAR slot=OBJ reg=0, HALT
478        let mut program = vec![OP_MATCH_SUBJ];
479        program.extend_from_slice(&0xAABBu64.to_le_bytes());
480        program.extend_from_slice(&[OP_BIND_VAR, SLOT_OBJ, 0, OP_HALT]);
481        let results = execute_query_program(&program, &[quin]).unwrap();
482        assert_eq!(results, vec![0xEEFF]);
483    }
484}