Class GuardrailEnforcer

java.lang.Object
ai.redouble.nucleo.harness.GuardrailEnforcer
public final class GuardrailEnforcer extends Object
Framework-triggered enforcement of the job-based guardrail kinds. Admission, content and auth guards run at the dispatch path - the one place every execution route crosses, which is what makes protection a property of the tool rather than of the route: the dispatcher calls enforceInput(Job, JobContext) after dependency resolution and before resource allocation, and enforceOutput(Job, Object, JobContext) after resources are released and before the result is delivered. Validation guards run at a producing orchestrator's final-answer seat through enforceValidation(List, Object, JobContext), while the producer still holds its conversation and can act on a refusal. (The SCOPE rung is not enforced here: scope is a pure value judgment run inline at the submission door - see the dispatcher's submission rules and ScopeAuthority.)

Guards run as their own jobs, submitted through the dispatcher's internal door on the gated job's behalf and awaited on the gated job's thread while it holds no resources - the same safety argument as dependency waiting. The internal door runs the scope wall against the guard the gated job itself was admitted under: a scoped guard whose claim drifts from that flow is refused before it runs, and a guard that declares ScopeAuthority is sealed with it, so any judge it spawns inherits the gated flow's binding.

Three outcomes, kept apart on purpose. A GuardrailException anywhere in an executed guard's failure chain is the refusal and fails the gated job with it. Any other failure of an executed guard is an infrastructure error and fails the gated job closed with that error as-is, never laundered into a refusal. A guard refused at the door never ran and rendered no verdict on the target: that refusal is a code error in the guard's own scope declaration and surfaces as a SystemException of the gated job, so a producer never treats it as feedback it could act on. Guardrail jobs are not GuardedExecution, so enforcement never recurses.

Zero-guard executions are an auditable fact: the enforcer writes the applied-guard counts to OBS_GUARDS_INPUT / OBS_GUARDS_OUTPUT / OBS_GUARDS_VALIDATION on every guarded job's context.

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

  • Field Details

    • OBS_GUARDS_INPUT

      public static final String OBS_GUARDS_INPUT
      Metadata key: number of input-side guards applied to this job (0 is auditable).
      See Also:

    • OBS_GUARDS_OUTPUT

      public static final String OBS_GUARDS_OUTPUT
      Metadata key: number of output-side guards applied to this job (0 is auditable).
      See Also:

    • OBS_GUARDS_VALIDATION

      public static final String OBS_GUARDS_VALIDATION
      Metadata key: number of validation guards applied to this job's latest candidate answer (0 is auditable).
      See Also:

    • OBS_CALLER_CLASS

      public static final String OBS_CALLER_CLASS
      Metadata key: the calling job's class name, stashed at the submission door.
      See Also:

  • Method Details

    • enforceInput

      public static void enforceInput(Job<?> job, JobContext<?> context) throws Exception
      Runs the input-side guards of a guarded job: declared admission guards, declared INPUT-direction content guards, then declared auth guards. First refusal or failure fails the gated job before any resource is allocated.
      Throws:
      Exception

    • enforceOutput

      public static void enforceOutput(Job<?> job, Object result, JobContext<?> context) throws Exception
      Runs the OUTPUT-direction content guards of a guarded job against its result, after resources are released and before the result is delivered. A refusal turns the completed attempt into a failure; the caller never sees the result.
      Throws:
      Exception

    • enforceContent

      public static void enforceContent(List<ContentGuardrail<?>> guards, ContentGuardrail.Direction direction, Object target, JobContext<?> onBehalfOf) throws Exception
      Runs the given content guards of one direction against a target outside dispatch enforcement, on behalf of the job whose context is given. The entry point for code that must police an object that never passes through a gated dispatch - e.g. a synthesized recovery result at the recovery wrapper's edge.
      Throws:
      Exception

    • enforceValidation

      public static void enforceValidation(List<? extends ValidationGuardrail<?>> guards, Object candidate, JobContext<?> producer) throws Exception
      Runs a producer's validation guards against one candidate final answer, on the producer's behalf and from the producer's thread, while the producer still holds its conversation. A refusal is the producer's to act on; the caller of this method feeds it back into the loop.
      Throws:
      Exception