Interface Scope

All Known Implementing Classes:
CaseScope, ChannelScope, CompositeScope, CustomerScope, OrderScope, ReadOnlyScope, TenantScope
public interface Scope
A scope: the value that says what a flow is about - a ticket, a project, a tenant - carried as a small axis-typed value produced by a Scoped carrier. A scope judges candidates ITSELF: pass(Scope) throws when it recognizes the candidate's type and clearly sees a violation; anything it does not recognize passes silently - a scope constrains only what it speaks for. The thrown GuardrailException is the refusal, its message the legible, LLM-actionable reason.

Recognition follows Java inheritance: a refining axis extends its parent axis (CityScope extends RegionScope), and two scopes are related when their class chains share any Scope-implementing class - parent vs child, child vs parent, or two siblings under one parent. Related scopes are compared on exactly the axes both sides carry, because each matches(Scope) level guards its own cast and skips itself for a candidate that does not reach its depth. Only genuinely unrelated types pass silently.

The comparison itself is matches(Scope), whose default is value equality: a flat per-axis scope is a pure record (record TenantScope(String tenantId) implements Scope {}) and needs nothing else. A hierarchical axis is a plain immutable class (records cannot extend) overriding matches at each level. Richer semantics - sets, ranges - override pass(Scope) outright.

Implementations must be immutable: scopes are captured frozen at an authority's dispatch and read by every check in its subtree.

Since:
0.1 (2026-08-18)
Author:
Andrey Santrosyan

  • Method Summary

    Modifier and Type
    Method
    Description
    default boolean
    matches(Scope candidate)
    Compares the candidate on the axes BOTH sides carry.
    default void
    pass(Scope candidate)
    Judges a candidate scope value: returns silently when this scope does not recognize the candidate's type or the candidate satisfies it; throws when it recognizes the type and clearly sees a violation.

  • Method Details

    • pass

      default void pass(Scope candidate) throws GuardrailException
      Judges a candidate scope value: returns silently when this scope does not recognize the candidate's type or the candidate satisfies it; throws when it recognizes the type and clearly sees a violation. Recognition is sharing any Scope-implementing class in the two class chains; the comparison then covers exactly the axes both sides carry.
      Throws:
      GuardrailException - the refusal, with the reason as its message

    • matches

      default boolean matches(Scope candidate)
      Compares the candidate on the axes BOTH sides carry. Called only with a candidate that shares an axis with this scope, so the topmost level of the chain casts freely; every deeper level guards its own cast with instanceof and returns super.matches alone for a candidate that does not reach its depth. The default - value equality - is right for flat record scopes.