Interface Guardrail<T>

Type Parameters:
T - the type this guardrail validates
All Superinterfaces:
Identifiable, Job<Void>
All Known Subinterfaces:
AdmissionGuardrail, AuthGuardrail<T>, ContentGuardrail<T>, ValidationGuardrail<T>
All Known Implementing Classes:
AbstractAdmissionGuardrail, AbstractAuthGuardrail, AbstractContentGuardrail, AbstractValidationGuardrail, AgentClassAllowListAdmissionGuardrail, ExfiltrationMarkerGuardrail, PayloadSizeCapGuardrail, PIIDetectionGuardrail, PrincipalAllowListGuardrail, SchemaConformanceGuardrail, SizeCapGuardrail, UrlGuardrail
public sealed interface Guardrail<T> extends Job<Void> permits AuthGuardrail<T>, ContentGuardrail<T>, AdmissionGuardrail, ValidationGuardrail<T>
A guardrail: a job that validates a single target object at a tool-invocation edge.

The hierarchy is sealed into the four JOB-BASED kinds of the context ladder - each consuming one more piece of framework-provided context than the previous:

  1. AdmissionGuardrail - no target; judges (principal, calling agent, tool) before a call exists
  2. ContentGuardrail - the target alone; a pure function of the payload
  3. AuthGuardrail - target plus the JobSnapshot (principal, tool, position in execution)
  4. ValidationGuardrail - target plus a live producer: judges a candidate final answer while the orchestrator that produced it still holds its conversation, so a refusal is fed back to that producer instead of failing its caller
The first three are declared by tools (GuardedExecution) and enforced by the framework at the dispatch path for every execution route; the fourth is declared by a producing orchestrator and enforced at its final-answer seat. SCOPE, which additionally consumes what the flow is about, is not a guardrail job at all: scope is a pure value judgment (Scope, ScopeGuard) enforced inline at the submission chokepoint, where every child a flow creates is born - guardrail jobs included - see ScopeAuthority and the dispatcher's submission rules.

A guardrail never receives a live framework object. Its complete evaluation context is the target and the immutable JobSnapshot of the gated job. Everything else a check needs is a lookup keyed by values found in those, performed by the guardrail's own job (guardrails may declare resources).

Refusal is always GuardrailException - correctable, so the agent loop can act on it. Infrastructure failures inside a guardrail propagate as themselves and fail the gated job closed; they are never converted into refusals.

Since:
0.1 (2026-02-01)
Author:
Andrey Santrosyan

  • Method Details

    • validate

      void validate(T target) throws GuardrailException
      Validates the target object. Throws GuardrailException if validation fails.
      Parameters:
      target - the object to validate
      Throws:
      GuardrailException - if validation fails

    • setTarget

      void setTarget(T target)
      Set the target this guardrail will validate before it runs. Called by the enforcing code immediately before submitting the guardrail as a job.

    • targetType

      Class<T> targetType()
      The class of targets this guardrail validates. Used by the enforcer to decide applicability (targetType().isInstance(target)). Self-reported so the framework never resolves it reflectively.

    • setGatedSnapshot

      void setGatedSnapshot(JobSnapshot snapshot)
      Delivers the immutable snapshot of the gated job before submission. The snapshot is the guardrail's only window onto the invocation: principal (userId), tool (jobClass), position (jobId, parentJobId, workflowId), attempt and timestamps.