Scope Matching

One function, two callers, no state

chio_kernel_core::scope::resolve_matching_grants answers a single question: which grants in this scope authorize an Invoke of (server_id, tool_name) with these arguments. It is shipped, it is step 3 of evaluate, and formal/proof-manifest.toml names it and resolve_capability_grants as covered Rust symbols inside the bounded verified core.

The module opens by saying what it will not do:

//! The hosted kernel carries the richest matcher in
//! `chio-kernel::request_matching`, but the portable core must never
//! silently drop a grant constraint. Constraints that can be evaluated
//! from request arguments are enforced here; constraints that require
//! richer kernel state (governed intent, runtime attestation, SQL result
//! inspection, regex compilation, etc.) fail closed with an explicit
//! error instead of widening scope.

Two matchers exist because two runtimes exist. The hosted kernel has a regex engine, a governed-transaction evaluator, and the request’s model metadata. The portable core is no_std plus alloc, and the matcher takes four values: the scope, the tool name, the server id, and the arguments. Everything below follows from that signature. There is no clock, no store, no session, and no attestation record on this path, so any constraint whose meaning depends on one of those is not evaluable here, and the matcher says so by name rather than passing the grant through.

What comes back

A match is a borrow of a grant plus its position and its rank. Nothing is cloned and nothing is 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 two public entry points differ only in how they treat an empty result, and the difference is load-bearing for callers.

The proxy does not treat a match as an answer. It calls resolve_capability_grants with a synthesized argument object and 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) rather than against the arguments blob the matcher saw. A non-empty match set where nothing binds falls into the same capability scope does not authorize this AG-UI event block as OutOfScope; ConstraintError blocks with capability scope constraint failed: {reason}. Because the proxy uses any(), the specificity order described below is computed and then ignored on that path.

The function walks scope.grants only. resource_grants and prompt_grants are never consulted here; the hosted kernel matches those through separate helpers (capability_matches_resource_request, capability_matches_prompt_request) that have no portable equivalent.

Target match first, and it is not a glob

A grant is considered at all only when three predicates hold: matches_pattern(grant.server_id, server_id), the same on the tool name, and grant.operations.contains(&Operation::Invoke). matches_pattern is exactly pattern == "*" || pattern == candidate. A bare star matches everything; anything else is byte equality. There is no files-* prefix form and no path-style globbing on server or tool names. The trailing-star prefix rule that does exist in pattern_covers applies to resource and prompt subset checks during delegation, not to matching a request.

The operations check is equally literal. A grant listing only ReadResult or Delegate never admits a tool invocation, whatever its constraints say.

Decided and refused constraints

Only after the target matches does the matcher read constraints, and every constraint on a grant must hold for that grant to cover the request. The Constraint enum in crates/core/chio-core-types/src/capability/scope.rs carries 27 variants. The portable matcher decides 8 of them from arguments alone. The other 19 land in one match arm:

Constraint::RegexMatch(_)
| Constraint::GovernedIntentRequired
| Constraint::RequireApprovalAbove { .. }
| Constraint::RequireCumulativeApprovalAbove { .. }
| Constraint::SellerExact(_)
| Constraint::MinimumRuntimeAssurance(_)
| Constraint::MinimumAutonomyTier(_)
| Constraint::TableAllowlist(_)
| Constraint::ColumnDenylist(_)
| Constraint::MaxRowsReturned(_)
| Constraint::OperationClass(_)
| Constraint::ContentReviewTier(_)
| Constraint::MaxTransactionAmountUsd(_)
| Constraint::RequireDualApproval(_)
| Constraint::ModelConstraint { .. }
| Constraint::MemoryWriteDenyPatterns(_)
| Constraint::OutputDigestSha256(_)
| Constraint::RequireFindingPurchase(_)
| Constraint::RequireFindingRecovery(_) => Err(ScopeMatchError::ConstraintError(format!(
    "portable kernel cannot safely evaluate {}",
    constraint_name(constraint)
))),

constraint_name is an exhaustive match returning the snake_case wire name, so the error text an operator sees is the same token they wrote in the grant: portable kernel cannot safely evaluate minimum_runtime_assurance. Through evaluate it arrives wrapped as constraint evaluation failed: portable kernel cannot safely evaluate minimum_runtime_assurance, which is what evaluate_fails_closed_on_unsupported_constraint asserts on.

The table an author needs before writing a grant

Read the hosted column as three behaviors, not one. Eleven variants are decided. Ten return Ok(true) here and are enforced somewhere else, so a grant carrying only those is admitted by the matcher and still subject to a later refusal. Three return Ok(false), which is not an error: the grant drops out of the candidate list and a sibling grant may still admit the call.

How the eight read a request

Four of them work over 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. The other four ignore that flattening and walk the raw arguments value themselves: MaxArgsSize re-serializes it, Custom recurses looking for one entry, and the two allowlists recurse with collect_string_values_strict.

The most surprising property of the group is that the four leaf-scanning constraints are not bound to a named parameter. PathPrefix, DomainExact, DomainGlob, and MaxLength apply to whatever in the arguments happens to look like their subject. The other four are not: MaxArgsSize measures the whole payload, Custom names its own key (compared case-sensitively, unlike the path and allowlist key predicates, which lowercase first), and the allowlists match a fixed key list.

The strict allowlist collector is the one place the portable core deliberately copies hosted semantics rather than simplifying. collect_string_values_strict returns false on any non-string, non-array leaf, so {"audience": null}, {"audience": 42}, {"audience": []}, and the mixed array {"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. resolve_matching_grants_audience_null_fails_closed_and_missing_allows pins the null, empty-string, and missing shapes for both allowlists; resolve_matching_grants_audience_allowlist_rejects_non_string_values and resolve_matching_grants_audience_mixed_null_array_fails_closed cover the rest.

A failed constraint drops one grant; an unevaluable one ends the call

These two outcomes look similar and are not. When an evaluable constraint returns false, the loop does continue and the next grant gets its turn. When any target-matching grant carries an unevaluable constraint, the error propagates out of the loop immediately and the whole resolution fails, including grants that had already matched and grants that were never reached.

resolve_matching_grants_fails_closed_when_target_match_has_unsupported_constraint builds exactly that trap: a srv-a/echo grant carrying MinimumRuntimeAssurance and an unconstrained */* grant beside it. The wildcard fallback does not save the request; the call errors. The companion test resolve_matching_grants_ignores_unsupported_constraints_on_unrelated_grants moves the same constraint onto a srv-b grant and the request is admitted, because constraints are read only after the target matches. A scope is poisoned for a request by any grant that both targets it and carries something the runtime cannot decide.

With one wrinkle worth knowing before you debug a scope: constraints_match walks the grant’s constraint vector in author order and returns Ok(false) at the first constraint that fails, so an unevaluable constraint listed after an evaluable one that already failed is never reached. The same grant then drops silently on one request and errors the whole resolution on another, depending only on which arguments arrived. Do not read the absence of a ConstraintError as evidence that a grant carries no unevaluable constraint.

Specificity, and the index that survives

Surviving grants are ranked, not 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))
});

Three keys, descending, with grant-list order as the tiebreak. Note that the first two components test string equality against the request, not against the literal *, so exactness is measured per request rather than per grant. The third key ranks a more constrained grant higher, which is safe in the portable core for one reason: a grant only reaches the ranking after every one of its constraints already held, so constraint count is a proxy for how much of the request the grant actually described. The hosted matcher reuses the same tuple without that property. Ten of its variants return Ok(true) unevaluated, so a hosted grant can outrank a sibling on constraints nobody checked at this stage. exact_grants_sort_ahead_of_wildcard_fallbacks pins the ordering against a two-grant scope written wildcard-first: the exact grant lands at position 0 of the returned list carrying grant index 1 and specificity (1, 1, 0), and the wildcard follows at position 1 still carrying grant index 0.

evaluate then takes matches.first() and nothing else. One grant admits the request or it does not. Portable adapters that call resolve_matching_grants directly still receive the whole ranked list and decide for themselves, which is how the AG-UI proxy ends up iterating it.

The hosted kernel walks the ranked list one candidate at a time. A resumed durable admission skips any candidate permits_matching_grant rejects, which means both a grant index the recorded budget hold id does not name and a grant whose cost caps do not match the operation’s payment requirement. For each surviving candidate the order is governed-transaction validation, then the guard pipeline under its time budget, then the runtime admission hook, and only last check_and_increment_budget. Guards run before the monetary hold, not after it. Not every failure advances to the next candidate. 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 therefore decides the request only after every later candidate has also failed, and only if no candidate recorded a budget error first.

The winning index is not telemetry. It reaches GuardContext.matched_grant_index before any guard runs, crosses the WASM guard ABI as GuardRequest.matched_grant_index (chio-wasm-guards/src/abi.rs, mirrored field for field in chio-guard-sdk), lands in receipt attribution metadata as grant_index alongside the subject key, issuer key, and delegation depth, and is persisted on the tool-outcome record, where a restore validates it against the JSON safe-integer bound and rejects raw.matched_grant_index otherwise. Most consequentially, the hosted kernel derives the durable budget hold id from it (admission-budget:{operation_id}:{grant_index}), so a resumed admission only permits the grant index it originally authorized. Renumbering the grants in a scope changes an identifier that durable state already committed to.

One refusal you will never see from evaluate

RequireCumulativeApprovalAbove is on the refusal list, but no evaluate entry point reaches it. On the plain path, verify_capability_with_floor passes cumulative_approval_enabled = false, so verification rejects the token first with cumulative_approval_budget was not negotiated. On the full-floor path a peer may negotiate the feature, and then evaluate_with_full_floor_and_root checks scope.has_cumulative_approval() explicitly 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, so that path is closed too. The matcher’s own ConstraintError for that variant is reachable only by calling resolve_matching_grants directly, which is what resolve_matching_grants_rejects_cumulative_approval_until_enforced does. Independent refusals stacked, one outcome. That is the intended shape: negotiated features in capability/features.rs gate whether a token is even admissible, and the matcher is the last line rather than the first.

Guarantees and limits

Next steps

• Capabilities · the token, the grant fields this page ranks, and all 27 constraint variants as data
• Delegation · scope subsetting between two tokens, where Constraint::is_preserved_by compares constraints for equality rather than evaluating them, with RequireCumulativeApprovalAbove as the one variant that gets an ordering rule instead
• Core & Shell · the exclusion list this matcher sits inside, and the five ordered steps of pure evaluation
• Fail-Closed Semantics · what the rest of the kernel does with a refusal it cannot evaluate
• Data-Layer Guards · where table_allowlist, column_denylist, and operation_class are actually enforced