Skip to main content

clm_rust_core/layer0/
transition.rs

1//! Layer 0: canonical state-transition grammar (Sprint 530).
2//!
3//! `CHANGE_CALCULUS`, `TransitionPayload` and their validation were defined three
4//! times in this crate: in `handle_kind.rs`, in `layer2/sync/types.rs`, and inline
5//! in `layer2/sync/codec.rs`. They are Layer 0 primitives, so they live here and the
6//! other modules re-export them.
7
8use serde::{Deserialize, Serialize};
9use std::collections::BTreeMap;
10
11/// The closed set of transition kinds (`INV-TAPE-04`). The KIND of a change is card
12/// content in the lifecycle sidecar, never a column.
13pub const CHANGE_CALCULUS: &[&str] = &[
14    "CREATE", "UPDATE", "SEAL", "RELOCATE", "ROTATE", "TOMBSTONE",
15    "SEED", "FORK", "PIN", "CONFLICT_BRANCH",
16];
17
18#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
19#[serde(rename_all = "camelCase")]
20pub struct TransitionPayload {
21    pub kind: String,
22    pub handle: String,
23    #[serde(default, skip_serializing_if = "Option::is_none")]
24    pub to_handle: Option<String>,
25    pub from: Option<String>,
26    pub to: Option<String>,
27    #[serde(default, skip_serializing_if = "Option::is_none")]
28    pub meta: Option<String>,
29    #[serde(default, skip_serializing_if = "Option::is_none")]
30    pub source_ref: Option<String>,
31    #[serde(default, skip_serializing_if = "Option::is_none")]
32    pub branch_ref: Option<String>,
33    pub clock: BTreeMap<String, u64>,
34    pub author: String,
35}
36
37/// A reference is a qualified hash when it is `blake3:` or `sha256:` plus 64 hex digits.
38pub fn is_qualified_hash(val: &str) -> bool {
39    val.split_once(':')
40        .map(|(a, h)| (a == crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3 || a == crate::layer0::vocabulary::HASH_ALGORITHM_SHA256) && h.len() == 64 && h.chars().all(|c| c.is_ascii_hexdigit()))
41        .unwrap_or(false)
42}
43
44pub fn validate_transition_payload(payload: &TransitionPayload) -> Result<(), String> {
45    if !CHANGE_CALCULUS.contains(&payload.kind.as_str()) {
46        return Err(format!("Invalid transition kind: {}", payload.kind));
47    }
48    if payload.handle.is_empty() || payload.author.is_empty() {
49        return Err("Transition handle and author must be non-empty".to_string());
50    }
51    for r in [&payload.from, &payload.to, &payload.meta, &payload.source_ref].into_iter().flatten() {
52        if !is_qualified_hash(r) {
53            return Err(format!("Reference must be a qualified hash: {r}"));
54        }
55    }
56    if payload.kind == "CREATE" && payload.from.is_some() {
57        return Err("CREATE transition must have from=null".to_string());
58    }
59    if payload.kind == "TOMBSTONE" && payload.to.is_some() {
60        return Err("TOMBSTONE transition must have to=null".to_string());
61    }
62    if payload.kind == "RELOCATE" && payload.to_handle.as_deref().unwrap_or("").is_empty() {
63        return Err("RELOCATE transition requires toHandle".to_string());
64    }
65    if payload.kind == "SEED" {
66        if payload.from.is_some() {
67            return Err("SEED transition must have from=null".to_string());
68        }
69        if payload.to.is_none() || payload.source_ref.is_none() {
70            return Err("SEED transition requires qualified to and sourceRef".to_string());
71        }
72    }
73    if payload.kind == "FORK" {
74        if payload.from.is_none() || payload.to.is_none() {
75            return Err("FORK transition requires active from and to hashes".to_string());
76        }
77        if payload.to_handle.as_deref().unwrap_or("").is_empty() {
78            return Err("FORK transition requires toHandle".to_string());
79        }
80        if payload.source_ref.is_none() {
81            return Err("FORK transition requires sourceRef provenance".to_string());
82        }
83    }
84    if payload.kind == "PIN" && (payload.from.is_none() || payload.to.is_none() || payload.from != payload.to) {
85        return Err("PIN transition requires active from and to hashes equal to current head".to_string());
86    }
87    if payload.kind == "CONFLICT_BRANCH" {
88        if payload.from.is_none() || payload.to.is_none() {
89            return Err("CONFLICT_BRANCH transition requires active from and to hashes".to_string());
90        }
91        if payload.branch_ref.as_deref().unwrap_or("").is_empty() {
92            return Err("CONFLICT_BRANCH transition requires non-empty branchRef".to_string());
93        }
94    }
95    Ok(())
96}