< Summary

Information
Class: AsiBackbone.Core.Decisions.GovernanceDecision
Assembly: AsiBackbone.Core
File(s): /home/runner/work/AsiBackbone/AsiBackbone/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs
Line coverage
100%
Covered lines: 152
Uncovered lines: 0
Coverable lines: 152
Total lines: 530
Line coverage: 100%
Branch coverage
97%
Covered branches: 37
Total branches: 38
Branch coverage: 97.3%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
.cctor()100%11100%
.ctor(...)100%11100%
get_CanProceed()100%22100%
get_IsAllowed()100%11100%
get_IsWarning()100%11100%
get_IsDenied()100%11100%
get_IsDeferred()100%11100%
get_RequiresAcknowledgment()100%11100%
get_EscalationRecommended()100%11100%
get_HasReasons()100%11100%
Allow(...)100%11100%
Deny(...)100%11100%
Deny(...)100%11100%
Deny(...)100%11100%
Warning(...)100%11100%
Warning(...)100%11100%
Warning(...)100%11100%
Defer(...)100%11100%
RequireAcknowledgment(...)100%11100%
Escalate(...)100%11100%
WithTraceId(...)100%11100%
NormalizeOptional(...)100%22100%
NormalizeTelemetryIdentifier(...)100%44100%
NormalizeReasons(...)93.75%1616100%
NormalizeReasonCollection(...)100%1010100%
CreateFallbackReason(...)100%11100%
CreateReadOnlyReason(...)100%11100%
CreateReasonCodes(...)100%44100%

File(s)

/home/runner/work/AsiBackbone/AsiBackbone/src/AsiBackbone.Core/Decisions/GovernanceDecision.cs

#LineLine coverage
 1using System.Collections.ObjectModel;
 2using AsiBackbone.Core.Results;
 3
 4namespace AsiBackbone.Core.Decisions;
 5
 6/// <summary>
 7/// Represents a framework-neutral governance decision produced by an AsiBackbone evaluation flow.
 8/// </summary>
 9public sealed class GovernanceDecision
 10{
 11    private const string DefaultDeniedCode = "decision.denied";
 12    private const string DefaultDeniedMessage = "Decision denied the operation.";
 13    private const string DefaultWarningCode = "decision.warning";
 14    private const string DefaultWarningMessage = "Decision produced a warning.";
 15
 16    /// <summary>
 17    /// Defines the maximum retained length for normalized correlation identifiers.
 18    /// </summary>
 19    /// <remarks>
 20    /// Correlation identifiers are trimmed before enforcement. Values longer than this limit are truncated to keep tele
 21    /// </remarks>
 22    public const int MaxCorrelationIdLength = 256;
 23
 24    /// <summary>
 25    /// Defines the maximum retained length for normalized trace identifiers.
 26    /// </summary>
 27    /// <remarks>
 28    /// Trace identifiers are trimmed before enforcement. Values longer than this limit are truncated to keep telemetry-
 29    /// </remarks>
 30    public const int MaxTraceIdLength = 256;
 31
 332    private static readonly ReadOnlyCollection<OperationReason> EmptyReasons =
 333        Array.AsReadOnly(Array.Empty<OperationReason>());
 34
 335    private static readonly ReadOnlyCollection<string> EmptyReasonCodes =
 336        Array.AsReadOnly(Array.Empty<string>());
 37
 79938    private GovernanceDecision(
 79939        GovernanceDecisionOutcome outcome,
 79940        IReadOnlyList<OperationReason> reasons,
 79941        string? correlationId,
 79942        string? traceId,
 79943        string? policyVersion,
 79944        string? policyHash)
 45    {
 79946        Outcome = outcome;
 79947        Reasons = reasons;
 79948        ReasonCodes = CreateReasonCodes(reasons);
 79949        CorrelationId = NormalizeTelemetryIdentifier(correlationId, MaxCorrelationIdLength);
 79950        TraceId = NormalizeTelemetryIdentifier(traceId, MaxTraceIdLength);
 79951        PolicyVersion = NormalizeOptional(policyVersion);
 79952        PolicyHash = NormalizeOptional(policyHash);
 79953    }
 54
 55    /// <summary>
 56    /// Gets the selected governance decision outcome.
 57    /// </summary>
 58    public GovernanceDecisionOutcome Outcome { get; }
 59
 60    /// <summary>
 61    /// Gets reasons associated with the governance decision.
 62    /// </summary>
 63    public IReadOnlyList<OperationReason> Reasons { get; }
 64
 65    /// <summary>
 66    /// Gets machine-readable reason codes associated with the governance decision.
 67    /// </summary>
 68    public IReadOnlyList<string> ReasonCodes { get; }
 69
 70    /// <summary>
 71    /// Gets the correlation identifier associated with the decision, when supplied by the host.
 72    /// </summary>
 73    public string? CorrelationId { get; }
 74
 75    /// <summary>
 76    /// Gets the trace identifier associated with the decision, when supplied by the host.
 77    /// </summary>
 78    public string? TraceId { get; }
 79
 80    /// <summary>
 81    /// Gets the policy version associated with the decision, when supplied by the host.
 82    /// </summary>
 83    public string? PolicyVersion { get; }
 84
 85    /// <summary>
 86    /// Gets the policy hash associated with the decision, when supplied by the host.
 87    /// </summary>
 88    public string? PolicyHash { get; }
 89
 90    /// <summary>
 91    /// Gets a value indicating whether the decision allows immediate execution.
 92    /// </summary>
 14293    public bool CanProceed => Outcome is GovernanceDecisionOutcome.Allowed or GovernanceDecisionOutcome.Warning;
 94
 95    /// <summary>
 96    /// Gets a value indicating whether the decision allows the operation.
 97    /// </summary>
 6898    public bool IsAllowed => Outcome is GovernanceDecisionOutcome.Allowed;
 99
 100    /// <summary>
 101    /// Gets a value indicating whether the decision allows the operation with warnings.
 102    /// </summary>
 93103    public bool IsWarning => Outcome is GovernanceDecisionOutcome.Warning;
 104
 105    /// <summary>
 106    /// Gets a value indicating whether the decision denies the operation.
 107    /// </summary>
 341108    public bool IsDenied => Outcome is GovernanceDecisionOutcome.Denied;
 109
 110    /// <summary>
 111    /// Gets a value indicating whether the decision defers the operation.
 112    /// </summary>
 19113    public bool IsDeferred => Outcome is GovernanceDecisionOutcome.Deferred;
 114
 115    /// <summary>
 116    /// Gets a value indicating whether the decision requires acknowledgment before execution.
 117    /// </summary>
 129118    public bool RequiresAcknowledgment => Outcome is GovernanceDecisionOutcome.AcknowledgmentRequired;
 119
 120    /// <summary>
 121    /// Gets a value indicating whether the decision recommends escalation.
 122    /// </summary>
 11123    public bool EscalationRecommended => Outcome is GovernanceDecisionOutcome.EscalationRecommended;
 124
 125    /// <summary>
 126    /// Gets a value indicating whether the decision includes reason data.
 127    /// </summary>
 12128    public bool HasReasons => Reasons.Count > 0;
 129
 130    /// <summary>
 131    /// Creates an allowed governance decision.
 132    /// </summary>
 133    /// <param name="correlationId">Optional correlation identifier.</param>
 134    /// <param name="traceId">Optional trace identifier.</param>
 135    /// <param name="policyVersion">Optional policy version.</param>
 136    /// <param name="policyHash">Optional policy hash.</param>
 137    /// <returns>An allowed governance decision.</returns>
 138    public static GovernanceDecision Allow(
 139        string? correlationId = null,
 140        string? traceId = null,
 141        string? policyVersion = null,
 142        string? policyHash = null)
 143    {
 216144        return new GovernanceDecision(
 216145            GovernanceDecisionOutcome.Allowed,
 216146            EmptyReasons,
 216147            correlationId,
 216148            traceId,
 216149            policyVersion,
 216150            policyHash);
 151    }
 152
 153    /// <summary>
 154    /// Creates a denied governance decision.
 155    /// </summary>
 156    /// <param name="code">The machine-readable reason code.</param>
 157    /// <param name="message">The human-readable reason message.</param>
 158    /// <param name="correlationId">Optional correlation identifier.</param>
 159    /// <param name="traceId">Optional trace identifier.</param>
 160    /// <param name="policyVersion">Optional policy version.</param>
 161    /// <param name="policyHash">Optional policy hash.</param>
 162    /// <returns>A denied governance decision.</returns>
 163    public static GovernanceDecision Deny(
 164        string code,
 165        string message,
 166        string? correlationId = null,
 167        string? traceId = null,
 168        string? policyVersion = null,
 169        string? policyHash = null)
 170    {
 188171        return Deny(
 188172            OperationReason.Create(code, message),
 188173            correlationId,
 188174            traceId,
 188175            policyVersion,
 188176            policyHash);
 177    }
 178
 179    /// <summary>
 180    /// Creates a denied governance decision.
 181    /// </summary>
 182    /// <param name="reason">The reason associated with the denied decision.</param>
 183    /// <param name="correlationId">Optional correlation identifier.</param>
 184    /// <param name="traceId">Optional trace identifier.</param>
 185    /// <param name="policyVersion">Optional policy version.</param>
 186    /// <param name="policyHash">Optional policy hash.</param>
 187    /// <returns>A denied governance decision.</returns>
 188    public static GovernanceDecision Deny(
 189        OperationReason reason,
 190        string? correlationId = null,
 191        string? traceId = null,
 192        string? policyVersion = null,
 193        string? policyHash = null)
 194    {
 209195        ArgumentNullException.ThrowIfNull(reason);
 196
 208197        return new GovernanceDecision(
 208198            GovernanceDecisionOutcome.Denied,
 208199            CreateReadOnlyReason(reason),
 208200            correlationId,
 208201            traceId,
 208202            policyVersion,
 208203            policyHash);
 204    }
 205
 206    /// <summary>
 207    /// Creates a denied governance decision.
 208    /// </summary>
 209    /// <param name="reasons">The reasons associated with the denied decision.</param>
 210    /// <param name="correlationId">Optional correlation identifier.</param>
 211    /// <param name="traceId">Optional trace identifier.</param>
 212    /// <param name="policyVersion">Optional policy version.</param>
 213    /// <param name="policyHash">Optional policy hash.</param>
 214    /// <returns>A denied governance decision.</returns>
 215    public static GovernanceDecision Deny(
 216        IEnumerable<OperationReason> reasons,
 217        string? correlationId = null,
 218        string? traceId = null,
 219        string? policyVersion = null,
 220        string? policyHash = null)
 221    {
 65222        return new GovernanceDecision(
 65223            GovernanceDecisionOutcome.Denied,
 65224            NormalizeReasons(reasons, DefaultDeniedCode, DefaultDeniedMessage),
 65225            correlationId,
 65226            traceId,
 65227            policyVersion,
 65228            policyHash);
 229    }
 230
 231    /// <summary>
 232    /// Creates a warning governance decision.
 233    /// </summary>
 234    /// <param name="code">The machine-readable reason code.</param>
 235    /// <param name="message">The human-readable reason message.</param>
 236    /// <param name="correlationId">Optional correlation identifier.</param>
 237    /// <param name="traceId">Optional trace identifier.</param>
 238    /// <param name="policyVersion">Optional policy version.</param>
 239    /// <param name="policyHash">Optional policy hash.</param>
 240    /// <returns>A warning governance decision.</returns>
 241    public static GovernanceDecision Warning(
 242        string code,
 243        string message,
 244        string? correlationId = null,
 245        string? traceId = null,
 246        string? policyVersion = null,
 247        string? policyHash = null)
 248    {
 15249        return Warning(
 15250            OperationReason.Create(code, message),
 15251            correlationId,
 15252            traceId,
 15253            policyVersion,
 15254            policyHash);
 255    }
 256
 257    /// <summary>
 258    /// Creates a warning governance decision.
 259    /// </summary>
 260    /// <param name="reason">The reason associated with the warning decision.</param>
 261    /// <param name="correlationId">Optional correlation identifier.</param>
 262    /// <param name="traceId">Optional trace identifier.</param>
 263    /// <param name="policyVersion">Optional policy version.</param>
 264    /// <param name="policyHash">Optional policy hash.</param>
 265    /// <returns>A warning governance decision.</returns>
 266    public static GovernanceDecision Warning(
 267        OperationReason reason,
 268        string? correlationId = null,
 269        string? traceId = null,
 270        string? policyVersion = null,
 271        string? policyHash = null)
 272    {
 108273        ArgumentNullException.ThrowIfNull(reason);
 274
 107275        return new GovernanceDecision(
 107276            GovernanceDecisionOutcome.Warning,
 107277            CreateReadOnlyReason(reason),
 107278            correlationId,
 107279            traceId,
 107280            policyVersion,
 107281            policyHash);
 282    }
 283
 284    /// <summary>
 285    /// Creates a warning governance decision.
 286    /// </summary>
 287    /// <param name="reasons">The reasons associated with the warning decision.</param>
 288    /// <param name="correlationId">Optional correlation identifier.</param>
 289    /// <param name="traceId">Optional trace identifier.</param>
 290    /// <param name="policyVersion">Optional policy version.</param>
 291    /// <param name="policyHash">Optional policy hash.</param>
 292    /// <returns>A warning governance decision.</returns>
 293    public static GovernanceDecision Warning(
 294        IEnumerable<OperationReason> reasons,
 295        string? correlationId = null,
 296        string? traceId = null,
 297        string? policyVersion = null,
 298        string? policyHash = null)
 299    {
 18300        return new GovernanceDecision(
 18301            GovernanceDecisionOutcome.Warning,
 18302            NormalizeReasons(reasons, DefaultWarningCode, DefaultWarningMessage),
 18303            correlationId,
 18304            traceId,
 18305            policyVersion,
 18306            policyHash);
 307    }
 308
 309    /// <summary>
 310    /// Creates a deferred governance decision.
 311    /// </summary>
 312    /// <param name="code">The machine-readable reason code.</param>
 313    /// <param name="message">The human-readable reason message.</param>
 314    /// <param name="correlationId">Optional correlation identifier.</param>
 315    /// <param name="traceId">Optional trace identifier.</param>
 316    /// <param name="policyVersion">Optional policy version.</param>
 317    /// <param name="policyHash">Optional policy hash.</param>
 318    /// <returns>A deferred governance decision.</returns>
 319    public static GovernanceDecision Defer(
 320        string code,
 321        string message,
 322        string? correlationId = null,
 323        string? traceId = null,
 324        string? policyVersion = null,
 325        string? policyHash = null)
 326    {
 28327        return new GovernanceDecision(
 28328            GovernanceDecisionOutcome.Deferred,
 28329            CreateReadOnlyReason(OperationReason.Create(code, message)),
 28330            correlationId,
 28331            traceId,
 28332            policyVersion,
 28333            policyHash);
 334    }
 335
 336    /// <summary>
 337    /// Creates an acknowledgment-required governance decision.
 338    /// </summary>
 339    /// <param name="code">The machine-readable reason code.</param>
 340    /// <param name="message">The human-readable reason message.</param>
 341    /// <param name="correlationId">Optional correlation identifier.</param>
 342    /// <param name="traceId">Optional trace identifier.</param>
 343    /// <param name="policyVersion">Optional policy version.</param>
 344    /// <param name="policyHash">Optional policy hash.</param>
 345    /// <returns>An acknowledgment-required governance decision.</returns>
 346    public static GovernanceDecision RequireAcknowledgment(
 347        string code,
 348        string message,
 349        string? correlationId = null,
 350        string? traceId = null,
 351        string? policyVersion = null,
 352        string? policyHash = null)
 353    {
 93354        return new GovernanceDecision(
 93355            GovernanceDecisionOutcome.AcknowledgmentRequired,
 93356            CreateReadOnlyReason(OperationReason.Create(code, message)),
 93357            correlationId,
 93358            traceId,
 93359            policyVersion,
 93360            policyHash);
 361    }
 362
 363    /// <summary>
 364    /// Creates an escalation-recommended governance decision.
 365    /// </summary>
 366    /// <param name="code">The machine-readable reason code.</param>
 367    /// <param name="message">The human-readable reason message.</param>
 368    /// <param name="correlationId">Optional correlation identifier.</param>
 369    /// <param name="traceId">Optional trace identifier.</param>
 370    /// <param name="policyVersion">Optional policy version.</param>
 371    /// <param name="policyHash">Optional policy hash.</param>
 372    /// <returns>An escalation-recommended governance decision.</returns>
 373    public static GovernanceDecision Escalate(
 374        string code,
 375        string message,
 376        string? correlationId = null,
 377        string? traceId = null,
 378        string? policyVersion = null,
 379        string? policyHash = null)
 380    {
 19381        return new GovernanceDecision(
 19382            GovernanceDecisionOutcome.EscalationRecommended,
 19383            CreateReadOnlyReason(OperationReason.Create(code, message)),
 19384            correlationId,
 19385            traceId,
 19386            policyVersion,
 19387            policyHash);
 388    }
 389
 390    /// <summary>
 391    /// Creates a copy of this decision with the supplied trace identifier.
 392    /// </summary>
 393    /// <param name="traceId">Optional trace identifier.</param>
 394    /// <returns>A decision preserving the outcome, reasons, correlation identifier, and policy identifiers.</returns>
 395    public GovernanceDecision WithTraceId(string? traceId)
 396    {
 41397        return new GovernanceDecision(
 41398            Outcome,
 41399            Reasons,
 41400            CorrelationId,
 41401            traceId,
 41402            PolicyVersion,
 41403            PolicyHash);
 404    }
 405
 406    private static string? NormalizeOptional(string? value)
 407    {
 3196408        return string.IsNullOrWhiteSpace(value)
 3196409            ? null
 3196410            : value.Trim();
 411    }
 412
 413    private static string? NormalizeTelemetryIdentifier(string? value, int maxLength)
 414    {
 1598415        string? normalized = NormalizeOptional(value);
 416
 1598417        return normalized is null || normalized.Length <= maxLength
 1598418            ? normalized
 1598419            : normalized[..maxLength];
 420    }
 421
 422    private static ReadOnlyCollection<OperationReason> NormalizeReasons(
 423        IEnumerable<OperationReason>? reasons,
 424        string fallbackCode,
 425        string fallbackMessage)
 426    {
 83427        if (reasons is null)
 428        {
 2429            return CreateFallbackReason(fallbackCode, fallbackMessage);
 430        }
 431
 81432        if (reasons is ICollection<OperationReason> collection)
 433        {
 78434            return NormalizeReasonCollection(collection, fallbackCode, fallbackMessage);
 435        }
 436
 3437        OperationReason? firstReason = null;
 3438        List<OperationReason>? normalizedReasons = null;
 439
 14440        foreach (OperationReason? reason in reasons)
 441        {
 4442            if (reason is null)
 443            {
 444                continue;
 445            }
 446
 4447            if (firstReason is null)
 448            {
 2449                firstReason = reason;
 2450                continue;
 451            }
 452
 2453            normalizedReasons ??= [firstReason];
 2454            normalizedReasons.Add(reason);
 455        }
 456
 3457        return firstReason is null
 3458            ? CreateFallbackReason(fallbackCode, fallbackMessage)
 3459            : normalizedReasons is null
 3460            ? CreateReadOnlyReason(firstReason)
 3461            : normalizedReasons.AsReadOnly();
 462    }
 463
 464    private static ReadOnlyCollection<OperationReason> NormalizeReasonCollection(
 465        ICollection<OperationReason> reasons,
 466        string fallbackCode,
 467        string fallbackMessage)
 468    {
 78469        if (reasons.Count == 0)
 470        {
 3471            return CreateFallbackReason(fallbackCode, fallbackMessage);
 472        }
 473
 75474        var normalizedReasons = new OperationReason[reasons.Count];
 75475        int normalizedCount = 0;
 476
 380477        foreach (OperationReason? reason in reasons)
 478        {
 115479            if (reason is not null)
 480            {
 108481                normalizedReasons[normalizedCount] = reason;
 108482                normalizedCount++;
 483            }
 484        }
 485
 75486        if (normalizedCount == 0)
 487        {
 3488            return CreateFallbackReason(fallbackCode, fallbackMessage);
 489        }
 490
 72491        if (normalizedCount == normalizedReasons.Length)
 492        {
 69493            return Array.AsReadOnly(normalizedReasons);
 494        }
 495
 3496        var filteredReasons = new OperationReason[normalizedCount];
 3497        Array.Copy(normalizedReasons, filteredReasons, normalizedCount);
 498
 3499        return Array.AsReadOnly(filteredReasons);
 500    }
 501
 502    private static ReadOnlyCollection<OperationReason> CreateFallbackReason(
 503        string fallbackCode,
 504        string fallbackMessage)
 505    {
 9506        return CreateReadOnlyReason(OperationReason.Create(fallbackCode, fallbackMessage));
 507    }
 508
 509    private static ReadOnlyCollection<OperationReason> CreateReadOnlyReason(OperationReason reason)
 510    {
 464511        return Array.AsReadOnly([reason]);
 512    }
 513
 514    private static ReadOnlyCollection<string> CreateReasonCodes(IReadOnlyList<OperationReason> reasons)
 515    {
 799516        if (reasons.Count == 0)
 517        {
 237518            return EmptyReasonCodes;
 519        }
 520
 562521        string[] reasonCodes = new string[reasons.Count];
 522
 2324523        for (int index = 0; index < reasons.Count; index++)
 524        {
 600525            reasonCodes[index] = reasons[index].Code;
 526        }
 527
 562528        return Array.AsReadOnly(reasonCodes);
 529    }
 530}

Methods/Properties

.cctor()
.ctor(AsiBackbone.Core.Decisions.GovernanceDecisionOutcome,System.Collections.Generic.IReadOnlyList`1<AsiBackbone.Core.Results.OperationReason>,System.String,System.String,System.String,System.String)
get_CanProceed()
get_IsAllowed()
get_IsWarning()
get_IsDenied()
get_IsDeferred()
get_RequiresAcknowledgment()
get_EscalationRecommended()
get_HasReasons()
Allow(System.String,System.String,System.String,System.String)
Deny(System.String,System.String,System.String,System.String,System.String,System.String)
Deny(AsiBackbone.Core.Results.OperationReason,System.String,System.String,System.String,System.String)
Deny(System.Collections.Generic.IEnumerable`1<AsiBackbone.Core.Results.OperationReason>,System.String,System.String,System.String,System.String)
Warning(System.String,System.String,System.String,System.String,System.String,System.String)
Warning(AsiBackbone.Core.Results.OperationReason,System.String,System.String,System.String,System.String)
Warning(System.Collections.Generic.IEnumerable`1<AsiBackbone.Core.Results.OperationReason>,System.String,System.String,System.String,System.String)
Defer(System.String,System.String,System.String,System.String,System.String,System.String)
RequireAcknowledgment(System.String,System.String,System.String,System.String,System.String,System.String)
Escalate(System.String,System.String,System.String,System.String,System.String,System.String)
WithTraceId(System.String)
NormalizeOptional(System.String)
NormalizeTelemetryIdentifier(System.String,System.Int32)
NormalizeReasons(System.Collections.Generic.IEnumerable`1<AsiBackbone.Core.Results.OperationReason>,System.String,System.String)
NormalizeReasonCollection(System.Collections.Generic.ICollection`1<AsiBackbone.Core.Results.OperationReason>,System.String,System.String)
CreateFallbackReason(System.String,System.String)
CreateReadOnlyReason(AsiBackbone.Core.Results.OperationReason)
CreateReasonCodes(System.Collections.Generic.IReadOnlyList`1<AsiBackbone.Core.Results.OperationReason>)