Skip to main content

qualia_core_db/inference/conditioning/
prepared_request.rs

1//! Prepared conditioning request snapshot and exact-token admission gating.
2//!
3//! Enforces:
4//! 1. Dual limits: both `max_bytes` and `input_tokens` verified against the exact final rendered stream.
5//! 2. Separate output reservation: `actual_input_tokens + reserved_output_tokens <= supported_context_tokens`.
6//! 3. Full metadata snapshot: binds profile ID, version, evidence revision, access scope,
7//!    model instance, adapter hash, and rendered token digest into the prepared request.
8//! 4. Generation of a canonical `InferenceCacheKey` compatible with the Tier-1 prefix cache.
9
10use super::spec::ConditioningError;
11use crate::inference::inference_agent::prefix_cache::InferenceCacheKey;
12
13/// Snapshot of a fully validated and admitted conditioning request ready for execution.
14#[derive(Debug, Clone, PartialEq, Eq)]
15pub struct PreparedConditioningSnapshot {
16    pub profile_id: String,
17    pub profile_version: u32,
18    pub spec_identity: u64,
19    pub evidence_revision: u64,
20    pub access_scope: u64,
21    pub model_instance: u64,
22    pub adapter_hash: u64,
23    pub tokenizer_revision: u64,
24    pub actual_input_tokens: u32,
25    pub reserved_output_tokens: u32,
26    pub exact_tokens: Vec<u32>,
27}
28
29impl PreparedConditioningSnapshot {
30    /// Create and validate a prepared request snapshot against exact context ceilings.
31    ///
32    /// Fails closed with `ContextBudgetExceeded` if:
33    /// - rendered tokens exceed `max_input_tokens`
34    /// - rendered bytes exceed `max_bytes`
35    /// - total tokens (`actual_input_tokens + reserved_output_tokens +
36    ///   thinking_token_budget`) exceed `supported_context_tokens`
37    pub fn prepare(
38        profile_id: impl Into<String>,
39        profile_version: u32,
40        spec_identity: u64,
41        evidence_revision: u64,
42        access_scope: u64,
43        model_instance: u64,
44        adapter_hash: u64,
45        tokenizer_revision: u64,
46        exact_tokens: Vec<u32>,
47        raw_rendered_bytes: usize,
48        max_bytes: usize,
49        max_input_tokens: u32,
50        reserved_output_tokens: u32,
51        thinking_token_budget: Option<u32>,
52        supported_context_tokens: u32,
53    ) -> Result<Self, ConditioningError> {
54        let actual_input_tokens = exact_tokens.len() as u32;
55
56        // Byte ceiling check
57        if raw_rendered_bytes > max_bytes {
58            return Err(ConditioningError::ContextBudgetExceeded);
59        }
60
61        // Token ceiling check
62        if actual_input_tokens > max_input_tokens {
63            return Err(ConditioningError::ContextBudgetExceeded);
64        }
65
66        // Deliberation reservation: thinking tokens occupy the same context
67        // envelope as visible output, so they are folded into the reserved
68        // output side before the envelope check.
69        let effective_output_tokens = reserved_output_tokens
70            .checked_add(thinking_token_budget.unwrap_or(0))
71            .ok_or(ConditioningError::ContextBudgetExceeded)?;
72
73        // Total context envelope check (input + reserved output <= supported context)
74        let total_tokens = actual_input_tokens
75            .checked_add(effective_output_tokens)
76            .ok_or(ConditioningError::ContextBudgetExceeded)?;
77
78        if total_tokens > supported_context_tokens {
79            return Err(ConditioningError::ContextBudgetExceeded);
80        }
81
82        Ok(Self {
83            profile_id: profile_id.into(),
84            profile_version,
85            spec_identity,
86            evidence_revision,
87            access_scope,
88            model_instance,
89            adapter_hash,
90            tokenizer_revision,
91            actual_input_tokens,
92            reserved_output_tokens,
93            exact_tokens,
94        })
95    }
96
97    /// Derive the Tier-1 prefix cache key for this prepared request.
98    pub fn derive_cache_key(&self, kv_floats: usize, n_layers: usize) -> InferenceCacheKey {
99        InferenceCacheKey::with_provenance(
100            self.model_instance,
101            self.tokenizer_revision,
102            self.adapter_hash,
103            self.access_scope,
104            self.spec_identity,
105            &self.exact_tokens,
106            self.access_scope,
107            kv_floats,
108            n_layers,
109        )
110    }
111
112    /// Check compatibility with another snapshot (for cache namespace and session binding).
113    pub fn is_compatible_with(&self, other: &Self) -> bool {
114        self.profile_id == other.profile_id
115            && self.profile_version == other.profile_version
116            && self.spec_identity == other.spec_identity
117            && self.evidence_revision == other.evidence_revision
118            && self.access_scope == other.access_scope
119            && self.model_instance == other.model_instance
120            && self.adapter_hash == other.adapter_hash
121            && self.tokenizer_revision == other.tokenizer_revision
122    }
123}
124
125#[cfg(test)]
126mod tests {
127    use super::*;
128
129    #[test]
130    fn test_prepared_request_exact_token_admission() {
131        let tokens = vec![1, 100, 200, 300, 2]; // 5 tokens
132        let prep = PreparedConditioningSnapshot::prepare(
133            "medical_v1",
134            1,
135            0x101,
136            1,
137            0x42,
138            0xABCD,
139            0,
140            1 | (2 << 32),
141            tokens,
142            50,   // raw bytes
143            100,  // max bytes
144            10,   // max input tokens
145            5,    // reserved output tokens
146            None, // no thinking reservation
147            20,   // supported context tokens (5 + 5 <= 20)
148        );
149
150        assert!(prep.is_ok());
151        let snap = prep.unwrap();
152        assert_eq!(snap.actual_input_tokens, 5);
153        assert_eq!(snap.reserved_output_tokens, 5);
154
155        let key = snap.derive_cache_key(1024, 32);
156        assert_eq!(key.model_instance, 0xABCD);
157        assert_eq!(key.adapter_hash, 0);
158        assert_eq!(key.tenant_scope, 0x42);
159        assert_eq!(key.profile_spec_hash, 0x101);
160        assert_eq!(key.prompt_token_count, 5);
161    }
162
163    #[test]
164    fn test_prepared_request_context_overflow_rejected() {
165        let tokens = vec![1; 100]; // 100 tokens
166        let prep = PreparedConditioningSnapshot::prepare(
167            "general_v1",
168            1,
169            0x101,
170            1,
171            0x42,
172            0xABCD,
173            0,
174            1 | (2 << 32),
175            tokens,
176            500,
177            1000,
178            200,
179            50, // 100 + 50 = 150 > 128 context
180            None,
181            128,
182        );
183
184        assert_eq!(prep.err(), Some(ConditioningError::ContextBudgetExceeded));
185    }
186
187    #[test]
188    fn test_thinking_budget_counts_against_context_envelope() {
189        let tokens = vec![1; 100]; // 100 tokens
190                                   // 100 input + 20 output + 20 thinking = 140 > 128 context → fail closed.
191        let prep = PreparedConditioningSnapshot::prepare(
192            "thinking_v1",
193            1,
194            0x101,
195            1,
196            0x42,
197            0xABCD,
198            0,
199            1 | (2 << 32),
200            tokens.clone(),
201            500,
202            1000,
203            200,
204            20,
205            Some(20),
206            128,
207        );
208        assert_eq!(prep.err(), Some(ConditioningError::ContextBudgetExceeded));
209
210        // Same envelope without the thinking reservation admits (100 + 20 <= 128).
211        let prep_ok = PreparedConditioningSnapshot::prepare(
212            "thinking_v1",
213            1,
214            0x101,
215            1,
216            0x42,
217            0xABCD,
218            0,
219            1 | (2 << 32),
220            tokens,
221            500,
222            1000,
223            200,
224            20,
225            None,
226            128,
227        );
228        assert!(prep_ok.is_ok());
229    }
230}