Scope Matching

Ranking and fallback

Follow the selected grant from the ranking into admission. Surviving grants are ranked, never filtered further:

matches.push(MatchedGrant {
    index,
    grant,
    specificity: (
        u8::from(grant.server_id == server_id),
        u8::from(grant.tool_name == tool_name),
        grant.constraints.len(),
    ),
});
// ...
matches.sort_by(|left, right| {
    right
        .specificity
        .cmp(&left.specificity)
        .then_with(|| left.index.cmp(&right.index))
});

The first two keys test string equality against the request, so exactness is per request. The third ranks a more constrained grant higher, which is safe in the portable core because a grant reaches the ranking only after every one of its constraints held. The hosted matcher reuses the tuple while ten of its variants return Ok(true) at this stage, so a hosted grant can outrank a sibling on constraints that are checked later.

exact_grants_sort_ahead_of_wildcard_fallbacks pins the order against a two-grant scope written wildcard-first: the exact grant lands at position 0 carrying grant index 1 and specificity (1, 1, 0), and the wildcard follows at position 1 carrying index 0. Portable evaluate takes the first match, matches.first(); adapters that call resolve_matching_grants directly receive the whole ranked list, which is how the AG-UI proxy iterates it.

• A resumed durable admission skips any candidate permits_matching_grant rejects: a grant index the recorded budget hold id does not name, or a grant whose cost caps do not match the operation's payment requirement.
• For each remaining candidate the order is governed-transaction validation, the guard pipeline under its time budget, the runtime admission hook, and last check_and_increment_budget. Guards run before the monetary hold.
• Governed-validation errors, guard denials, and BudgetExhausted with a released runtime reservation continue the loop. A runtime-admission denial, a pending-approval outcome, and any other budget error return on the candidate that produced them.
• When the loop ends with no selection, a recorded budget error outranks a guard denial, which outranks a governed-validation error. A guard denial against the most specific grant decides the request only after every later candidate has also failed and none recorded a budget error.

Constraint behavior by runtime

Read the hosted column as three behaviors. Eleven variants are decided here. Ten return Ok(true) and are enforced elsewhere, so a grant carrying only those passes the matcher and can still be refused later. Three return Ok(false) without reading the value, even ContentReviewTier::None or RequireDualApproval(false), because their enforcement needs runtime context from a dedicated path; that is a candidate drop, and a sibling grant may still admit the call.

Argument reading

PathPrefix, DomainExact, DomainGlob, and MaxLength scan collect_string_leaves, a recursive walk that flattens the arguments into (key, value) pairs for every string in the tree. Arrays inherit the enclosing key; numbers, booleans, and nulls are not leaves. These four apply to whatever in the arguments looks like their subject, unbound to any named parameter. The other four walk the raw arguments value: MaxArgsSize re-serializes it, Custom recurses for one entry, and the two allowlists recurse with collect_string_values_strict.

PathPrefixNo candidate: does not match

Every string leaf whose lowercased key contains path or is one of file, filepath, dir, directory, root, cwd, plus every value that carries a slash or backslash and no ://. All must sit under the prefix, compared segment by segment after lexical normalization.

DomainExact, DomainGlobNo candidate: does not match

Every string leaf that parse_domain accepts: scheme, userinfo, port, path, query, and fragment are stripped, then the host is lowercased and dot-trimmed. All must equal the expected domain, or match the glob through the backtracking wildcard_matches.

MaxLengthNo candidate: matches vacuously

Every string leaf value, compared by byte length, not character count. An argument object with no strings satisfies any length cap.

MaxArgsSizeAlways evaluable

arguments.to_string().len(), the compact re-serialization, so whitespace in the caller's JSON never counts against the cap.

Custom(key, expected)No candidate: does not match

A recursive search for any object entry under key, compared case-sensitively, whose value is the exact string expected. One matching entry anywhere in the arguments satisfies it.

AudienceAllowlistKey absent: matches. Present but empty or non-string: does not match

Values under recipient, recipients, audience, to, channel, channels, collected strictly.

MemoryStoreAllowlistSame three-way split as the audience allowlist

Values under store, memory_store, collection, namespace, matched case-insensitively at any depth.

parse_domain accepts any non-empty string that contains a dot and consists only of ASCII alphanumerics, hyphens, and dots, plus the literal localhost. Under that rule report.txt is a domain candidate, and because the domain constraints require every candidate to match, a request carrying a URL and one unrelated dotted token drops the grant. looks_like_path treats any value with a slash and no :// the same way, so an incidental application/json has to sit under the prefix too.

AudienceAllowlist claims the key to at any depth, so a date range written as {"to": "2026-07-28"} is an observed audience value and fails the allowlist. Scope these constraints to tools whose arguments are the constrained value and little else.

• Path matching is lexical. normalize_path treats \ as a separator, resolves . and .., and compares byte-equal segments with no filesystem access, so it resolves no symlink, folds no case, and expands no ~. A .. that pops above the root returns None, which makes path_has_prefix false. A symlink inside an allowed prefix that points outside it satisfies PathPrefix; the Filesystem Guard checks that case.
• DomainGlob globs the whole hostname string, not label by label. * crosses dots, so *.larkfield.example also admits a.b.larkfield.example, and a trailing star is a raw prefix match: larkfield.example* admits larkfield.example.example.net. The pattern is lowercased without normalize_domain, so a pattern written with a trailing dot never matches.

The strict collector returns false on any non-string, non-array leaf, so {"audience": null}, {"audience": 42}, {"audience": []}, and {"audience": ["security", null]} all fail closed while an absent key allows. Treating an explicit null as absence would let anyone who controls a nullable field switch the allowlist off. The portable core copies these semantics from the hosted kernel case for case; resolve_matching_grants_audience_null_fails_closed_and_missing_allows, resolve_matching_grants_audience_allowlist_rejects_non_string_values, and resolve_matching_grants_audience_mixed_null_array_fails_closed pin them.

Matcher API

A match borrows a grant with its position and its rank. Nothing is cloned or normalized into a new shape.

pub struct MatchedGrant<'a> {
    /// Index of this grant inside the scope's grant vector.
    pub index: usize,
    /// The matched grant itself.
    pub grant: &'a ToolGrant,
    /// Specificity tuple: `(server-exact, tool-exact, constraint-count)`.
    pub specificity: (u8, u8, usize),
}

pub enum ScopeMatchError {
    /// No grant in the scope covers the requested `(server, tool, Invoke)`.
    OutOfScope,
    /// The portable kernel cannot safely evaluate a constraint carried by a
    /// target-matching grant.
    ConstraintError(String),
}

The proxy treats a match as a candidate. It calls resolve_capability_grants with a synthesized argument object, then requires matches.iter().any(|matched| grant_binds_event(matched.grant, event)), a second predicate that re-reads the grant's Custom constraints against trusted event fields (event_id, session_id, target_component_type, target_component_id). A non-empty match set where nothing binds falls into the same capability scope does not authorize this AG-UI event block as OutOfScope, and ConstraintError blocks with capability scope constraint failed: {reason}. Because the proxy uses any(), it computes the specificity order and then ignores it.

Cumulative approval before matching

RequireCumulativeApprovalAbove is on the portable refusal list, and every evaluate entry point refuses it before matching. On the plain path, verify_capability_with_floor passes cumulative_approval_enabled = false, so verification rejects the token with cumulative_approval_budget was not negotiated. On the full-floor path a peer may negotiate the feature, and evaluate_with_full_floor_and_root checks scope.has_cumulative_approval() and denies with UnsupportedCapabilityFeature before scope matching runs.

The AG-UI proxy runs the same has_cumulative_approval() check before it calls resolve_capability_grants. The matcher's own ConstraintError for the variant is reachable only through a direct resolve_matching_grants call, which resolve_matching_grants_rejects_cumulative_approval_until_enforced makes. Negotiated features in capability/features.rs decide whether a token is admissible at all, and the matcher is the last check in that sequence.

Tests and model checking

• constraint_name is an exhaustive match, so a new Constraint variant fails to compile until it is placed among the decided or refused variants in constraint_matches.
• Four tests in tests/mutation_boundaries.rs pin the strict allowlist shapes for both allowlists.
• tests/scope_proptest.rs runs four proptest properties at 96 cases by default, overridable through PROPTEST_CASES: a normalized descendant of a PathPrefix matches and a sibling directory does not; domain matching normalizes case and URL authority; a domain glob admits a subdomain and not the base domain; MaxLength and MaxArgsSize are inclusive at the boundary.
• Kani checks public_resolve_matching_grants_rejects_out_of_scope_request and public_resolve_matching_grants_preserves_wildcard_matching, both listed in .kani/harnesses.toml: a grant that does not cover the request yields an empty match set, and a */* grant yields exactly one match with specificity (0, 0, 0).

The Kani harnesses cover their fixtures: fixed server and tool strings, Value::Null arguments, and kani::assume pinning the scope to one unconstrained Invoke grant through assume_single_unconstrained_invoke_grant. The #[cfg(kani)] shortcut at the top of resolve_matching_grants refuses a constrained one-grant fixture outright, so constraint semantics rest on the proptest and unit suites.

The hosted kernel decides the 8 shared variants with the same semantics in crates/kernel/chio-kernel/src/request_matching.rs, pinned by tests that mirror those for crates/kernel/chio-kernel-core/src/scope.rs.