< Summary

Information
Class: AsiBackbone.Core.Audit.DecisionReceiptBuilder
Assembly: AsiBackbone.Core
File(s): /home/runner/work/AsiBackbone/AsiBackbone/src/AsiBackbone.Core/Audit/DecisionReceiptBuilder.cs
Line coverage
100%
Covered lines: 119
Uncovered lines: 0
Coverable lines: 119
Total lines: 406
Line coverage: 100%
Branch coverage
100%
Covered branches: 12
Total branches: 12
Branch coverage: 100%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

File(s)

/home/runner/work/AsiBackbone/AsiBackbone/src/AsiBackbone.Core/Audit/DecisionReceiptBuilder.cs

#LineLine coverage
 1using AsiBackbone.Core.Actors;
 2using AsiBackbone.Core.Constraints;
 3using AsiBackbone.Core.Decisions;
 4using AsiBackbone.Core.Signing;
 5
 6namespace AsiBackbone.Core.Audit;
 7
 8/// <summary>
 9/// Provides a fluent construction path for complex <see cref="DecisionReceipt" /> values.
 10/// </summary>
 11/// <remarks>
 12/// The builder is intended for ergonomic object creation in host code, samples, and tests. It preserves the immutable
 13/// <see cref="DecisionReceipt" /> value model by producing a new receipt when <see cref="Build" /> is called.
 14/// </remarks>
 15public sealed class DecisionReceiptBuilder
 16{
 17    private readonly IGovernanceActorContext actor;
 18    private readonly string operationName;
 19    private readonly string outcome;
 3120    private readonly List<string> reasonCodes = [];
 21
 22    private Dictionary<string, string>? metadata;
 23    private string? eventId;
 24    private DateTimeOffset? occurredUtc;
 25    private string? correlationId;
 26    private string? traceId;
 27    private string? policyVersion;
 28    private string? policyHash;
 29    private string? decisionReceiptId;
 30    private string? spanId;
 31    private string? parentSpanId;
 32    private long? decisionLatencyMs;
 33    private string? constraintSetHash;
 34    private int? constraintCount;
 35    private double? riskScore;
 36    private string? policyScope;
 37    private string? tenantHash;
 38    private string? organizationHash;
 39    private string? emitterStatus;
 40    private string? emitterProvider;
 41    private long? outboxSequence;
 42    private string? gatewayExecutionId;
 43    private string? decisionStage;
 44    private string? schemaVersion;
 45    private string? capabilityGrantId;
 46
 3147    private DecisionReceiptBuilder(
 3148        IGovernanceActorContext actor,
 3149        string operationName,
 3150        string outcome,
 3151        IEnumerable<string>? reasonCodes = null)
 52    {
 3153        ArgumentNullException.ThrowIfNull(actor);
 54
 3155        this.actor = actor;
 3156        this.operationName = operationName;
 3157        this.outcome = outcome;
 3158        _ = WithReasonCodes(reasonCodes);
 3159    }
 60
 61    /// <summary>
 62    /// Creates a builder for a host-defined audit outcome.
 63    /// </summary>
 64    public static DecisionReceiptBuilder Create(
 65        IGovernanceActorContext actor,
 66        string operationName,
 67        string outcome)
 68    {
 869        return new DecisionReceiptBuilder(actor, operationName, outcome);
 70    }
 71
 72    /// <summary>
 73    /// Creates a builder initialized from a governance decision.
 74    /// </summary>
 75    public static DecisionReceiptBuilder FromDecision(
 76        IGovernanceActorContext actor,
 77        string operationName,
 78        GovernanceDecision decision)
 79    {
 1980        ArgumentNullException.ThrowIfNull(decision);
 81
 1882        return new DecisionReceiptBuilder(
 1883            actor,
 1884            operationName,
 1885            CanonicalEnumWireNames.ForDecisionOutcome(decision.Outcome),
 1886            decision.ReasonCodes)
 1887            .WithCorrelationId(decision.CorrelationId)
 1888            .WithTraceId(decision.TraceId)
 1889            .WithPolicyVersion(decision.PolicyVersion)
 1890            .WithPolicyHash(decision.PolicyHash);
 91    }
 92
 93    /// <summary>
 94    /// Creates a builder initialized from a constraint evaluation result.
 95    /// </summary>
 96    public static DecisionReceiptBuilder FromConstraint(
 97        IGovernanceActorContext actor,
 98        string operationName,
 99        ConstraintEvaluationResult constraintResult)
 100    {
 6101        ArgumentNullException.ThrowIfNull(constraintResult);
 102
 5103        return new DecisionReceiptBuilder(
 5104            actor,
 5105            operationName,
 5106            CanonicalEnumWireNames.ForConstraintOutcome(constraintResult.Outcome),
 5107            constraintResult.ReasonCodes);
 108    }
 109
 110    /// <summary>
 111    /// Sets the audit event identifier.
 112    /// </summary>
 113    public DecisionReceiptBuilder WithEventId(string? value)
 114    {
 22115        eventId = value;
 22116        return this;
 117    }
 118
 119    /// <summary>
 120    /// Sets the event occurrence timestamp.
 121    /// </summary>
 122    public DecisionReceiptBuilder WithOccurredUtc(DateTimeOffset? value)
 123    {
 12124        occurredUtc = value;
 12125        return this;
 126    }
 127
 128    /// <summary>
 129    /// Replaces the reason-code collection.
 130    /// </summary>
 131    public DecisionReceiptBuilder WithReasonCodes(IEnumerable<string>? values)
 132    {
 31133        reasonCodes.Clear();
 134
 31135        if (values is not null)
 136        {
 23137            reasonCodes.AddRange(values);
 138        }
 139
 31140        return this;
 141    }
 142
 143    /// <summary>
 144    /// Adds one reason code to the builder.
 145    /// </summary>
 146    public DecisionReceiptBuilder AddReasonCode(string value)
 147    {
 4148        reasonCodes.Add(value);
 4149        return this;
 150    }
 151
 152    /// <summary>
 153    /// Sets the correlation identifier.
 154    /// </summary>
 155    public DecisionReceiptBuilder WithCorrelationId(string? value)
 156    {
 29157        correlationId = value;
 29158        return this;
 159    }
 160
 161    /// <summary>
 162    /// Sets the trace identifier.
 163    /// </summary>
 164    public DecisionReceiptBuilder WithTraceId(string? value)
 165    {
 29166        traceId = value;
 29167        return this;
 168    }
 169
 170    /// <summary>
 171    /// Sets the policy version.
 172    /// </summary>
 173    public DecisionReceiptBuilder WithPolicyVersion(string? value)
 174    {
 20175        policyVersion = value;
 20176        return this;
 177    }
 178
 179    /// <summary>
 180    /// Sets the policy hash.
 181    /// </summary>
 182    public DecisionReceiptBuilder WithPolicyHash(string? value)
 183    {
 20184        policyHash = value;
 20185        return this;
 186    }
 187
 188    /// <summary>
 189    /// Replaces the metadata collection.
 190    /// </summary>
 191    public DecisionReceiptBuilder WithMetadata(IReadOnlyDictionary<string, string>? values)
 192    {
 15193        metadata = null;
 194
 15195        if (values is not null)
 196        {
 46197            foreach (KeyValuePair<string, string> item in values)
 198            {
 9199                (metadata ??= new Dictionary<string, string>(StringComparer.Ordinal))[item.Key] = item.Value;
 200            }
 201        }
 202
 15203        return this;
 204    }
 205
 206    /// <summary>
 207    /// Adds or replaces one metadata value.
 208    /// </summary>
 209    public DecisionReceiptBuilder AddMetadata(string key, string value)
 210    {
 8211        (metadata ??= new Dictionary<string, string>(StringComparer.Ordinal))[key] = value;
 8212        return this;
 213    }
 214
 215    /// <summary>
 216    /// Sets the stable decision receipt identifier.
 217    /// </summary>
 218    public DecisionReceiptBuilder WithDecisionReceiptId(string? value)
 219    {
 2220        decisionReceiptId = value;
 2221        return this;
 222    }
 223
 224    /// <summary>
 225    /// Sets the span identifier.
 226    /// </summary>
 227    public DecisionReceiptBuilder WithSpanId(string? value)
 228    {
 2229        spanId = value;
 2230        return this;
 231    }
 232
 233    /// <summary>
 234    /// Sets the parent span identifier.
 235    /// </summary>
 236    public DecisionReceiptBuilder WithParentSpanId(string? value)
 237    {
 2238        parentSpanId = value;
 2239        return this;
 240    }
 241
 242    /// <summary>
 243    /// Sets the decision latency in milliseconds.
 244    /// </summary>
 245    public DecisionReceiptBuilder WithDecisionLatencyMs(long? value)
 246    {
 2247        decisionLatencyMs = value;
 2248        return this;
 249    }
 250
 251    /// <summary>
 252    /// Sets the evaluated constraint-set hash.
 253    /// </summary>
 254    public DecisionReceiptBuilder WithConstraintSetHash(string? value)
 255    {
 2256        constraintSetHash = value;
 2257        return this;
 258    }
 259
 260    /// <summary>
 261    /// Sets the evaluated constraint count.
 262    /// </summary>
 263    public DecisionReceiptBuilder WithConstraintCount(int? value)
 264    {
 2265        constraintCount = value;
 2266        return this;
 267    }
 268
 269    /// <summary>
 270    /// Sets the host-defined risk score.
 271    /// </summary>
 272    public DecisionReceiptBuilder WithRiskScore(double? value)
 273    {
 2274        riskScore = value;
 2275        return this;
 276    }
 277
 278    /// <summary>
 279    /// Sets the host-defined policy scope.
 280    /// </summary>
 281    public DecisionReceiptBuilder WithPolicyScope(string? value)
 282    {
 2283        policyScope = value;
 2284        return this;
 285    }
 286
 287    /// <summary>
 288    /// Sets the privacy-preserving tenant hash.
 289    /// </summary>
 290    public DecisionReceiptBuilder WithTenantHash(string? value)
 291    {
 2292        tenantHash = value;
 2293        return this;
 294    }
 295
 296    /// <summary>
 297    /// Sets the privacy-preserving organization hash.
 298    /// </summary>
 299    public DecisionReceiptBuilder WithOrganizationHash(string? value)
 300    {
 2301        organizationHash = value;
 2302        return this;
 303    }
 304
 305    /// <summary>
 306    /// Sets the provider-neutral emitter status.
 307    /// </summary>
 308    public DecisionReceiptBuilder WithEmitterStatus(string? value)
 309    {
 2310        emitterStatus = value;
 2311        return this;
 312    }
 313
 314    /// <summary>
 315    /// Sets the provider-neutral emitter provider name.
 316    /// </summary>
 317    public DecisionReceiptBuilder WithEmitterProvider(string? value)
 318    {
 2319        emitterProvider = value;
 2320        return this;
 321    }
 322
 323    /// <summary>
 324    /// Sets the outbox sequence.
 325    /// </summary>
 326    public DecisionReceiptBuilder WithOutboxSequence(long? value)
 327    {
 2328        outboxSequence = value;
 2329        return this;
 330    }
 331
 332    /// <summary>
 333    /// Sets the gateway execution identifier.
 334    /// </summary>
 335    public DecisionReceiptBuilder WithGatewayExecutionId(string? value)
 336    {
 2337        gatewayExecutionId = value;
 2338        return this;
 339    }
 340
 341    /// <summary>
 342    /// Sets the provider-neutral decision stage.
 343    /// </summary>
 344    public DecisionReceiptBuilder WithDecisionStage(string? value)
 345    {
 2346        decisionStage = value;
 2347        return this;
 348    }
 349
 350    /// <summary>
 351    /// Sets the decision receipt schema version.
 352    /// </summary>
 353    public DecisionReceiptBuilder WithSchemaVersion(string? value)
 354    {
 2355        schemaVersion = value;
 2356        return this;
 357    }
 358
 359    /// <summary>
 360    /// Sets the identifier of the capability grant that authorized the operation.
 361    /// </summary>
 362    public DecisionReceiptBuilder WithCapabilityGrantId(string? value)
 363    {
 1364        capabilityGrantId = value;
 1365        return this;
 366    }
 367
 368    /// <summary>
 369    /// Builds an immutable decision receipt value.
 370    /// </summary>
 371    public DecisionReceipt Build()
 372    {
 33373        var receipt = DecisionReceipt.Create(
 33374            actor,
 33375            operationName,
 33376            outcome,
 33377            reasonCodes,
 33378            eventId,
 33379            occurredUtc,
 33380            correlationId,
 33381            traceId,
 33382            policyVersion,
 33383            policyHash,
 33384            metadata,
 33385            decisionReceiptId,
 33386            spanId,
 33387            parentSpanId,
 33388            decisionLatencyMs,
 33389            constraintSetHash,
 33390            constraintCount,
 33391            riskScore,
 33392            policyScope,
 33393            tenantHash,
 33394            organizationHash,
 33395            emitterStatus,
 33396            emitterProvider,
 33397            outboxSequence,
 33398            gatewayExecutionId,
 33399            decisionStage,
 33400            schemaVersion);
 401
 33402        return string.IsNullOrWhiteSpace(capabilityGrantId)
 33403            ? receipt
 33404            : receipt.WithCapabilityGrantId(capabilityGrantId);
 405    }
 406}

Methods/Properties

.ctor(AsiBackbone.Core.Actors.IGovernanceActorContext,System.String,System.String,System.Collections.Generic.IEnumerable`1<System.String>)
Create(AsiBackbone.Core.Actors.IGovernanceActorContext,System.String,System.String)
FromDecision(AsiBackbone.Core.Actors.IGovernanceActorContext,System.String,AsiBackbone.Core.Decisions.GovernanceDecision)
FromConstraint(AsiBackbone.Core.Actors.IGovernanceActorContext,System.String,AsiBackbone.Core.Constraints.ConstraintEvaluationResult)
WithEventId(System.String)
WithOccurredUtc(System.Nullable`1<System.DateTimeOffset>)
WithReasonCodes(System.Collections.Generic.IEnumerable`1<System.String>)
AddReasonCode(System.String)
WithCorrelationId(System.String)
WithTraceId(System.String)
WithPolicyVersion(System.String)
WithPolicyHash(System.String)
WithMetadata(System.Collections.Generic.IReadOnlyDictionary`2<System.String,System.String>)
AddMetadata(System.String,System.String)
WithDecisionReceiptId(System.String)
WithSpanId(System.String)
WithParentSpanId(System.String)
WithDecisionLatencyMs(System.Nullable`1<System.Int64>)
WithConstraintSetHash(System.String)
WithConstraintCount(System.Nullable`1<System.Int32>)
WithRiskScore(System.Nullable`1<System.Double>)
WithPolicyScope(System.String)
WithTenantHash(System.String)
WithOrganizationHash(System.String)
WithEmitterStatus(System.String)
WithEmitterProvider(System.String)
WithOutboxSequence(System.Nullable`1<System.Int64>)
WithGatewayExecutionId(System.String)
WithDecisionStage(System.String)
WithSchemaVersion(System.String)
WithCapabilityGrantId(System.String)
Build()