Package com.tnsai.guardrails

Class OutputGuardrailEnforcer

java.lang.Object
com.tnsai.guardrails.OutputGuardrailEnforcer
public final class OutputGuardrailEnforcer extends Object
Resolves the active output guardrail for an action and enforces it against the executor's return value immediately after the action body completes.

The guardrail is expressed as an OutputGuardrailConfig — sourced either from an @OutputGuardrail annotation (method- or class-level) or, for builder-built roles, from RoleBuilder.outputGuardrail(...) via Role.getOutputGuardrailConfig() (TNS-561). Resolution precedence: method annotation > builder role config > class annotation.

Phase 1 enforcement matrix

  • minChars / maxChars — character bounds on String-typed return values. 0 means "no bound" on either side. Non-String returns (records, POJOs, collections, …) are passed through.
  • onFailure — see applyFailureAction(com.tnsai.annotations.OutputGuardrail.FailureAction, com.tnsai.guardrails.OutputGuardrailConfig, com.tnsai.metadata.ActionMetadata, com.tnsai.guardrails.GuardrailViolationException.Cause, java.lang.String, java.lang.String) for the full disposition matrix. In Phase 1, RETRY degrades to REJECT (the enforcer doesn't have a re-execution callback yet).
  • fallback — substituted on OutputGuardrail.FailureAction.FALLBACK when the value would otherwise have been rejected.
Since:
0.5.4 (issue #171, Phase 1); builder-config path added 0.11.1 (TNS-561)

  • Method Details

    • enforce

      public static Object enforce(ActionMetadata action, Role role, Object result)
      Enforces the (possibly inherited) output guardrail on result. May return a substituted or truncated value; may throw GuardrailViolationException per the onFailure policy.
      Parameters:
      action - the action just executed (for guardrail discovery + error context)
      role - the role instance hosting the action (for builder config + class-level fallback)
      result - the executor's raw return value
      Returns:
      the (possibly substituted/truncated) value to surface to the caller

    • enforceForTarget

      public static Object enforceForTarget(ActionMetadata action, Object target, Object result)
      Enforces method- or class-level output guardrails for a generic action target. This is the non-Role counterpart used by SCOP dispatch; builder role config applies only when the target is a Role.
      Parameters:
      action - the action just executed (for guardrail discovery + error context)
      target - object that owns the action method; may be null, in which case only the method annotation and the action's own getOutputGuardrailConfig() apply
      result - the executor's raw return value
      Returns:
      the (possibly substituted/truncated) value to surface to the caller
      Since:
      0.18.3