Skip to main content

provable_contracts/ontology/extract/
cli_surface.rs

1//! aprender#3745 S2 (#3777) — `extract:cli-surface`: the release candidate's OWN interface becomes the graph the
2//! release cells are derived from.
3//!
4//! Operator, 2026-09-21: *"the way to prevent testing leakage is tests are dervived from surface and SHACL
5//! enforced...WE ARE NOT ENFORCING our interface AT ALL..it is hand coded not derived"*. So nothing here names a
6//! verb or a flag: the input is `apr surface --json` (schema `apr-cli-surface/v1`, #3749), emitted by the binary
7//! under test and passed to pv as a file, and every node is read from it.
8//!
9//! | node | IRI | from |
10//! |---|---|---|
11//! | `cli:Command` (+ `cli:ModelCommand` when an arg has role `model`) | `cli-command/<path…>` | `commands[]` |
12//! | `cli:Arg` | `cli-arg/<path…>/<id>` | `commands[].args[]`, and `global_args[]` under `cli-arg/-/<id>` |
13//! | `cli:ModeValue` | `cli-mode/<path…>/<id>/<level>` | every level of a `mode` arg (level `unset` = the default) |
14//! | `cli:InputShape` | `cli-shape/<path…>/<id>` | every `prompt` / `input-file` arg |
15//!
16//! Additive fields are allowed within v1 (#3745 amendment 2), so a key this reader does not know is ignored; an
17//! unknown `schema` or an unknown `role` is refused BY NAME — a role nobody can interpret is not read as `other`.
18
19use std::collections::BTreeMap;
20use std::path::Path;
21
22use crate::ontology::rdf::{iri_path, Graph, Term, ONT_BASE, RDF_TYPE};
23
24pub const SCHEMA: &str = "apr-cli-surface/v1";
25/// Every schema this reader accepts: v1.1 adds `commands[].generates` (#3745 amendment 3, additive).
26pub const SCHEMAS: [&str; 2] = [SCHEMA, "apr-cli-surface/v1.1"];
27/// Every role v1 may carry (#3745 note + amendment 1).
28pub const ROLES: [&str; 8] = [
29    "model",
30    "prompt",
31    "input-file",
32    "backend",
33    "sampling",
34    "mode",
35    "other",
36    "unknown",
37];
38/// The level every mode arg has first: not passed, i.e. its default. It never conflicts with anything.
39pub const UNSET: &str = "unset";
40
41/// The vocabulary root: `https://ont.paiml.dev/v1alpha1/cli/<name>` (`cli:` in a shape).
42#[must_use]
43pub fn cli(name: &str) -> String {
44    format!("{ONT_BASE}cli/{name}")
45}
46
47/// One argument as the surface declares it.
48#[derive(Debug, Clone, PartialEq, Eq)]
49pub struct Arg {
50    pub id: String,
51    pub long: Option<String>,
52    pub short: Option<String>,
53    pub positional: bool,
54    pub required: bool,
55    pub value_type: String,
56    pub values: Vec<String>,
57    pub role: String,
58    pub marker: Option<String>,
59    pub hidden: bool,
60    pub conflicts_with: Vec<String>,
61    /// Role `sampling` (#3745, fc 17dfb1291): which sampling knob this arg is — read from the typed group the arg
62    /// joined, never its name. `None` on every other arg.
63    pub sampling_kind: Option<String>,
64}
65
66impl Arg {
67    /// How the arg is spelled on a command line: `--long`, else `-s`, else `<id>` for a positional.
68    #[must_use]
69    pub fn spelling(&self) -> String {
70        match (&self.long, &self.short, self.positional) {
71            (Some(l), _, _) => format!("--{l}"),
72            (None, Some(s), _) => format!("-{s}"),
73            _ => format!("<{}>", self.id),
74        }
75    }
76
77    /// A mode arg's levels, `unset` first: a flag is `unset | true`; a finite set is `unset` (when not required)
78    /// plus each value. Any other role has no levels.
79    #[must_use]
80    pub fn levels(&self) -> Vec<String> {
81        if self.role != "mode" {
82            return Vec::new();
83        }
84        let mut out = Vec::new();
85        if !self.required {
86            out.push(UNSET.to_string());
87        }
88        if self.value_type == "flag" || self.value_type == "count" {
89            out.push("true".to_string());
90        } else {
91            out.extend(self.values.iter().cloned());
92        }
93        out
94    }
95}
96
97/// One subcommand path.
98#[derive(Debug, Clone, PartialEq, Eq)]
99pub struct Command {
100    pub key: String,
101    pub path: Vec<String>,
102    pub leaf: bool,
103    pub hidden: bool,
104    pub foreign: bool,
105    /// D2 (#3745): does the command GENERATE text — read from a typed marker in S1, never inferred. `None` when
106    /// the surface predates the field.
107    pub generates: Option<bool>,
108    pub args: Vec<Arg>,
109}
110
111impl Command {
112    #[must_use]
113    pub fn takes_model(&self) -> bool {
114        self.args.iter().any(|a| a.role == "model")
115    }
116
117    /// The input shapes: every prompt / input-file arg, by spelling.
118    #[must_use]
119    pub fn input_shapes(&self) -> Vec<&Arg> {
120        self.args
121            .iter()
122            .filter(|a| a.role == "prompt" || a.role == "input-file")
123            .collect()
124    }
125
126    /// The mode args (the command's own, then the globals the surface propagates to every path).
127    pub fn mode_args<'a>(&'a self, globals: &'a [Arg]) -> impl Iterator<Item = &'a Arg> {
128        self.args
129            .iter()
130            .chain(globals.iter())
131            .filter(|a| a.role == "mode" && !a.levels().is_empty())
132    }
133}
134
135/// The surface as read.
136#[derive(Debug, Clone, PartialEq, Eq)]
137pub struct Surface {
138    pub file: String,
139    pub version: String,
140    pub git_sha: String,
141    pub global_args: Vec<Arg>,
142    pub commands: Vec<Command>,
143}
144
145/// A surface this reader refuses, by name. The DECLARATION's fault (exit 3).
146#[derive(Debug, Clone, PartialEq, Eq)]
147pub struct SurfaceError {
148    pub file: String,
149    pub what: String,
150}
151
152impl std::fmt::Display for SurfaceError {
153    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
154        write!(f, "{}: {}", self.file, self.what)
155    }
156}
157
158impl std::error::Error for SurfaceError {}
159
160pub fn read(path: &Path) -> Result<Surface, SurfaceError> {
161    let file = path.display().to_string();
162    let text = std::fs::read_to_string(path).map_err(|e| SurfaceError {
163        file: file.clone(),
164        what: format!("unreadable: {e}"),
165    })?;
166    parse(&file, &text)
167}
168
169fn str_of(v: &serde_json::Value, key: &str) -> Option<String> {
170    v.get(key)
171        .and_then(serde_json::Value::as_str)
172        .map(str::to_string)
173}
174
175fn bool_of(v: &serde_json::Value, key: &str) -> bool {
176    v.get(key)
177        .and_then(serde_json::Value::as_bool)
178        .unwrap_or(false)
179}
180
181fn strings(v: &serde_json::Value, key: &str) -> Vec<String> {
182    v.get(key)
183        .and_then(serde_json::Value::as_array)
184        .into_iter()
185        .flatten()
186        .filter_map(serde_json::Value::as_str)
187        .map(str::to_string)
188        .collect()
189}
190
191/// Parse one surface document. An unknown `schema` or `role` is an error naming it.
192pub fn parse(file: &str, text: &str) -> Result<Surface, SurfaceError> {
193    let err = |what: String| SurfaceError {
194        file: file.to_string(),
195        what,
196    };
197    let v: serde_json::Value =
198        serde_json::from_str(text).map_err(|e| err(format!("not JSON: {e}")))?;
199    let schema = v
200        .get("schema")
201        .and_then(serde_json::Value::as_str)
202        .unwrap_or("");
203    if !SCHEMAS.contains(&schema) {
204        return Err(err(format!(
205            "schema {schema:?} is not {} — refused by name",
206            SCHEMAS.join(" or ")
207        )));
208    }
209    let args_of = |node: &serde_json::Value, key: &str, owner: &str| {
210        node.get(key)
211            .and_then(serde_json::Value::as_array)
212            .into_iter()
213            .flatten()
214            .map(|a| parse_arg(a).map_err(|w| err(format!("{owner}: {w}"))))
215            .collect::<Result<Vec<Arg>, SurfaceError>>()
216    };
217    let global_args = args_of(&v, "global_args", "global_args")?;
218    let mut commands = Vec::new();
219    for c in v
220        .get("commands")
221        .and_then(serde_json::Value::as_array)
222        .into_iter()
223        .flatten()
224    {
225        let key = str_of(c, "key").unwrap_or_default();
226        commands.push(Command {
227            path: strings(c, "path"),
228            leaf: bool_of(c, "leaf"),
229            hidden: bool_of(c, "hidden"),
230            foreign: bool_of(c, "foreign"),
231            generates: c.get("generates").and_then(serde_json::Value::as_bool),
232            args: args_of(c, "args", &key)?,
233            key,
234        });
235    }
236    let binary = v.get("binary").cloned().unwrap_or_default();
237    Ok(Surface {
238        file: file.to_string(),
239        version: str_of(&binary, "version").unwrap_or_default(),
240        git_sha: str_of(&binary, "git_sha").unwrap_or_default(),
241        global_args,
242        commands,
243    })
244}
245
246fn parse_arg(a: &serde_json::Value) -> Result<Arg, String> {
247    let id = str_of(a, "id").unwrap_or_default();
248    let role = str_of(a, "role").unwrap_or_default();
249    if !ROLES.contains(&role.as_str()) {
250        return Err(format!(
251            "arg {id:?} has role {role:?}, which apr-cli-surface/v1 does not define — refused by name"
252        ));
253    }
254    Ok(Arg {
255        long: str_of(a, "long"),
256        short: str_of(a, "short"),
257        positional: bool_of(a, "positional"),
258        required: bool_of(a, "required"),
259        value_type: str_of(a, "value_type").unwrap_or_default(),
260        values: strings(a, "values"),
261        role,
262        marker: str_of(a, "marker"),
263        hidden: bool_of(a, "hidden"),
264        conflicts_with: strings(a, "conflicts_with"),
265        sampling_kind: str_of(a, "sampling_kind"),
266        id,
267    })
268}
269
270/// What the extraction counted — the receipt's derived-surface numbers and the two shrink-only ratchets.
271#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize)]
272pub struct SurfaceStats {
273    pub commands: usize,
274    pub leaves: usize,
275    pub model_commands: usize,
276    pub generating_commands: usize,
277    /// Did every model command's surface say whether it generates (D2)? `false` is a violation at the release.
278    pub generates_declared: bool,
279    pub by_role: BTreeMap<String, usize>,
280    /// Shrink-only ratchet (#3745, cop): args no role type claims yet. Baseline 259, all in foreign subtrees.
281    pub unknown_args: usize,
282    pub unknown_outside_foreign: usize,
283    /// Shrink-only ratchet: model / input-file / prompt POSITIONALS whose stdin form v1 cannot declare.
284    pub stdin_undeclared: usize,
285}
286
287fn path_of(c: &Command) -> Vec<&str> {
288    c.path.iter().map(String::as_str).collect()
289}
290
291/// Write the surface's nodes into `g`.
292pub fn emit(g: &mut Graph, s: &Surface) -> SurfaceStats {
293    let mut st = SurfaceStats {
294        generates_declared: true,
295        ..SurfaceStats::default()
296    };
297    for a in &s.global_args {
298        emit_arg(g, &["-"], a);
299    }
300    for c in &s.commands {
301        emit_command(g, c, &mut st);
302    }
303    st
304}
305
306fn emit_command(g: &mut Graph, c: &Command, st: &mut SurfaceStats) {
307    st.commands += 1;
308    let path = path_of(c);
309    let n = iri_path("cli-command", &path);
310    g.insert(n.clone(), RDF_TYPE, Term::iri(cli("Command")));
311    g.insert(n.clone(), cli("key"), Term::string(&c.key));
312    g.insert(n.clone(), cli("leaf"), Term::boolean(c.leaf));
313    g.insert(n.clone(), cli("hidden"), Term::boolean(c.hidden));
314    g.insert(n.clone(), cli("foreign"), Term::boolean(c.foreign));
315    if let Some(gen) = c.generates {
316        g.insert(n.clone(), cli("generates"), Term::boolean(gen));
317    }
318    if c.leaf {
319        st.leaves += 1;
320    }
321    if c.takes_model() {
322        st.model_commands += 1;
323        g.insert(n.clone(), RDF_TYPE, Term::iri(cli("ModelCommand")));
324        match c.generates {
325            Some(true) => st.generating_commands += 1,
326            Some(false) => {}
327            None => st.generates_declared = false,
328        }
329    }
330    for a in &c.args {
331        *st.by_role.entry(a.role.clone()).or_default() += 1;
332        if a.role == "unknown" {
333            st.unknown_args += 1;
334            if !c.foreign {
335                st.unknown_outside_foreign += 1;
336            }
337        }
338        let stdin_capable = matches!(a.role.as_str(), "model" | "input-file" | "prompt");
339        if a.positional && stdin_capable {
340            st.stdin_undeclared += 1;
341        }
342        let an = emit_arg(g, &path, a);
343        g.insert(n.clone(), cli("arg"), Term::iri(an));
344    }
345}
346
347fn emit_arg(g: &mut Graph, path: &[&str], a: &Arg) -> String {
348    let mut segs: Vec<&str> = path.to_vec();
349    segs.push(&a.id);
350    let n = iri_path("cli-arg", &segs);
351    g.insert(n.clone(), RDF_TYPE, Term::iri(cli("Arg")));
352    g.insert(n.clone(), cli("id"), Term::string(&a.id));
353    g.insert(n.clone(), cli("spelling"), Term::string(a.spelling()));
354    g.insert(n.clone(), cli("role"), Term::string(&a.role));
355    g.insert(n.clone(), cli("valueType"), Term::string(&a.value_type));
356    g.insert(n.clone(), cli("positional"), Term::boolean(a.positional));
357    g.insert(n.clone(), cli("required"), Term::boolean(a.required));
358    if let Some(m) = &a.marker {
359        g.insert(n.clone(), cli("marker"), Term::string(m));
360    }
361    for c in &a.conflicts_with {
362        g.insert(n.clone(), cli("conflictsWith"), Term::string(c));
363    }
364    for level in a.levels() {
365        let mut s2 = segs.clone();
366        s2.push(&level);
367        let m = iri_path("cli-mode", &s2);
368        g.insert(m.clone(), RDF_TYPE, Term::iri(cli("ModeValue")));
369        g.insert(m.clone(), cli("level"), Term::string(&level));
370        g.insert(n.clone(), cli("modeValue"), Term::iri(m));
371    }
372    if a.role == "prompt" || a.role == "input-file" {
373        let s = iri_path("cli-shape", &segs);
374        g.insert(s.clone(), RDF_TYPE, Term::iri(cli("InputShape")));
375        g.insert(s.clone(), cli("spelling"), Term::string(a.spelling()));
376        g.insert(n.clone(), cli("inputShape"), Term::iri(s));
377    }
378    n
379}
380
381/// The positive control (R-3, the #3706 Σ-tie), drawn every gate run: a planted two-command surface whose `run`
382/// declares a model positional must yield `cli:ModelCommand` for `run` with a role-`model` arg; the same surface
383/// with that arg's role changed to `other` must NOT. An extractor that stopped reading `role` — or read it from
384/// the arg's NAME — would type both the same, and this goes `not-fired`.
385#[must_use]
386pub fn positive_control() -> bool {
387    let typed = |role: &str| {
388        let text = PC_SURFACE.replace("__ROLE__", role);
389        let Ok(s) = parse("__pc_surface__.json", &text) else {
390            return None;
391        };
392        let mut g = Graph::new();
393        let st = emit(&mut g, &s);
394        let run = iri_path("cli-command", &["run"]);
395        let is_model = g
396            .objects(&run, RDF_TYPE)
397            .iter()
398            .any(|t| t.as_iri() == Some(cli("ModelCommand").as_str()));
399        Some((is_model, st.model_commands))
400    };
401    matches!(
402        (typed("model"), typed("other")),
403        (Some((true, 1)), Some((false, 0)))
404    )
405}
406
407const PC_SURFACE: &str = r#"{"schema":"apr-cli-surface/v1","binary":{"name":"apr","version":"0.0.0-pc","git_sha":"pc"},
408"global_args":[{"id":"json","long":"json","value_type":"flag","values":["true","false"],"role":"mode"}],
409"commands":[
410 {"path":["run"],"key":"run","leaf":true,"hidden":false,"foreign":false,"generates":true,"args":[
411   {"id":"model","positional":true,"required":true,"value_type":"path","role":"__ROLE__","marker":"ModelRef"},
412   {"id":"prompt","long":"prompt","value_type":"text","role":"prompt","marker":"PromptText"},
413   {"id":"chat","long":"chat","value_type":"flag","values":["true","false"],"role":"mode"}]},
414 {"path":["list"],"key":"list","leaf":true,"hidden":false,"foreign":false,"args":[]}]}"#;
415
416#[cfg(test)]
417mod tests {
418    use super::*;
419
420    #[test]
421    fn the_control_fires_and_a_foreign_schema_or_role_is_refused_by_name() {
422        assert!(positive_control());
423        let e = parse("x.json", r#"{"schema":"apr-cli-surface/v9"}"#).expect_err("refused");
424        assert!(e.what.contains("v9") && e.what.contains(SCHEMA), "{e}");
425        let bad = PC_SURFACE.replace("__ROLE__", "modelish");
426        let e = parse("x.json", &bad).expect_err("unknown role refused");
427        assert!(e.what.contains("modelish"), "{e}");
428    }
429
430    #[test]
431    fn levels_start_at_unset_and_the_ratchets_count_what_v1_cannot_say() {
432        let s = parse("pc.json", &PC_SURFACE.replace("__ROLE__", "model")).expect("parses");
433        let run = &s.commands[0];
434        let modes: Vec<(String, Vec<String>)> = run
435            .mode_args(&s.global_args)
436            .map(|a| (a.spelling(), a.levels()))
437            .collect();
438        assert_eq!(
439            modes,
440            vec![
441                ("--chat".to_string(), vec!["unset".into(), "true".into()]),
442                ("--json".to_string(), vec!["unset".into(), "true".into()]),
443            ],
444            "the command's own mode args, then the propagated globals"
445        );
446        let mut g = Graph::new();
447        let st = emit(&mut g, &s);
448        assert_eq!(st.model_commands, 1);
449        assert_eq!(st.generating_commands, 1);
450        assert!(st.generates_declared);
451        assert_eq!(st.stdin_undeclared, 1, "the model positional");
452        let no_gen = PC_SURFACE
453            .replace("__ROLE__", "model")
454            .replace(r#""generates":true,"#, "");
455        let st2 = emit(
456            &mut Graph::new(),
457            &parse("pc.json", &no_gen).expect("parses"),
458        );
459        assert!(
460            !st2.generates_declared,
461            "a model command that does not say is named"
462        );
463    }
464
465    const COUNT_SURFACE: &str = r#"{"schema":"apr-cli-surface/v1","binary":{},
466"global_args":[],
467"commands":[
468 {"path":["a"],"key":"a","leaf":true,"hidden":false,"foreign":false,"args":[
469   {"id":"u1","long":"u1","value_type":"text","role":"unknown"},
470   {"id":"p","long":"p","value_type":"text","role":"prompt"},
471   {"id":"f","long":"f","value_type":"path","role":"input-file"},
472   {"id":"o","long":"o","value_type":"text","role":"other"},
473   {"id":"m","positional":true,"value_type":"path","role":"model"}]},
474 {"path":["b"],"key":"b","leaf":false,"hidden":false,"foreign":true,"args":[
475   {"id":"u2","long":"u2","value_type":"text","role":"unknown"},
476   {"id":"u3","long":"u3","value_type":"text","role":"unknown"},
477   {"id":"u5","long":"u5","value_type":"text","role":"unknown"}]},
478 {"path":["c"],"key":"c","leaf":true,"hidden":false,"foreign":false,"args":[
479   {"id":"u4","long":"u4","value_type":"text","role":"unknown"}]}]}"#;
480
481    #[test]
482    fn emit_counts_commands_leaves_roles_and_unknowns_exactly() {
483        let s = parse("c.json", COUNT_SURFACE).expect("parses");
484        let mut g = Graph::new();
485        let st = emit(&mut g, &s);
486        assert_eq!(st.commands, 3);
487        assert_eq!(st.leaves, 2);
488        assert_eq!(st.model_commands, 1);
489        assert_eq!(st.by_role.get("unknown"), Some(&5));
490        assert_eq!(st.by_role.get("prompt"), Some(&1));
491        assert_eq!(st.by_role.get("model"), Some(&1));
492        assert_eq!(st.unknown_args, 5);
493        assert_eq!(st.unknown_outside_foreign, 2, "a and c are not foreign");
494    }
495
496    #[test]
497    fn emit_arg_returns_its_node_and_types_only_prompt_and_input_file_as_shapes() {
498        let s = parse("c.json", COUNT_SURFACE).expect("parses");
499        let mut g = Graph::new();
500        let _ = emit(&mut g, &s);
501        let shape_of = |g: &Graph, id: &str| {
502            g.objects(&iri_path("cli-arg", &["a", id]), &cli("inputShape"))
503                .len()
504        };
505        assert_eq!(shape_of(&g, "p"), 1);
506        assert_eq!(shape_of(&g, "f"), 1);
507        assert_eq!(shape_of(&g, "o"), 0);
508        assert_eq!(shape_of(&g, "m"), 0);
509        let arg = &s.commands[0].args[1];
510        let mut g2 = Graph::new();
511        let n = emit_arg(&mut g2, &["a"], arg);
512        assert_eq!(n, iri_path("cli-arg", &["a", "p"]));
513        assert!(!g2.is_empty());
514    }
515
516    #[test]
517    fn mode_args_drops_a_mode_arg_with_no_levels_and_display_names_file_and_what() {
518        let text = r#"{"schema":"apr-cli-surface/v1","binary":{},"global_args":[],
519"commands":[{"path":["x"],"key":"x","leaf":true,"hidden":false,"foreign":false,"args":[
520 {"id":"empty","long":"empty","required":true,"value_type":"enum","values":[],"role":"mode"},
521 {"id":"ok","long":"ok","value_type":"flag","role":"mode"}]}]}"#;
522        let s = parse("m.json", text).expect("parses");
523        let ids: Vec<&str> = s.commands[0]
524            .mode_args(&s.global_args)
525            .map(|a| a.id.as_str())
526            .collect();
527        assert_eq!(ids, vec!["ok"]);
528        let e = SurfaceError {
529            file: "f.json".into(),
530            what: "broken".into(),
531        };
532        assert_eq!(e.to_string(), "f.json: broken");
533    }
534}