Skip to main content

qualia_client_core/
chat_inference.rs

1//! End-to-end Webizen-gated chat inference with retrieval, streaming, and provenance.
2
3use std::path::Path;
4use std::sync::atomic::{AtomicBool, Ordering};
5use std::sync::{Arc, Mutex, OnceLock};
6
7use qualia_core_db::{
8    inference::conditioning::{select_prioritized_parts, RequestPart},
9    llm_agent::{
10        AgentError, AgentIntent, AgentOutput, AgentRuntime, LocalLlmAgent, WebizenVerdict,
11    },
12    modalities::logic::n3_compiler::N3OutputMode,
13    orchestrator::{ModelLifecycle, OrchestrationResult},
14    q_hash,
15    wal::WriteAheadLog,
16    NQuin,
17};
18use serde::{Deserialize, Serialize};
19
20use crate::chat_retrieval::{GraphCitation, RetrievalBundle};
21use crate::chat_session;
22use crate::context_binding::{self, InferenceContextPacket};
23use crate::ontology_router::OntologyRoutingDecision;
24
25const OBJECT_HASH_MASK: u64 = 0x0FFF_FFFF_FFFF_FFFF;
26
27/// Default output budget fed to the semantic-profile compiler when a profile
28/// does not declare its own `budget.output_tokens`. The profile's declared
29/// budget always wins; this only bounds the unconfigured case.
30const CHAT_CONDITIONING_OUTPUT_TOKENS: u32 = 1024;
31
32static INFERENCE_CANCEL: AtomicBool = AtomicBool::new(false);
33
34/// One consumer GPU normally has one practical full-model decode lane. Named
35/// local-agent turns acquire this cold-path lease before switching/using the
36/// resident model, preventing competing loads and VRAM overcommit.
37static LOCAL_AGENT_DECODE_LANE: OnceLock<Mutex<()>> = OnceLock::new();
38
39#[derive(Debug, Clone, Serialize, Deserialize)]
40pub struct ChatInferenceResult {
41    pub text: String,
42    pub provenance_hashes: Vec<String>,
43    pub citations: Vec<GraphCitation>,
44    pub retrieval_triple_count: usize,
45    pub tokens_generated: u32,
46    pub inference_duration_ms: u64,
47    pub committed: bool,
48    pub block_reason: Option<String>,
49    #[serde(default, skip_serializing_if = "Option::is_none")]
50    pub sub_agent_of: Option<String>,
51    #[serde(default, skip_serializing_if = "Option::is_none")]
52    pub agent_did: Option<String>,
53    #[serde(default, skip_serializing_if = "Option::is_none")]
54    pub model_id: Option<String>,
55    #[serde(default, skip_serializing_if = "Option::is_none")]
56    pub agent_backend: Option<String>,
57    /// Super-Quin fields when the neuro-symbolic sieve completes (6 × u64, zero JSON objects).
58    #[serde(default, skip_serializing_if = "Option::is_none")]
59    pub semantic_quin: Option<[u64; 6]>,
60    #[serde(default)]
61    pub wal_committed: bool,
62    #[serde(default)]
63    pub sieve_token_count: u8,
64    #[serde(default)]
65    pub shield_alert: bool,
66    #[serde(default, skip_serializing_if = "Option::is_none")]
67    pub axiom_bounds_label: Option<String>,
68    /// Bilateral micro-commons mutation awaiting guardian co-signature.
69    #[serde(default)]
70    pub wal_suspended: bool,
71    #[serde(default, skip_serializing_if = "Option::is_none")]
72    pub suspended_agreement_id: Option<u64>,
73    /// Prompt Precision receipt: which profile/plan drove this turn and how
74    /// the prepared request was lowered for the route that served it.
75    #[serde(default, skip_serializing_if = "Option::is_none")]
76    pub conditioning: Option<crate::conditioning::PreparedRouteReceipt>,
77}
78
79impl Default for ChatInferenceResult {
80    fn default() -> Self {
81        Self {
82            text: String::new(),
83            provenance_hashes: Vec::new(),
84            citations: Vec::new(),
85            retrieval_triple_count: 0,
86            tokens_generated: 0,
87            inference_duration_ms: 0,
88            committed: false,
89            block_reason: None,
90            sub_agent_of: None,
91            agent_did: None,
92            model_id: None,
93            agent_backend: None,
94            semantic_quin: None,
95            wal_committed: false,
96            sieve_token_count: 0,
97            shield_alert: false,
98            axiom_bounds_label: None,
99            wal_suspended: false,
100            suspended_agreement_id: None,
101            conditioning: None,
102        }
103    }
104}
105
106/// Requests inference cancellation.
107pub fn request_cancel_inference() {
108    INFERENCE_CANCEL.store(true, Ordering::SeqCst);
109}
110
111/// Clears the cancellation flag.
112pub fn clear_cancel_inference() {
113    INFERENCE_CANCEL.store(false, Ordering::SeqCst);
114}
115
116/// `true` when inference-cancelled.
117pub fn is_inference_cancelled() -> bool {
118    INFERENCE_CANCEL.load(Ordering::SeqCst)
119}
120
121#[derive(Debug, Clone, Default)]
122pub struct ChatInferenceOptions {
123    pub reply_to_fragment_id: Option<String>,
124    /// Override session environment: route through sieve + orchestrator WAL path.
125    pub graph_mutation: bool,
126    /// Pointed ontology profile of the named agent serving this turn.  The
127    /// profile narrows relevance routing; it does not grant access itself.
128    pub semantic_profile: Option<crate::agent_registry::AgentSemanticProfile>,
129    /// Optional per-agent ontology/data-source boundary. An empty list keeps
130    /// the session's existing scope; a populated list can only narrow it.
131    pub allowed_ontology_ids: Vec<String>,
132}
133
134/// Runs chat inference with options.
135pub fn run_chat_inference_with_options(
136    session_id: &str,
137    prompt: &str,
138    on_token: Option<Arc<dyn Fn(String) + Send + Sync>>,
139) -> ChatInferenceResult {
140    run_chat_inference_full(
141        session_id,
142        prompt,
143        on_token,
144        ChatInferenceOptions::default(),
145    )
146}
147
148/// Run a local turn using a named roster agent.  A pinned model is activated on
149/// demand before inference; the lifecycle implementation owns any resident
150/// mapping replacement.  This is a cold control-path operation and never runs
151/// inside the decode/evaluator hot path.
152pub fn run_chat_inference_for_agent(
153    session_id: &str,
154    prompt: &str,
155    agent_slug: Option<&str>,
156    on_token: Option<Arc<dyn Fn(String) + Send + Sync>>,
157) -> ChatInferenceResult {
158    let Some(slug) = agent_slug.filter(|slug| !slug.trim().is_empty()) else {
159        return run_chat_inference_with_options(session_id, prompt, on_token);
160    };
161    let started = std::time::Instant::now();
162    let lane = LOCAL_AGENT_DECODE_LANE.get_or_init(|| Mutex::new(()));
163    let _lease = lane.lock().unwrap_or_else(|poisoned| poisoned.into_inner());
164    let Some(state) = crate::state::APP_STATE.get() else {
165        return empty_result(started, "Application not initialized", None);
166    };
167    let storage = match state.config.lock() {
168        Ok(config) => config.storage_path.clone(),
169        Err(error) => return empty_result(started, &error.to_string(), None),
170    };
171    let Some(agent) = crate::agent_registry::get_agent(Path::new(&storage), slug) else {
172        return empty_result(started, &format!("Unknown agent @{slug}"), None);
173    };
174    if !agent.enabled {
175        return empty_result(started, &format!("Agent @{} is disabled", agent.slug), None);
176    }
177    let model_id = match &agent.backend {
178        crate::agent_registry::AgentBackendSpec::LocalEngine { model_id } => model_id.clone(),
179        crate::agent_registry::AgentBackendSpec::RemoteMcp { .. } => {
180            return empty_result(
181                started,
182                "Remote agent must be dispatched through its MCP provider",
183                None,
184            );
185        }
186    };
187    if let Err(error) =
188        crate::chat_agents::bind_local_roster_agent(Path::new(&storage), session_id, &agent)
189    {
190        return empty_result(started, &format!("Could not bind agent: {error}"), None);
191    }
192    if let Some(model_id) = model_id {
193        let active_record = crate::api::load_active_model_record_from_disk();
194        let already_active = active_record
195            .as_ref()
196            .is_some_and(|active| active.model_id == model_id);
197        if !already_active {
198            // Local agents share a consumer device's bounded decode lane.  A
199            // model switch is explicit: scrub the old resident mapping before
200            // asking the lifecycle to map and activate the selected agent's
201            // model.  Agent definitions and queued-job records remain intact.
202            if let Some(active) = active_record {
203                crate::model_lifecycle::unload_active_model(Some(active.profile_id));
204            }
205            if let Err(error) =
206                crate::model_lifecycle::activate_model_for_id(&model_id, Path::new(&storage))
207            {
208                return empty_result(
209                    started,
210                    &format!("Could not load @{slug}'s model `{model_id}`: {error}"),
211                    None,
212                );
213            }
214        }
215    }
216    run_chat_inference_full(
217        session_id,
218        prompt,
219        on_token,
220        ChatInferenceOptions {
221            semantic_profile: Some(agent.semantic_profile),
222            allowed_ontology_ids: agent.data_policy.allowed_ontology_ids,
223            ..ChatInferenceOptions::default()
224        },
225    )
226}
227
228/// Runs full chat inference.
229pub fn run_chat_inference_full(
230    session_id: &str,
231    prompt: &str,
232    on_token: Option<Arc<dyn Fn(String) + Send + Sync>>,
233    options: ChatInferenceOptions,
234) -> ChatInferenceResult {
235    clear_cancel_inference();
236    // Interactive chat uses the sampling chain (temperature / top-p / repeat-penalty) instead of
237    // greedy argmax, which collapses instruct models into repetition / degenerate loops. Benchmarks
238    // keep the unconfigured greedy default. See qualia_core_db::sampler::SamplerConfig::chat_default.
239    qualia_core_db::llm_bench::set_sampler_config(Some(
240        qualia_core_db::sampler::SamplerConfig::chat_default(),
241    ));
242    let started = std::time::Instant::now();
243
244    let state = match crate::state::APP_STATE.get() {
245        Some(s) => s,
246        None => {
247            return empty_result(started, "Application not initialized", None);
248        }
249    };
250
251    let storage = state.config.lock().unwrap().storage_path.clone();
252    let catalog = crate::api::load_workspace_catalog();
253    let ib_settings = crate::inference_backend::load_inference_backend_settings();
254    let use_ollama = matches!(
255        ib_settings.backend,
256        crate::chat_agents::AgentBackendKind::Ollama
257    );
258
259    // Native GGUF path requires an active model; optional Ollama harness does not.
260    if !use_ollama && crate::model_lifecycle::get_model_lifecycle_state() != ModelLifecycle::Active
261    {
262        return empty_result(
263            started,
264            "No active model — download and activate a model in LLM Hub, or switch Inference Backend to Ollama in Settings.",
265            None,
266        );
267    }
268
269    let env = match context_binding::refresh_session_environment(
270        Path::new(&storage),
271        &catalog,
272        session_id,
273    ) {
274        Ok(e) => e,
275        Err(e) => return empty_result(started, &e.to_string(), None),
276    };
277
278    let bounds_label = env.axiom_bounds.label();
279    let empty = |reason: &str| empty_result(started, reason, Some(&bounds_label));
280
281    if let Err(reason) = validate_axiom_preflight(prompt, &env.axiom_bounds) {
282        return empty_result(started, &reason, Some(&bounds_label));
283    }
284
285    let profile = crate::user_profile::load_profile();
286    let mut agent_cfg =
287        match crate::chat_agents::load_local_agent_config(Path::new(&storage), session_id) {
288            Ok(c) => c,
289            Err(e) => return empty(&e),
290        };
291    // Session agent backend tracks the global preference for this turn.
292    agent_cfg.backend = ib_settings.backend;
293    if use_ollama {
294        agent_cfg.model_id = Some(ib_settings.ollama_model.clone());
295    }
296
297    let focus_terms = options
298        .semantic_profile
299        .as_ref()
300        .map(crate::agent_registry::AgentSemanticProfile::focus_terms)
301        .unwrap_or_default();
302    let routing = crate::ontology_router::route_prompt_with_focus_and_allowlist(
303        &env,
304        prompt,
305        &focus_terms,
306        &options.allowed_ontology_ids,
307    );
308    let retrieval = crate::chat_retrieval::retrieve_graph_context(
309        Path::new(&storage),
310        &env,
311        prompt,
312        &routing.ontology_ids,
313    );
314
315    let mut packet = match build_augmented_packet(
316        Path::new(&storage),
317        session_id,
318        &env,
319        prompt,
320        &retrieval,
321        &catalog,
322        &routing,
323        options.semantic_profile.as_ref(),
324        options.reply_to_fragment_id.as_deref(),
325    ) {
326        Ok(p) => p,
327        Err(e) => return empty(&e.to_string()),
328    };
329
330    let graph_mutation = options.graph_mutation || env.graph_mutation;
331
332    // Prompt Precision: the persisted active profile is compiled once per turn
333    // into the shared prepared semantic request; each route below lowers the
334    // same plan (Ollama `system` role, native/orchestrated envelope prepend).
335    // A declared profile that fails to compile fails closed — enforced
336    // requirements are never silently dropped.
337    let prepared = match crate::conditioning::prepare_active_semantic_request(
338        Path::new(&storage),
339        prompt,
340        &profile.public_did,
341        &packet.graph_context_json,
342        CHAT_CONDITIONING_OUTPUT_TOKENS,
343    ) {
344        Ok(p) => p,
345        Err(error) => {
346            return empty(&format!(
347                "Conditioning profile rejected this request: {error}"
348            ))
349        }
350    };
351
352    // Precision contracts are cold-path model configuration. They apply only
353    // to the direct native chat decode path, where both input and output caps
354    // can be enforced. Graph-mutation turns use the orchestrator-owned decode
355    // path and therefore remain unchanged until it accepts a DecodeControl.
356    let active_precision = if graph_mutation || use_ollama {
357        None
358    } else {
359        let Some(active) = crate::api::load_active_model_record_from_disk() else {
360            return empty("No active model record — activate in LLM Hub.");
361        };
362        match crate::conditioning::apply_active_model_precision(
363            &active.model_id,
364            &mut packet.augmented_prompt,
365            prompt,
366        ) {
367            Ok(precision) => precision,
368            Err(error) => {
369                return empty(&format!(
370                    "Conditioning contract rejected chat input: {error}"
371                ))
372            }
373        }
374    };
375
376    // ── Optional Ollama harness (retrieval + ontology routing still Qualia) ──
377    if use_ollama {
378        return run_ollama_chat_turn(
379            session_id,
380            &agent_cfg,
381            &packet,
382            &retrieval,
383            &ib_settings,
384            prepared.as_ref(),
385            on_token,
386            started,
387            Path::new(&storage),
388            empty,
389        );
390    }
391
392    // The compiled envelope is prepended after contract lowering so the model
393    // precision byte cap cannot truncate declared enforced requirements; the
394    // envelope itself is already bounded by the profile's own max_bytes.
395    if let Some(request) = &prepared {
396        packet.augmented_prompt = format!("{}\n\n{}", request.text, packet.augmented_prompt);
397    }
398
399    let active = match crate::api::load_active_model_record_from_disk() {
400        Some(r) => r,
401        None => return empty("No active model record — activate in LLM Hub."),
402    };
403
404    let agent = LocalLlmAgent::with_local_backend(
405        agent_cfg.sub_agent_did.clone(),
406        qualia_core_db::llm_agent::AgentBackend::Local {
407            model_path: packet.model_path.clone(),
408            context_window: active.context_window,
409            quantization: active.quantization.clone(),
410            vision_projector_path: active.mmproj_path.clone(),
411            modality: active.modality.clone(),
412            architecture: active.architecture.clone(),
413        },
414    );
415
416    if let Some(lex_path) = resolve_sieve_lex_path(
417        Path::new(&storage),
418        &env,
419        &packet.model_path,
420        &routing.ontology_ids,
421    ) {
422        agent.configure_sieve_lex(lex_path);
423    }
424    if let Err(err) =
425        crate::model_lifecycle::task_orchestrator().load_model(&agent, active.profile_id)
426    {
427        return empty(&format!("Model unavailable: {err}"));
428    }
429    crate::model_lifecycle::record_llm_memory_sample(
430        agent
431            .memory_used_bytes
432            .load(std::sync::atomic::Ordering::Relaxed),
433    );
434
435    let frame_hash = q_hash(&format!("purpose:ChatSession:{session_id}"));
436    let (intent_predicate, mcp_intent_frame_hash, output_mode) = if graph_mutation {
437        (frame_hash, frame_hash, N3OutputMode::GraphMutation)
438    } else {
439        (
440            q_hash("llm:ReadGraph"),
441            q_hash("purpose:General"),
442            N3OutputMode::FreeText,
443        )
444    };
445
446    let intent = AgentIntent {
447        intent_predicate,
448        requested_graph_scope: packet.graph_scope_hashes.clone(),
449        context_namespaces: packet.context_namespaces.clone(),
450        requires_network: false,
451        ilp_offer_micro_cents: 0,
452        principal_did_hash: q_hash(&profile.public_did),
453        mcp_intent_frame_hash,
454        output_mode,
455        clearance_ceiling: 0,
456        max_sentinel_depth: 32,
457        active_profile: packet.active_profile.clone(),
458    };
459
460    if is_inference_cancelled() {
461        return empty("Generation cancelled");
462    }
463
464    #[cfg(not(target_arch = "wasm32"))]
465    if let Err(reason) = crate::inference_policy::bind_turn(session_id, &agent) {
466        return empty(&format!("Inference authority unavailable: {reason}"));
467    }
468
469    if graph_mutation {
470        return run_orchestrated_inference(
471            session_id,
472            &agent,
473            &agent_cfg,
474            &packet,
475            &retrieval,
476            intent,
477            prepared.as_ref(),
478            started,
479            Path::new(&storage),
480            empty,
481        );
482    }
483
484    match agent.validate_intent(&intent) {
485        WebizenVerdict::Deny { reason, .. } => return empty(reason),
486        WebizenVerdict::DenyWithExplanation { explanation, .. } => return empty(&explanation),
487        WebizenVerdict::RequireReconfirmation { reason } => return empty(&reason),
488        _ => {}
489    }
490
491    // The active precision contract's output cap wins when present; otherwise
492    // the semantic profile's own output budget is enforced on native decode.
493    let decode_output_budget = active_precision
494        .as_ref()
495        .map(|precision| precision.output_budget_tokens)
496        .or_else(|| prepared.as_ref().map(|request| request.token_budget));
497
498    let t0 = std::time::Instant::now();
499    let output = if let Some(cb) = on_token {
500        let (text, mut prov, tokens, semantic_quin) = if let Some(budget) = decode_output_budget {
501            let control = qualia_core_db::llm_agent::DecodeControl::default();
502            control.set_token_budget(budget);
503            if let Some(thinking) = active_precision
504                .as_ref()
505                .and_then(|p| p.thinking_budget_tokens)
506            {
507                control.set_thinking_token_budget(thinking);
508            }
509            agent.infer_local_model_controlled(
510                &packet.augmented_prompt,
511                &packet.graph_context_json,
512                control,
513                Some(move |delta: String| {
514                    if !is_inference_cancelled() {
515                        cb(delta);
516                    }
517                }),
518            )
519        } else {
520            agent.infer_local_model_streaming(
521                &packet.augmented_prompt,
522                &packet.graph_context_json,
523                Some(move |delta: String| {
524                    if !is_inference_cancelled() {
525                        cb(delta);
526                    }
527                }),
528            )
529        };
530        prov.extend(retrieval.provenance_hashes.iter().copied());
531        prov.sort_unstable();
532        prov.dedup();
533        AgentOutput {
534            text,
535            semantic_quin,
536            provenance_quins: prov,
537            tokens_generated: tokens,
538            inference_duration_ms: t0.elapsed().as_millis() as u64,
539            peak_memory_bytes: 0,
540        }
541    } else {
542        match if let Some(budget) = decode_output_budget {
543            let control = qualia_core_db::llm_agent::DecodeControl::default();
544            control.set_token_budget(budget);
545            if let Some(thinking) = active_precision
546                .as_ref()
547                .and_then(|p| p.thinking_budget_tokens)
548            {
549                control.set_thinking_token_budget(thinking);
550            }
551            let (text, provenance_quins, tokens_generated, semantic_quin) = agent
552                .infer_local_model_controlled(
553                    &packet.augmented_prompt,
554                    &packet.graph_context_json,
555                    control,
556                    None::<fn(String)>,
557                );
558            Ok(AgentOutput {
559                text,
560                semantic_quin,
561                provenance_quins,
562                tokens_generated,
563                inference_duration_ms: t0.elapsed().as_millis() as u64,
564                peak_memory_bytes: 0,
565            })
566        } else {
567            agent.infer(&packet.augmented_prompt, &packet.graph_context_json)
568        } {
569            Ok(mut o) => {
570                o.provenance_quins
571                    .extend(retrieval.provenance_hashes.iter().copied());
572                o.provenance_quins.sort_unstable();
573                o.provenance_quins.dedup();
574                o
575            }
576            Err(AgentError::WebizenDenied { reason, .. }) => return empty(&reason),
577            Err(AgentError::SieveMisaligned) => {
578                return empty(
579                    "Shield — sieve misaligned: model output did not match graph grammar.",
580                );
581            }
582            Err(e) => return empty(&format!("{e:?}")),
583        }
584    };
585
586    if is_inference_cancelled() {
587        return cancelled_result(&output, &retrieval, started);
588    }
589
590    match agent.validate_output(&output) {
591        WebizenVerdict::Deny { reason, .. } => {
592            return blocked_result(&output, &retrieval, started, reason.to_string());
593        }
594        WebizenVerdict::DenyWithExplanation { explanation, .. } => {
595            return blocked_result(&output, &retrieval, started, explanation);
596        }
597        _ => {}
598    }
599
600    let _ = persist_citations(session_id, Path::new(&storage), &output, &retrieval);
601
602    crate::model_lifecycle::record_llm_memory_sample(
603        agent
604            .memory_used_bytes
605            .load(std::sync::atomic::Ordering::Relaxed),
606    );
607    let mut result = finalize_success_result(
608        output, &retrieval, started, &agent_cfg, false, 0, false, None,
609    );
610    result.conditioning = prepared
611        .as_ref()
612        .map(|request| request.receipt("native", "envelope", false, None));
613    result
614}
615
616/// Chat turn via optional Ollama HTTP harness.
617///
618/// Qualia still owns retrieval, ontology routing, axiom preflight, and
619/// citation provenance. Generation is delegated to Ollama so ETL/chat work
620/// can proceed while native GGUF inference is unavailable.
621fn run_ollama_chat_turn(
622    session_id: &str,
623    agent_cfg: &crate::chat_agents::ParticipantAgentConfig,
624    packet: &InferenceContextPacket,
625    retrieval: &RetrievalBundle,
626    settings: &crate::inference_backend::InferenceBackendSettings,
627    prepared: Option<&crate::conditioning::PreparedSemanticRequest>,
628    on_token: Option<Arc<dyn Fn(String) + Send + Sync>>,
629    started: std::time::Instant,
630    storage: &Path,
631    empty: impl Fn(&str) -> ChatInferenceResult,
632) -> ChatInferenceResult {
633    if is_inference_cancelled() {
634        return empty("Generation cancelled");
635    }
636
637    let harness = crate::ollama_harness::OllamaHarness::from_settings(settings);
638    const BASE_SYSTEM: &str = "You are a Webizen/Qualia assistant. Ground answers in the provided graph context when present. Prefer precise, citation-aware replies. Do not invent legal or medical facts.";
639    // Ollama natively supports a system role: the prepared semantic request
640    // travels there unflattened, and the profile's output budget is carried
641    // as `num_predict`.
642    let system_owned;
643    let system = match prepared {
644        Some(request) => {
645            system_owned = format!("{BASE_SYSTEM}\n\n{}", request.text);
646            system_owned.as_str()
647        }
648        None => BASE_SYSTEM,
649    };
650    let user = packet.augmented_prompt.as_str();
651
652    let generation = match harness.generate_with_options(
653        system,
654        user,
655        prepared.map(|request| request.token_budget),
656    ) {
657        Ok(g) => g,
658        Err(e) => {
659            return empty(&format!(
660                "Ollama harness failed ({url}): {e}. Check Settings → Ollama (base URL, model, daemon running).",
661                url = harness.base_url
662            ));
663        }
664    };
665
666    if is_inference_cancelled() {
667        return empty("Generation cancelled");
668    }
669
670    // Surface full completion once (streaming wire-up for Ollama is a follow-up).
671    if let Some(cb) = on_token.as_ref() {
672        if !generation.text.is_empty() {
673            cb(generation.text.clone());
674        }
675    }
676
677    let mut provenance = retrieval.provenance_hashes.clone();
678    provenance.sort_unstable();
679    provenance.dedup();
680
681    let tokens = generation.eval_count.unwrap_or(0);
682    let output = AgentOutput {
683        text: generation.text,
684        semantic_quin: None,
685        provenance_quins: provenance,
686        tokens_generated: tokens,
687        inference_duration_ms: started.elapsed().as_millis() as u64,
688        peak_memory_bytes: 0,
689    };
690
691    if output.text.trim().is_empty() {
692        return empty("Ollama returned an empty completion");
693    }
694
695    // Provenance from retrieval is required for grounded turns when graph context exists.
696    if !retrieval.citations.is_empty() && output.provenance_quins.is_empty() {
697        return empty("Ollama turn produced no provenance hashes from graph retrieval");
698    }
699
700    let _ = persist_citations(session_id, storage, &output, retrieval);
701    let mut result =
702        finalize_success_result(output, retrieval, started, agent_cfg, false, 0, false, None);
703    result.model_id = Some(generation.model);
704    result.agent_backend = Some("ollama".into());
705    result.conditioning = prepared.map(|request| request.receipt("ollama", "system", false, None));
706    result
707}
708
709fn run_orchestrated_inference(
710    session_id: &str,
711    agent: &LocalLlmAgent,
712    agent_cfg: &crate::chat_agents::ParticipantAgentConfig,
713    packet: &InferenceContextPacket,
714    retrieval: &RetrievalBundle,
715    intent: AgentIntent,
716    prepared: Option<&crate::conditioning::PreparedSemanticRequest>,
717    started: std::time::Instant,
718    storage: &Path,
719    empty: impl Fn(&str) -> ChatInferenceResult,
720) -> ChatInferenceResult {
721    let orch = crate::model_lifecycle::task_orchestrator();
722    let mut suspended = crate::guardianship::suspended_queue()
723        .lock()
724        .expect("suspended_queue");
725    let mut result = orch.orchestrate_inference(
726        agent,
727        &packet.augmented_prompt,
728        &packet.graph_context_json,
729        intent.clone(),
730        Some(&mut *suspended),
731    );
732
733    if let OrchestrationResult::Blocked {
734        rule_violated,
735        reason,
736    } = &result
737    {
738        if should_retry_symbolic_block(*rule_violated, reason) {
739            let corrective_prompt = build_corrective_retry_prompt(packet, reason);
740            result = orch.orchestrate_inference(
741                agent,
742                &corrective_prompt,
743                &packet.graph_context_json,
744                intent,
745                Some(&mut *suspended),
746            );
747        }
748    }
749
750    match result {
751        OrchestrationResult::Committed {
752            text,
753            mut provenance_quins,
754            semantic_quin,
755            wal_committed,
756            wal_suspended,
757            suspended_agreement_id,
758        } => {
759            provenance_quins.extend(retrieval.provenance_hashes.iter().copied());
760            provenance_quins.sort_unstable();
761            provenance_quins.dedup();
762
763            let sieve_tokens = if semantic_quin.is_some() { 3 } else { 0 };
764            let output = AgentOutput {
765                text,
766                semantic_quin,
767                provenance_quins,
768                tokens_generated: sieve_tokens,
769                inference_duration_ms: started.elapsed().as_millis() as u64,
770                peak_memory_bytes: 0,
771            };
772            let _ = persist_citations(session_id, storage, &output, retrieval);
773            crate::model_lifecycle::record_llm_memory_sample(
774                agent
775                    .memory_used_bytes
776                    .load(std::sync::atomic::Ordering::Relaxed),
777            );
778            let mut result = finalize_success_result(
779                output,
780                retrieval,
781                started,
782                agent_cfg,
783                wal_committed,
784                sieve_tokens.min(255) as u8,
785                wal_suspended,
786                suspended_agreement_id,
787            );
788            result.conditioning = prepared.map(|request| {
789                request.receipt(
790                    "orchestrated",
791                    "envelope",
792                    false,
793                    Some(
794                        "orchestrated decode carries the prepared request as a prompt envelope; the output token budget is advisory until DecodeControl is wired through the orchestrator"
795                            .to_string(),
796                    ),
797                )
798            });
799            result
800        }
801        OrchestrationResult::Blocked { reason, .. } => empty(reason),
802        OrchestrationResult::Failed(ref msg) if msg.contains("SieveMisaligned") => {
803            empty("Shield — sieve misaligned: model output did not match graph grammar.")
804        }
805        OrchestrationResult::Failed(msg) => empty(&msg),
806    }
807}
808
809fn should_retry_symbolic_block(rule_violated: u64, reason: &str) -> bool {
810    rule_violated == q_hash("q42:N3Compiler")
811        || reason.contains("SHACL")
812        || reason.contains("parseable N3")
813}
814
815fn build_corrective_retry_prompt(packet: &InferenceContextPacket, reason: &str) -> String {
816    let mut lines = vec![packet.augmented_prompt.clone()];
817    lines.push("[Symbolic corrective prompt]".to_string());
818    lines.push(format!(
819        "Your previous structured output was blocked by the deterministic SHACL/N3 gate: {reason}"
820    ));
821    if !packet.routed_ontology_ids.is_empty() {
822        lines.push(format!(
823            "Routed ontologies for this turn: {}",
824            packet.routed_ontology_ids.join(", ")
825        ));
826    }
827    if !packet.context_namespaces.is_empty() {
828        lines.push(format!(
829            "Context namespaces: {}",
830            packet
831                .context_namespaces
832                .iter()
833                .map(|h| format!("0x{h:016x}"))
834                .collect::<Vec<_>>()
835                .join(", ")
836        ));
837    }
838    lines.push(
839        "Emit only grounded N3 assertions or graph-mutation output that stays within the routed ontology predicates and shape expectations."
840            .to_string(),
841    );
842    lines.join("\n")
843}
844
845fn finalize_success_result(
846    output: AgentOutput,
847    retrieval: &RetrievalBundle,
848    started: std::time::Instant,
849    agent_cfg: &crate::chat_agents::ParticipantAgentConfig,
850    wal_committed: bool,
851    sieve_token_count: u8,
852    wal_suspended: bool,
853    suspended_agreement_id: Option<u64>,
854) -> ChatInferenceResult {
855    let duration_ms = started.elapsed().as_millis() as u64;
856    crate::model_lifecycle::record_last_decode_tok_s(output.tokens_generated, duration_ms);
857    ChatInferenceResult {
858        text: output.text,
859        provenance_hashes: output
860            .provenance_quins
861            .iter()
862            .map(|h| format!("0x{h:016x}"))
863            .collect(),
864        citations: retrieval.citations.clone(),
865        retrieval_triple_count: retrieval.triple_count,
866        tokens_generated: output.tokens_generated,
867        inference_duration_ms: duration_ms,
868        committed: true,
869        block_reason: None,
870        sub_agent_of: Some(agent_cfg.principal_did.clone()),
871        agent_did: Some(agent_cfg.sub_agent_did.clone()),
872        model_id: agent_cfg.model_id.clone(),
873        agent_backend: Some(agent_cfg.backend.as_str().to_string()),
874        semantic_quin: output.semantic_quin.map(quin_to_fields),
875        wal_committed,
876        sieve_token_count,
877        shield_alert: false,
878        axiom_bounds_label: None,
879        wal_suspended,
880        suspended_agreement_id,
881        conditioning: None,
882    }
883}
884
885fn cancelled_result(
886    output: &AgentOutput,
887    retrieval: &RetrievalBundle,
888    started: std::time::Instant,
889) -> ChatInferenceResult {
890    ChatInferenceResult {
891        text: output.text.clone(),
892        provenance_hashes: vec![],
893        citations: retrieval.citations.clone(),
894        retrieval_triple_count: retrieval.triple_count,
895        tokens_generated: output.tokens_generated,
896        inference_duration_ms: started.elapsed().as_millis() as u64,
897        committed: false,
898        block_reason: Some("Generation cancelled".to_string()),
899        sub_agent_of: None,
900        agent_did: None,
901        model_id: None,
902        agent_backend: None,
903        semantic_quin: output.semantic_quin.map(quin_to_fields),
904        wal_committed: false,
905        sieve_token_count: 0,
906        shield_alert: false,
907        axiom_bounds_label: None,
908        wal_suspended: false,
909        suspended_agreement_id: None,
910        conditioning: None,
911    }
912}
913
914fn quin_to_fields(q: NQuin) -> [u64; 6] {
915    [
916        q.subject,
917        q.predicate,
918        q.object,
919        q.context,
920        q.metadata,
921        q.parity,
922    ]
923}
924
925fn resolve_sieve_lex_path(
926    storage: &Path,
927    env: &crate::chat_session::ChatEnvironment,
928    model_path: &str,
929    preferred_ontology_ids: &[String],
930) -> Option<String> {
931    let index = storage.join("Index");
932    let ordered_ids = if preferred_ontology_ids.is_empty() {
933        env.ontology_ids.clone()
934    } else {
935        let mut ids = preferred_ontology_ids.to_vec();
936        for ont_id in &env.ontology_ids {
937            if !ids.contains(ont_id) {
938                ids.push(ont_id.clone());
939            }
940        }
941        ids
942    };
943    for ont_id in &ordered_ids {
944        let q42 = index.join(format!("{ont_id}.q42"));
945        if q42.is_file() {
946            if qualia_core_db::q42_volume::is_unified_volume(&q42).ok() == Some(true) {
947                return Some(q42.to_string_lossy().into_owned());
948            }
949        }
950        if let Some(lex) = crate::chat_ontology::resolve_wordnet_lex(&q42) {
951            return Some(lex.to_string_lossy().into_owned());
952        }
953        let lex_sibling = index.join(format!("{ont_id}.q42.lex"));
954        if lex_sibling.is_file() {
955            return Some(lex_sibling.to_string_lossy().into_owned());
956        }
957    }
958    if let Some(q42) = crate::chat_ontology::resolve_wordnet_q42(storage) {
959        if let Some(lex) = crate::chat_ontology::resolve_wordnet_lex(&q42) {
960            return Some(lex.to_string_lossy().into_owned());
961        }
962    }
963    let schema_q42 = "data/schemaorg/30.0/schemaorg-current-https.q42";
964    if Path::new(schema_q42).is_file() {
965        return Some(schema_q42.to_string());
966    }
967    let schema_lex = "data/schemaorg/30.0/schemaorg-current-https.q42.lex";
968    if Path::new(schema_lex).is_file() {
969        return Some(schema_lex.to_string());
970    }
971    let mut p = Path::new(model_path).to_path_buf();
972    if let Some(stem) = p.file_stem().and_then(|s| s.to_str()).map(str::to_string) {
973        p.set_file_name(format!("{stem}.q42.lex"));
974        if p.is_file() {
975            return Some(p.to_string_lossy().into_owned());
976        }
977    }
978    None
979}
980
981fn blocked_result(
982    output: &AgentOutput,
983    retrieval: &RetrievalBundle,
984    started: std::time::Instant,
985    reason: String,
986) -> ChatInferenceResult {
987    ChatInferenceResult {
988        text: output.text.clone(),
989        provenance_hashes: output
990            .provenance_quins
991            .iter()
992            .map(|h| format!("0x{h:016x}"))
993            .collect(),
994        citations: retrieval.citations.clone(),
995        retrieval_triple_count: retrieval.triple_count,
996        tokens_generated: output.tokens_generated,
997        inference_duration_ms: started.elapsed().as_millis() as u64,
998        committed: false,
999        block_reason: Some(reason.clone()),
1000        sub_agent_of: None,
1001        agent_did: None,
1002        model_id: None,
1003        agent_backend: None,
1004        semantic_quin: output.semantic_quin.map(quin_to_fields),
1005        wal_committed: false,
1006        sieve_token_count: 0,
1007        shield_alert: reason.contains("Shield"),
1008        axiom_bounds_label: None,
1009        wal_suspended: false,
1010        suspended_agreement_id: None,
1011        conditioning: None,
1012    }
1013}
1014
1015fn empty_result(
1016    started: std::time::Instant,
1017    reason: &str,
1018    bounds_label: Option<&str>,
1019) -> ChatInferenceResult {
1020    let shield = reason.contains("Shield");
1021    ChatInferenceResult {
1022        text: String::new(),
1023        provenance_hashes: vec![],
1024        citations: vec![],
1025        retrieval_triple_count: 0,
1026        tokens_generated: 0,
1027        inference_duration_ms: started.elapsed().as_millis() as u64,
1028        committed: false,
1029        block_reason: Some(reason.to_string()),
1030        sub_agent_of: None,
1031        agent_did: None,
1032        model_id: None,
1033        agent_backend: None,
1034        semantic_quin: None,
1035        wal_committed: false,
1036        sieve_token_count: 0,
1037        shield_alert: shield,
1038        axiom_bounds_label: if shield {
1039            bounds_label.map(str::to_string)
1040        } else {
1041            None
1042        },
1043        wal_suspended: false,
1044        suspended_agreement_id: None,
1045        conditioning: None,
1046    }
1047}
1048
1049const ANACHRONISM_TERMS: &[&str] = &[
1050    "internet",
1051    "smartphone",
1052    "blockchain",
1053    "covid",
1054    "tiktok",
1055    "youtube",
1056    "wifi",
1057    "email",
1058];
1059
1060/// Pre-flight axiom bounds check before KV prefill / orchestrator dispatch.
1061pub fn validate_axiom_preflight(
1062    prompt: &str,
1063    bounds: &context_binding::AxiomBounds,
1064) -> Result<(), String> {
1065    if bounds.start_year > bounds.end_year {
1066        return Err("Shield — invalid axiom bounds (start year is after end year)".to_string());
1067    }
1068
1069    for year in extract_years(prompt) {
1070        if year < bounds.start_year || year > bounds.end_year {
1071            return Err(format!(
1072                "Shield — Fact clipped — outside axiom bounds [{}–{}]",
1073                bounds.start_year, bounds.end_year
1074            ));
1075        }
1076    }
1077
1078    if bounds.end_year <= 1935 {
1079        let lower = prompt.to_ascii_lowercase();
1080        for term in ANACHRONISM_TERMS {
1081            if lower.contains(term) {
1082                return Err(format!(
1083                    "Shield — Fact clipped — anachronism detected outside axiom bounds [{}–{}]",
1084                    bounds.start_year, bounds.end_year
1085                ));
1086            }
1087        }
1088    }
1089
1090    Ok(())
1091}
1092
1093fn extract_years(text: &str) -> Vec<u16> {
1094    let bytes = text.as_bytes();
1095    let mut years = Vec::new();
1096    let mut i = 0;
1097    while i + 4 <= bytes.len() {
1098        if bytes[i..i + 4].iter().all(|b| b.is_ascii_digit()) {
1099            if let Ok(s) = std::str::from_utf8(&bytes[i..i + 4]) {
1100                if let Ok(y) = s.parse::<u16>() {
1101                    if (1000..=2999).contains(&y) {
1102                        years.push(y);
1103                    }
1104                }
1105            }
1106            i += 4;
1107        } else {
1108            i += 1;
1109        }
1110    }
1111    years
1112}
1113
1114fn build_augmented_packet(
1115    storage: &Path,
1116    session_id: &str,
1117    env: &crate::chat_session::ChatEnvironment,
1118    user_prompt: &str,
1119    retrieval: &RetrievalBundle,
1120    catalog: &qualia_core_db::resource_catalog::ResourceCatalog,
1121    routing: &OntologyRoutingDecision,
1122    semantic_profile: Option<&crate::agent_registry::AgentSemanticProfile>,
1123    reply_to_fragment_id: Option<&str>,
1124) -> Result<InferenceContextPacket, String> {
1125    let mut packet = context_binding::build_inference_packet(env, user_prompt, catalog)
1126        .map_err(|e| e.to_string())?;
1127    packet.context_namespaces = routing.context_namespaces.clone();
1128    packet.routed_ontology_ids = routing.ontology_ids.clone();
1129    packet.routing_brief = routing.routing_brief.clone();
1130
1131    let thread_block = if let Some(fragment_id) = reply_to_fragment_id {
1132        crate::chat_graph::build_thread_context_block(storage, session_id, fragment_id, 6)
1133            .unwrap_or_default()
1134    } else {
1135        String::new()
1136    };
1137
1138    let files_block =
1139        crate::chat_files::build_chat_files_context_block(storage, session_id, 12_000);
1140
1141    // Inforg (CML) context: prior turns the person marked with #project/#topic/#task, permission-gated.
1142    let inforg_block = crate::cml_context::retrieve_context(storage, user_prompt, 6);
1143
1144    let session = crate::chat_session::load_session(storage, session_id).ok();
1145    let cooperative_block = session
1146        .as_ref()
1147        .map(|s| {
1148            crate::chat_agents::build_cooperative_agents_block(
1149                storage,
1150                session_id,
1151                &s.messages,
1152                &s.meta.participants,
1153            )
1154        })
1155        .unwrap_or_default();
1156    let semantic_block = semantic_profile
1157        .map(crate::agent_registry::AgentSemanticProfile::briefing)
1158        .unwrap_or_default();
1159
1160    let enriched_context = serde_json::json!({
1161        "environment": serde_json::from_str::<serde_json::Value>(&packet.graph_context_json).unwrap_or_default(),
1162        "axiom_bounds": {
1163            "start_year": env.axiom_bounds.start_year,
1164            "end_year": env.axiom_bounds.end_year,
1165            "spatial_context_hash": format!("0x{:016x}", env.axiom_bounds.spatial_context_hash),
1166            "spatial_context_label": env.axiom_bounds.spatial_context_label,
1167            "label": env.axiom_bounds.label(),
1168        },
1169        "retrieval": {
1170            "triple_count": retrieval.triple_count,
1171            "daemon_match_count": retrieval.daemon_match_count,
1172            "citations": retrieval.citations,
1173            "provenance_hashes": retrieval.provenance_hashes.iter().map(|h| format!("0x{h:016x}")).collect::<Vec<_>>(),
1174        },
1175        "ontology_routing": {
1176            "ontology_ids": routing.ontology_ids.clone(),
1177            "matched_terms": routing.matched_terms.clone(),
1178            "context_namespaces": routing.context_namespaces.iter().map(|h| format!("0x{h:016x}")).collect::<Vec<_>>(),
1179            "brief": routing.routing_brief.clone(),
1180        },
1181        "agent_semantic_profile": semantic_profile,
1182        "chat_graph_thread": thread_block,
1183        "chat_files": files_block,
1184        "cooperative_agents": cooperative_block,
1185        "inforg_context": inforg_block.clone(),
1186    });
1187    packet.graph_context_json =
1188        serde_json::to_string(&enriched_context).unwrap_or(packet.graph_context_json);
1189
1190    // Typed conditioning admission (Prompt Precision chat-graph stages): the
1191    // grounded chat-graph thread is a `RequestPart::chat_graph` admitted ahead
1192    // of evidence and ungrounded linear history, so a tight context window
1193    // prunes the flat fallback blocks before the DAG thread. Blocks are
1194    // reassembled in document order after selection — selection decides
1195    // admission, not layout.
1196    let user_tail = if thread_block.is_empty() {
1197        format!("\n\n---\nUser: {user_prompt}\n---")
1198    } else {
1199        format!("\n\n---\nUser (replying to graph fragment): {user_prompt}\n---")
1200    };
1201    // Byte approximation of the active context window (~4 bytes per token);
1202    // 0 = unknown window → unbounded (pre-conditioning behaviour).
1203    let byte_cap = if env.context_window == 0 {
1204        usize::MAX
1205    } else {
1206        (env.context_window as usize).saturating_mul(4)
1207    };
1208
1209    let blocks = [
1210        RequestPart::required_instruction(&env.capability_briefing),
1211        RequestPart::evidence("agent-profile", &semantic_block, None),
1212        RequestPart::evidence("ontology-routing", &routing.routing_brief, None),
1213        RequestPart::history(&cooperative_block),
1214        RequestPart::chat_graph(&thread_block, reply_to_fragment_id),
1215        RequestPart::evidence("chat-files", &files_block, None),
1216        RequestPart::evidence("graph-retrieval", &retrieval.context_block, None),
1217        RequestPart::history(&inforg_block),
1218    ];
1219    let mut parts = [RequestPart::required_instruction(""); 9];
1220    parts[..8].copy_from_slice(&blocks);
1221    parts[8] = RequestPart::user_prompt(&user_tail);
1222
1223    let mut selected = [RequestPart::required_instruction(""); 9];
1224    let selected_count =
1225        select_prioritized_parts(&parts, byte_cap, &mut selected).map_err(|e| {
1226            format!("conditioning could not retain mandatory chat request parts: {e:?}")
1227        })?;
1228    let admitted = &selected[..selected_count];
1229
1230    let mut augmented = String::new();
1231    for part in &blocks {
1232        if part.content.is_empty() || !admitted.contains(part) {
1233            continue;
1234        }
1235        if !augmented.is_empty() {
1236            augmented.push_str("\n\n");
1237        }
1238        augmented.push_str(part.content);
1239    }
1240    augmented.push_str(&user_tail);
1241    packet.augmented_prompt = augmented;
1242
1243    Ok(packet)
1244}
1245
1246fn persist_citations(
1247    session_id: &str,
1248    storage: &Path,
1249    output: &AgentOutput,
1250    retrieval: &RetrievalBundle,
1251) -> Result<(), String> {
1252    let dir = chat_session::chats_dir(storage).join(session_id);
1253    std::fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
1254    let wal_path = dir.join("citations.wal");
1255    let mut wal = WriteAheadLog::open(&wal_path).map_err(|e| e.to_string())?;
1256
1257    let session_subject = q_hash(&format!("chat:session:{session_id}"));
1258    for hash in &output.provenance_quins {
1259        let object = *hash & OBJECT_HASH_MASK;
1260        let quin = NQuin {
1261            subject: session_subject,
1262            predicate: q_hash("q42:groundedBy"),
1263            object,
1264            context: q_hash("chat:agent"),
1265            metadata: 0,
1266            parity: session_subject ^ q_hash("q42:groundedBy") ^ object ^ q_hash("chat:agent"),
1267        };
1268        wal.append_mutation(&quin).map_err(|e| e.to_string())?;
1269    }
1270
1271    let meta_path = dir.join("last_inference.json");
1272    let meta = serde_json::json!({
1273        "provenance_count": output.provenance_quins.len(),
1274        "citations": retrieval.citations,
1275        "tokens": output.tokens_generated,
1276    });
1277    std::fs::write(
1278        meta_path,
1279        serde_json::to_string_pretty(&meta).unwrap_or_default(),
1280    )
1281    .map_err(|e| e.to_string())?;
1282    Ok(())
1283}
1284
1285/// NDJSON stream events for Flutter FRB.
1286pub fn stream_event_token(delta: &str) -> String {
1287    serde_json::json!({"event":"token","data":delta}).to_string()
1288}
1289
1290/// Done stream event.
1291pub fn stream_event_done(result: &ChatInferenceResult) -> String {
1292    serde_json::json!({"event":"done","data":result}).to_string()
1293}
1294
1295/// Error stream event.
1296pub fn stream_event_error(msg: &str) -> String {
1297    serde_json::json!({"event":"error","data":msg}).to_string()
1298}