clm-kernel 0.0.13

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Layer 0: GTime formatting, parsing, and canonical timestamps.
//! Canonical Path: kernel/clm_rust_core/src/layer0/gtime.rs
//! Parity: TypeScript `src/layer0/gtime.ts`, Python `clm/layer0/gtime.py`

use std::collections::BTreeMap;
use serde::{Deserialize, Serialize};

pub use super::gtime_attribution::*;

pub const G_TIME_EXTENSIONS: &[&str] = &["did", "kid", "sig"];

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum GTimeForm {
    Pipe,
    LegacyTs,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeclaredGTime {
    pub form: GTimeForm,
    pub algorithm: String,
    pub timestamp: String,
    pub locale: String,
    pub extensions: BTreeMap<String, String>,
    pub raw: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LegacyGTime {
    pub timestamp: String,
    pub raw: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MalformedGTime {
    pub raw: String,
    pub reason: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum ParsedGTime {
    Declared(DeclaredGTime),
    Legacy(LegacyGTime),
    Malformed(MalformedGTime),
}

impl ParsedGTime {
    pub fn is_declared(&self) -> bool {
        matches!(self, ParsedGTime::Declared(_))
    }
    pub fn is_legacy(&self) -> bool {
        matches!(self, ParsedGTime::Legacy(_))
    }
    pub fn is_malformed(&self) -> bool {
        matches!(self, ParsedGTime::Malformed(_))
    }
}

pub fn normalize_g_time_timestamp(timestamp: &str) -> Result<String, String> {
    let ts = timestamp.trim();
    let parsed = match chrono::DateTime::parse_from_rfc3339(ts) {
        Ok(dt) => dt,
        Err(err) => {
            if ts.len() < 5 {
                return Err(format!("Invalid g_time timestamp: {err}"));
            }
            let offset_start = ts.len() - 5;
            let offset = &ts[offset_start..];
            if (offset.starts_with('+') || offset.starts_with('-'))
                && offset[1..].chars().all(|ch| ch.is_ascii_digit())
            {
                let normalized = format!("{}{}:{}", &ts[..offset_start], &offset[..3], &offset[3..]);
                chrono::DateTime::parse_from_rfc3339(&normalized)
                    .map_err(|e| format!("Invalid g_time timestamp: {e}"))?
            } else {
                return Err(format!("Invalid g_time timestamp: {err}"));
            }
        }
    };
    Ok(parsed.to_rfc3339_opts(chrono::SecondsFormat::Millis, true))
}

fn is_supported_algorithm(algo: &str) -> bool {
    let a = algo.trim().to_lowercase();
    matches!(a.as_str(), "blake3" | "sha256" | "sha-256" | "sha384" | "sha512")
}

pub fn format_canonical_g_time(
    algo: &str,
    timestamp: &str,
    locale: &str,
    extensions: Option<&BTreeMap<String, String>>,
) -> String {
    let norm_algo = if algo.trim().eq_ignore_ascii_case("sha-256") {
        "sha256".to_string()
    } else {
        algo.trim().trim_end_matches(':').to_lowercase()
    };
    let norm_ts = normalize_g_time_timestamp(timestamp).unwrap_or_else(|_| timestamp.to_string());
    let mut base = format!("{}|{}|{}", norm_algo, norm_ts, locale);
    if let Some(exts) = extensions {
        for (k, v) in exts.iter() {
            if !v.is_empty() {
                base.push_str(&format!("|{}={}", k, v));
            }
        }
    }
    base
}

pub fn stamp_g_time(
    algo: &str,
    timestamp: Option<&str>,
    locale: Option<&str>,
    extensions: Option<&BTreeMap<String, String>>,
) -> String {
    let now = chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Millis, true);
    let ts = timestamp.unwrap_or(&now);
    let loc = locale.unwrap_or("UTC");
    format_canonical_g_time(algo, ts, loc, extensions)
}

fn is_valid_ext_key(key: &str) -> bool {
    if key.is_empty() || key.len() > 32 {
        return false;
    }
    let mut chars = key.chars();
    match chars.next() {
        Some(c) if c.is_ascii_lowercase() => {}
        _ => return false,
    }
    chars.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_' || c == '-')
}

fn parse_extensions(
    segments: &[&str],
    separator: char,
    require_registered: bool,
) -> Result<BTreeMap<String, String>, String> {
    let mut map = BTreeMap::new();
    for seg in segments {
        let s = seg.trim();
        if s.is_empty() {
            continue;
        }
        let Some((k_raw, v_raw)) = s.split_once(separator) else {
            return Err(format!("Extension segment lacks a '{}' separator: \"{}\"", separator, s));
        };
        let key = k_raw.trim().to_lowercase();
        let val = v_raw.trim().to_string();
        if !is_valid_ext_key(&key) {
            return Err(format!("Invalid extension key: \"{}\"", key));
        }
        if require_registered && !G_TIME_EXTENSIONS.contains(&key.as_str()) {
            return Err(format!(
                "Unregistered extension key: \"{}\" (registered: {})",
                key,
                G_TIME_EXTENSIONS.join(", ")
            ));
        }
        if map.contains_key(&key) {
            return Err(format!("Duplicate extension key: \"{}\"", key));
        }
        if val.is_empty() || val.contains('|') || val.contains(';') {
            return Err(format!("Empty or delimiter-bearing extension value for \"{}\"", key));
        }
        map.insert(key, val);
    }
    Ok(map)
}

pub fn parse_g_time(raw: &str) -> ParsedGTime {
    let s = raw.trim();
    if s.is_empty() {
        return ParsedGTime::Malformed(MalformedGTime {
            raw: raw.to_string(),
            reason: "Empty or non-string g_time".to_string(),
        });
    }

    if s.contains('|') {
        let parts: Vec<&str> = s.split('|').collect();
        if parts.len() < 3 {
            return ParsedGTime::Malformed(MalformedGTime {
                raw: s.to_string(),
                reason: format!("Pipe form requires at least 3 fields, found {}", parts.len()),
            });
        }
        let algo = parts[0].trim().to_lowercase();
        if !is_supported_algorithm(&algo) {
            return ParsedGTime::Malformed(MalformedGTime {
                raw: s.to_string(),
                reason: format!("Unsupported algorithm in coordinate a: \"{}\"", parts[0]),
            });
        }
        let ts_str = parts[1].trim();
        if normalize_g_time_timestamp(ts_str).is_err() {
            return ParsedGTime::Malformed(MalformedGTime {
                raw: s.to_string(),
                reason: format!("Invalid timestamp in coordinate t: \"{}\"", parts[1]),
            });
        }
        let locale = parts[2].trim();
        if locale.contains('=') {
            return ParsedGTime::Malformed(MalformedGTime {
                raw: s.to_string(),
                reason: format!("Coordinate c must be a locale, not an extension: \"{}\"", locale),
            });
        }
        match parse_extensions(&parts[3..], '=', true) {
            Ok(exts) => ParsedGTime::Declared(DeclaredGTime {
                form: GTimeForm::Pipe,
                algorithm: algo,
                timestamp: ts_str.to_string(),
                locale: locale.to_string(),
                extensions: exts,
                raw: s.to_string(),
            }),
            Err(reason) => ParsedGTime::Malformed(MalformedGTime {
                raw: s.to_string(),
                reason,
            }),
        }
    } else if s.starts_with("a:") {
        let mut kv_map = BTreeMap::new();
        for part in s.split(';') {
            let trimmed = part.trim();
            if trimmed.is_empty() {
                continue;
            }
            let Some((k, v)) = trimmed.split_once(':') else {
                return ParsedGTime::Malformed(MalformedGTime {
                    raw: s.to_string(),
                    reason: format!("Segment lacks key:value separator: \"{}\"", trimmed),
                });
            };
            let k = k.trim().to_string();
            let v = v.trim().to_string();
            if k.is_empty() {
                return ParsedGTime::Malformed(MalformedGTime {
                    raw: s.to_string(),
                    reason: format!("Empty key in segment: \"{}\"", trimmed),
                });
            }
            if kv_map.contains_key(&k) {
                return ParsedGTime::Malformed(MalformedGTime {
                    raw: s.to_string(),
                    reason: format!("Duplicate key in g_time: \"{}\"", k),
                });
            }
            kv_map.insert(k, v);
        }
        let Some(algo_raw) = kv_map.remove("a") else {
            return ParsedGTime::Malformed(MalformedGTime {
                raw: s.to_string(),
                reason: "Unsupported or missing algorithm 'a'".to_string(),
            });
        };
        if !is_supported_algorithm(&algo_raw) {
            return ParsedGTime::Malformed(MalformedGTime {
                raw: s.to_string(),
                reason: format!("Unsupported or missing algorithm 'a': \"{}\"", algo_raw),
            });
        }
        let Some(ts_raw) = kv_map.remove("t") else {
            return ParsedGTime::Malformed(MalformedGTime {
                raw: s.to_string(),
                reason: "Invalid or missing timestamp 't'".to_string(),
            });
        };
        if normalize_g_time_timestamp(&ts_raw).is_err() {
            return ParsedGTime::Malformed(MalformedGTime {
                raw: s.to_string(),
                reason: format!("Invalid or missing timestamp 't': \"{}\"", ts_raw),
            });
        }
        let locale = kv_map.remove("c").unwrap_or_default();
        ParsedGTime::Declared(DeclaredGTime {
            form: GTimeForm::LegacyTs,
            algorithm: algo_raw,
            timestamp: ts_raw,
            locale,
            extensions: kv_map,
            raw: s.to_string(),
        })
    } else if normalize_g_time_timestamp(s).is_ok() {
        ParsedGTime::Legacy(LegacyGTime {
            timestamp: s.to_string(),
            raw: s.to_string(),
        })
    } else {
        ParsedGTime::Malformed(MalformedGTime {
            raw: s.to_string(),
            reason: "Unrecognised g_time shape".to_string(),
        })
    }
}