polyc-capability 2026.8.3

#![allow(clippy::pedantic, clippy::nursery, missing_docs)]

use serde_json::json;

use super::*;

fn spec(name: &str) -> ToolSpec {
    ToolSpec::new(name, "d", json!({}))
}

fn profile(origin: ToolOrigin) -> ToolProfile {
    ToolProfile {
        origin,
        read_only: false,
        destructive: false,
        open_world: false,
    }
}

const fn set(caps: &[Capability]) -> CapabilitySet {
    let mut s = CapabilitySet::EMPTY;
    let mut i = 0;
    while i < caps.len() {
        s = s.with(caps[i]);
        i += 1;
    }
    s
}

// ── Set type ─────────────────────────────────────────────────────────────────

#[test]
fn set_algebra_is_sound() {
    let a = set(&[Capability::LocalRead, Capability::ArbitraryEgress]);
    let b = set(&[Capability::ArbitraryEgress, Capability::MutateExternal]);
    assert!(a.contains(Capability::LocalRead));
    assert!(!a.contains(Capability::MutateExternal));
    assert_eq!(
        a.union(b),
        set(&[
            Capability::LocalRead,
            Capability::ArbitraryEgress,
            Capability::MutateExternal
        ])
    );
    assert_eq!(a.intersection(b), set(&[Capability::ArbitraryEgress]));
    assert_eq!(a.difference(b), set(&[Capability::LocalRead]));
    assert!(set(&[Capability::LocalRead]).is_subset_of(a));
    assert!(!a.is_subset_of(b));
    assert!(CapabilitySet::EMPTY.is_empty());
    assert!(CapabilitySet::EMPTY.is_subset_of(CapabilitySet::EMPTY));
    // `all()` contains every member of the taxonomy.
    for c in Capability::ALL {
        assert!(
            CapabilitySet::all().contains(c),
            "{} missing from all()",
            c.as_str()
        );
    }
    // Iteration round-trips through FromIterator.
    let rebuilt: CapabilitySet = a.iter().collect();
    assert_eq!(rebuilt, a);
}

#[test]
fn names_round_trip_and_unknown_names_grant_nothing() {
    // Every capability's stable name parses back to itself.
    for c in Capability::ALL {
        assert_eq!(Capability::from_name(c.as_str()), Some(c), "{}", c.as_str());
    }
    assert_eq!(Capability::from_name("egress"), None);
    assert_eq!(Capability::from_name(""), None);

    // from_names: recognized names land in the set; unknown names are
    // reported, never granted (a typo in operator config grants nothing).
    let (parsed, unknown) =
        CapabilitySet::from_names(["arbitrary-egress", "definitely-not-a-capability", ""]);
    assert_eq!(parsed, set(&[Capability::ArbitraryEgress]));
    assert_eq!(
        unknown,
        vec!["definitely-not-a-capability".to_owned(), String::new()]
    );

    // names() is the inverse of from_names for valid input.
    let all_names = CapabilitySet::all().names();
    let (reparsed, unknown) = CapabilitySet::from_names(all_names);
    assert_eq!(reparsed, CapabilitySet::all());
    assert!(unknown.is_empty());
}

// ── Requirement derivation ────────────────────────────────────────────────────

// The derivation table, one row per annotation × origin combination that
// exists in the tool surface today (#591 acceptance).
#[test]
fn required_capabilities_maps_annotations_and_provenance() {
    // Sandbox-confined read-only built-in (file_read, grep, glob).
    let local_read = ToolProfile {
        read_only: true,
        ..profile(ToolOrigin::LocalSandbox)
    };
    assert_eq!(
        required_capabilities(local_read),
        set(&[Capability::LocalRead])
    );

    // Sandbox-confined mutating built-in (file_write) — even a destructive one
    // mutates only inside the box, so it stays local. `shell_exec` is NOT an
    // example here: it also reaches the network, so `required_for_spec` gives
    // it `ArbitraryEgress` by name instead of this profile (`#2508`).
    let local_write = ToolProfile {
        destructive: true,
        ..profile(ToolOrigin::LocalSandbox)
    };
    assert_eq!(
        required_capabilities(local_write),
        set(&[Capability::LocalRead, Capability::LocalWrite])
    );

    // Open-world fetcher (web_fetch): arbitrary egress.
    let web = ToolProfile {
        read_only: true,
        open_world: true,
        ..profile(ToolOrigin::Fetcher)
    };
    assert_eq!(
        required_capabilities(web),
        set(&[Capability::ArbitraryEgress])
    );

    // Paying fetcher (paid_fetch, destructive): egress + external mutation.
    let paid = ToolProfile {
        destructive: true,
        open_world: true,
        ..profile(ToolOrigin::Fetcher)
    };
    assert_eq!(
        required_capabilities(paid),
        set(&[Capability::ArbitraryEgress, Capability::MutateExternal])
    );

    // Read-only operator-registered connector (service_list): fixed-connector
    // read only — the exemption that used to be a special case.
    let registered_read = ToolProfile {
        read_only: true,
        ..profile(ToolOrigin::RegisteredConnector)
    };
    assert_eq!(
        required_capabilities(registered_read),
        set(&[Capability::FixedConnectorRead])
    );

    // Open-world flag on a REGISTERED read-only connector affects ingestion
    // (taint), not the required set: the dial still goes to the one
    // operator-vouched endpoint (the service_status case, #585).
    let registered_open_read = ToolProfile {
        read_only: true,
        open_world: true,
        ..profile(ToolOrigin::RegisteredConnector)
    };
    assert_eq!(
        required_capabilities(registered_open_read),
        set(&[Capability::FixedConnectorRead])
    );

    // Mutating registered connector: reaches its endpoint AND mutates outside.
    let registered_mutating = profile(ToolOrigin::RegisteredConnector);
    assert_eq!(
        required_capabilities(registered_mutating),
        set(&[Capability::FixedConnectorRead, Capability::MutateExternal])
    );

    // Destructive dominates read_only for a connector (an incoherent
    // self-declaration must not shed the mutation requirement).
    let registered_destructive_read = ToolProfile {
        read_only: true,
        destructive: true,
        ..profile(ToolOrigin::RegisteredConnector)
    };
    assert_eq!(
        required_capabilities(registered_destructive_read),
        set(&[Capability::FixedConnectorRead, Capability::MutateExternal])
    );

    // First-party built-ins (history/wallet families): same shape as a
    // registered connector.
    let first_party_read = ToolProfile {
        read_only: true,
        ..profile(ToolOrigin::FirstParty)
    };
    assert_eq!(
        required_capabilities(first_party_read),
        set(&[Capability::FixedConnectorRead])
    );

    // Unclassifiable ⇒ the full privileged set, fail closed (#591 acceptance).
    let unknown = ToolProfile {
        read_only: true, // self-declared hints do not help an unknown origin
        ..profile(ToolOrigin::Unknown)
    };
    assert_eq!(required_capabilities(unknown), CapabilitySet::all());
}

#[test]
fn profile_reads_spec_annotations() {
    let s = spec("t").read_only().open_world();
    let p = ToolProfile::for_spec(&s, ToolOrigin::RegisteredConnector);
    assert!(p.read_only && p.open_world && !p.destructive);
    assert_eq!(p.origin, ToolOrigin::RegisteredConnector);
}

// A self-declared read-only, closed-world connector WITHOUT operator
// registration is not taint-immune: taint-immunity (fixed-connector read) is
// earned only by registry provenance, never by the connector's own hints
// (the MCP-spec rule, #592's trust scoping — pinned here in the pure core).
#[test]
fn self_declared_hints_never_earn_taint_immunity() {
    let self_declared = ToolProfile {
        read_only: true,
        ..profile(ToolOrigin::Unknown)
    };
    let required = required_capabilities(self_declared);
    // Requires the taint-revoked capabilities, so taint gates it.
    assert!(required.contains(Capability::ArbitraryEgress));
    assert!(required.contains(Capability::MutateExternal));
    let granted = granted_capabilities(GrantPolicy::default(), TaintState::Tainted);
    assert!(!required.is_subset_of(granted));
}

// ── Grant derivation ──────────────────────────────────────────────────────────

#[test]
fn taint_revokes_egress_and_external_mutation() {
    let policy = GrantPolicy::default();
    let clean = granted_capabilities(policy, TaintState::Clean);
    assert_eq!(clean, CapabilitySet::all());

    let tainted = granted_capabilities(policy, TaintState::Tainted);
    assert!(!tainted.contains(Capability::ArbitraryEgress));
    assert!(!tainted.contains(Capability::MutateExternal));
    // Everything else survives: local work and fixed-connector reads.
    assert!(tainted.contains(Capability::LocalRead));
    assert!(tainted.contains(Capability::LocalWrite));
    assert!(tainted.contains(Capability::FixedConnectorRead));
}

// Monotonicity, exhaustively: under every fixed base policy, adding taint never
// adds a capability (#591 acceptance).
#[test]
fn grants_are_monotonic_under_every_fixed_policy() {
    let all_sets = || {
        (0..32u8).map(|bits| {
            Capability::ALL
                .into_iter()
                .enumerate()
                .filter(|(i, _)| bits & (1 << i) != 0)
                .map(|(_, c)| c)
                .collect::<CapabilitySet>()
        })
    };
    for base in all_sets() {
        let policy = GrantPolicy { base };
        let clean = granted_capabilities(policy, TaintState::Clean);
        let tainted = granted_capabilities(policy, TaintState::Tainted);
        assert!(
            tainted.is_subset_of(clean),
            "taint added a capability under base={:?}",
            base.names()
        );
        assert!(
            tainted.is_subset_of(base),
            "granted escaped the base policy under base={:?}",
            base.names()
        );
    }
}

// ── Decision engine ───────────────────────────────────────────────────────────

#[test]
fn veto_takes_precedence_over_everything() {
    let policy = CallPolicy {
        veto: Some("path escapes the workspace".to_owned()),
        requires_human: true,
        sandbox_escalation: true,
        transform: ArgTransform::Rewrite("{}".to_owned()),
    };
    // Even a call missing capabilities denies rather than escalates: a human
    // approval cannot satisfy a hard policy veto.
    let out = decide(
        CapabilitySet::all(),
        CapabilitySet::EMPTY,
        &policy,
        "shell_exec",
    );
    assert_eq!(
        out,
        GateOutcome::Deny("path escapes the workspace".to_owned())
    );
}

#[test]
fn missing_capabilities_escalate_with_the_missing_set() {
    let required = set(&[Capability::ArbitraryEgress]);
    let granted = granted_capabilities(GrantPolicy::default(), TaintState::Tainted);
    let out = decide(required, granted, &CallPolicy::default(), "web_fetch");
    let GateOutcome::Escalate { reason, missing } = out else {
        panic!("expected escalate, got {out:?}");
    };
    assert_eq!(missing, set(&[Capability::ArbitraryEgress]));
    assert!(
        reason.contains("web_fetch"),
        "reason names the tool: {reason}"
    );
    assert!(!reason.is_empty());
}

#[test]
fn policy_gate_escalates_with_empty_missing_set_and_empty_reason() {
    // An intrinsic/argument-aware gate (requires_human) escalates even when
    // every capability is granted — with no missing set and no special
    // reason, so edges render their default prompt.
    let policy = CallPolicy {
        requires_human: true,
        ..CallPolicy::default()
    };
    let out = decide(
        set(&[Capability::LocalRead]),
        CapabilitySet::all(),
        &policy,
        "shell_exec",
    );
    assert_eq!(
        out,
        GateOutcome::Escalate {
            reason: String::new(),
            missing: CapabilitySet::EMPTY
        }
    );

    // Same for a sandbox-denial escalation.
    let policy = CallPolicy {
        sandbox_escalation: true,
        ..CallPolicy::default()
    };
    let out = decide(
        set(&[Capability::LocalWrite]),
        CapabilitySet::all(),
        &policy,
        "file_write",
    );
    assert!(matches!(out, GateOutcome::Escalate { missing, .. } if missing.is_empty()));
}

#[test]
fn allowed_calls_honor_the_argument_transform() {
    let granted = CapabilitySet::all();
    let required = set(&[Capability::LocalRead]);

    let out = decide(required, granted, &CallPolicy::default(), "file_read");
    assert_eq!(out, GateOutcome::Allow);

    let rewrite = CallPolicy {
        transform: ArgTransform::Rewrite(r#"{"path":"safe.txt"}"#.to_owned()),
        ..CallPolicy::default()
    };
    assert_eq!(
        decide(required, granted, &rewrite, "file_read"),
        GateOutcome::Modify(r#"{"path":"safe.txt"}"#.to_owned())
    );

    let inject = CallPolicy {
        transform: ArgTransform::InjectContext("note".to_owned()),
        ..CallPolicy::default()
    };
    assert_eq!(
        decide(required, granted, &inject, "file_read"),
        GateOutcome::InjectContext("note".to_owned())
    );

    // A transform never applies to an escalating call — the transform is
    // honored only when the call is otherwise allowed.
    let out = decide(
        CapabilitySet::all(),
        granted.difference(TAINT_REVOKED),
        &rewrite,
        "t",
    );
    assert!(matches!(out, GateOutcome::Escalate { .. }));
}

// The exhaustive table over required × granted: for EVERY pair of sets, the
// engine's outcome is pinned by pure subset algebra (no veto / policy gate).
#[test]
fn decision_table_is_exhaustive_over_required_and_granted() {
    let all_sets = || {
        (0..32u8).map(|bits| {
            Capability::ALL
                .into_iter()
                .enumerate()
                .filter(|(i, _)| bits & (1 << i) != 0)
                .map(|(_, c)| c)
                .collect::<CapabilitySet>()
        })
    };
    for required in all_sets() {
        for granted in all_sets() {
            let out = decide(required, granted, &CallPolicy::default(), "t");
            if required.is_subset_of(granted) {
                assert_eq!(
                    out,
                    GateOutcome::Allow,
                    "required={:?} granted={:?}",
                    required.names(),
                    granted.names()
                );
            } else {
                let GateOutcome::Escalate { missing, .. } = out else {
                    panic!(
                        "expected escalate for required={:?} granted={:?}",
                        required.names(),
                        granted.names()
                    );
                };
                assert_eq!(missing, required.difference(granted));
                assert!(!missing.is_empty());
            }
        }
    }
}

// The three rows that change behavior relative to the old OR-of-heuristics
// (#591 acceptance), driven through derivation + engine end-to-end.
#[test]
fn behavior_changing_rows_are_pinned() {
    let tainted_grants = granted_capabilities(GrantPolicy::default(), TaintState::Tainted);

    // Row 1: tainted × mutate-external × policy-would-allow ⇒ escalate.
    // (A mutating connector call under taint used to pass when base policy
    // allowed it — a message body is an exfiltration channel.)
    let mutating = required_capabilities(profile(ToolOrigin::RegisteredConnector));
    let out = decide(
        mutating,
        tainted_grants,
        &CallPolicy::default(),
        "send_message",
    );
    assert!(
        matches!(out, GateOutcome::Escalate { ref missing, .. } if missing.contains(Capability::MutateExternal)),
        "got {out:?}"
    );

    // Row 2: tainted × fixed-connector-read ⇒ allow (the read-only
    // first-party exemption, now structural instead of a carve-out).
    let read = required_capabilities(ToolProfile {
        read_only: true,
        ..profile(ToolOrigin::RegisteredConnector)
    });
    assert_eq!(
        decide(read, tainted_grants, &CallPolicy::default(), "service_list"),
        GateOutcome::Allow
    );
}

// Extending the taxonomy requires no decision-engine change: the engine is
// pure set algebra and never names a specific capability. Pinned by driving
// every single-member set through the same subset rule — a new member added
// to `Capability::ALL` automatically joins this loop (and the exhaustive
// tables above) with no edit to `decide`.
#[test]
fn engine_is_uniform_over_the_taxonomy() {
    for c in Capability::ALL {
        let single = CapabilitySet::of(c);
        let out = decide(single, CapabilitySet::EMPTY, &CallPolicy::default(), "t");
        assert!(
            matches!(out, GateOutcome::Escalate { missing, .. } if missing == single),
            "{}",
            c.as_str()
        );
        assert_eq!(
            decide(single, single, &CallPolicy::default(), "t"),
            GateOutcome::Allow,
            "{}",
            c.as_str()
        );
    }
}

// ── Annotation-monotonicity clamp (#598 seed) ────────────────────────────────

#[test]
fn redeclaration_only_ever_grows_the_required_set() {
    let origins = [
        ToolOrigin::LocalSandbox,
        ToolOrigin::Fetcher,
        ToolOrigin::FirstParty,
        ToolOrigin::RegisteredConnector,
        ToolOrigin::Unknown,
    ];
    let bools = [false, true];
    let mut profiles = Vec::new();
    for origin in origins {
        for read_only in bools {
            for destructive in bools {
                for open_world in bools {
                    profiles.push(ToolProfile {
                        origin,
                        read_only,
                        destructive,
                        open_world,
                    });
                }
            }
        }
    }
    // Exhaustive over old × new profiles: the clamped re-declaration never
    // shrinks the required set and never earns taint-immunity at runtime.
    for &old in &profiles {
        for &new in &profiles {
            let clamped = monotonic_redeclaration(old, new);
            let before = required_capabilities(old);
            let after = required_capabilities(clamped);
            assert!(
                before.is_subset_of(after),
                "re-declaration shrank requirements: old={old:?} new={new:?} clamped={clamped:?}"
            );
            // The specific downgrades called out in #598: open-world ⇒
            // closed-world and gaining read-only never take effect.
            assert!(
                !old.open_world || clamped.open_world,
                "open-world never downgrades to closed-world"
            );
            assert!(
                old.read_only || !clamped.read_only,
                "a tool never gains read-only at runtime"
            );
        }
    }

    // Growth still works: a connector declaring a new destructive tool grows
    // the requirement.
    let old = ToolProfile {
        read_only: true,
        ..profile(ToolOrigin::RegisteredConnector)
    };
    let new = ToolProfile {
        destructive: true,
        ..profile(ToolOrigin::RegisteredConnector)
    };
    let clamped = monotonic_redeclaration(old, new);
    assert!(required_capabilities(clamped).contains(Capability::MutateExternal));
}

// ── Access grant (the admin invite, #700) ─────────────────────────────────────

// The never-granted marker: `GrantAccess` is held out of the grantable
// taxonomy, so it is absent from `all()`, from the default grant in EVERY taint
// state, and from name parsing — no policy or wire input can seed it.
#[test]
fn grant_access_is_never_granted_by_any_input() {
    // Not in the grantable taxonomy, so not in `all()` (the default base and the
    // fail-closed requirement for an unknown tool).
    assert!(!Capability::ALL.contains(&Capability::GrantAccess));
    assert!(!CapabilitySet::all().contains(Capability::GrantAccess));

    // Never in a derived grant, for either taint state, under the default and
    // an all-granting policy alike.
    for policy in [
        GrantPolicy::default(),
        GrantPolicy {
            base: CapabilitySet::EMPTY,
        },
    ] {
        for taint in [TaintState::Clean, TaintState::Tainted] {
            assert!(
                !granted_capabilities(policy, taint).contains(Capability::GrantAccess),
                "grant-access must never be granted (policy={policy:?}, taint={taint:?})"
            );
        }
    }

    // Unnameable in operator config: the name exists for display/telemetry but
    // cannot be parsed back INTO a grant, so a CR list can't confer it.
    assert_eq!(Capability::from_name("grant-access"), None);
    let (parsed, unknown) = CapabilitySet::from_names(["grant-access"]);
    assert!(parsed.is_empty(), "grant-access parses to nothing");
    assert_eq!(unknown, vec!["grant-access".to_owned()]);
}

// The load-bearing #700 invariant: the admin invite (an `AccessGrant`-origin
// tool) escalates for EVERY taint state and policy mode — a clean conversation
// included. This is the assertion that FAILS under #699's classification
// (invite as a first-party mutation, allowed on a clean context) and PASSES
// now.
#[test]
fn access_grant_always_escalates_in_every_state() {
    // The invite's requirement, regardless of how it declares itself.
    let required = required_capabilities(ToolProfile {
        read_only: false,
        destructive: true,
        open_world: true,
        ..profile(ToolOrigin::AccessGrant)
    });
    assert!(
        required.contains(Capability::GrantAccess),
        "an access-grant tool requires the never-granted marker"
    );

    for policy in [
        GrantPolicy::default(),
        GrantPolicy {
            base: CapabilitySet::EMPTY,
        },
    ] {
        for taint in [TaintState::Clean, TaintState::Tainted] {
            let granted = granted_capabilities(policy, taint);
            let out = decide(required, granted, &CallPolicy::default(), "invite");
            // #699 regression: a clean conversation must NOT be an autonomous
            // allow.
            assert_ne!(out, GateOutcome::Allow, "policy={policy:?} taint={taint:?}");
            let GateOutcome::Escalate { reason, missing } = out else {
                panic!("expected escalate for policy={policy:?} taint={taint:?}");
            };
            assert!(
                missing.contains(Capability::GrantAccess),
                "the shortfall names the access-grant marker"
            );
            assert!(reason.contains("invite"), "reason names the tool: {reason}");
        }
    }
}

// The #713 sibling of `grant_access_is_never_granted_by_any_input`: the
// remove-access marker must be equally un-grantable, or the removal tool
// could stop escalating under some future policy/taint combination.
#[test]
fn revoke_access_is_never_granted_by_any_input() {
    // Not in the grantable taxonomy, so not in `all()` (the default base and
    // the fail-closed requirement for an unknown tool).
    assert!(!Capability::ALL.contains(&Capability::RevokeAccess));
    assert!(!CapabilitySet::all().contains(Capability::RevokeAccess));

    // Never in a derived grant, for either taint state, under the default and
    // an all-granting policy alike.
    for policy in [
        GrantPolicy::default(),
        GrantPolicy {
            base: CapabilitySet::EMPTY,
        },
    ] {
        for taint in [TaintState::Clean, TaintState::Tainted] {
            assert!(
                !granted_capabilities(policy, taint).contains(Capability::RevokeAccess),
                "revoke-access must never be granted (policy={policy:?}, taint={taint:?})"
            );
        }
    }

    // Unnameable in operator config: the name exists for display/telemetry but
    // cannot be parsed back INTO a grant, so a CR list can't confer it.
    assert_eq!(Capability::from_name("revoke-access"), None);
    let (parsed, unknown) = CapabilitySet::from_names(["revoke-access"]);
    assert!(parsed.is_empty(), "revoke-access parses to nothing");
    assert_eq!(unknown, vec!["revoke-access".to_owned()]);
}

// The #713 sibling of `access_grant_always_escalates_in_every_state`: the
// remove-access tool (an `AccessRevoke`-origin tool) escalates for EVERY
// taint state and policy mode — a clean conversation included, exactly like
// the admin invite it mirrors.
#[test]
fn revoke_access_always_escalates_in_every_state() {
    let required = required_capabilities(ToolProfile {
        read_only: false,
        destructive: true,
        open_world: false,
        ..profile(ToolOrigin::AccessRevoke)
    });
    assert!(
        required.contains(Capability::RevokeAccess),
        "an access-revoke tool requires the never-granted marker"
    );

    for policy in [
        GrantPolicy::default(),
        GrantPolicy {
            base: CapabilitySet::EMPTY,
        },
    ] {
        for taint in [TaintState::Clean, TaintState::Tainted] {
            let granted = granted_capabilities(policy, taint);
            let out = decide(required, granted, &CallPolicy::default(), "revoke");
            assert_ne!(out, GateOutcome::Allow, "policy={policy:?} taint={taint:?}");
            let GateOutcome::Escalate { reason, missing } = out else {
                panic!("expected escalate for policy={policy:?} taint={taint:?}");
            };
            assert!(
                missing.contains(Capability::RevokeAccess),
                "the shortfall names the revoke-access marker"
            );
            assert!(reason.contains("revoke"), "reason names the tool: {reason}");
        }
    }
}

// The #715 sibling of `revoke_access_is_never_granted_by_any_input`: the
// manage-admin marker must be equally un-grantable, or the demote tool could
// stop escalating under some future policy/taint combination.
#[test]
fn manage_admin_is_never_granted_by_any_input() {
    // Not in the grantable taxonomy, so not in `all()` (the default base and
    // the fail-closed requirement for an unknown tool).
    assert!(!Capability::ALL.contains(&Capability::ManageAdmin));
    assert!(!CapabilitySet::all().contains(Capability::ManageAdmin));

    // Never in a derived grant, for either taint state, under the default and
    // an all-granting policy alike.
    for policy in [
        GrantPolicy::default(),
        GrantPolicy {
            base: CapabilitySet::EMPTY,
        },
    ] {
        for taint in [TaintState::Clean, TaintState::Tainted] {
            assert!(
                !granted_capabilities(policy, taint).contains(Capability::ManageAdmin),
                "manage-admin must never be granted (policy={policy:?}, taint={taint:?})"
            );
        }
    }

    // Unnameable in operator config: the name exists for display/telemetry but
    // cannot be parsed back INTO a grant, so a CR list can't confer it.
    assert_eq!(Capability::from_name("manage-admin"), None);
    let (parsed, unknown) = CapabilitySet::from_names(["manage-admin"]);
    assert!(parsed.is_empty(), "manage-admin parses to nothing");
    assert_eq!(unknown, vec!["manage-admin".to_owned()]);
}

// The #715 sibling of `revoke_access_always_escalates_in_every_state`: the
// demote tool (an `AdminManage`-origin tool) escalates for EVERY taint state
// and policy mode — a clean conversation included, exactly like the admin
// invite/revoke it completes the set alongside.
#[test]
fn manage_admin_always_escalates_in_every_state() {
    let required = required_capabilities(ToolProfile {
        read_only: false,
        destructive: true,
        open_world: false,
        ..profile(ToolOrigin::AdminManage)
    });
    assert!(
        required.contains(Capability::ManageAdmin),
        "an admin-manage tool requires the never-granted marker"
    );

    for policy in [
        GrantPolicy::default(),
        GrantPolicy {
            base: CapabilitySet::EMPTY,
        },
    ] {
        for taint in [TaintState::Clean, TaintState::Tainted] {
            let granted = granted_capabilities(policy, taint);
            let out = decide(required, granted, &CallPolicy::default(), "demote");
            assert_ne!(out, GateOutcome::Allow, "policy={policy:?} taint={taint:?}");
            let GateOutcome::Escalate { reason, missing } = out else {
                panic!("expected escalate for policy={policy:?} taint={taint:?}");
            };
            assert!(
                missing.contains(Capability::ManageAdmin),
                "the shortfall names the manage-admin marker"
            );
            assert!(reason.contains("demote"), "reason names the tool: {reason}");
        }
    }
}

// ── Copy ──────────────────────────────────────────────────────────────────────

#[test]
fn escalation_reason_is_plain_language_on_every_shape() {
    let shapes = [
        set(&[Capability::ArbitraryEgress]),
        set(&[Capability::MutateExternal]),
        set(&[Capability::ArbitraryEgress, Capability::MutateExternal]),
        set(&[Capability::LocalWrite]),
        set(&[Capability::GrantAccess]),
    ];
    for missing in shapes {
        let reason = escalation_reason("my_tool", missing);
        assert!(reason.contains("my_tool"), "{reason}");
        // The user-facing copy rules: no internal jargon, no apology words.
        for banned in [
            "capability",
            "trifecta",
            "egress",
            "exfiltrat",
            "taint",
            "please",
            "sorry",
            "unfortunately",
        ] {
            assert!(
                !reason.to_lowercase().contains(banned),
                "banned word {banned:?} in {reason:?}"
            );
        }
    }
    // The wording is honest, not alarming: a lower-risk call reads as a
    // routine check, and the outcome labels are stable for telemetry.
    assert_eq!(GateOutcome::Allow.label(), "allow");
    assert_eq!(
        GateOutcome::Escalate {
            reason: String::new(),
            missing: CapabilitySet::EMPTY
        }
        .label(),
        "escalate"
    );
    assert_eq!(GateOutcome::Deny(String::new()).label(), "deny");
    assert_eq!(GateOutcome::Modify(String::new()).label(), "modify");
    assert_eq!(
        GateOutcome::InjectContext(String::new()).label(),
        "inject_context"
    );
}

// ── Deployment viability (#1415) ────────────────────────────────────────────────

#[test]
fn requirement_name_round_trips_through_from_name() {
    for req in Requirement::ALL {
        assert_eq!(Requirement::from_name(req.as_str()), Some(req));
    }
    assert_eq!(Requirement::from_name("no-such-requirement"), None);
}

#[test]
fn requirement_names_are_unique() {
    let mut names: Vec<&str> = Requirement::ALL.iter().map(|r| r.as_str()).collect();
    let before = names.len();
    names.sort_unstable();
    names.dedup();
    assert_eq!(
        names.len(),
        before,
        "every Requirement must have a distinct wire name"
    );
}

#[test]
fn deployment_capabilities_default_is_nothing_viable() {
    let caps = DeploymentCapabilities::default();
    for req in Requirement::ALL {
        assert!(
            !caps.is_viable(req),
            "{req:?} must not be viable by default"
        );
    }
    assert!(caps.viable_names().is_empty());
}

#[test]
fn deployment_capabilities_viable_names_round_trips_through_from_names() {
    let caps = DeploymentCapabilities {
        mail_relay: true,
        wallet_link_ceremony: false,
        email_magic_link_ceremony: true,
        payments_proxy: false,
    };
    let names = caps.viable_names();
    assert_eq!(names, vec!["mail-relay", "ceremony-page:email-magic-link"]);
    assert_eq!(DeploymentCapabilities::from_names(names), caps);
}

#[test]
fn deployment_capabilities_from_names_ignores_unknown_entries() {
    let caps = DeploymentCapabilities::from_names(["mail-relay", "not-a-real-requirement"]);
    assert!(caps.mail_relay);
    assert!(!caps.payments_proxy);
}

#[test]
fn all_viable_is_true_only_when_every_requirement_is_met() {
    let caps = DeploymentCapabilities {
        mail_relay: true,
        payments_proxy: false,
        ..DeploymentCapabilities::default()
    };
    assert!(
        caps.all_viable(&[]),
        "an empty requirement list is always viable"
    );
    assert!(caps.all_viable(&[Requirement::MailRelay]));
    assert!(!caps.all_viable(&[Requirement::MailRelay, Requirement::PaymentsProxy]));
    assert!(!caps.all_viable(&[Requirement::PaymentsProxy]));
}