Skip to main content

qualia_core_db/inference/
orchestrator.rs

1//! The Orchestration Sieve — LLM Sub-Agent Dispatch Layer
2//!
3//! Sits between raw input (multi-modal data, user prompts) and the Webizen VM.
4//! Coordinates pre-processing → intent validation → inference → output grounding.
5//!
6//! Flow:
7//!   RawInput → `Orchestrator` → validate_intent → [LlmAgent.infer] → validate_output → .q42 commit
8
9use crate::llm_agent::{AgentIntent, AgentRuntime, LocalLlmAgent, WebizenVerdict};
10use crate::modalities::logic::n3_compiler::{
11    compile_rules_with_shacl_gate, default_observation_shape, N3OutputMode,
12};
13use crate::modalities::logic::n3_parser::{N3Event, N3Parser};
14use crate::modalities::logic::shacl::{
15    CompiledShape, ShaclCompiler, ShaclConstraint, ShaclSeverity,
16};
17use crate::solvers::grounding::{
18    evaluate_output_grounding, GroundingResolver, GroundingThresholds, GroundingVerdict,
19};
20#[cfg(not(target_arch = "wasm32"))]
21use crate::wal::{commit_semantic_mutation, WalHandoffResult, WriteAheadLog};
22use crate::webizen::{SlgArena, SlgOpcode, VmFrame};
23use crate::{q_hash, NQuin};
24use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
25use std::sync::Arc;
26use std::thread;
27
28#[derive(Debug, Clone, Copy, PartialEq, Eq)]
29pub enum ModelLifecycle {
30    Discovered,
31    MappedToDisk,
32    StreamingVRAM,
33    Active,
34    Scrubbing,
35}
36
37/// The outcome of a full orchestrated inference cycle.
38#[derive(Debug)]
39pub enum OrchestrationResult {
40    /// Output was validated, grounded, and ready to commit to the semantic graph.
41    Committed {
42        text: String,
43        provenance_quins: Vec<u64>,
44        semantic_quin: Option<NQuin>,
45        wal_committed: bool,
46        wal_suspended: bool,
47        suspended_agreement_id: Option<u64>,
48    },
49    /// Webizen blocked the operation at pre-flight or post-flight.
50    Blocked {
51        rule_violated: u64,
52        reason: &'static str,
53    },
54    /// Inference failed (timeout, backend unavailable, etc.)
55    Failed(String),
56}
57
58#[derive(Debug, Clone, Copy, PartialEq, Eq)]
59pub enum ThermalStatus {
60    /// Normal operating temperatures. Full 3-Core Triad utilization.
61    Cool,
62    /// Elevated temperatures. Restrict non-essential parallelism and heavy sieving.
63    Warm,
64    /// Critical temperatures. Pause background ingestion/indexing, throttle to critical-path single-thread only.
65    Critical,
66}
67
68pub trait ThermalGovernor: Send + Sync {
69    /// Returns the current thermal state of the host device.
70    fn get_thermal_state(&self) -> ThermalStatus;
71
72    /// Optional hook for the governor to self-adjust or log transitions.
73    fn adjust_policy(&self, status: ThermalStatus) {
74        let _ = status; // Default no-op
75    }
76}
77
78pub struct NullThermalGovernor;
79impl ThermalGovernor for NullThermalGovernor {
80    /// Always-`Cool` governor (thermal checks disabled).
81    fn get_thermal_state(&self) -> ThermalStatus {
82        ThermalStatus::Cool
83    }
84}
85
86use crate::solvers::calculus::{ODEFunction, RungeKutta4Static};
87use crate::solvers::SolverConfig;
88
89struct NewtonCoolingODE {
90    ambient_temp: f64,
91    cooling_constant: f64,
92    power_input: f64,
93}
94
95impl ODEFunction for NewtonCoolingODE {
96    /// ODE right-hand side for the thermal model (load + ambient
97    /// cooling terms).
98    fn derivatives(&self, _t: f64, y: &[f64; 4]) -> [f64; 4] {
99        let temp = y[0];
100        let dt_dt = -self.cooling_constant * (temp - self.ambient_temp) + self.power_input;
101        [dt_dt, 0.0, 0.0, 0.0]
102    }
103}
104
105pub struct CalculusThermalGovernor {
106    current_temp: std::sync::Mutex<f64>,
107}
108
109impl CalculusThermalGovernor {
110    /// Governor seeded at `initial_temp` °C.
111    pub fn new(initial_temp: f64) -> Self {
112        Self {
113            current_temp: std::sync::Mutex::new(initial_temp),
114        }
115    }
116}
117
118impl ThermalGovernor for CalculusThermalGovernor {
119    /// Thermal status after advancing the Newton-cooling ODE one
120    /// RK4 step from the last temperature.
121    fn get_thermal_state(&self) -> ThermalStatus {
122        let mut temp = self.current_temp.lock().unwrap();
123
124        let ode = NewtonCoolingODE {
125            ambient_temp: 25.0,
126            cooling_constant: 0.1,
127            power_input: 5.0, // Represents current SoC TDP
128        };
129
130        let mut solver = RungeKutta4Static::new(0.1, SolverConfig::default());
131        let final_state = solver
132            .integrate(&ode, 0.0, [*temp, 0.0, 0.0, 0.0], 1.0)
133            .unwrap();
134
135        *temp = final_state.y[0];
136
137        if *temp > 85.0 {
138            ThermalStatus::Critical
139        } else if *temp > 65.0 {
140            ThermalStatus::Warm
141        } else {
142            ThermalStatus::Cool
143        }
144    }
145}
146
147pub struct TaskOrchestrator {
148    thermal_governor: Box<dyn ThermalGovernor>,
149    pub current_model_state: Arc<std::sync::Mutex<ModelLifecycle>>,
150    pub current_model_id: Arc<std::sync::Mutex<Option<u64>>>,
151    pub resident_memory_bytes: Arc<AtomicU64>,
152    pub scrubbing_lock: Arc<AtomicBool>,
153    pub mlock_enabled: Arc<AtomicBool>,
154}
155
156impl TaskOrchestrator {
157    /// Compiled shapes this intent routes to.
158    fn routed_shapes(intent: &AgentIntent) -> Vec<CompiledShape> {
159        let compiler = ShaclCompiler::new();
160        let mut shapes = Vec::new();
161
162        let has_namespace = |needles: &[&str]| {
163            needles.iter().any(|needle| {
164                let hash = q_hash(needle);
165                intent.context_namespaces.iter().any(|ns| *ns == hash)
166            })
167        };
168
169        if has_namespace(&[
170            "health", "medical", "clinical", "fhir", "loinc", "snomed", "anatomy",
171        ]) {
172            shapes.push(default_observation_shape());
173            shapes.push(compiler.compile_class(
174                "fhir:Observation",
175                "health:heartRate",
176                ShaclConstraint::MinInclusive(20.0),
177                ShaclSeverity::Violation,
178            ));
179        }
180
181        if has_namespace(&[
182            "legal",
183            "law",
184            "contract",
185            "guardian",
186            "guardianship",
187            "rights",
188            "agreement",
189            "consent",
190        ]) {
191            shapes.push(compiler.compile_class(
192                "q42:Agreement",
193                "q42:hasGuardian",
194                ShaclConstraint::MinCount(1),
195                ShaclSeverity::Violation,
196            ));
197            shapes.push(compiler.compile_class(
198                "q42:Agreement",
199                "q42:requiresConsensus",
200                ShaclConstraint::MinCount(1),
201                ShaclSeverity::Violation,
202            ));
203        }
204
205        if has_namespace(&["commons", "governance", "community"]) {
206            shapes.push(compiler.compile_class(
207                "q42:CommonsAgreement",
208                "q42:hasDomainScope",
209                ShaclConstraint::MinCount(1),
210                ShaclSeverity::Violation,
211            ));
212        }
213
214        // CogAI agent shapes — always active for any inference intent.
215        // Validates cog:Agent identity, cog:Goal alignment, and inference authorization.
216        shapes.push(compiler.compile_class(
217            "cog:Agent",
218            "cog:agentID",
219            ShaclConstraint::MinCount(1),
220            ShaclSeverity::Violation,
221        ));
222        shapes.push(compiler.compile_class(
223            "q42:InferenceIntent",
224            "q42:inferenceAuthorizedBy",
225            ShaclConstraint::MinCount(1),
226            ShaclSeverity::Violation,
227        ));
228        shapes.push(compiler.compile_class(
229            "q42:InferenceIntent",
230            "q42:provenanceCitations",
231            ShaclConstraint::MinInclusive(1.0),
232            ShaclSeverity::Warning,
233        ));
234
235        if shapes.is_empty() {
236            shapes.push(default_observation_shape());
237        }
238        shapes
239    }
240
241    /// Orchestrator driven by `thermal_governor`.
242    pub fn new(thermal_governor: Box<dyn ThermalGovernor>) -> Self {
243        Self {
244            thermal_governor,
245            current_model_state: Arc::new(std::sync::Mutex::new(ModelLifecycle::Discovered)),
246            current_model_id: Arc::new(std::sync::Mutex::new(None)),
247            resident_memory_bytes: Arc::new(AtomicU64::new(0)),
248            scrubbing_lock: Arc::new(AtomicBool::new(false)),
249            mlock_enabled: Arc::new(AtomicBool::new(false)),
250        }
251    }
252
253    /// Human-readable label for the current thermal state.
254    pub fn thermal_state_label(&self) -> &'static str {
255        match self.thermal_governor.get_thermal_state() {
256            ThermalStatus::Cool => "Cool",
257            ThermalStatus::Warm => "Warm",
258            ThermalStatus::Critical => "Critical",
259        }
260    }
261
262    /// Currently resident model id, if any.
263    pub fn resident_model_id(&self) -> Option<u64> {
264        *self.current_model_id.lock().unwrap()
265    }
266
267    /// Bytes held by the resident model.
268    pub fn resident_memory_bytes(&self) -> u64 {
269        self.resident_memory_bytes.load(Ordering::Relaxed)
270    }
271
272    /// Record `model_id`/`bytes` as resident (ledger only — the
273    /// caller owns actual loading).
274    pub fn register_resident_model(&self, model_id: u64, bytes: u64) {
275        *self.current_model_id.lock().unwrap() = Some(model_id);
276        self.resident_memory_bytes.store(bytes, Ordering::Relaxed);
277    }
278
279    /// Load `model_id` through `agent` when not already resident;
280    /// evicts the current model first if needed.
281    pub fn load_model(&self, agent: &LocalLlmAgent, model_id: u64) -> Result<(), &'static str> {
282        if self.scrubbing_lock.load(Ordering::Acquire) {
283            return Err("Cannot load model: Swarm Worker is actively scrubbing memory arena");
284        }
285        if let Some(active_model) = self.resident_model_id() {
286            if active_model != model_id {
287                return Err("Cannot load model: another model is still resident; evict it first");
288            }
289        }
290
291        let mut state = self.current_model_state.lock().unwrap();
292        *state = ModelLifecycle::MappedToDisk;
293        *state = ModelLifecycle::StreamingVRAM;
294        *state = ModelLifecycle::Active;
295        drop(state);
296        *self.current_model_id.lock().unwrap() = Some(model_id);
297
298        // Prefer the unified schema.org volume (embedded Q42LEX). Legacy
299        // `.q42.lex` sidecar remains a fallback until sidecars are gone.
300        let schema_q42 = "data/schemaorg/30.0/schemaorg-current-https.q42";
301        let schema_lex = "data/schemaorg/30.0/schemaorg-current-https.q42.lex";
302        if std::path::Path::new(schema_q42).exists() {
303            agent.configure_sieve_lex(schema_q42);
304        } else if std::path::Path::new(schema_lex).exists() {
305            agent.configure_sieve_lex(schema_lex);
306        } else if let crate::llm_agent::AgentBackend::Local { model_path, .. } = &agent.backend {
307            let mut p = std::path::PathBuf::from(model_path);
308            if let Some(stem) = p.file_stem().and_then(|s| s.to_str()).map(str::to_string) {
309                p.set_file_name(format!("{stem}.q42.lex"));
310                if p.exists() {
311                    agent.configure_sieve_lex(p.to_string_lossy().into_owned());
312                }
313            }
314        }
315        Ok(())
316    }
317
318    /// Evict `model_id` from the residency ledger.
319    pub fn evict_model(&self, model_id: u64) {
320        let resident = self.resident_model_id();
321        if resident.is_none() {
322            self.resident_memory_bytes.store(0, Ordering::Relaxed);
323            if let Ok(mut st) = self.current_model_state.lock() {
324                *st = ModelLifecycle::Discovered;
325            }
326            return;
327        }
328        if resident != Some(model_id) {
329            return;
330        }
331
332        if let Ok(mut state) = self.current_model_state.lock() {
333            *state = ModelLifecycle::Scrubbing;
334        }
335
336        self.scrubbing_lock.store(true, Ordering::Release);
337        let scrub_bytes = self.resident_memory_bytes.swap(0, Ordering::Relaxed);
338
339        let lock_clone = self.scrubbing_lock.clone();
340        let state_clone = self.current_model_state.clone();
341        let model_clone = self.current_model_id.clone();
342
343        // Asynchronous scrubbing over a fixed stack buffer keeps the sweep deterministic and heap-free.
344        thread::spawn(move || {
345            let mut scrub_block = [0u8; 4096];
346            let mut remaining = scrub_bytes.max(scrub_block.len() as u64);
347            while remaining > 0 {
348                let write_len = remaining.min(scrub_block.len() as u64) as usize;
349                for byte in scrub_block.iter_mut().take(write_len) {
350                    unsafe { std::ptr::write_volatile(byte, 0) };
351                }
352                remaining = remaining.saturating_sub(write_len as u64);
353                if remaining > 0 {
354                    std::thread::yield_now();
355                }
356            }
357
358            // Release the cryptographic lock and revert state
359            lock_clone.store(false, Ordering::Release);
360            if let Ok(mut model) = model_clone.lock() {
361                *model = None;
362            }
363            if let Ok(mut st) = state_clone.lock() {
364                *st = ModelLifecycle::Discovered;
365            }
366            crate::resident_model::clear_resident_model();
367        });
368    }
369
370    /// Parse LLM-emitted N3, validate via SHACL compiler, and execute on the Sentinel VM.
371    fn gate_llm_n3_output(
372        text: &str,
373        contract_hash: u64,
374        intent: &AgentIntent,
375    ) -> Result<(), &'static str> {
376        let mut rules = Vec::new();
377        let mut parser = N3Parser::new(text);
378        parser
379            .parse_all(|event| {
380                if let N3Event::LogicRule(rule) = event {
381                    rules.push(rule);
382                }
383                Ok(())
384            })
385            .map_err(|_| "Invalid N3 output from LLM")?;
386
387        if rules.is_empty() {
388            return Err("LLM did not emit parseable N3 assertions");
389        }
390
391        let routed_shapes = Self::routed_shapes(intent);
392        let shapes: Vec<&CompiledShape> = routed_shapes.iter().collect();
393        let mut opcodes = [SlgOpcode::Call; 256];
394        let mut quins = [crate::NQuin::default(); 64];
395        // The gate validates each Rule against the routed SHACL shapes (fail closed),
396        // then compiles internally — pass the parsed rules directly.
397        let program =
398            compile_rules_with_shacl_gate(&rules, &shapes, &mut opcodes, &mut quins, contract_hash)
399                .map_err(|_| "SHACL validation failed for LLM N3 output")?;
400
401        let mut arena = SlgArena::new();
402        let mut frame = VmFrame::default();
403        let _ = crate::modalities::logic::n3_compiler::execute_compiled_program(
404            &mut arena,
405            &opcodes[..program.opcode_count],
406            &mut frame,
407            32,
408        )
409        .map_err(|_| "Sentinel VM memory overflow")?;
410        Ok(())
411    }
412
413    /// Runs a full, Webizen-gated inference cycle for a registered LLM sub-agent.
414    ///
415    /// This is the citation-presence gate (no grounding resolver). For the deeper
416    /// gate that verifies the claim is *supported* by its cited facts, use
417    /// [`Self::orchestrate_inference_grounded`].
418    pub fn orchestrate_inference(
419        &self,
420        agent: &dyn AgentRuntime,
421        prompt: &str,
422        graph_context: &str,
423        intent: AgentIntent,
424        suspended: Option<&mut crate::crdt::SuspendedTransactionQueue>,
425    ) -> OrchestrationResult {
426        self.orchestrate_inference_inner(agent, prompt, graph_context, intent, suspended, None)
427    }
428
429    /// Like [`Self::orchestrate_inference`], but adds the KG↔LLM **grounding gate** to
430    /// the post-flight: the model's structured claim is graded against its *resolved*
431    /// cited facts. A weakly-grounded claim is routed to human review (blocked, not
432    /// committed); an ungrounded one is blocked outright. Both happen **before** the
433    /// WAL commit, so an unsupported claim never reaches the graph.
434    pub fn orchestrate_inference_grounded(
435        &self,
436        agent: &dyn AgentRuntime,
437        prompt: &str,
438        graph_context: &str,
439        intent: AgentIntent,
440        suspended: Option<&mut crate::crdt::SuspendedTransactionQueue>,
441        resolver: &dyn GroundingResolver,
442        thresholds: GroundingThresholds,
443    ) -> OrchestrationResult {
444        self.orchestrate_inference_inner(
445            agent,
446            prompt,
447            graph_context,
448            intent,
449            suspended,
450            Some((resolver, thresholds)),
451        )
452    }
453
454    /// Core inference orchestration: intent validation, sanctuary
455    /// and thermal gates, resident-model load, grounding gate, then
456    /// agent inference.
457    fn orchestrate_inference_inner(
458        &self,
459        agent: &dyn AgentRuntime,
460        prompt: &str,
461        graph_context: &str,
462        intent: AgentIntent,
463        suspended: Option<&mut crate::crdt::SuspendedTransactionQueue>,
464        grounding: Option<(&dyn GroundingResolver, GroundingThresholds)>,
465    ) -> OrchestrationResult {
466        let thermal_state = self.thermal_governor.get_thermal_state();
467
468        match thermal_state {
469            ThermalStatus::Critical => {
470                if !intent.is_critical() {
471                    return OrchestrationResult::Blocked {
472                        rule_violated: 0xDEADBEEF, // Mock constant for Thermal Block
473                        reason: "Device critical thermal state. Non-essential inference paused.",
474                    };
475                }
476            }
477            ThermalStatus::Warm => {
478                // Future extension: dampened logic
479            }
480            ThermalStatus::Cool => {}
481        }
482
483        // 1. Pre-flight: validate intent against Rights Ontology
484        match agent.validate_intent(&intent) {
485            WebizenVerdict::Deny {
486                rule_violated,
487                reason,
488                conduct_record,
489            } => {
490                // If the verdict contains a conduct violation Quin, propagate it to the immutable ledger
491                #[cfg(not(target_arch = "wasm32"))]
492                if let Some(quin) = conduct_record {
493                    if let Ok(mut wal) = crate::wal::WriteAheadLog::open(".qualia_conduct.wal") {
494                        let _ = wal.append_mutation(&quin);
495
496                        // Cryptographic signing pipeline (using a static key for demonstration of wiring)
497                        let secret = [42u8; 32];
498                        let signing_key = ed25519_dalek::SigningKey::from_bytes(&secret);
499                        let frame = [quin];
500                        let sub_root = crate::agency::compute_scoped_merkle_root(
501                            &frame,
502                            intent.principal_did_hash,
503                        );
504                        let _signature = crate::agency::sign_agency_root(&signing_key, &sub_root);
505
506                        // In production, the signature and quin would be passed to SuperBlockWriter
507                    }
508                }
509                #[cfg(target_arch = "wasm32")]
510                let _ = conduct_record;
511                return OrchestrationResult::Blocked {
512                    rule_violated,
513                    reason,
514                };
515            }
516            WebizenVerdict::DenyWithExplanation {
517                rule_violated,
518                reason: _,
519                explanation: _,
520            } => {
521                // Return blocked with the detailed explanation
522                return OrchestrationResult::Blocked {
523                    rule_violated,
524                    reason: "Intent Frame Violation",
525                };
526            }
527            WebizenVerdict::RequireReconfirmation { reason: _ } => {
528                return OrchestrationResult::Blocked {
529                    rule_violated: 0,
530                    reason: "Reconfirmation required",
531                };
532            }
533            WebizenVerdict::Sanitised { .. } => { /* intent was scrubbed; proceed with caution */ }
534            WebizenVerdict::Permit => {}
535        }
536
537        // 1b. Quantum egress gate — block classified prompts from remote QPU
538        if let Some(reason) = crate::modalities::logic::qubo::quantum_prompt_gate(prompt) {
539            return OrchestrationResult::Blocked {
540                rule_violated: crate::q_hash("q42:QuantumTaskShape"),
541                reason,
542            };
543        }
544
545        // 1c. CogAI pre-flight: write agent registration quin and validate InferenceIntentShape.
546        // The `register_agent` quin is written to AGENT_CONTEXT so downstream SPARQL queries
547        // can resolve cog:Agent identity without re-deriving it from the principal DID.
548        {
549            use crate::temporal_graph::register_agent;
550            let _agent_quin = register_agent(intent.principal_did_hash, 0);
551            // Future: append _agent_quin to the per-request provenance accumulator.
552        }
553
554        // 2. Inference
555        let output = match agent.infer(prompt, graph_context) {
556            Ok(o) => o,
557            Err(e) => return OrchestrationResult::Failed(format!("{:?}", e)),
558        };
559
560        // 2b. Optional CogAI symbolic path: compile LLM-emitted N3 through SHACL → bytecode.
561        // Skipped when the neuro-symbolic sieve already emitted a structured Quin.
562        if output.semantic_quin.is_none()
563            && (intent.output_mode == N3OutputMode::N3Assertions
564                || intent.output_mode == N3OutputMode::GraphMutation)
565        {
566            if let Err(reason) =
567                Self::gate_llm_n3_output(&output.text, intent.principal_did_hash, &intent)
568            {
569                return OrchestrationResult::Blocked {
570                    rule_violated: crate::q_hash("q42:N3Compiler"),
571                    reason,
572                };
573            }
574        }
575
576        // 3. Post-flight: validate output grounding
577        match agent.validate_output(&output) {
578            WebizenVerdict::Deny {
579                rule_violated,
580                reason,
581                conduct_record,
582            } => {
583                #[cfg(not(target_arch = "wasm32"))]
584                if let Some(quin) = conduct_record {
585                    if let Ok(mut wal) = crate::wal::WriteAheadLog::open(".qualia_conduct.wal") {
586                        let _ = wal.append_mutation(&quin);
587                    }
588                }
589                #[cfg(target_arch = "wasm32")]
590                let _ = conduct_record;
591                return OrchestrationResult::Blocked {
592                    rule_violated,
593                    reason,
594                };
595            }
596            WebizenVerdict::DenyWithExplanation {
597                rule_violated,
598                reason: _,
599                explanation: _,
600            } => {
601                return OrchestrationResult::Blocked {
602                    rule_violated,
603                    reason: "Output blocked due to frame bounds",
604                };
605            }
606            WebizenVerdict::RequireReconfirmation { reason: _ } => {
607                return OrchestrationResult::Blocked {
608                    rule_violated: 0,
609                    reason: "Output requires reconfirmation",
610                };
611            }
612            _ => {}
613        }
614
615        // 3b. Grounding gate (optional): when a fact resolver is supplied and the
616        // output carries a structured claim, verify the claim is actually *supported*
617        // by its cited facts — not merely that a citation exists. Fail closed: an
618        // ungrounded claim is blocked; a partially-grounded one is routed to human
619        // review. Runs before any WAL commit, so unsupported claims never persist.
620        if let (Some((resolver, thresholds)), Some(claim)) =
621            (grounding, output.semantic_quin.as_ref())
622        {
623            match evaluate_output_grounding(claim, &output.provenance_quins, resolver, thresholds) {
624                GroundingVerdict::Grounded { .. } => {}
625                GroundingVerdict::Weak { .. } => {
626                    return OrchestrationResult::Blocked {
627                        rule_violated: q_hash("q42:GroundingRequiresReview"),
628                        reason: "Claim only partially grounded in its cited facts — requires human review before commit.",
629                    };
630                }
631                GroundingVerdict::Ungrounded { .. } => {
632                    return OrchestrationResult::Blocked {
633                        rule_violated: q_hash("q42:GroundingRequired"),
634                        reason:
635                            "Claim does not trace to its cited facts (ungrounded). Cannot commit.",
636                    };
637                }
638            }
639        }
640
641        #[cfg(not(target_arch = "wasm32"))]
642        let mut semantic_quin = output.semantic_quin;
643        #[cfg(not(target_arch = "wasm32"))]
644        let mut wal_written = false;
645        #[cfg(not(target_arch = "wasm32"))]
646        let mut wal_suspended = false;
647        #[cfg(not(target_arch = "wasm32"))]
648        let mut suspended_agreement_id = None;
649
650        #[cfg(target_arch = "wasm32")]
651        let semantic_quin = output.semantic_quin;
652        #[cfg(target_arch = "wasm32")]
653        let (wal_written, wal_suspended, suspended_agreement_id) = {
654            if suspended.is_some() {
655                log::debug!(
656                    "WASM orchestration received a suspended queue; persistence remains delegated to the host"
657                );
658            }
659            (false, false, None)
660        };
661
662        #[cfg(not(target_arch = "wasm32"))]
663        if let Some(ref mut quin) = semantic_quin {
664            if let Ok(mut wal) = WriteAheadLog::open(".qualia_graph_mutations.wal") {
665                let secret = [42u8; 32];
666                let signing_key = ed25519_dalek::SigningKey::from_bytes(&secret);
667                let mut local_suspended = crate::crdt::SuspendedTransactionQueue::new();
668                let queue = suspended.unwrap_or(&mut local_suspended);
669                let agent_did_hash = q_hash(agent.agent_did());
670                match commit_semantic_mutation(
671                    &mut wal,
672                    quin,
673                    intent.principal_did_hash,
674                    agent_did_hash,
675                    &signing_key,
676                    queue,
677                ) {
678                    Ok(WalHandoffResult::Committed) => {
679                        wal_written = true;
680                    }
681                    Ok(WalHandoffResult::Suspended { agreement_id }) => {
682                        wal_written = true;
683                        wal_suspended = true;
684                        suspended_agreement_id = Some(agreement_id);
685                    }
686                    Err(_) => {}
687                }
688            }
689        }
690
691        OrchestrationResult::Committed {
692            text: output.text,
693            provenance_quins: output.provenance_quins,
694            semantic_quin,
695            wal_committed: wal_written,
696            wal_suspended,
697            suspended_agreement_id,
698        }
699    }
700}
701
702#[cfg(test)]
703pub mod tests {
704    use super::*;
705    use crate::llm_agent::{AgentIntent, AgentRuntime, LocalLlmAgent, SANCTUARY_SCOPE_WEBIZEN};
706    use crate::modalities::logic::n3_compiler::N3OutputMode;
707
708    #[test]
709    /// `TaskOrchestrator::qualia_validate_ring_buffer`.
710    pub fn qualia_validate_ring_buffer() {}
711
712    #[test]
713    fn test_orchestrator_full_permit_path() {
714        let agent = LocalLlmAgent::new("did:git:orch-test", "model.gguf");
715        let intent = AgentIntent {
716            intent_predicate: 0x1234,
717            requested_graph_scope: vec![0xABCD],
718            context_namespaces: vec![],
719            requires_network: false,
720            ilp_offer_micro_cents: 0,
721            principal_did_hash: 0,
722            mcp_intent_frame_hash: 0x1234,
723            output_mode: N3OutputMode::FreeText,
724            clearance_ceiling: 0,
725            max_sentinel_depth: 32,
726            active_profile: None,
727        };
728        let orch = TaskOrchestrator::new(Box::new(NullThermalGovernor));
729        let result = orch.orchestrate_inference(
730            &agent,
731            "Summarise my health graph.",
732            "some_graph_bytes",
733            intent,
734            None,
735        );
736        assert!(matches!(result, OrchestrationResult::Committed { .. }));
737    }
738
739    #[test]
740    fn test_orchestrator_blocks_sanctuary_intent() {
741        let agent = LocalLlmAgent::new("did:git:orch-test", "model.gguf");
742        let intent = AgentIntent {
743            intent_predicate: 0x1234,
744            requested_graph_scope: vec![SANCTUARY_SCOPE_WEBIZEN],
745            context_namespaces: vec![],
746            requires_network: false,
747            ilp_offer_micro_cents: 0,
748            principal_did_hash: 0,
749            mcp_intent_frame_hash: 0x1234,
750            output_mode: N3OutputMode::FreeText,
751            clearance_ceiling: 0,
752            max_sentinel_depth: 32,
753            active_profile: None,
754        };
755        let orch = TaskOrchestrator::new(Box::new(NullThermalGovernor));
756        let result =
757            orch.orchestrate_inference(&agent, "Show me sanctuary data.", "ctx", intent, None);
758        assert!(matches!(result, OrchestrationResult::Blocked { .. }));
759    }
760
761    // ─── Grounding gate ──────────────────────────────────────────────────────
762    use crate::llm_agent::{AgentBackend, AgentError, AgentOutput};
763    use crate::solvers::grounding::{GroundingResolver, GroundingThresholds};
764    use std::collections::HashMap;
765
766    fn claim_quin(s: u64, p: u64, o: u64) -> NQuin {
767        NQuin {
768            subject: s,
769            predicate: p,
770            object: o,
771            context: 0,
772            metadata: 0,
773            parity: 0,
774        }
775    }
776
777    /// A mock agent that emits a fixed structured claim + citations, delegating the
778    /// rest of the runtime to a real local agent. `validate_output` permits so the
779    /// test isolates the *grounding* gate from the citation-presence gate.
780    struct ClaimAgent {
781        inner: LocalLlmAgent,
782        output: AgentOutput,
783    }
784    impl AgentRuntime for ClaimAgent {
785        fn backend(&self) -> &AgentBackend {
786            self.inner.backend()
787        }
788        fn agent_did(&self) -> &str {
789            self.inner.agent_did()
790        }
791        fn validate_intent(&self, intent: &AgentIntent) -> WebizenVerdict {
792            self.inner.validate_intent(intent)
793        }
794        fn infer(&self, _p: &str, _g: &str) -> Result<AgentOutput, AgentError> {
795            Ok(self.output.clone())
796        }
797        fn validate_output(&self, _o: &AgentOutput) -> WebizenVerdict {
798            WebizenVerdict::Permit
799        }
800        fn memory_budget_remaining(&self) -> u64 {
801            self.inner.memory_budget_remaining()
802        }
803    }
804
805    struct MapResolver(HashMap<u64, NQuin>);
806    impl GroundingResolver for MapResolver {
807        fn resolve(&self, h: u64) -> Option<NQuin> {
808            self.0.get(&h).copied()
809        }
810    }
811
812    fn grounding_intent() -> AgentIntent {
813        AgentIntent {
814            intent_predicate: 0x1234,
815            requested_graph_scope: vec![0xABCD],
816            context_namespaces: vec![],
817            requires_network: false,
818            ilp_offer_micro_cents: 0,
819            principal_did_hash: 0,
820            mcp_intent_frame_hash: 0x1234,
821            output_mode: N3OutputMode::FreeText,
822            clearance_ceiling: 0,
823            max_sentinel_depth: 32,
824            active_profile: None,
825        }
826    }
827
828    fn claim_agent(claim: NQuin, citations: Vec<u64>) -> ClaimAgent {
829        ClaimAgent {
830            inner: LocalLlmAgent::new("did:git:claim-agent", "model.gguf"),
831            output: AgentOutput {
832                text: "asserted".into(),
833                semantic_quin: Some(claim),
834                provenance_quins: citations,
835                tokens_generated: 1,
836                inference_duration_ms: 0,
837                peak_memory_bytes: 0,
838            },
839        }
840    }
841
842    #[test]
843    fn grounding_gate_commits_a_supported_claim() {
844        let claim = claim_quin(1, 2, 3);
845        let agent = claim_agent(claim, vec![0xAA]);
846        let mut m = HashMap::new();
847        m.insert(0xAA, claim_quin(1, 2, 3)); // citation resolves to the exact fact
848        let resolver = MapResolver(m);
849        let orch = TaskOrchestrator::new(Box::new(NullThermalGovernor));
850        let result = orch.orchestrate_inference_grounded(
851            &agent,
852            "assert",
853            "ctx",
854            grounding_intent(),
855            None,
856            &resolver,
857            GroundingThresholds::default(),
858        );
859        assert!(
860            matches!(result, OrchestrationResult::Committed { .. }),
861            "got {result:?}"
862        );
863    }
864
865    #[test]
866    fn grounding_gate_blocks_an_ungrounded_claim() {
867        let claim = claim_quin(1, 2, 3);
868        let agent = claim_agent(claim, vec![0xBB]);
869        let mut m = HashMap::new();
870        m.insert(0xBB, claim_quin(7, 8, 9)); // cited fact is unrelated to the claim
871        let resolver = MapResolver(m);
872        let orch = TaskOrchestrator::new(Box::new(NullThermalGovernor));
873        let result = orch.orchestrate_inference_grounded(
874            &agent,
875            "assert",
876            "ctx",
877            grounding_intent(),
878            None,
879            &resolver,
880            GroundingThresholds::default(),
881        );
882        assert!(
883            matches!(result, OrchestrationResult::Blocked { reason, .. } if reason.contains("ungrounded")),
884            "ungrounded claim must be blocked, got {result:?}"
885        );
886    }
887
888    #[test]
889    fn grounding_gate_routes_partial_support_to_review() {
890        // Endpoints 1 and 3 are each cited somewhere, but no single fact matches a
891        // role of the claim → review band → blocked pending human review.
892        let claim = claim_quin(1, 2, 3);
893        let agent = claim_agent(claim, vec![0xC1, 0xC2]);
894        let mut m = HashMap::new();
895        m.insert(0xC1, claim_quin(1, 50, 60));
896        m.insert(0xC2, claim_quin(60, 70, 3));
897        let resolver = MapResolver(m);
898        let orch = TaskOrchestrator::new(Box::new(NullThermalGovernor));
899        let result = orch.orchestrate_inference_grounded(
900            &agent,
901            "assert",
902            "ctx",
903            grounding_intent(),
904            None,
905            &resolver,
906            GroundingThresholds::default(),
907        );
908        assert!(
909            matches!(result, OrchestrationResult::Blocked { reason, .. } if reason.contains("human review")),
910            "partial grounding must require review, got {result:?}"
911        );
912    }
913
914    #[test]
915    fn ungrounded_claim_still_commits_without_a_resolver() {
916        // The plain (non-grounded) entrypoint must be unchanged: no resolver → the
917        // grounding gate is skipped entirely, preserving existing behaviour.
918        let claim = claim_quin(1, 2, 3);
919        let agent = claim_agent(claim, vec![0xBB]);
920        let orch = TaskOrchestrator::new(Box::new(NullThermalGovernor));
921        let result = orch.orchestrate_inference(&agent, "assert", "ctx", grounding_intent(), None);
922        assert!(
923            matches!(result, OrchestrationResult::Committed { .. }),
924            "got {result:?}"
925        );
926    }
927
928    #[test]
929    fn test_thermal_critical_blocks_non_essential_inference() {
930        struct MockCriticalThermalGovernor;
931        impl ThermalGovernor for MockCriticalThermalGovernor {
932            fn get_thermal_state(&self) -> ThermalStatus {
933                ThermalStatus::Critical
934            }
935        }
936
937        let agent = LocalLlmAgent::new("did:git:orch-test", "model.gguf");
938        let intent = AgentIntent {
939            intent_predicate: 0x1234, // non-critical
940            requested_graph_scope: vec![],
941            context_namespaces: vec![],
942            requires_network: false,
943            ilp_offer_micro_cents: 0,
944            principal_did_hash: 0,
945            mcp_intent_frame_hash: 0x1234,
946            output_mode: N3OutputMode::FreeText,
947            clearance_ceiling: 0,
948            max_sentinel_depth: 32,
949            active_profile: None,
950        };
951        let orch = TaskOrchestrator::new(Box::new(MockCriticalThermalGovernor));
952        let result = orch.orchestrate_inference(&agent, "Query", "ctx", intent, None);
953        assert!(matches!(
954            result,
955            OrchestrationResult::Blocked {
956                rule_violated: 0xDEADBEEF,
957                ..
958            }
959        ));
960    }
961
962    #[test]
963    fn test_async_scrub_lock_invariant() {
964        let orch = TaskOrchestrator::new(Box::new(NullThermalGovernor));
965        let agent = LocalLlmAgent::new("did:git:orch-test", "model.gguf");
966
967        // 1. Initially it should load fine
968        assert!(orch.load_model(&agent, 123).is_ok());
969
970        // 2. Trigger an eviction (spawns background thread to scrub)
971        orch.evict_model(123);
972
973        // 3. IMMEDIATELY try to load a new model. The lock should reject it.
974        let load_result = orch.load_model(&agent, 456);
975        assert!(
976            load_result.is_err(),
977            "Orchestrator violated mechanical sympathy! Mapped model while Swarm worker was still scrubbing."
978        );
979
980        // 4. Wait for the background Swarm worker to complete its duty of care
981        std::thread::sleep(std::time::Duration::from_millis(50));
982
983        // 5. Try loading again. The lock should be cleared.
984        let second_load_result = orch.load_model(&agent, 456);
985        assert!(
986            second_load_result.is_ok(),
987            "Orchestrator failed to load model after scrubbing lock cleared."
988        );
989        assert_eq!(orch.resident_model_id(), Some(456));
990
991        // Ensure Webizen VM logic handles yielding
992        let mut vm = crate::modalities::logic::core::WebizenVM::with_scrubbing_lock(
993            orch.scrubbing_lock.clone(),
994        );
995        let bytecode = vec![crate::modalities::logic::core::WebizenOpcode::LoadModel(
996            999,
997        )];
998        vm.load_bytecode(&bytecode);
999
1000        let quin = crate::NQuin {
1001            subject: 0,
1002            predicate: 0,
1003            object: 0,
1004            context: 0,
1005            metadata: 0,
1006            parity: 0,
1007        };
1008
1009        // If we trigger evict again, the VM should yield on LoadModel
1010        orch.evict_model(456);
1011        let exec_result = vm.execute_implication(&quin);
1012        assert!(exec_result.is_none());
1013        assert_eq!(
1014            vm.yielded_op,
1015            Some(crate::modalities::logic::core::WebizenOpcode::LoadModel(
1016                999
1017            ))
1018        );
1019
1020        // Wait for scrub to clear
1021        std::thread::sleep(std::time::Duration::from_millis(50));
1022        assert_eq!(orch.resident_model_id(), None);
1023    }
1024
1025    fn write_fever_lex_bytes() -> Vec<u8> {
1026        let h_sub = q_hash("Patient");
1027        let h_pred = q_hash("fever");
1028        let h_obj = q_hash("True");
1029        let entries = [(h_sub, "Patient"), (h_pred, "fever"), (h_obj, "True")];
1030        let mut sorted = entries.to_vec();
1031        sorted.sort_unstable_by_key(|(h, _)| *h);
1032        let entry_count = sorted.len() as u64;
1033        let strings_offset = 32 + entry_count * 16;
1034        let mut blob = Vec::new();
1035        let mut index = Vec::new();
1036        for (hash, text) in &sorted {
1037            let str_off = blob.len() as u64;
1038            let b = text.as_bytes();
1039            let len = b.len().min(65535) as u16;
1040            // Q42LEX string payload format: [LEX_TAG_STRING=0x01][len_lo][len_hi][utf8...]
1041            // Must match Q42LexMmap::read_string_at which checks the tag byte first.
1042            blob.push(0x01u8); // LEX_TAG_STRING
1043            blob.extend_from_slice(&len.to_le_bytes());
1044            blob.extend_from_slice(&b[..len as usize]);
1045            index.extend_from_slice(&hash.to_le_bytes());
1046            index.extend_from_slice(&str_off.to_le_bytes());
1047        }
1048        let mut out = Vec::new();
1049        out.extend_from_slice(b"Q42LEX\0\0");
1050        out.extend_from_slice(&entry_count.to_le_bytes());
1051        out.extend_from_slice(&strings_offset.to_le_bytes());
1052        out.extend_from_slice(&1u64.to_le_bytes());
1053        out.extend_from_slice(&index);
1054        out.extend_from_slice(&blob);
1055        out
1056    }
1057
1058    /// End-to-end: mmap lex → FSM sieve (3 tokens) → fiduciary stamp → volatile WAL commit.
1059    #[test]
1060    #[serial_test::serial]
1061    fn test_e2e_llm_to_wal_pipeline() {
1062        let _profiler = dhat::Profiler::builder().testing().build();
1063
1064        let lex_bytes = write_fever_lex_bytes();
1065        let lex_mmap = crate::q42_lex::Q42LexMmap::from_bytes(&lex_bytes).expect("lex");
1066        let tok = crate::gguf_sharder::GgufTokenizer::default();
1067        let spec = crate::neuro_symbolic_sieve::SieveLexSpec::fever_observation();
1068        let mut sieve = crate::neuro_symbolic_sieve::NeuroSymbolicSieve::from_lex_and_tokenizer(
1069            &lex_mmap, &tok, &spec,
1070        );
1071        assert!(
1072            sieve.masks_ready(),
1073            "lex must resolve fever triple token IDs"
1074        );
1075        let (sub, pred, obj) = sieve.resolved_token_triple().expect("triple");
1076
1077        let wal_file = tempfile::NamedTempFile::new().expect("wal temp");
1078        let mut wal = WriteAheadLog::open(wal_file.path()).expect("wal open");
1079        let secret = [42u8; 32];
1080        let signing_key = ed25519_dalek::SigningKey::from_bytes(&secret);
1081        let mut suspended = crate::crdt::SuspendedTransactionQueue::new();
1082        let principal = q_hash("did:q42:test-principal");
1083        let agent_did = q_hash("did:git:orch-test");
1084
1085        let stats_before = dhat::HeapStats::get();
1086
1087        assert!(sieve.apply_token(sub).is_ok());
1088        assert!(sieve.apply_token(pred).is_ok());
1089        assert!(sieve.apply_token(obj).is_ok());
1090        assert_eq!(
1091            sieve.emitted_len(),
1092            3,
1093            "must halt at exactly 3 sieve tokens"
1094        );
1095        assert!(sieve.is_complete());
1096
1097        let mut quin = sieve.assemble_quin(q_hash("clinical:fever-context"));
1098        let handoff = commit_semantic_mutation(
1099            &mut wal,
1100            &mut quin,
1101            principal,
1102            agent_did,
1103            &signing_key,
1104            &mut suspended,
1105        )
1106        .expect("wal handoff");
1107
1108        let stats_after = dhat::HeapStats::get();
1109        assert_eq!(
1110            stats_after.total_blocks - stats_before.total_blocks,
1111            0,
1112            "sieve decode + WAL write must not heap-allocate"
1113        );
1114        assert_eq!(
1115            stats_after.total_bytes - stats_before.total_bytes,
1116            0,
1117            "sieve decode + WAL write must not heap-allocate"
1118        );
1119
1120        assert_eq!(handoff, WalHandoffResult::Committed);
1121        let recovered = wal.recover().expect("recover");
1122        assert_eq!(recovered.len(), 1, "WAL must contain one 48-byte Quin");
1123        assert_eq!(recovered[0].subject, q_hash("Patient"));
1124        assert_eq!(recovered[0].predicate, q_hash("fever"));
1125        assert_eq!(recovered[0].object, q_hash("True"));
1126        assert_eq!(recovered[0].context, principal);
1127        assert_eq!(
1128            recovered[0].parity,
1129            recovered[0].subject
1130                ^ recovered[0].predicate
1131                ^ recovered[0].object
1132                ^ recovered[0].context
1133                ^ recovered[0].metadata
1134        );
1135
1136        // Optional GPU path: chunked prefill + sieved decode when Gemma GGUF is present.
1137        let gemma = std::path::Path::new(
1138            "C:/Projects/qualiaDB/gemma-4-E4B-it-GGUF/gemma-4-E4B-it-Q4_K_M.gguf",
1139        );
1140        if !gemma.exists() {
1141            return;
1142        }
1143        let mut lex_tmp = tempfile::NamedTempFile::new().expect("lex temp");
1144        std::io::Write::write_all(&mut lex_tmp, &lex_bytes).expect("lex write");
1145        let agent = LocalLlmAgent::new("did:git:e2e-fever", gemma.to_string_lossy());
1146        agent.configure_sieve_lex(lex_tmp.path().to_string_lossy().into_owned());
1147        let frame_hash = q_hash("intent:fever");
1148        let fever_intent = AgentIntent {
1149            intent_predicate: frame_hash,
1150            requested_graph_scope: vec![q_hash("snomed:hasFever")],
1151            context_namespaces: vec![q_hash("health"), q_hash("snomed")],
1152            requires_network: false,
1153            ilp_offer_micro_cents: 0,
1154            principal_did_hash: principal,
1155            mcp_intent_frame_hash: frame_hash,
1156            output_mode: N3OutputMode::GraphMutation,
1157            clearance_ceiling: 0,
1158            max_sentinel_depth: 32,
1159            active_profile: None,
1160        };
1161        assert_eq!(agent.validate_intent(&fever_intent), WebizenVerdict::Permit);
1162        if let Ok(output) = AgentRuntime::infer(&agent, "The user has a fever", "clinical-context")
1163        {
1164            assert!(
1165                output.tokens_generated <= 3,
1166                "sieve must cap generation at 3 tokens"
1167            );
1168            if let Some(q) = output.semantic_quin {
1169                assert_ne!(q.subject, 0);
1170                assert_ne!(q.predicate, 0);
1171            }
1172        }
1173    }
1174}