Skip to main content

clm_rust_core/layer0/
spec_profile.rs

1//! Layer 0: The payload profile `clm.spec.v1`: its constants, its refusal type and its depth rule
2//! Canonical Path: kernel/clm_rust_core/src/layer0/spec_profile.rs
3//!
4//! The scanner in `spec_scan` and the encoder, identities and keys in
5//! `spec_identity` share these names. `spec_identity` re-exports the public ones.
6
7use std::fmt;
8
9pub const SPEC_DOMAIN_TAG: &str = "clm.spec.v1";
10pub const SPEC_HASH_QUALIFIER: &str = crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3;
11pub const MAX_SAFE_INTEGER: i64 = crate::layer0::limits::SPEC_MAX_SAFE_INTEGER;
12pub const MIN_SAFE_INTEGER: i64 = -MAX_SAFE_INTEGER;
13/// Deepest nesting of arrays and objects that a payload may have. Anything
14/// deeper is refused as malformed, so the recursive walks stay inside a small
15/// and known share of the call stack.
16pub const MAX_NESTING_DEPTH: usize = crate::layer0::limits::SPEC_MAX_NESTING_DEPTH as usize;
17/// Deepest nesting of recipes. One recipe level adds three payload levels and
18/// the identity adds one, so this is the deepest recipe whose quoted form still
19/// fits in a payload. A deeper recipe is refused as malformed by every function.
20pub const MAX_RECIPE_DEPTH: usize = crate::layer0::limits::SPEC_MAX_RECIPE_DEPTH as usize;
21
22pub const REFUSED_FLOAT: &str = "float";
23pub const REFUSED_DUPLICATE_KEY: &str = "duplicate_key";
24pub const REFUSED_NON_ASCII_KEY: &str = "non_ascii_key";
25pub const REFUSED_INTEGER_RANGE: &str = "integer_out_of_range";
26pub const REFUSED_UNSUPPORTED_TYPE: &str = "unsupported_type";
27pub const REFUSED_INVALID_STRING: &str = "invalid_string";
28pub const REFUSED_MALFORMED: &str = "malformed";
29pub const REFUSED_ACTION_OPERAND: &str = "action_operand";
30pub const REFUSED_UNRESOLVED_INPUT: &str = "unresolved_input";
31pub const REFUSED_UNKNOWN_COMPONENT: &str = "unknown_component";
32
33pub const OPERAND_REFERENCE: &str = "reference";
34pub const OPERAND_DEFERRED: &str = "deferred";
35pub const OPERAND_ACTION: &str = "action";
36
37pub const KIND_RECIPE: &str = "recipe";
38pub const KIND_DEEP_KEY: &str = "deep_key";
39pub const KIND_SHALLOW_KEY: &str = "shallow_key";
40
41/// A payload or recipe falls outside the profile. `reason` is machine-readable.
42#[derive(Debug, Clone, PartialEq, Eq)]
43pub struct SpecProfileError {
44    pub reason: &'static str,
45    pub detail: String,
46}
47
48impl SpecProfileError {
49    pub(crate) fn new(reason: &'static str, detail: impl Into<String>) -> Self {
50        Self { reason, detail: detail.into() }
51    }
52}
53
54impl fmt::Display for SpecProfileError {
55    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
56        write!(formatter, "{}: {}", self.reason, self.detail)
57    }
58}
59
60impl std::error::Error for SpecProfileError {}
61
62pub(crate) type Refusable<T> = Result<T, SpecProfileError>;
63
64pub(crate) fn descend(depth: usize, limit: usize, what: &str) -> Refusable<usize> {
65    if depth >= limit {
66        return Err(SpecProfileError::new(REFUSED_MALFORMED, format!("{what} nests deeper than {limit} levels")));
67    }
68    Ok(depth + 1)
69}
70
71pub(crate) fn is_safe_integer(integer: i64) -> bool {
72    (MIN_SAFE_INTEGER..=MAX_SAFE_INTEGER).contains(&integer)
73}