Skip to main content

qualia_core_db/inference/conditioning_opt/
runtime_contract.rs

1//! Immutable, verified model-precision configuration for runtime chat lowering.
2//!
3//! A contract carries only the calibration controls that are safe to apply on
4//! every request. It is not a learned adapter and does not load model weights.
5//! The caller must bind it to a registered target and the matching active
6//! `ConditioningRegistry` profile before it is eligible for use.
7
8use crate::inference::conditioning::ConditioningBudget;
9
10/// How a chat lowerer must arrange the invariant portion of a prompt.
11#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
12#[serde(rename_all = "kebab-case")]
13pub enum PrefixConfiguration {
14    /// Keep the ordinary deterministic conditioning header before request data.
15    Standard,
16    /// Keep a canonical header byte-for-byte stable to make compatible prefix
17    /// cache implementations eligible for reuse.
18    CanonicalCacheAligned,
19}
20
21impl PrefixConfiguration {
22    /// Static string.
23    pub const fn as_str(self) -> &'static str {
24        match self {
25            Self::Standard => "standard",
26            Self::CanonicalCacheAligned => "canonical-cache-aligned",
27        }
28    }
29}
30
31/// Context reduction policy chosen during a verified calibration campaign.
32#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
33#[serde(rename_all = "kebab-case")]
34pub enum CompressionStrategy {
35    /// Preserve all context when it fits; otherwise preserve the deterministic
36    /// prefix and user request inside the configured cap.
37    PreservePrefix,
38    /// Prefer a compact context envelope while always retaining the user
39    /// request and conditioning header.
40    CompactContext,
41}
42
43impl CompressionStrategy {
44    /// Static string.
45    pub const fn as_str(self) -> &'static str {
46        match self {
47            Self::PreservePrefix => "preserve-prefix",
48            Self::CompactContext => "compact-context",
49        }
50    }
51}
52
53/// A model-specific precision contract that has passed an external evaluation
54/// and can be bound to an active profile version.
55#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
56pub struct ModelPrecisionContract {
57    pub profile_id: String,
58    pub profile_version: u64,
59    pub spec_identity: u64,
60    pub budget: ConditioningBudget,
61    pub prefix: PrefixConfiguration,
62    pub compression: CompressionStrategy,
63}
64
65impl ModelPrecisionContract {
66    /// Creates a default `ModelPrecisionContract`.
67    pub fn new(
68        profile_id: impl Into<String>,
69        profile_version: u64,
70        spec_identity: u64,
71        budget: ConditioningBudget,
72        prefix: PrefixConfiguration,
73        compression: CompressionStrategy,
74    ) -> Result<Self, &'static str> {
75        let profile_id = profile_id.into();
76        if profile_id.is_empty()
77            || profile_version == 0
78            || budget.input_tokens == 0
79            || budget.output_tokens == 0
80            || budget.max_bytes == 0
81        {
82            return Err("invalid model precision contract");
83        }
84        Ok(Self {
85            profile_id,
86            profile_version,
87            spec_identity,
88            budget,
89            prefix,
90            compression,
91        })
92    }
93}