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 use crate::layer0::transition::CHANGE_CALCULUS;
65
66fn split_handle(handle: &str) -> Option<(&str, &str, Option<&str>)> {
71 let lower = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_lowercase() || b == b'_');
72 if let Some(rest) = handle.strip_prefix("urn:pcard:") {
73 let (kind, subject) = match rest.split_once(':') {
74 Some((k, s)) => (k, Some(s)),
75 None => (rest, None),
76 };
77 if !lower(kind) {
78 return None;
79 }
80 return Some(("pcard", kind, subject));
81 }
82 if let Some(rest) = handle.strip_prefix("urn:vcard:") {
83 let (kind, subject) = match rest.split_once(':') {
84 Some((k, s)) => (k, Some(s)),
85 None => (rest, None),
86 };
87 if !lower(kind) {
88 return None;
89 }
90 return Some(("vcard", kind, subject));
91 }
92 let rest = handle.strip_prefix(crate::layer0::vocabulary::URI_SCHEME_URN_MCARD)?;
95 let (sector, rest) = rest.split_once(':')?;
96 let (kind, subject) = match rest.split_once(':') {
97 Some((k, s)) => (k, Some(s)),
98 None => (rest, None),
99 };
100 if !lower(sector) || !lower(kind) {
101 return None;
102 }
103 Some((sector, kind, subject))
104}
105
106pub fn kind_of(handle: &str) -> Option<HandleKind> {
108 let (sector, kind, subject) = split_handle(handle)?;
109 let declared = KIND_SECTORS
110 .iter()
111 .find(|(s, _)| *s == sector)
112 .map(|(_, kinds)| kinds.contains(&kind))
113 .unwrap_or(false);
114 Some(HandleKind {
115 sector: sector.to_string(),
116 kind: kind.to_string(),
117 handle: handle.to_string(),
118 declared,
119 subject: subject.map(str::to_string),
120 })
121}
122
123pub fn sector_of(handle: &str) -> Option<&str> {
125 split_handle(handle).map(|(s, _, _)| s)
126}
127
128pub fn kind_name_of(handle: &str) -> Option<&str> {
130 split_handle(handle).map(|(_, k, _)| k)
131}
132
133pub fn is_sector(handle: &str, sector: &str) -> bool {
135 sector_of(handle) == Some(sector)
136}
137
138pub fn is_declared(handle: &str) -> bool {
140 kind_of(handle).map(|k| k.declared).unwrap_or(false)
141}
142
143pub fn declared_kinds() -> Vec<String> {
145 let mut out: Vec<String> = KIND_SECTORS
146 .iter()
147 .flat_map(|(s, kinds)| kinds.iter().map(move |k| format!("{s}:{k}")))
148 .collect();
149 out.sort();
150 out
151}
152
153#[cfg(test)]
154mod tests {
155 use super::*;
156
157 #[test]
158 fn parses_the_declared_sectors() {
159 let k = kind_of("urn:pcard:sprint:orc-02").expect("a handle");
160 assert_eq!(k.sector, "pcard");
161 assert_eq!(k.kind, "sprint");
162 assert_eq!(k.subject.as_deref(), Some("orc-02"));
163 assert!(k.declared);
164
165 let v = kind_of("urn:vcard:seal:9f2c").expect("a handle");
166 assert_eq!(v.sector, "vcard");
167 assert_eq!(v.kind, "seal");
168 assert_eq!(v.subject.as_deref(), Some("9f2c"));
169 assert!(v.declared);
170 }
171
172 #[test]
173 fn a_subject_may_contain_colons() {
174 let k = kind_of("urn:mcard:node:did:key:z6Mk").expect("a handle");
175 assert_eq!(k.sector, "node");
176 assert_eq!(k.kind, "did");
177 assert_eq!(k.subject.as_deref(), Some("key:z6Mk"));
178 }
179
180 #[test]
181 fn an_undeclared_kind_is_a_finding_not_a_null() {
182 let k = kind_of("urn:mcard:bogus:thing").expect("well formed");
183 assert!(!k.declared, "an undeclared kind must report declared:false");
184 }
185
186 #[test]
187 fn a_non_handle_is_none() {
188 assert!(kind_of("not-a-handle").is_none());
189 assert!(kind_of("urn:mcard:Pcard:Sprint").is_none(), "the grammar is lowercase");
190 assert!(kind_of("urn:mcard:pcard").is_none(), "no kind");
191 assert!(kind_of("urn:pcard").is_none(), "no kind");
192 assert!(kind_of("urn:vcard").is_none(), "no kind");
193 assert!(kind_of("").is_none());
194 }
195
196 #[test]
197 fn declared_kinds_matches_the_other_bindings() {
198 assert_eq!(declared_kinds().len(), 36);
203 }
204}