Skip to main content

webizen_studio/
semantic_instruments.rs

1//! Webizen library dialect for semantic instruments (SI-10).
2//!
3//! Held-gate copy, Demo/Reference chips, collect ≠ activate. No Host widen.
4//! Shared by Desktop Aether and WASM Poet. No Aether tree here.
5
6/// Soft why-text for missing / unknown pack. Never "broken".
7pub const HELD_WHY: &str = "held / not yet — open a pack or seed demos";
8
9pub const INSPECT_BEFORE_FETCH: &str = "inspect before network fetch";
10
11pub const COLLECT_NOT_ACTIVATE: &str = "collected is not active";
12
13pub const DEMO_CHIP: &str = "Demo";
14pub const REFERENCE_CHIP: &str = "Reference";
15
16/// WASM / lite hosts cannot mmap native Q42 v3 volumes. Inspect N3/HCF; hold the volume.
17pub const WASM_Q42_HELD: &str =
18    "held / not yet — native Q42 v3 volumes are not loadable on this WASM profile; N3/HCF remain inspectable";
19
20#[derive(Clone, Copy, Debug, PartialEq, Eq)]
21pub enum LibraryAction {
22    Inspect,
23    Collect,
24    Activate,
25    Run,
26    Cancel,
27    ViewReceipt,
28}
29
30/// Action label.
31pub fn action_label(action: LibraryAction) -> &'static str {
32    match action {
33        LibraryAction::Inspect => "inspect",
34        LibraryAction::Collect => "collect",
35        LibraryAction::Activate => "activate",
36        LibraryAction::Run => "run",
37        LibraryAction::Cancel => "cancel",
38        LibraryAction::ViewReceipt => "view receipt",
39    }
40}
41
42/// Activate/run need a closed lock. Inspect, collect, cancel, receipts do not.
43pub fn action_requires_closed(action: LibraryAction) -> bool {
44    matches!(action, LibraryAction::Activate | LibraryAction::Run)
45}
46
47/// Dispatch is the instrument entry point. `Host.*` is refused, not invented.
48pub fn host_id_refused(entry: &str) -> bool {
49    entry.contains("Host.")
50}
51
52#[derive(Clone, Debug, PartialEq, Eq)]
53pub struct LibraryCard {
54    pub release_id: String,
55    pub chip: &'static str,
56}
57
58#[derive(Clone, Debug, PartialEq, Eq)]
59pub enum LibraryOutcome {
60    Held { why: String },
61    Ready(LibraryCard),
62}
63
64/// Catalog chips.
65pub fn catalog_chips() -> &'static [&'static str] {
66    &[DEMO_CHIP, REFERENCE_CHIP]
67}
68
69/// Sanitizes a held reason.
70pub fn sanitize_held_why(raw: &str) -> String {
71    let folded = raw.to_ascii_lowercase();
72    if folded.contains("broken") || raw.trim().is_empty() || folded.contains("unavailable") {
73        return HELD_WHY.to_string();
74    }
75    if folded.contains("held") || folded.contains("open a pack") || folded.contains("seed demo") {
76        raw.trim().to_string()
77    } else {
78        HELD_WHY.to_string()
79    }
80}
81
82/// Map invoke result. Missing pack → held. Never "broken".
83pub fn interpret_invoke(ok: bool, blob: &str, err: Option<&str>) -> LibraryOutcome {
84    if ok {
85        if let Some(card) = parse_library_card(blob) {
86            return LibraryOutcome::Ready(card);
87        }
88    }
89    let diagnostic = err.unwrap_or(blob);
90    let folded = diagnostic.to_ascii_lowercase();
91    let why = if folded.contains("e300")
92        || folded.contains("not found")
93        || folded.contains("missing")
94        || folded.contains("held / not yet")
95        || folded.contains("open a pack")
96    {
97        sanitize_held_why(diagnostic)
98    } else {
99        HELD_WHY.to_string()
100    };
101    LibraryOutcome::Held { why }
102}
103
104fn parse_library_card(src: &str) -> Option<LibraryCard> {
105    let release_id = extract_quoted_field(src, "release_id")
106        .or_else(|| extract_quoted_field(src, "releaseId"))
107        .or_else(|| extract_quoted_field(src, "pack_id"))?;
108    if release_id.is_empty() {
109        return None;
110    }
111    let chip = if src.to_ascii_lowercase().contains("reference") {
112        REFERENCE_CHIP
113    } else {
114        DEMO_CHIP
115    };
116    Some(LibraryCard { release_id, chip })
117}
118
119fn extract_quoted_field(src: &str, key: &str) -> Option<String> {
120    let patterns = [
121        format!("{key}: \""),
122        format!("{key}:\""),
123        format!("\"{key}\": \""),
124        format!("\"{key}\":\""),
125    ];
126    for pat in patterns {
127        if let Some(start) = src.find(&pat) {
128            let rest = &src[start + pat.len()..];
129            if let Some(end) = rest.find('"') {
130                return Some(rest[..end].to_string());
131            }
132        }
133    }
134    None
135}
136
137/// `true` when copy avoids broken terms.
138pub fn copy_avoids_broken(text: &str) -> bool {
139    !text.to_ascii_lowercase().contains("broken")
140}
141
142#[cfg(test)]
143mod tests {
144    use super::*;
145
146    #[test]
147    fn held_copy_never_says_broken() {
148        assert_eq!(HELD_WHY, "held / not yet — open a pack or seed demos");
149        assert_eq!(sanitize_held_why("volume broken"), HELD_WHY);
150        assert_eq!(sanitize_held_why(""), HELD_WHY);
151        assert_eq!(sanitize_held_why("Unavailable: start daemon"), HELD_WHY);
152        assert!(copy_avoids_broken(HELD_WHY));
153        assert!(copy_avoids_broken(INSPECT_BEFORE_FETCH));
154        assert!(copy_avoids_broken(COLLECT_NOT_ACTIVATE));
155        match interpret_invoke(false, "", Some("E300@0..0: pack not found")) {
156            LibraryOutcome::Held { why } => {
157                assert_eq!(why, HELD_WHY);
158                assert!(copy_avoids_broken(&why));
159            }
160            other => panic!("{other:?}"),
161        }
162        match interpret_invoke(false, "broken pack", Some("missing pack")) {
163            LibraryOutcome::Held { why } => assert_eq!(why, HELD_WHY),
164            other => panic!("{other:?}"),
165        }
166    }
167
168    #[test]
169    fn collect_is_not_activate() {
170        assert_eq!(COLLECT_NOT_ACTIVATE, "collected is not active");
171        assert_ne!(
172            action_label(LibraryAction::Collect),
173            action_label(LibraryAction::Activate)
174        );
175        assert!(!action_requires_closed(LibraryAction::Collect));
176        assert!(!action_requires_closed(LibraryAction::Inspect));
177        assert!(!action_requires_closed(LibraryAction::Cancel));
178        assert!(!action_requires_closed(LibraryAction::ViewReceipt));
179        assert!(action_requires_closed(LibraryAction::Activate));
180        assert!(action_requires_closed(LibraryAction::Run));
181        assert_eq!(action_label(LibraryAction::Collect), "collect");
182        assert_eq!(action_label(LibraryAction::Activate), "activate");
183        assert_eq!(action_label(LibraryAction::ViewReceipt), "view receipt");
184    }
185
186    #[test]
187    fn host_dot_ids_are_refused() {
188        assert!(host_id_refused("Host.assess"));
189        assert!(host_id_refused("Capability.Host.run"));
190        assert!(!host_id_refused("assess"));
191        assert!(!host_id_refused("recognise"));
192        assert!(!host_id_refused("GraphDatabase.lexicon_manifest"));
193    }
194
195    #[test]
196    fn wasm_q42_is_held_degradation() {
197        assert!(WASM_Q42_HELD.starts_with("held / not yet"));
198        assert!(WASM_Q42_HELD.contains("Q42"));
199        assert!(WASM_Q42_HELD.contains("WASM"));
200        assert!(WASM_Q42_HELD.contains("N3/HCF"));
201        assert!(copy_avoids_broken(WASM_Q42_HELD));
202        assert!(!WASM_Q42_HELD.to_ascii_lowercase().contains("broken"));
203    }
204
205    #[test]
206    fn inspect_before_fetch() {
207        assert_eq!(INSPECT_BEFORE_FETCH, "inspect before network fetch");
208        assert_eq!(action_label(LibraryAction::Inspect), "inspect");
209        assert!(!action_requires_closed(LibraryAction::Inspect));
210        assert_eq!(catalog_chips(), &[DEMO_CHIP, REFERENCE_CHIP]);
211        assert_eq!(DEMO_CHIP, "Demo");
212        assert_eq!(REFERENCE_CHIP, "Reference");
213        let src = r#"{release_id: "si:demo:unit-convert", category: "Demo"}"#;
214        match interpret_invoke(true, src, None) {
215            LibraryOutcome::Ready(card) => {
216                assert_eq!(card.release_id, "si:demo:unit-convert");
217                assert_eq!(card.chip, DEMO_CHIP);
218            }
219            other => panic!("{other:?}"),
220        }
221    }
222}