polyc-capability 2026.7.0

#![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, shell_exec) — even a
    // destructive one mutates only inside the box, so it stays local.
    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));
}

#[test]
fn taint_resilient_set_survives_only_when_policy_declares_it() {
    // Declared: arbitrary egress survives the subtraction.
    let resilient = GrantPolicy {
        base: CapabilitySet::all(),
        taint_resilient: set(&[Capability::ArbitraryEgress]),
    };
    let granted = granted_capabilities(resilient, TaintState::Tainted);
    assert!(granted.contains(Capability::ArbitraryEgress));
    // Only the declared capability survives — external mutation stays revoked.
    assert!(!granted.contains(Capability::MutateExternal));

    // Not declared (the default): nothing survives.
    let granted = granted_capabilities(GrantPolicy::default(), TaintState::Tainted);
    assert!(!granted.contains(Capability::ArbitraryEgress));

    // The resilient set never grants beyond the base policy.
    let narrow = GrantPolicy {
        base: set(&[Capability::LocalRead]),
        taint_resilient: set(&[Capability::ArbitraryEgress]),
    };
    for taint in [TaintState::Clean, TaintState::Tainted] {
        assert_eq!(
            granted_capabilities(narrow, taint),
            set(&[Capability::LocalRead]),
            "resilience must not mint a capability the base never granted"
        );
    }
}

// Monotonicity, exhaustively: under EVERY fixed policy (all 32×32
// base × taint-resilient combinations), 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() {
        for resilient in all_sets() {
            let policy = GrantPolicy {
                base,
                taint_resilient: resilient,
            };
            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={:?} resilient={:?}",
                base.names(),
                resilient.names()
            );
            assert!(
                tainted.is_subset_of(base),
                "granted escaped the base policy under base={:?} resilient={:?}",
                base.names(),
                resilient.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 × arbitrary-egress × taint-resilient policy ⇒ allow.
    let resilient_policy = GrantPolicy {
        base: CapabilitySet::all(),
        taint_resilient: set(&[Capability::ArbitraryEgress]),
    };
    let resilient_grants = granted_capabilities(resilient_policy, TaintState::Tainted);
    let fetch = required_capabilities(ToolProfile {
        read_only: true,
        open_world: true,
        ..profile(ToolOrigin::Fetcher)
    });
    assert_eq!(
        decide(fetch, resilient_grants, &CallPolicy::default(), "web_fetch"),
        GateOutcome::Allow
    );

    // Row 3: 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));
}

// ── 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]),
    ];
    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"
    );
}