wire/

trust.rs

//! Trust state machine — v0.1 minimal subset, extended in v3.2 (RFC-001).
//!
//! Tier semantics:
//!   - UNTRUSTED: card pinned, no claim verified yet; messages ignored.
//!   - ORG_VERIFIED: (v3.2 / RFC-001 §5) peer shares a verified `org_did`
//!     with us — *organisational* trust, NOT personal. Bilateral SAS is
//!     still required to cross into VERIFIED. Promotion from UNTRUSTED is
//!     one-way.
//!   - VERIFIED: SAS confirmed bilateral; messages accepted. Promotion
//!     accepts UNTRUSTED-or-ORG_VERIFIED as source (RFC-001 §5: "a
//!     SAS-paired peer that happens to share our org is recorded at
//!     VERIFIED, not downgraded").
//!   - ATTESTED: reserved (v0.2+) — used today only for self-attest.
//!   - TRUSTED: reserved (v0.2+).
//!
//! Promotion is one-way. Demotion would be ambiguous in a bilateral setting
//! and is deliberately not modeled. RFC-001 §5 invariant:
//!   "ORG_VERIFIED never satisfies a `>= VERIFIED` policy check."
//! That invariant is captured by `tier_order` (ORG_VERIFIED=1 < VERIFIED=2)
//! and by AC2 property test (tests/trust_ceiling_prop.rs) asserting no
//! claim-event walk reaches VERIFIED without a SasConfirmed step.

use serde_json::{Value, json};
use std::collections::BTreeMap;
use time::OffsetDateTime;
use time::format_description::well_known::Rfc3339;

use crate::signing::{b64encode, make_key_id};

/// Tier ranking — higher is more trusted. Useful for `>=` gating.
///
/// RFC-001 §5 invariant: ORG_VERIFIED sits strictly between UNTRUSTED and
/// VERIFIED. A policy check of `tier >= VERIFIED` MUST NOT pass for an
/// ORG_VERIFIED peer — only an explicit SAS-confirmation can cross that line.
pub fn tier_order() -> BTreeMap<&'static str, u32> {
    [
        ("UNTRUSTED", 0u32),
        ("ORG_VERIFIED", 1),
        ("VERIFIED", 2),
        ("ATTESTED", 3),
        ("TRUSTED", 4),
    ]
    .into_iter()
    .collect()
}

#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub enum Tier {
    Untrusted,
    OrgVerified,
    Verified,
    Attested,
    Trusted,
}

impl Tier {
    pub fn as_str(self) -> &'static str {
        match self {
            Tier::Untrusted => "UNTRUSTED",
            Tier::OrgVerified => "ORG_VERIFIED",
            Tier::Verified => "VERIFIED",
            Tier::Attested => "ATTESTED",
            Tier::Trusted => "TRUSTED",
        }
    }
}

/// Trust state — kept as a free-form JSON Value so we can persist + read with
/// any conforming impl. v0.2+ may swap this for a typed struct.
pub type Trust = Value;

pub fn empty_trust() -> Trust {
    json!({"version": 1, "agents": {}})
}

pub fn get_tier(trust: &Trust, peer_handle: &str) -> String {
    trust
        .get("agents")
        .and_then(|a| a.get(peer_handle))
        .and_then(|a| a.get("tier"))
        .and_then(Value::as_str)
        .unwrap_or("UNTRUSTED")
        .to_string()
}

/// Effective trust tier — what the daemon can ACT on, not just what
/// trust.json was promoted to.
///
/// Surface-honest. trust.json may say VERIFIED, but if relay_state
/// has no `bilateral_completed_at` AND no `slot_token`, the daemon
/// literally cannot push to that peer. Showing the operator a
/// VERIFIED tag in that case is a lie about capability — fall back
/// to PENDING_ACK so the diagnosis line + pending-push attribution
/// agree.
///
/// Originally lived in `cli.rs::effective_peer_tier`. Moved to
/// `trust.rs` 2026-06-01 so `config::compute_pending_push_breakdown`
/// can call it without a circular dep, and so any future surface
/// (web doctor, MCP wire_status, etc.) gets the same canonical
/// answer.
///
/// History: v0.14.2 (#162 fix #5) introduced the
/// `bilateral_completed_at` durable signal — pre-#162 peers fall
/// back to `slot_token` presence as a legacy probe so already-paired
/// peers keep reporting VERIFIED instead of regressing the moment
/// they're upgraded.
pub fn effective_tier(trust: &Value, relay_state: &Value, handle: &str) -> String {
    let raw = get_tier(trust, handle);
    if raw != "VERIFIED" {
        return raw;
    }
    let peer_obj = relay_state.get("peers").and_then(|p| p.get(handle));
    let bilateral_at = peer_obj
        .and_then(|p| p.get("bilateral_completed_at"))
        .and_then(Value::as_str);
    if bilateral_at.is_some() {
        return raw;
    }
    // A VERIFIED pin isn't effectively usable until we hold the peer's reply
    // slot. RFC-006 Part B: the slot lives in `endpoints[]` — the single
    // peer-routing source — not a flat `slot_token` field (Part B stopped
    // writing it; reading it here is dead, no legacy state to tolerate).
    let has_slot = crate::endpoints::peer_endpoints_in_priority_order(relay_state, handle)
        .iter()
        .any(|e| !e.slot_token.is_empty());
    if has_slot {
        raw
    } else {
        "PENDING_ACK".to_string()
    }
}

/// Resolve a bare peer handle to the full DID stored in trust. Falls back
/// to `did:wire:<peer_handle>` (the bare-handle form) when the peer isn't
/// pinned — preserves pre-pair best-effort routing for unknown peers.
///
/// v0.14.2 (#162 fix #4): without this, send paths (`cmd_send` /
/// `tool_send`) built `to: did:wire:sunlit-aurora`, but pinned peers'
/// real DIDs carry the long fingerprint suffix
/// (`did:wire:sunlit-aurora-ec6f890d`). A bare-handle `to:` mismatches
/// the receiver's self-DID and risks rejection at canonical / cursor
/// check time (honey-pine's report observed this on the first queued
/// event). Use this helper at every send-build site to canonicalize
/// against the pinned peer's actual DID.
pub fn resolve_peer_did(trust: &Value, peer_handle: &str) -> String {
    trust
        .get("agents")
        .and_then(|a| a.get(peer_handle))
        .and_then(|p| p.get("did"))
        .and_then(Value::as_str)
        .map(str::to_string)
        .unwrap_or_else(|| format!("did:wire:{peer_handle}"))
}

/// Pin a peer's card into our trust at the given tier (default UNTRUSTED).
///
/// The caller must independently run SAS confirmation (via `compute_sas`)
/// before calling `promote_to_verified`. Pinning alone DOES NOT verify.
///
/// SECURITY (#245 — grindable nick-collision pin-overwrite): the trust store is
/// keyed by the peer's persona nick, which is a deterministic function of the
/// keypair over a small (~65k) word-list — so an attacker can grind keys (or
/// simply set the card's `handle` field) until their nick collides with a
/// victim's, then OVERWRITE the victim's pin (its keys/DID), hijacking the nick:
/// the real victim's messages then fail verify (their key is gone) and the
/// attacker's verify as the victim. This guard REFUSES to overwrite an existing
/// nick whose pinned `did` differs from the incoming card's `did`. DIDs carry
/// the key fingerprint (`did:wire:<nick>-<fp>`), so they are NOT grindable to
/// match a *specific* full DID — and a same-identity re-pin / key-succession
/// keeps the same DID, so legitimate updates are unaffected. (The complete fix —
/// letting two distinct identities that collide on a nick COEXIST by re-keying
/// the whole store by DID — is the larger follow-up tracked in #245.)
pub fn add_agent_card_pin(
    trust: &mut Trust,
    card: &Value,
    tier: Option<&str>,
) -> Result<(), String> {
    let did = card.get("did").and_then(Value::as_str).unwrap_or_default();
    // v0.5.7+: prefer the explicit `handle` field on the card (display name).
    // Fall back to stripping the DID prefix for legacy cards. For v0.5.7+
    // pubkey-suffixed DIDs (`did:wire:paul-abc12345`), the display_handle
    // helper strips the pubkey suffix back off.
    let handle = card
        .get("handle")
        .and_then(Value::as_str)
        .map(str::to_string)
        .unwrap_or_else(|| crate::agent_card::display_handle_from_did(did).to_string());
    if handle.is_empty() {
        return Err(format!("card has no resolvable handle (did={did:?})"));
    }
    // #245 collision guard: refuse to overwrite a different identity's pin.
    if let Some(existing_did) = trust
        .get("agents")
        .and_then(|a| a.get(&handle))
        .and_then(|e| e.get("did"))
        .and_then(Value::as_str)
        && !existing_did.is_empty()
        && !did.is_empty()
        && existing_did != did
    {
        return Err(format!(
            "trust pin collision on nick '{handle}': already pinned to {existing_did}, refusing to overwrite with a DIFFERENT identity {did} (possible grindable-nick attack — #245). \
             Use `wire forget-peer {handle}` first if you intend to replace it."
        ));
    }
    let tier = tier.unwrap_or("UNTRUSTED");
    let now = now_iso();

    let mut public_keys = Vec::new();
    if let Some(vks) = card.get("verify_keys").and_then(Value::as_object) {
        for (key_id_full, key_record) in vks {
            // Strip the `ed25519:` algorithm prefix to match v3.1 trust.json shape.
            let key_id = key_id_full.strip_prefix("ed25519:").unwrap_or(key_id_full);
            public_keys.push(json!({
                "key_id": key_id,
                "key": key_record.get("key").cloned().unwrap_or(Value::Null),
                "added_at": now,
                "active": true,
            }));
        }
    }

    let agents = trust
        .as_object_mut()
        .expect("trust must be an object")
        .entry("agents")
        .or_insert_with(|| json!({}));

    agents[handle] = json!({
        "tier": tier,
        "did": did,
        "public_keys": public_keys,
        "card": card.clone(),
        "pinned_at": now,
    });
    Ok(())
}

/// Promote UNTRUSTED or ORG_VERIFIED → VERIFIED. Returns `Err(reason)` if
/// not pinned or already past VERIFIED.
///
/// RFC-001 §5: a SAS-confirmed peer that happens to share our org is
/// recorded at VERIFIED, not downgraded — so ORG_VERIFIED is an accepted
/// source for VERIFIED promotion. ATTESTED and TRUSTED are above VERIFIED
/// and would be a downgrade; we refuse.
pub fn promote_to_verified(trust: &mut Trust, peer_handle: &str) -> Result<(), String> {
    let agents = trust
        .as_object_mut()
        .ok_or("trust is not an object")?
        .get_mut("agents")
        .and_then(Value::as_object_mut)
        .ok_or_else(|| format!("peer {peer_handle:?} not pinned"))?;

    let agent = agents
        .get_mut(peer_handle)
        .ok_or_else(|| format!("peer {peer_handle:?} not pinned"))?;

    let current = agent
        .get("tier")
        .and_then(Value::as_str)
        .unwrap_or("UNTRUSTED")
        .to_string();
    if current != "UNTRUSTED" && current != "ORG_VERIFIED" {
        return Err(format!(
            "peer {peer_handle:?} already at tier {current:?} — promotion is one-way"
        ));
    }
    agent["tier"] = json!("VERIFIED");
    agent["verified_at"] = json!(now_iso());
    Ok(())
}

/// Promote UNTRUSTED → ORG_VERIFIED. Returns `Err(reason)` if not pinned or
/// already past UNTRUSTED.
///
/// RFC-001 §5: ORG_VERIFIED is granted on cryptographic + policy grounds
/// (the peer's `member_cert` for an org we accept verifies against that
/// org's pubkey) but DOES NOT satisfy the SAS-confirmation ceremony that
/// VERIFIED requires. It is a one-way intermediate step a peer may cross
/// before or after VERIFIED, but never *instead of* VERIFIED.
///
/// This function does NOT perform the cryptographic verification of
/// `member_cert` — that lives in [`crate::identity::verify_member_cert`]
/// and the caller must run it first. The trust mutation here is the policy
/// recording: "we accept this peer as ORG_VERIFIED under our active org
/// policy."
pub fn promote_to_org_verified(trust: &mut Trust, peer_handle: &str) -> Result<(), String> {
    let agents = trust
        .as_object_mut()
        .ok_or("trust is not an object")?
        .get_mut("agents")
        .and_then(Value::as_object_mut)
        .ok_or_else(|| format!("peer {peer_handle:?} not pinned"))?;

    let agent = agents
        .get_mut(peer_handle)
        .ok_or_else(|| format!("peer {peer_handle:?} not pinned"))?;

    let current = agent
        .get("tier")
        .and_then(Value::as_str)
        .unwrap_or("UNTRUSTED")
        .to_string();
    if current != "UNTRUSTED" {
        return Err(format!(
            "peer {peer_handle:?} already at tier {current:?} — \
             org_verified promotion fires from UNTRUSTED only"
        ));
    }
    agent["tier"] = json!("ORG_VERIFIED");
    agent["org_verified_at"] = json!(now_iso());
    Ok(())
}

/// RFC-001 §6 project fan-out: the pinned peer handles eligible to receive a
/// `wire send --project <tag>` broadcast.
///
/// A peer is eligible iff (a) its effective tier is **>= ORG_VERIFIED** (so we
/// never fan out to an unverified or unreachable peer) AND (b) its pinned
/// agent-card carries `project == <tag>`. `project` is **unsigned routing
/// metadata** (RFC-001 §6) — it selects recipients, it never grants trust; the
/// tier floor is the trust gate, the project tag is only the address book.
///
/// `self_handle` is excluded (our own ATTESTED self-pin must never be a
/// recipient). Pure over the two state blobs so it unit-tests without any CLI
/// or live relay. Result is sorted for deterministic output.
pub fn project_recipients(
    trust: &Value,
    relay_state: &Value,
    self_handle: &str,
    project: &str,
) -> Vec<String> {
    let order = tier_order();
    let floor = order.get("ORG_VERIFIED").copied().unwrap_or(1);
    let mut out = Vec::new();
    if let Some(agents) = trust.get("agents").and_then(Value::as_object) {
        for (handle, agent) in agents {
            if handle == self_handle {
                continue;
            }
            let tier = effective_tier(trust, relay_state, handle);
            let rank = order.get(tier.as_str()).copied().unwrap_or(0);
            if rank < floor {
                continue;
            }
            let proj = agent.get("card").and_then(crate::agent_card::card_project);
            if proj == Some(project) {
                out.push(handle.clone());
            }
        }
    }
    out.sort();
    out
}

/// Self-pin our own keypair into trust at ATTESTED. Convenience for `wire init`.
pub fn add_self_to_trust(trust: &mut Trust, handle: &str, public_key: &[u8]) {
    let agents = trust
        .as_object_mut()
        .expect("trust must be an object")
        .entry("agents")
        .or_insert_with(|| json!({}));
    let key_id = make_key_id(handle, public_key);
    agents[handle] = json!({
        "tier": "ATTESTED",
        "did": crate::agent_card::did_for_with_key(handle, public_key),
        "public_keys": [{
            "key_id": key_id,
            "key": b64encode(public_key),
            "added_at": now_iso(),
            "active": true,
        }],
    });
}

fn now_iso() -> String {
    let now = OffsetDateTime::now_utc();
    now.format(&Rfc3339)
        .unwrap_or_else(|_| "1970-01-01T00:00:00Z".to_string())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::agent_card::{build_agent_card, sign_agent_card};
    use crate::signing::generate_keypair;

    #[test]
    fn empty_trust_shape() {
        let t = empty_trust();
        assert_eq!(t["version"], 1);
        assert!(t["agents"].is_object());
        assert_eq!(t["agents"].as_object().unwrap().len(), 0);
    }

    #[test]
    fn get_tier_unknown_returns_untrusted() {
        assert_eq!(get_tier(&empty_trust(), "ghost"), "UNTRUSTED");
    }

    #[test]
    fn resolve_peer_did_returns_pinned_did_with_full_suffix() {
        // v0.14.2 (#162 fix #4): a pinned peer's full DID includes the
        // long-fingerprint suffix; a bare-handle DID would mismatch the
        // receiver's self-DID and risk rejection at canonical/cursor
        // verification.
        let (sk, pk) = generate_keypair();
        let card = sign_agent_card(
            &build_agent_card("sunlit-aurora", &pk, None, None, None),
            &sk,
        );
        let pinned_did = card.get("did").and_then(Value::as_str).unwrap();
        assert!(
            pinned_did.starts_with("did:wire:sunlit-aurora-"),
            "test setup: card DID should carry long-hex suffix"
        );
        let mut t = empty_trust();
        add_agent_card_pin(&mut t, &card, Some("VERIFIED")).unwrap();

        let resolved = resolve_peer_did(&t, "sunlit-aurora");
        assert_eq!(
            resolved, pinned_did,
            "pinned peer must resolve to its full DID, not the bare handle"
        );
    }

    #[test]
    fn add_agent_card_pin_refuses_nick_collision_from_a_different_identity() {
        // #245: two distinct keypairs can share a persona nick (the ~65k
        // word-list is grindable, and the card's `handle` field is spoofable).
        // Pinning a DIFFERENT identity under an already-pinned nick must be
        // REFUSED, not silently overwrite (which would hijack the nick).
        let (sk_a, pk_a) = generate_keypair();
        let card_a = sign_agent_card(
            &build_agent_card("raven-kettle", &pk_a, None, None, None),
            &sk_a,
        );
        let did_a = card_a
            .get("did")
            .and_then(Value::as_str)
            .unwrap()
            .to_string();

        let (sk_b, pk_b) = generate_keypair();
        let card_b = sign_agent_card(
            &build_agent_card("raven-kettle", &pk_b, None, None, None),
            &sk_b,
        );
        let did_b = card_b
            .get("did")
            .and_then(Value::as_str)
            .unwrap()
            .to_string();
        assert_ne!(did_a, did_b, "test setup: distinct keys ⇒ distinct DIDs");

        let mut t = empty_trust();
        add_agent_card_pin(&mut t, &card_a, Some("VERIFIED")).unwrap();

        // Different identity, same nick → refused; incumbent A survives.
        let err = add_agent_card_pin(&mut t, &card_b, Some("VERIFIED")).unwrap_err();
        assert!(
            err.contains("collision"),
            "expected collision error, got: {err}"
        );
        assert_eq!(
            t["agents"]["raven-kettle"]["did"], did_a,
            "incumbent A's pin must NOT be overwritten by colliding identity B"
        );

        // Same identity re-pin (e.g. tier bump / key succession keeps the DID)
        // is still allowed.
        add_agent_card_pin(&mut t, &card_a, Some("TRUSTED")).unwrap();
        assert_eq!(t["agents"]["raven-kettle"]["tier"], "TRUSTED");
    }

    #[test]
    fn resolve_peer_did_falls_back_to_bare_for_unknown_peer() {
        // Pre-pair best-effort: an unknown peer canonicalizes to the
        // bare-handle DID. cmd_send / tool_send keep working pre-pair;
        // post-pair the resolve path takes over.
        let t = empty_trust();
        assert_eq!(
            resolve_peer_did(&t, "ghost-peer"),
            "did:wire:ghost-peer",
            "unknown peer falls back to bare-handle DID"
        );
    }

    #[test]
    fn add_agent_card_pin_defaults_untrusted() {
        let (sk, pk) = generate_keypair();
        let card = sign_agent_card(&build_agent_card("paul", &pk, None, None, None), &sk);
        let mut t = empty_trust();
        add_agent_card_pin(&mut t, &card, None).unwrap();
        assert_eq!(get_tier(&t, "paul"), "UNTRUSTED");
        // v0.5.7+: DID is pubkey-suffixed.
        let did = t["agents"]["paul"]["did"].as_str().unwrap();
        assert!(did.starts_with("did:wire:paul-"), "got: {did}");
    }

    #[test]
    fn add_pin_strips_ed25519_prefix_from_key_id() {
        let (sk, pk) = generate_keypair();
        let card = sign_agent_card(&build_agent_card("paul", &pk, None, None, None), &sk);
        let mut t = empty_trust();
        add_agent_card_pin(&mut t, &card, None).unwrap();
        let kid = t["agents"]["paul"]["public_keys"][0]["key_id"]
            .as_str()
            .unwrap();
        assert!(kid.contains(':'));
        assert!(!kid.starts_with("ed25519:"));
    }

    #[test]
    fn promote_to_verified_one_way() {
        let (sk, pk) = generate_keypair();
        let card = sign_agent_card(&build_agent_card("paul", &pk, None, None, None), &sk);
        let mut t = empty_trust();
        add_agent_card_pin(&mut t, &card, None).unwrap();
        promote_to_verified(&mut t, "paul").unwrap();
        assert_eq!(get_tier(&t, "paul"), "VERIFIED");
        assert!(t["agents"]["paul"]["verified_at"].is_string());
    }

    #[test]
    fn promote_to_verified_idempotent_block() {
        let (sk, pk) = generate_keypair();
        let card = sign_agent_card(&build_agent_card("paul", &pk, None, None, None), &sk);
        let mut t = empty_trust();
        add_agent_card_pin(&mut t, &card, None).unwrap();
        promote_to_verified(&mut t, "paul").unwrap();
        let err = promote_to_verified(&mut t, "paul").unwrap_err();
        assert!(err.contains("VERIFIED"), "got: {err}");
    }

    #[test]
    fn promote_unknown_peer_fails() {
        let mut t = empty_trust();
        let err = promote_to_verified(&mut t, "ghost").unwrap_err();
        assert!(err.contains("not pinned"), "got: {err}");
    }

    #[test]
    fn add_self_to_trust_attests() {
        let (_, pk) = generate_keypair();
        let mut t = empty_trust();
        add_self_to_trust(&mut t, "paul", &pk);
        assert_eq!(get_tier(&t, "paul"), "ATTESTED");
        let did = t["agents"]["paul"]["did"].as_str().unwrap();
        assert!(did.starts_with("did:wire:paul-"), "got: {did}");
    }

    #[test]
    fn tier_order_matches_promotion_semantics() {
        let order = tier_order();
        assert!(order["UNTRUSTED"] < order["ORG_VERIFIED"]);
        assert!(order["ORG_VERIFIED"] < order["VERIFIED"]);
        assert!(order["VERIFIED"] < order["ATTESTED"]);
        assert!(order["ATTESTED"] < order["TRUSTED"]);
    }

    // ─── RFC-001 §5: Tier::OrgVerified ────────────────────────────────────

    #[test]
    fn tier_as_str_covers_org_verified() {
        assert_eq!(Tier::OrgVerified.as_str(), "ORG_VERIFIED");
    }

    #[test]
    fn promote_to_org_verified_one_way() {
        let (sk, pk) = generate_keypair();
        let card = sign_agent_card(&build_agent_card("paul", &pk, None, None, None), &sk);
        let mut t = empty_trust();
        add_agent_card_pin(&mut t, &card, None).unwrap();
        promote_to_org_verified(&mut t, "paul").unwrap();
        assert_eq!(get_tier(&t, "paul"), "ORG_VERIFIED");
        assert!(t["agents"]["paul"]["org_verified_at"].is_string());
    }

    #[test]
    fn promote_to_org_verified_refuses_already_verified() {
        // Once a peer is VERIFIED (bilateral SAS), regressing them to
        // ORG_VERIFIED would be a downgrade. Refuse.
        let (sk, pk) = generate_keypair();
        let card = sign_agent_card(&build_agent_card("paul", &pk, None, None, None), &sk);
        let mut t = empty_trust();
        add_agent_card_pin(&mut t, &card, None).unwrap();
        promote_to_verified(&mut t, "paul").unwrap();
        let err = promote_to_org_verified(&mut t, "paul").unwrap_err();
        assert!(err.contains("VERIFIED"), "got: {err}");
        assert_eq!(get_tier(&t, "paul"), "VERIFIED");
    }

    #[test]
    fn promote_to_org_verified_refuses_self_idempotent() {
        // Twice-applied org promotion is a no-op error, not a silent reset
        // of `org_verified_at` — keeps the audit trail intact.
        let (sk, pk) = generate_keypair();
        let card = sign_agent_card(&build_agent_card("paul", &pk, None, None, None), &sk);
        let mut t = empty_trust();
        add_agent_card_pin(&mut t, &card, None).unwrap();
        promote_to_org_verified(&mut t, "paul").unwrap();
        let err = promote_to_org_verified(&mut t, "paul").unwrap_err();
        assert!(err.contains("ORG_VERIFIED"), "got: {err}");
    }

    #[test]
    fn promote_to_verified_accepts_org_verified_source() {
        // RFC-001 §5: a peer can be ORG_VERIFIED then later cross the SAS
        // ceremony into VERIFIED — without losing the cryptographic
        // membership claim. We preserve `org_verified_at` for audit.
        let (sk, pk) = generate_keypair();
        let card = sign_agent_card(&build_agent_card("paul", &pk, None, None, None), &sk);
        let mut t = empty_trust();
        add_agent_card_pin(&mut t, &card, None).unwrap();
        promote_to_org_verified(&mut t, "paul").unwrap();
        promote_to_verified(&mut t, "paul").unwrap();
        assert_eq!(get_tier(&t, "paul"), "VERIFIED");
        assert!(t["agents"]["paul"]["org_verified_at"].is_string());
        assert!(t["agents"]["paul"]["verified_at"].is_string());
    }

    #[test]
    fn promote_to_verified_refuses_attested_source() {
        // ATTESTED is reserved-but-above VERIFIED; a downgrade would lose
        // information. Refuse.
        let (_, pk) = generate_keypair();
        let mut t = empty_trust();
        add_self_to_trust(&mut t, "self", &pk);
        let err = promote_to_verified(&mut t, "self").unwrap_err();
        assert!(err.contains("ATTESTED"), "got: {err}");
    }

    #[test]
    fn effective_tier_matrix() {
        use serde_json::json;
        // VERIFIED in trust + bilateral_completed_at present → stays VERIFIED.
        let trust = json!({"agents": {"a": {"tier": "VERIFIED"}}});
        let relay = json!({"peers": {"a": {"bilateral_completed_at": "t"}}});
        assert_eq!(effective_tier(&trust, &relay, "a"), "VERIFIED");
        // RFC-006 Part B: a flat-only `slot_token` (no endpoints[]) is NOT a
        // routing source anymore — it reads PENDING_ACK, like any flat-only pin.
        let relay = json!({"peers": {"a": {"slot_token": "tok"}}});
        assert_eq!(effective_tier(&trust, &relay, "a"), "PENDING_ACK");
        // VERIFIED in trust + no bilateral_at + empty slot_token → PENDING_ACK.
        let relay = json!({"peers": {"a": {"slot_token": ""}}});
        assert_eq!(effective_tier(&trust, &relay, "a"), "PENDING_ACK");
        // VERIFIED in trust + peer missing from relay.peers entirely → PENDING_ACK.
        let relay = json!({"peers": {}});
        assert_eq!(effective_tier(&trust, &relay, "a"), "PENDING_ACK");
        // RFC-006 Part B: the slot lives in endpoints[], not a flat field. A
        // non-empty slot_token there must read as VERIFIED (the regression this
        // guards: Part B emptied the flat field, so a flat-only reader wrongly
        // downgraded every freshly-paired peer to PENDING_ACK).
        let relay = json!({"peers": {"a": {"endpoints": [
            {"relay_url": "https://r", "slot_id": "s", "slot_token": "tok", "scope": "federation"}
        ]}}});
        assert_eq!(effective_tier(&trust, &relay, "a"), "VERIFIED");
        // endpoints[] present but its slot_token empty → still PENDING_ACK.
        let relay = json!({"peers": {"a": {"endpoints": [
            {"relay_url": "https://r", "slot_id": "s", "slot_token": "", "scope": "federation"}
        ]}}});
        assert_eq!(effective_tier(&trust, &relay, "a"), "PENDING_ACK");
        // Non-VERIFIED trust tiers pass through unchanged.
        let trust = json!({"agents": {"a": {"tier": "UNTRUSTED"}}});
        assert_eq!(effective_tier(&trust, &relay, "a"), "UNTRUSTED");
        let trust = json!({"agents": {"a": {"tier": "ORG_VERIFIED"}}});
        assert_eq!(effective_tier(&trust, &relay, "a"), "ORG_VERIFIED");
    }

    #[test]
    fn project_recipients_filters_by_tier_and_project() {
        use serde_json::json;
        let trust = json!({"agents": {
            "alice":  {"tier": "ORG_VERIFIED", "card": {"project": "print-shop"}},
            "bob":    {"tier": "ORG_VERIFIED", "card": {"project": "lora-training"}},
            "carol":  {"tier": "UNTRUSTED",    "card": {"project": "print-shop"}},
            "dave":   {"tier": "VERIFIED",     "card": {"project": "print-shop"}},
            "selfie": {"tier": "ATTESTED",     "card": {"project": "print-shop"}},
            "noproj": {"tier": "ORG_VERIFIED", "card": {}},
        }});
        // VERIFIED dave needs a relay signal to read as VERIFIED (else PENDING_ACK).
        let relay = json!({"peers": {"dave": {"bilateral_completed_at": "t"}}});
        let r = project_recipients(&trust, &relay, "selfie", "print-shop");
        // alice (ORG_VERIFIED+match) and dave (VERIFIED+match) only. bob wrong
        // project; carol below floor; selfie is self; noproj has no tag.
        assert_eq!(r, vec!["alice".to_string(), "dave".to_string()]);
    }

    #[test]
    fn project_recipients_excludes_unreachable_verified() {
        use serde_json::json;
        // VERIFIED in trust but no relay signal → effective PENDING_ACK → we
        // can't actually deliver, so it must not be a fan-out recipient.
        let trust = json!({"agents": {
            "ghost": {"tier": "VERIFIED", "card": {"project": "x"}},
        }});
        let relay = json!({"peers": {}});
        assert!(project_recipients(&trust, &relay, "selfie", "x").is_empty());
    }

    #[test]
    fn org_verified_does_not_satisfy_verified_policy_check() {
        // The load-bearing RFC-001 invariant: a policy gate of
        // `tier >= VERIFIED` MUST refuse an ORG_VERIFIED peer.
        let order = tier_order();
        let verified_rank = order["VERIFIED"];
        let org_rank = order["ORG_VERIFIED"];
        assert!(
            org_rank < verified_rank,
            "ORG_VERIFIED ({org_rank}) must rank strictly below VERIFIED ({verified_rank})"
        );
    }
}