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 Summary

Modifier and Type	Method	Description
static Object	enforce(ActionMetadata action, Role role, Object result)	Enforces the (possibly inherited) output guardrail on result.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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