Skip to main content

clm_rust_core/layer0/
parameter_context.rs

1// @generated by tools/types/sync_runtime_contract.py from types/lattice/runtime_contract.json
2// DO NOT EDIT MANUALLY — run `python3 tools/types/sync_runtime_contract.py --write`
3// Normative Invariant: INV-596 (contract parameters reach kernel code through one ParameterContext)
4//! Contract parameters as one immutable Layer 0 value record, with a pure boundary parser.
5
6use std::collections::BTreeMap;
7
8/// Exit code of a boundary violation.
9pub const PRECONDITION_OR_BOUNDARY_VIOLATION: i32 = 5;
10/// Handle prefix of the parameter VCards.
11pub const VCARD_PARAMETER_PREFIX: &str = "urn:vcard:contract:param:";
12/// BLAKE3 digest of the contract NetMCard (INV-597); Layer 1 recomputes it and compares.
13pub const CONTRACT_NET_DIGEST: &str = "4d1e39310c6d7e9ed7ee594554d34f758a3b1df6ade491a16530a71445ac798f";
14/// Contract key and refinement base type, in contract order.
15pub const PARAMETER_TYPES: [(&str, &str); 7] = [
16    ("sqlite.busy_timeout_ms", "u32"),
17    ("sqlite.compaction_busy_timeout_ms", "u32"),
18    ("sqlite.lock_retry_max", "u32"),
19    ("sqlite.lock_retry_backoff_ms", "u32"),
20    ("codec.b64_chunk_bytes", "usize"),
21    ("text.encoding", "string"),
22    ("network.gateway_timeout_ms", "u32"),
23];
24
25/// Contract-owned parameters, resolved once at a process entry and passed inward.
26#[derive(Clone, Debug, PartialEq, Eq)]
27pub struct ParameterContext {
28    /// Wait duration for a SQLite write lock on an ordinary connection.
29    pub sqlite_busy_timeout_ms: u32,
30    /// Wait duration for a SQLite write lock during compaction.
31    pub sqlite_compaction_busy_timeout_ms: u32,
32    /// Maximum additional SQLite lock attempts after the initial attempt.
33    pub sqlite_lock_retry_max: u32,
34    /// Base interval for bounded linear SQLite lock retry backoff.
35    pub sqlite_lock_retry_backoff_ms: u32,
36    /// Byte chunk size for streaming base64 framing without internal padding.
37    pub codec_b64_chunk_bytes: usize,
38    /// Canonical text encoding for transport and persisted textual content.
39    pub text_encoding: String,
40    /// Request deadline for retrieving content through the handle gateway.
41    pub network_gateway_timeout_ms: u32,
42}
43
44impl Default for ParameterContext {
45    fn default() -> Self {
46        Self {
47            sqlite_busy_timeout_ms: 5000,
48            sqlite_compaction_busy_timeout_ms: 30000,
49            sqlite_lock_retry_max: 5,
50            sqlite_lock_retry_backoff_ms: 50,
51            codec_b64_chunk_bytes: 12288,
52            text_encoding: "utf-8".to_string(),
53            network_gateway_timeout_ms: 10000,
54        }
55    }
56}
57
58/// A boundary value met its contract refinement at bottom (MISU meet); the process halts.
59#[derive(Clone, Debug, PartialEq, Eq)]
60pub struct ParameterBoundaryError {
61    /// Contract key of the offending parameter.
62    pub key: String,
63    /// The boundary string that failed to narrow.
64    pub raw: String,
65    /// Why the value narrowed to bottom.
66    pub reason: String,
67    /// Boundary layer the value came from: `cli`, `env`, or `card`.
68    pub source: &'static str,
69}
70
71impl ParameterBoundaryError {
72    /// Process exit code for every boundary violation.
73    pub const EXIT_CODE: i32 = PRECONDITION_OR_BOUNDARY_VIOLATION;
74
75    fn new(key: &str, raw: &str, reason: String, source: &'static str) -> Self {
76        Self { key: key.to_string(), raw: raw.to_string(), reason, source }
77    }
78
79    /// Handle of the VCard whose refinement the value failed.
80    pub fn vcard(&self) -> String {
81        format!("{VCARD_PARAMETER_PREFIX}{}", self.key)
82    }
83}
84
85impl std::fmt::Display for ParameterBoundaryError {
86    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
87        write!(f, "{}={:?} from {}: {} ({})", self.key, self.raw, self.source, self.reason, self.vcard())
88    }
89}
90
91impl std::error::Error for ParameterBoundaryError {}
92
93/// A resolved parameter value, keyed by contract key in `ParameterContext::as_mapping`.
94#[derive(Clone, Debug, PartialEq, Eq)]
95pub enum ParameterValue {
96    /// An unsigned integer parameter.
97    Int(u64),
98    /// A string parameter.
99    Text(String),
100    /// A boolean parameter.
101    Bool(bool),
102}
103
104struct Spec {
105    key: &'static str,
106    env: &'static str,
107    low: u64,
108    high: u64,
109    multiple_of: u64,
110    allowed: Option<&'static [&'static str]>,
111}
112
113/// Boundary layers, highest precedence first after CLI: environment, then verified card overrides.
114struct Layers<'a> {
115    env: &'a BTreeMap<String, String>,
116    cli: &'a BTreeMap<String, String>,
117    card: &'a BTreeMap<String, String>,
118}
119
120impl<'a> Layers<'a> {
121    fn raw(&self, spec: &Spec) -> Option<(&'a str, &'static str)> {
122        if let Some(raw) = self.cli.get(spec.key) {
123            return Some((raw.as_str(), "cli"));
124        }
125        if let Some(raw) = self.env.get(spec.env) {
126            return Some((raw.as_str(), "env"));
127        }
128        self.card.get(spec.key).map(|raw| (raw.as_str(), "card"))
129    }
130}
131
132fn narrow_int(spec: &Spec, raw: &str, source: &'static str) -> Result<u64, ParameterBoundaryError> {
133    let bottom = |reason: String| ParameterBoundaryError::new(spec.key, raw, reason, source);
134    if raw.is_empty() || !raw.bytes().all(|byte| byte.is_ascii_digit()) {
135        return Err(bottom("not an unsigned decimal integer".to_string()));
136    }
137    let value: u64 = raw.parse().map_err(|_| bottom(format!("outside [{}, {}]", spec.low, spec.high)))?;
138    if value < spec.low || value > spec.high {
139        return Err(bottom(format!("outside [{}, {}]", spec.low, spec.high)));
140    }
141    if !value.is_multiple_of(spec.multiple_of) {
142        return Err(bottom(format!("not a multiple of {}", spec.multiple_of)));
143    }
144    Ok(value)
145}
146
147fn narrow_text(spec: &Spec, raw: &str, source: &'static str) -> Result<String, ParameterBoundaryError> {
148    if raw.is_empty() || spec.allowed.is_some_and(|allowed| !allowed.contains(&raw)) {
149        return Err(ParameterBoundaryError::new(spec.key, raw, "outside allowed_values".to_string(), source));
150    }
151    Ok(raw.to_string())
152}
153
154#[allow(dead_code)]
155fn narrow_bool(spec: &Spec, raw: &str, source: &'static str) -> Result<bool, ParameterBoundaryError> {
156    match raw {
157        "true" => Ok(true),
158        "false" => Ok(false),
159        _ => Err(ParameterBoundaryError::new(spec.key, raw, "not a boolean".to_string(), source)),
160    }
161}
162
163fn reject_unknown(layer: &BTreeMap<String, String>, source: &'static str) -> Result<(), ParameterBoundaryError> {
164    match layer.iter().find(|(key, _)| !SPECS.iter().any(|spec| spec.key == key.as_str())) {
165        Some((key, raw)) => Err(ParameterBoundaryError::new(key, raw, "unknown parameter".to_string(), source)),
166        None => Ok(()),
167    }
168}
169
170const SPECS: [Spec; 7] = [
171    Spec { key: "sqlite.busy_timeout_ms", env: "CLM_SQLITE_BUSY_TIMEOUT_MS", low: 100, high: 120000, multiple_of: 1, allowed: None },
172    Spec { key: "sqlite.compaction_busy_timeout_ms", env: "CLM_SQLITE_COMPACTION_BUSY_TIMEOUT_MS", low: 1000, high: 600000, multiple_of: 1, allowed: None },
173    Spec { key: "sqlite.lock_retry_max", env: "CLM_SQLITE_LOCK_RETRY_MAX", low: 0, high: 100, multiple_of: 1, allowed: None },
174    Spec { key: "sqlite.lock_retry_backoff_ms", env: "CLM_SQLITE_LOCK_RETRY_BACKOFF_MS", low: 1, high: 1000, multiple_of: 1, allowed: None },
175    Spec { key: "codec.b64_chunk_bytes", env: "CLM_CODEC_B64_CHUNK_BYTES", low: 3, high: 1048576, multiple_of: 3, allowed: None },
176    Spec { key: "text.encoding", env: "CLM_TEXT_ENCODING", low: 0, high: 0, multiple_of: 1, allowed: Some(&["utf-8"]) },
177    Spec { key: "network.gateway_timeout_ms", env: "CLM_NETWORK_GATEWAY_TIMEOUT_MS", low: 100, high: 120000, multiple_of: 1, allowed: None },
178];
179
180impl ParameterContext {
181    /// Resolve CLI over environment over contract default; any bottom is a `ParameterBoundaryError`.
182    pub fn from_mapping(env: &BTreeMap<String, String>, cli: &BTreeMap<String, String>) -> Result<Self, ParameterBoundaryError> {
183        Self::from_layers(env, cli, &BTreeMap::new())
184    }
185
186    /// Resolve CLI over environment over verified card override (contract keys) over contract default.
187    pub fn from_layers(env: &BTreeMap<String, String>, cli: &BTreeMap<String, String>, card: &BTreeMap<String, String>) -> Result<Self, ParameterBoundaryError> {
188        Self::default().with_layers(&Layers { env, cli, card })
189    }
190
191    /// A copy with `cli` (contract keys to boundary strings) applied and narrowed.
192    pub fn with_overrides(&self, cli: &BTreeMap<String, String>) -> Result<Self, ParameterBoundaryError> {
193        let empty = BTreeMap::new();
194        self.with_layers(&Layers { env: &empty, cli, card: &empty })
195    }
196
197    fn with_layers(&self, layers: &Layers<'_>) -> Result<Self, ParameterBoundaryError> {
198        reject_unknown(layers.cli, "cli")?;
199        reject_unknown(layers.card, "card")?;
200        let mut context = self.clone();
201        if let Some((raw, source)) = layers.raw(&SPECS[0]) { context.sqlite_busy_timeout_ms = u32::try_from(narrow_int(&SPECS[0], raw, source)?).expect("range fits the field"); }
202        if let Some((raw, source)) = layers.raw(&SPECS[1]) { context.sqlite_compaction_busy_timeout_ms = u32::try_from(narrow_int(&SPECS[1], raw, source)?).expect("range fits the field"); }
203        if let Some((raw, source)) = layers.raw(&SPECS[2]) { context.sqlite_lock_retry_max = u32::try_from(narrow_int(&SPECS[2], raw, source)?).expect("range fits the field"); }
204        if let Some((raw, source)) = layers.raw(&SPECS[3]) { context.sqlite_lock_retry_backoff_ms = u32::try_from(narrow_int(&SPECS[3], raw, source)?).expect("range fits the field"); }
205        if let Some((raw, source)) = layers.raw(&SPECS[4]) { context.codec_b64_chunk_bytes = usize::try_from(narrow_int(&SPECS[4], raw, source)?).expect("range fits the field"); }
206        if let Some((raw, source)) = layers.raw(&SPECS[5]) { context.text_encoding = narrow_text(&SPECS[5], raw, source)?; }
207        if let Some((raw, source)) = layers.raw(&SPECS[6]) { context.network_gateway_timeout_ms = u32::try_from(narrow_int(&SPECS[6], raw, source)?).expect("range fits the field"); }
208        Ok(context)
209    }
210
211    /// Contract key to resolved value.
212    pub fn as_mapping(&self) -> BTreeMap<&'static str, ParameterValue> {
213        let mut mapping = BTreeMap::new();
214        mapping.insert("sqlite.busy_timeout_ms", ParameterValue::Int(u64::from(self.sqlite_busy_timeout_ms)));
215        mapping.insert("sqlite.compaction_busy_timeout_ms", ParameterValue::Int(u64::from(self.sqlite_compaction_busy_timeout_ms)));
216        mapping.insert("sqlite.lock_retry_max", ParameterValue::Int(u64::from(self.sqlite_lock_retry_max)));
217        mapping.insert("sqlite.lock_retry_backoff_ms", ParameterValue::Int(u64::from(self.sqlite_lock_retry_backoff_ms)));
218        mapping.insert("codec.b64_chunk_bytes", ParameterValue::Int(self.codec_b64_chunk_bytes as u64));
219        mapping.insert("text.encoding", ParameterValue::Text(self.text_encoding.clone()));
220        mapping.insert("network.gateway_timeout_ms", ParameterValue::Int(u64::from(self.network_gateway_timeout_ms)));
221        mapping
222    }
223}