invalid_scope on delegation cannot say which of the three intersection terms was empty

[KunalJavelin]

Sub-issue of highflame-ai/highflame-sdk#143 — the scope-mechanism review. Also highflame-ai/highflame-authn#181 ask 3.

The bug

A delegated grant is a three-way intersection:

requested  ∩  the delegator's own token scopes  ∩  the sub-agent's allowed_scopes

When it comes out empty, tokenExchange returns one string for all three causes:

if len(scopes) == 0 {
    return nil, oauthBadRequest(oautherror.InvalidScope, "requested scopes are not available for delegation")
}

The three causes need opposite fixes:

Cause	What the caller must do
Requested nothing	pass an explicit scope — the exchange has no RFC 6749 §3.3 default, unlike every other grant
The parent does not hold it	widen the delegator's registration, or delegate from a different identity
The child was not registered for it	widen the sub-agent's allowed_scopes

Today all three read as the same failure. highflame-ai/highflame-authn#181 reports losing time to two of them in a row.

Why it is cheap

All three sets are already in scope at that line: requestedScopes, orchSet, and actorAllowed. Naming the empty term needs no new lookup.

Ask

Distinguish the three in the error_description. For example:

• "no scopes requested; the token-exchange grant has no default"
• "the delegating token does not hold: data:read"
• "the actor identity is not registered for: data:read"

Keep the invalid_scope error code — the change is in the description, so it is not a wire-contract break.

Related

The three-way intersection itself is now documented in the SDK: highflame-ai/highflame-sdk#150 put it in both READMEs, and highflame-ai/highflame-sdk#151 put it in both scope vocabularies. This issue is the runtime half — documentation only helps the person who read it first.