1#[derive(Debug, Clone, PartialEq, Eq)]
27pub struct HandleKind {
28 pub sector: String,
29 pub kind: String,
30 pub handle: String,
31 pub declared: bool,
32 pub subject: Option<String>,
33}
34
35pub const KIND_SECTORS: &[(&str, &[&str])] = &[
37 (
39 "mcard",
40 &[
41 "content", "knowledge", "schema", "contract", "registry", "record", "projection",
42 "derived", "lifecycle",
43 "artifact", "commit", "design_decision", "feedback", "specification",
46 "sprint_status", "telemetry", "test_result",
47 "function",
49 ],
50 ),
51 ("doc", &["vault", "document"]),
52 ("pcard", &["program", "sprint", "fiber"]),
53 ("vcard", &["seal", "execution", "contract"]),
54 ("agent", &["root", "actor"]),
56 ("node", &["did", "peer"]),
57 ("key", &["pub", "rotate"]),
58 ("execution", &["record", "trace", "migration"]),
60 ("telemetry", &["event"]),
61];
62
63pub const CHANGE_CALCULUS: &[&str] = &[
66 "CREATE", "UPDATE", "SEAL", "RELOCATE", "ROTATE", "TOMBSTONE",
67];
68
69fn split_handle(handle: &str) -> Option<(&str, &str, Option<&str>)> {
74 let lower = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_lowercase() || b == b'_');
75 if let Some(rest) = handle.strip_prefix("urn:pcard:") {
76 let (kind, subject) = match rest.split_once(':') {
77 Some((k, s)) => (k, Some(s)),
78 None => (rest, None),
79 };
80 if !lower(kind) {
81 return None;
82 }
83 return Some(("pcard", kind, subject));
84 }
85 if let Some(rest) = handle.strip_prefix("urn:vcard:") {
86 let (kind, subject) = match rest.split_once(':') {
87 Some((k, s)) => (k, Some(s)),
88 None => (rest, None),
89 };
90 if !lower(kind) {
91 return None;
92 }
93 return Some(("vcard", kind, subject));
94 }
95 let rest = handle.strip_prefix("urn:mcard:")?;
98 let (sector, rest) = rest.split_once(':')?;
99 let (kind, subject) = match rest.split_once(':') {
100 Some((k, s)) => (k, Some(s)),
101 None => (rest, None),
102 };
103 if !lower(sector) || !lower(kind) {
104 return None;
105 }
106 Some((sector, kind, subject))
107}
108
109pub fn kind_of(handle: &str) -> Option<HandleKind> {
111 let (sector, kind, subject) = split_handle(handle)?;
112 let declared = KIND_SECTORS
113 .iter()
114 .find(|(s, _)| *s == sector)
115 .map(|(_, kinds)| kinds.contains(&kind))
116 .unwrap_or(false);
117 Some(HandleKind {
118 sector: sector.to_string(),
119 kind: kind.to_string(),
120 handle: handle.to_string(),
121 declared,
122 subject: subject.map(str::to_string),
123 })
124}
125
126pub fn sector_of(handle: &str) -> Option<&str> {
128 split_handle(handle).map(|(s, _, _)| s)
129}
130
131pub fn kind_name_of(handle: &str) -> Option<&str> {
133 split_handle(handle).map(|(_, k, _)| k)
134}
135
136pub fn is_sector(handle: &str, sector: &str) -> bool {
138 sector_of(handle) == Some(sector)
139}
140
141pub fn is_declared(handle: &str) -> bool {
143 kind_of(handle).map(|k| k.declared).unwrap_or(false)
144}
145
146pub fn declared_kinds() -> Vec<String> {
148 let mut out: Vec<String> = KIND_SECTORS
149 .iter()
150 .flat_map(|(s, kinds)| kinds.iter().map(move |k| format!("{s}:{k}")))
151 .collect();
152 out.sort();
153 out
154}
155
156#[cfg(test)]
157mod tests {
158 use super::*;
159
160 #[test]
161 fn parses_the_declared_sectors() {
162 let k = kind_of("urn:pcard:sprint:orc-02").expect("a handle");
163 assert_eq!(k.sector, "pcard");
164 assert_eq!(k.kind, "sprint");
165 assert_eq!(k.subject.as_deref(), Some("orc-02"));
166 assert!(k.declared);
167
168 let v = kind_of("urn:vcard:seal:9f2c").expect("a handle");
169 assert_eq!(v.sector, "vcard");
170 assert_eq!(v.kind, "seal");
171 assert_eq!(v.subject.as_deref(), Some("9f2c"));
172 assert!(v.declared);
173 }
174
175 #[test]
176 fn a_subject_may_contain_colons() {
177 let k = kind_of("urn:mcard:node:did:key:z6Mk").expect("a handle");
178 assert_eq!(k.sector, "node");
179 assert_eq!(k.kind, "did");
180 assert_eq!(k.subject.as_deref(), Some("key:z6Mk"));
181 }
182
183 #[test]
184 fn an_undeclared_kind_is_a_finding_not_a_null() {
185 let k = kind_of("urn:mcard:bogus:thing").expect("well formed");
186 assert!(!k.declared, "an undeclared kind must report declared:false");
187 }
188
189 #[test]
190 fn a_non_handle_is_none() {
191 assert!(kind_of("not-a-handle").is_none());
192 assert!(kind_of("urn:mcard:Pcard:Sprint").is_none(), "the grammar is lowercase");
193 assert!(kind_of("urn:mcard:pcard").is_none(), "no kind");
194 assert!(kind_of("urn:pcard").is_none(), "no kind");
195 assert!(kind_of("urn:vcard").is_none(), "no kind");
196 assert!(kind_of("").is_none());
197 }
198
199 #[test]
200 fn declared_kinds_matches_the_other_bindings() {
201 assert_eq!(declared_kinds().len(), 36);
206 }
207}