Skip to main content

clm_rust_core/layer0/
gtime.rs

1//! Layer 0: GTime formatting, parsing, and canonical timestamps.
2//! Canonical Path: kernel/clm_rust_core/src/layer0/gtime.rs
3//! Parity: TypeScript `src/layer0/gtime.ts`, Python `clm/layer0/gtime.py`
4
5use std::collections::BTreeMap;
6use serde::{Deserialize, Serialize};
7
8pub use super::gtime_attribution::*;
9
10pub const DEFAULT_G_TIME_LOCALE: &str = "UTC";
11pub const G_TIME_AUTHOR_EXTENSION: &str = "did";
12pub const G_TIME_KEY_EXTENSION: &str = "kid";
13pub const G_TIME_SIGNATURE_EXTENSION: &str = "sig";
14pub const LEGACY_G_TIME_PREFIX: &str = "a:";
15
16pub const G_TIME_EXTENSIONS: &[&str] = &[G_TIME_AUTHOR_EXTENSION, G_TIME_KEY_EXTENSION, G_TIME_SIGNATURE_EXTENSION];
17
18pub(crate) fn canonical_algorithm_name(name: &str) -> String {
19    let lower = name.trim().to_lowercase();
20    if lower == crate::layer0::vocabulary::HASH_ALGORITHM_SHA_256 {
21        crate::layer0::vocabulary::HASH_ALGORITHM_SHA256.to_string()
22    } else {
23        lower
24    }
25}
26
27#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
28pub enum GTimeForm {
29    Pipe,
30    LegacyTs,
31}
32
33#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
34pub struct DeclaredGTime {
35    pub form: GTimeForm,
36    pub algorithm: String,
37    pub timestamp: String,
38    pub locale: String,
39    pub extensions: BTreeMap<String, String>,
40    pub raw: String,
41}
42
43#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
44pub struct LegacyGTime {
45    pub timestamp: String,
46    pub raw: String,
47}
48
49#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
50pub struct MalformedGTime {
51    pub raw: String,
52    pub reason: String,
53}
54
55#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
56pub enum ParsedGTime {
57    Declared(DeclaredGTime),
58    Legacy(LegacyGTime),
59    Malformed(MalformedGTime),
60}
61
62impl ParsedGTime {
63    pub fn is_declared(&self) -> bool {
64        matches!(self, ParsedGTime::Declared(_))
65    }
66    pub fn is_legacy(&self) -> bool {
67        matches!(self, ParsedGTime::Legacy(_))
68    }
69    pub fn is_malformed(&self) -> bool {
70        matches!(self, ParsedGTime::Malformed(_))
71    }
72}
73
74pub fn normalize_g_time_timestamp(timestamp: &str) -> Result<String, String> {
75    let ts = timestamp.trim();
76    if !ts.is_ascii() {
77        return Err("Invalid g_time timestamp: non-ASCII characters".to_string());
78    }
79    // Historical coordinates may omit the offset. Match Python's UTC policy
80    // for this form; parsing never changes the stored coordinate itself.
81    if let Ok(naive) = chrono::NaiveDateTime::parse_from_str(ts, "%Y-%m-%dT%H:%M:%S%.f") {
82        return Ok(naive
83            .and_utc()
84            .to_rfc3339_opts(chrono::SecondsFormat::Millis, true));
85    }
86    let parsed = match chrono::DateTime::parse_from_rfc3339(ts) {
87        Ok(dt) => dt,
88        Err(err) => {
89            if ts.len() < 5 {
90                return Err(format!("Invalid g_time timestamp: {err}"));
91            }
92            let offset_start = ts.len() - 5;
93            let offset = &ts[offset_start..];
94            if (offset.starts_with('+') || offset.starts_with('-'))
95                && offset[1..].chars().all(|ch| ch.is_ascii_digit())
96            {
97                let normalized = format!("{}{}:{}", &ts[..offset_start], &offset[..3], &offset[3..]);
98                chrono::DateTime::parse_from_rfc3339(&normalized)
99                    .map_err(|e| format!("Invalid g_time timestamp: {e}"))?
100            } else {
101                return Err(format!("Invalid g_time timestamp: {err}"));
102            }
103        }
104    };
105    Ok(parsed.to_rfc3339_opts(chrono::SecondsFormat::Millis, true))
106}
107
108fn is_supported_algorithm(algo: &str) -> bool {
109    let a = algo.trim().to_lowercase();
110    matches!(a.as_str(), crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3 | crate::layer0::vocabulary::HASH_ALGORITHM_SHA256 | crate::layer0::vocabulary::HASH_ALGORITHM_SHA_256 | crate::layer0::vocabulary::HASH_ALGORITHM_SHA384 | crate::layer0::vocabulary::HASH_ALGORITHM_SHA512)
111        || crate::hash::global_registry().lock().map(|registry| registry.get(&format!("{a}:")).is_some()).unwrap_or(false)
112}
113
114pub fn format_canonical_g_time(
115    algo: &str,
116    timestamp: &str,
117    locale: &str,
118    extensions: Option<&BTreeMap<String, String>>,
119) -> String {
120    let norm_algo = if algo.trim().eq_ignore_ascii_case(crate::layer0::vocabulary::HASH_ALGORITHM_SHA_256) {
121        crate::layer0::vocabulary::HASH_ALGORITHM_SHA256.to_string()
122    } else {
123        algo.trim().trim_end_matches(':').to_lowercase()
124    };
125    let norm_ts = normalize_g_time_timestamp(timestamp).unwrap_or_else(|_| timestamp.to_string());
126    let mut base = format!("{}|{}|{}", norm_algo, norm_ts, locale);
127    if let Some(exts) = extensions {
128        for (k, v) in exts.iter() {
129            if !v.is_empty() {
130                base.push_str(&format!("|{}={}", k, v));
131            }
132        }
133    }
134    base
135}
136
137pub fn stamp_g_time(
138    algo: &str,
139    timestamp: Option<&str>,
140    locale: Option<&str>,
141    extensions: Option<&BTreeMap<String, String>>,
142) -> String {
143    let now = chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Millis, true);
144    let ts = timestamp.unwrap_or(&now);
145    let loc = locale.unwrap_or(DEFAULT_G_TIME_LOCALE);
146    format_canonical_g_time(algo, ts, loc, extensions)
147}
148
149fn is_valid_ext_key(key: &str) -> bool {
150    if key.is_empty() || key.len() > 32 {
151        return false;
152    }
153    let mut chars = key.chars();
154    match chars.next() {
155        Some(c) if c.is_ascii_lowercase() => {}
156        _ => return false,
157    }
158    chars.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_' || c == '-')
159}
160
161fn parse_extensions(
162    segments: &[&str],
163    separator: char,
164    require_registered: bool,
165) -> Result<BTreeMap<String, String>, String> {
166    let mut map = BTreeMap::new();
167    for seg in segments {
168        let s = seg.trim();
169        if s.is_empty() {
170            continue;
171        }
172        let Some((k_raw, v_raw)) = s.split_once(separator) else {
173            return Err(format!("Extension segment lacks a '{}' separator: \"{}\"", separator, s));
174        };
175        let key = k_raw.trim().to_lowercase();
176        let val = v_raw.trim().to_string();
177        if !is_valid_ext_key(&key) {
178            return Err(format!("Invalid extension key: \"{}\"", key));
179        }
180        if require_registered && !G_TIME_EXTENSIONS.contains(&key.as_str()) {
181            return Err(format!(
182                "Unregistered extension key: \"{}\" (registered: {})",
183                key,
184                G_TIME_EXTENSIONS.join(", ")
185            ));
186        }
187        if map.contains_key(&key) {
188            return Err(format!("Duplicate extension key: \"{}\"", key));
189        }
190        if val.is_empty() || val.contains('|') || val.contains(';') {
191            return Err(format!("Empty or delimiter-bearing extension value for \"{}\"", key));
192        }
193        map.insert(key, val);
194    }
195    Ok(map)
196}
197
198pub fn parse_g_time(raw: &str) -> ParsedGTime {
199    let s = raw.trim();
200    if s.is_empty() {
201        return ParsedGTime::Malformed(MalformedGTime {
202            raw: raw.to_string(),
203            reason: "Empty or non-string g_time".to_string(),
204        });
205    }
206
207    if s.contains('|') {
208        let parts: Vec<&str> = s.split('|').collect();
209        if parts.len() < 3 {
210            return ParsedGTime::Malformed(MalformedGTime {
211                raw: s.to_string(),
212                reason: format!("Pipe form requires at least 3 fields, found {}", parts.len()),
213            });
214        }
215        let algo = parts[0].trim().to_lowercase();
216        if !is_supported_algorithm(&algo) {
217            return ParsedGTime::Malformed(MalformedGTime {
218                raw: s.to_string(),
219                reason: format!("Unsupported algorithm in coordinate a: \"{}\"", parts[0]),
220            });
221        }
222        let ts_str = parts[1].trim();
223        if normalize_g_time_timestamp(ts_str).is_err() {
224            return ParsedGTime::Malformed(MalformedGTime {
225                raw: s.to_string(),
226                reason: format!("Invalid timestamp in coordinate t: \"{}\"", parts[1]),
227            });
228        }
229        let locale = parts[2].trim();
230        if locale.contains('=') {
231            return ParsedGTime::Malformed(MalformedGTime {
232                raw: s.to_string(),
233                reason: format!("Coordinate c must be a locale, not an extension: \"{}\"", locale),
234            });
235        }
236        match parse_extensions(&parts[3..], '=', true) {
237            Ok(exts) => ParsedGTime::Declared(DeclaredGTime {
238                form: GTimeForm::Pipe,
239                algorithm: algo,
240                timestamp: ts_str.to_string(),
241                locale: locale.to_string(),
242                extensions: exts,
243                raw: s.to_string(),
244            }),
245            Err(reason) => ParsedGTime::Malformed(MalformedGTime {
246                raw: s.to_string(),
247                reason,
248            }),
249        }
250    } else if s.starts_with(LEGACY_G_TIME_PREFIX) {
251        let mut kv_map = BTreeMap::new();
252        for part in s.split(';') {
253            let trimmed = part.trim();
254            if trimmed.is_empty() {
255                continue;
256            }
257            let Some((k, v)) = trimmed.split_once(':') else {
258                return ParsedGTime::Malformed(MalformedGTime {
259                    raw: s.to_string(),
260                    reason: format!("Segment lacks key:value separator: \"{}\"", trimmed),
261                });
262            };
263            let k = k.trim().to_string();
264            let v = v.trim().to_string();
265            if k.is_empty() {
266                return ParsedGTime::Malformed(MalformedGTime {
267                    raw: s.to_string(),
268                    reason: format!("Empty key in segment: \"{}\"", trimmed),
269                });
270            }
271            if kv_map.contains_key(&k) {
272                return ParsedGTime::Malformed(MalformedGTime {
273                    raw: s.to_string(),
274                    reason: format!("Duplicate key in g_time: \"{}\"", k),
275                });
276            }
277            kv_map.insert(k, v);
278        }
279        let Some(algo_raw) = kv_map.remove("a") else {
280            return ParsedGTime::Malformed(MalformedGTime {
281                raw: s.to_string(),
282                reason: "Unsupported or missing algorithm 'a'".to_string(),
283            });
284        };
285        if !is_supported_algorithm(&algo_raw) {
286            return ParsedGTime::Malformed(MalformedGTime {
287                raw: s.to_string(),
288                reason: format!("Unsupported or missing algorithm 'a': \"{}\"", algo_raw),
289            });
290        }
291        let Some(ts_raw) = kv_map.remove("t") else {
292            return ParsedGTime::Malformed(MalformedGTime {
293                raw: s.to_string(),
294                reason: "Invalid or missing timestamp 't'".to_string(),
295            });
296        };
297        if normalize_g_time_timestamp(&ts_raw).is_err() {
298            return ParsedGTime::Malformed(MalformedGTime {
299                raw: s.to_string(),
300                reason: format!("Invalid or missing timestamp 't': \"{}\"", ts_raw),
301            });
302        }
303        let locale = kv_map.remove("c").unwrap_or_default();
304        ParsedGTime::Declared(DeclaredGTime {
305            form: GTimeForm::LegacyTs,
306            algorithm: algo_raw,
307            timestamp: ts_raw,
308            locale,
309            extensions: kv_map,
310            raw: s.to_string(),
311        })
312    } else if normalize_g_time_timestamp(s).is_ok() {
313        ParsedGTime::Legacy(LegacyGTime {
314            timestamp: s.to_string(),
315            raw: s.to_string(),
316        })
317    } else {
318        ParsedGTime::Malformed(MalformedGTime {
319            raw: s.to_string(),
320            reason: "Unrecognised g_time shape".to_string(),
321        })
322    }
323}
324
325/// Monotonic instant read supplied by Layer 0 (non-census).
326pub fn monotonic_now() -> std::time::Instant {
327    std::time::Instant::now()
328}
329
330/// Wall-clock UNIX epoch nanoseconds supplied by Layer 0 (non-census).
331pub fn unix_timestamp_nanos() -> u128 {
332    std::time::SystemTime::now()
333        .duration_since(std::time::UNIX_EPOCH)
334        .map(|d| d.as_nanos())
335        .unwrap_or(0)
336}