instruction-md 0.5.0

Read, check, resolve and verify instruction.md documents (the specification's first edition, instruction/1): the reader, the agent text, composition and signature verification
Documentation
//! S28 bindings as data: a `binding` extension manifest read (its `provides.protocol`), and the manifests this crate
//! ships so a host need not hard-code a protocol's stable versions. The port of `packages/spec/src/bindings.ts`. The
//! core names no protocol; these are extensions, versioned on their own, and a host may load others the same way.

use crate::protocol::Compat;
use serde_json::Value;

/// A version's maturity in its binding.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Maturity {
    Draft,
    Stable,
    Deprecated,
}

/// A binding: its extension id and version, and the protocol it describes.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Binding {
    pub id: String,
    pub version: String,
    pub name: String,
    /// Each version with its maturity, in the manifest's order.
    pub versions: Vec<(String, Maturity)>,
    pub compat: Compat,
    pub kinds: Vec<String>,
}

impl Binding {
    /// The stable versions: what a bare protocol name means (S28).
    pub fn stable(&self) -> Vec<&str> {
        self.versions.iter().filter(|(_, m)| *m == Maturity::Stable).map(|(v, _)| v.as_str()).collect()
    }
}

/// A binding manifest (format instruction-extension/1, role binding) read; `None` when it isn't one.
pub fn binding_from(m: &Value) -> Option<Binding> {
    if m.get("format")?.as_str()? != "instruction-extension/1" || !m.get("roles")?.as_array()?.iter().any(|r| r == "binding") {
        return None;
    }
    let p = m.get("provides")?.get("protocol")?;
    let versions = p
        .get("versions")?
        .as_object()?
        .iter()
        .map(|(v, s)| {
            let maturity = match s.as_str() {
                Some("stable") => Maturity::Stable,
                Some("deprecated") => Maturity::Deprecated,
                _ => Maturity::Draft,
            };
            (v.clone(), maturity)
        })
        .collect();
    let compat = match p.get("compat").and_then(Value::as_str) {
        Some("semver-minor") => Compat::SemverMinor,
        Some("date") => Compat::Date,
        _ => Compat::Exact,
    };
    Some(Binding {
        id: m.get("id")?.as_str()?.to_string(),
        version: m.get("version")?.as_str()?.to_string(),
        name: p.get("name")?.as_str()?.to_string(),
        versions,
        compat,
        kinds: p.get("kinds").and_then(Value::as_array).map(|k| k.iter().filter_map(|x| x.as_str().map(str::to_string)).collect()).unwrap_or_default(),
    })
}

/// x402 (HTTP 402 payments): version 2 stable, version 1 deprecated; versions compared as written.
pub fn x402() -> Binding {
    Binding {
        id: "org.x402/x402".into(),
        version: "2.0.0".into(),
        name: "x402".into(),
        versions: vec![("1".into(), Maturity::Deprecated), ("2".into(), Maturity::Stable)],
        compat: Compat::Exact,
        kinds: vec!["wallet".into(), "service".into()],
    }
}

/// The binding this crate ships for a protocol name.
pub fn known(name: &str) -> Option<Binding> {
    (name == "x402").then(x402)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn reads_a_manifest_and_ships_x402() {
        let m: Value = serde_json::from_str(r#"{"format":"instruction-extension/1","id":"org.x402/x402","version":"2.0.0","spec":["1"],"roles":["binding"],"provides":{"protocol":{"name":"x402","versions":{"1":"deprecated","2":"stable"},"compat":"exact","kinds":["wallet","service"]}}}"#).unwrap();
        assert_eq!(binding_from(&m), Some(x402()));
        assert_eq!(x402().stable(), vec!["2"]);
        assert!(known("a2a").is_none());
    }
}