instruction-md 0.6.1

Read, check, resolve and verify instruction.md files (Markdown rules for AI agents, specification instruction/1): the reader and its diagnostics, the exact text an agent receives, composition of bases and includes, and Ed25519 signature verification. No I/O, no unsafe.
Documentation
//! S28: a protocol value (`name` or `name/v1,v2`) parsed, and the versions two sides share under a binding's `compat`
//! rule — what a host needs to decide `protocol-unsupported`. The port of `packages/spec/src/protocol.ts`. A reader
//! checks only the syntax (`protocol-syntax`); choosing a version is the host's.

/// A protocol value: its name (`a2a`, `x402`, or `com.example/rail`) and the versions written, in order (empty for a
/// bare name: every version its binding marks stable).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Protocol {
    pub name: String,
    pub versions: Vec<String>,
}

/// A protocol value parsed; `None` when it isn't one (`protocol-syntax`).
pub fn parse(value: &str) -> Option<Protocol> {
    if !crate::allowance::protocol_ok(value) {
        return None;
    }
    let mut segs: Vec<&str> = value.split('/').collect();
    let reverse = segs[0].contains('.');
    let name_len = if reverse { 2 } else { 1 };
    let versions = if segs.len() > name_len { segs.pop().map(|v| v.split(',').map(str::to_string).collect()).unwrap_or_default() } else { Vec::new() };
    Some(Protocol { name: segs[..name_len].join("/"), versions })
}

/// How a binding compares versions (S28).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Compat {
    /// The version as written.
    Exact,
    /// From 1.0 the same major, any minor at or above; before 1.0 major.minor exactly.
    SemverMinor,
    /// The same revision date, or a later one.
    Date,
}

fn major_minor(v: &str) -> Option<(u64, u64)> {
    let v = v.strip_prefix('v').unwrap_or(v);
    let mut it = v.split('.');
    let major = it.next()?.parse().ok()?;
    let minor = it.next().map_or(Some(0), |m| m.parse().ok())?;
    Some((major, minor))
}

fn is_date(v: &str) -> bool {
    let b = v.as_bytes();
    b.len() == 10 && b[4] == b'-' && b[7] == b'-' && b.iter().enumerate().all(|(i, c)| i == 4 || i == 7 || c.is_ascii_digit())
}

/// Whether a host speaking `have` can serve a document that wants `want`, under `compat`.
pub fn compatible(compat: Compat, want: &str, have: &str) -> bool {
    match compat {
        Compat::Exact => want == have,
        Compat::Date => is_date(want) && is_date(have) && have >= want,
        Compat::SemverMinor => match (major_minor(want), major_minor(have)) {
            (Some((0, wm)), Some((hm_major, hm))) => hm_major == 0 && hm == wm,
            (Some((wma, wmi)), Some((hma, hmi))) => hma == wma && hmi >= wmi,
            _ => want == have,
        },
    }
}

/// The document's versions a host can serve, in the document's order; for a bare name, every host version the binding
/// marks stable (`stable`), else every host version. Empty: `protocol-unsupported`.
pub fn shared_versions(p: &Protocol, host: &[&str], compat: Compat, stable: Option<&[&str]>) -> Vec<String> {
    if p.versions.is_empty() {
        return host.iter().filter(|h| stable.is_none_or(|s| s.contains(h))).map(|h| h.to_string()).collect();
    }
    p.versions.iter().filter(|w| host.iter().any(|h| compatible(compat, w, h))).cloned().collect()
}

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

    #[test]
    fn parses_and_compares_as_the_reference() {
        assert_eq!(parse("a2a/1.0,1.1"), Some(Protocol { name: "a2a".into(), versions: vec!["1.0".into(), "1.1".into()] }));
        assert_eq!(parse("com.example/rail/1"), Some(Protocol { name: "com.example/rail".into(), versions: vec!["1".into()] }));
        assert_eq!(parse("x402"), Some(Protocol { name: "x402".into(), versions: vec![] }));
        assert_eq!(parse("x402/"), None);
        assert!(!compatible(Compat::SemverMinor, "0.2", "0.3"));
        assert!(compatible(Compat::SemverMinor, "0.2", "0.2"));
        assert!(compatible(Compat::SemverMinor, "1.0", "1.3"));
        assert!(!compatible(Compat::SemverMinor, "1.4", "1.3"));
        assert!(!compatible(Compat::SemverMinor, "1.0", "2.0"));
        assert!(compatible(Compat::Date, "2026-07-28", "2026-11-01"));
        assert!(shared_versions(&parse("x402/1").unwrap(), &["2"], Compat::Exact, None).is_empty());
        assert_eq!(shared_versions(&parse("a2a").unwrap(), &["1.0", "0.3"], Compat::SemverMinor, Some(&["1.0"])), vec!["1.0".to_string()]);
    }
}