IGuardRail Interface — GuardRail Engines

Interface Hierarchy

// BizFirst.Ai.GuardRails.Domain.Contracts

// Composite interface — implement this for a complete guard
public interface IGuardRail : IGuardRailExecutor, IGuardRailConfigValidator, IGuardRailDescriptor
{ }

// --- IGuardRailExecutor ---
public interface IGuardRailExecutor
{
    string Name    { get; }  // unique identifier (e.g. "RateLimitingGuard")
    string Version { get; }  // semantic version (e.g. "1.0.0")

    // Which phases this guard participates in
    IReadOnlyList<GuardRailPhase> SupportedPhases { get; }

    // The evaluation method — called once per phase
    Task<GuardRailCheckResult> ExecuteAsync(
        GuardRailExecutionContext context,
        GuardRailPhase phase,
        CancellationToken cancellationToken = default);
}

// --- IGuardRailConfigValidator ---
public interface IGuardRailConfigValidator
{
    // Quick boolean validation
    bool Validate(IDictionary<string, object?> configuration);

    // Detailed validation with errors and warnings
    GuardRailConfigValidationResult ValidateWithDetails(IDictionary<string, object?> configuration);
}

// --- IGuardRailDescriptor ---
public interface IGuardRailDescriptor
{
    string GuardName          { get; }  // display name
    string Description        { get; }  // what the guard does
    string ConfigurationSchema { get; }  // JSON Schema for its config
    IReadOnlyList<GuardRailDependency> Dependencies { get; }
    bool IsSecurityCritical   { get; }  // if true: fail-closed on exception
}

GuardRailPhase Enum

public enum GuardRailPhase
{
    Pre   = 0,   // Before executor — can block execution
    Post  = 1,   // After executor — can override output
    Error = 2    // On error — informational/logging only
}

Key Properties to Implement

Property	Required	Notes
`Name`	Yes	Unique identifier — used as the registry key
`SupportedPhases`	Yes	Only return phases you implement — reduces unnecessary calls
`ExecuteAsync`	Yes	Check `phase` parameter and return `Success()` for phases you don't handle
`ValidateWithDetails`	Yes	Called at design time when the Atlas Form saves guard configuration
`ConfigurationSchema`	Yes	JSON Schema for the guard's config — drives the Atlas Form field generation
`IsSecurityCritical`	Recommended	Set to `true` if a guard exception should block rather than fail-open

Guard Phase Check in ExecuteAsync Always check if (phase != GuardRailPhase.Pre) return GuardRailCheckResult.Success(); at the top of ExecuteAsync for guards that only run in one phase. The engine passes all phases to all guards — it is the guard's responsibility to return Success for phases it does not handle.

← The Guard Pipeline Next: GuardRailCheckResult →