< Summary

Information
Class: AsiBackbone.Samples.NcatAuditCompletionAdapter.NcatAuditCompletionAdapter
Assembly: AsiBackbone.Samples.NcatAuditCompletionAdapter
File(s): /home/runner/work/AsiBackbone/AsiBackbone/samples/NcatAuditCompletionAdapter/NcatAuditCompletionAdapter.cs
Line coverage
98%
Covered lines: 154
Uncovered lines: 3
Coverable lines: 157
Total lines: 290
Line coverage: 98%
Branch coverage
91%
Covered branches: 71
Total branches: 78
Branch coverage: 91%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
.ctor(...)100%66100%
DeliverAsync()100%121297.1%
ValidateHandoff(...)100%1212100%
ValidateDecisionCorrelation(...)100%88100%
PersistenceFailure(...)100%66100%
TryMapOutcome(...)100%1818100%
CreateLifecycleEventId(...)100%11100%
Equivalent(...)50%121295.65%
GetMetadata(...)50%22100%
NormalizeOptional(...)100%22100%
Terminal(...)100%11100%

File(s)

/home/runner/work/AsiBackbone/AsiBackbone/samples/NcatAuditCompletionAdapter/NcatAuditCompletionAdapter.cs

#LineLine coverage
 1using System.Security.Cryptography;
 2using System.Text;
 3using AsiBackbone.Core.Audit;
 4using AsiBackbone.Core.HostIntegration;
 5
 6namespace AsiBackbone.Samples.NcatAuditCompletionAdapter;
 7
 8/// <summary>
 9/// Maps a minimized NCAT audit-completion handoff into AsiBackbone governed execution evidence.
 10/// </summary>
 11/// <remarks>
 12/// This reference adapter intentionally depends only on AsiBackbone Core and the source-neutral
 13/// <see cref="NcatAuditCompletionHandoff" /> contract. A consuming host may translate its NCAT
 14/// completion receipt or completion-outbox entry into that contract without coupling either core product.
 15/// </remarks>
 16public sealed class NcatAuditCompletionAdapter
 17{
 18    private const string SourceCompletionEntryIdMetadataKey = "ncatCompletionEntryId";
 19    private const string SourceAdapterMetadataKey = "completionAdapter";
 20    private const string SourceAdapterMetadataValue = "NCAT";
 21    private const string LifecycleEventPrefix = "ncat-completion-";
 22
 23    private readonly IDecisionReceiptLifecycleStore lifecycleStore;
 24    private readonly INcatDecisionReceiptResolver decisionReceiptResolver;
 25    private readonly NcatAuditCompletionAdapterOptions options;
 26
 27    /// <summary>
 28    /// Initializes a new optional NCAT audit-completion adapter.
 29    /// </summary>
 3330    public NcatAuditCompletionAdapter(
 3331        IDecisionReceiptLifecycleStore lifecycleStore,
 3332        INcatDecisionReceiptResolver decisionReceiptResolver,
 3333        NcatAuditCompletionAdapterOptions? options = null)
 34    {
 3335        this.lifecycleStore = lifecycleStore ?? throw new ArgumentNullException(nameof(lifecycleStore));
 3236        this.decisionReceiptResolver = decisionReceiptResolver ?? throw new ArgumentNullException(nameof(decisionReceipt
 3137        this.options = options ?? new NcatAuditCompletionAdapterOptions();
 3138        this.options.Validate();
 2939    }
 40
 41    /// <summary>
 42    /// Attempts to append the governed completion lifecycle event before the source entry is acknowledged.
 43    /// </summary>
 44    public async ValueTask<NcatAuditCompletionDeliveryResult> DeliverAsync(
 45        NcatAuditCompletionHandoff handoff,
 46        CancellationToken cancellationToken = default)
 47    {
 3548        ArgumentNullException.ThrowIfNull(handoff);
 3549        cancellationToken.ThrowIfCancellationRequested();
 50
 3551        NcatAuditCompletionDeliveryResult? validationFailure = ValidateHandoff(handoff);
 3552        if (validationFailure is not null)
 53        {
 954            return validationFailure;
 55        }
 56
 2657        if (!TryMapOutcome(handoff.PersistenceOutcome, out GovernedOperationPersistenceOutcome persistenceOutcome))
 58        {
 159            return Terminal("unsupported-persistence-outcome");
 60        }
 61
 2562        IDecisionReceipt? decisionReceipt = await decisionReceiptResolver.ResolveAsync(
 2563            handoff.DecisionAuditRecordId!.Trim(),
 2564            NormalizeOptional(handoff.CorrelationId),
 2565            cancellationToken).ConfigureAwait(false);
 66
 2567        if (decisionReceipt is null)
 68        {
 169            return new NcatAuditCompletionDeliveryResult(
 170                NcatAuditCompletionDeliveryDisposition.Deferred,
 171                "decision-residue-not-available");
 72        }
 73
 2474        NcatAuditCompletionDeliveryResult? correlationFailure = ValidateDecisionCorrelation(handoff, decisionReceipt);
 2475        if (correlationFailure is not null)
 76        {
 277            return correlationFailure;
 78        }
 79
 80        GovernedOperationExecutionReceipt executionReceipt;
 81        try
 82        {
 2283            executionReceipt = GovernedOperationExecutionReceipt.Create(
 2284                operationExecutionId: handoff.OperationExecutionId!,
 2285                persistenceOutcome: persistenceOutcome,
 2286                executionAttemptId: handoff.ExecutionAttemptId,
 2287                mutationBatchId: handoff.MutationBatchId,
 2288                mutationRecordCount: handoff.AuditRecordCount,
 2289                mutationManifestHash: handoff.MutationManifestHash,
 2290                mutationManifestAlgorithm: handoff.MutationManifestAlgorithm,
 2291                completedUtc: handoff.CompletedUtc,
 2292                persistenceProvider: options.PersistenceProvider,
 2293                decisionAuditRecordId: handoff.DecisionAuditRecordId);
 1894        }
 495        catch (ArgumentException exception)
 96        {
 497            return Terminal("invalid-execution-receipt", exception.GetType().Name);
 98        }
 99
 18100        string lifecycleEventId = CreateLifecycleEventId(handoff.CompletionEntryId);
 18101        IReadOnlyDictionary<string, string> metadata = new Dictionary<string, string>(StringComparer.Ordinal)
 18102        {
 18103            [SourceCompletionEntryIdMetadataKey] = handoff.CompletionEntryId.Trim(),
 18104            [SourceAdapterMetadataKey] = SourceAdapterMetadataValue
 18105        };
 106
 18107        DecisionReceiptLifecycleEvent lifecycleEvent = HostAccountabilityLifecycleEvent.FromExecutionReceipt(
 18108            decisionReceipt,
 18109            executionReceipt,
 18110            eventId: lifecycleEventId,
 18111            metadata: metadata);
 112
 18113        DecisionReceiptLifecycleEvent? existing = await lifecycleStore.FindByEventIdAsync(
 18114            lifecycleEventId,
 18115            cancellationToken).ConfigureAwait(false);
 116
 18117        if (existing is not null)
 118        {
 3119            return Equivalent(existing, lifecycleEvent)
 3120                ? new NcatAuditCompletionDeliveryResult(
 3121                    NcatAuditCompletionDeliveryDisposition.Duplicate,
 3122                    "completion-already-delivered",
 3123                    lifecycleEventId,
 3124                    executionReceipt,
 3125                    existing)
 3126                : Terminal("idempotency-conflict", lifecycleEventId: lifecycleEventId);
 127        }
 128
 129        try
 130        {
 15131            DecisionReceiptLifecycleEvent appended = await lifecycleStore.AppendAsync(
 15132                lifecycleEvent,
 15133                cancellationToken).ConfigureAwait(false);
 134
 12135            return new NcatAuditCompletionDeliveryResult(
 12136                NcatAuditCompletionDeliveryDisposition.Delivered,
 12137                "lifecycle-event-appended",
 12138                appended.EventId,
 12139                executionReceipt,
 12140                appended);
 141        }
 0142        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
 143        {
 0144            throw;
 145        }
 3146        catch (Exception exception)
 147        {
 3148            return PersistenceFailure(handoff, lifecycleEventId, executionReceipt, lifecycleEvent, exception);
 149        }
 35150    }
 151
 152    private static NcatAuditCompletionDeliveryResult? ValidateHandoff(NcatAuditCompletionHandoff handoff)
 153    {
 35154        return string.IsNullOrWhiteSpace(handoff.CompletionEntryId)
 35155            ? Terminal("completion-entry-id-required")
 35156            : string.IsNullOrWhiteSpace(handoff.OperationExecutionId)
 35157            ? Terminal("operation-execution-id-required")
 35158            : string.IsNullOrWhiteSpace(handoff.DecisionAuditRecordId)
 35159            ? Terminal("decision-audit-record-id-required")
 35160            : string.IsNullOrWhiteSpace(handoff.PersistenceOutcome)
 35161            ? Terminal("persistence-outcome-required")
 35162            : handoff.AuditRecordCount < 0
 35163            ? Terminal("audit-record-count-invalid")
 35164            : handoff.DeliveryAttempt < 0
 35165            ? Terminal("delivery-attempt-invalid")
 35166            : null;
 167    }
 168
 169    private static NcatAuditCompletionDeliveryResult? ValidateDecisionCorrelation(
 170        NcatAuditCompletionHandoff handoff,
 171        IDecisionReceipt decisionReceipt)
 172    {
 24173        string? correlationId = NormalizeOptional(handoff.CorrelationId);
 24174        if (correlationId is not null &&
 24175            !string.Equals(correlationId, decisionReceipt.CorrelationId, StringComparison.Ordinal))
 176        {
 1177            return Terminal("correlation-id-mismatch");
 178        }
 179
 23180        string? traceId = NormalizeOptional(handoff.TraceId);
 23181        return traceId is not null &&
 23182            !string.Equals(traceId, decisionReceipt.TraceId, StringComparison.Ordinal)
 23183            ? Terminal("trace-id-mismatch")
 23184            : null;
 185    }
 186
 187    private NcatAuditCompletionDeliveryResult PersistenceFailure(
 188        NcatAuditCompletionHandoff handoff,
 189        string lifecycleEventId,
 190        GovernedOperationExecutionReceipt executionReceipt,
 191        DecisionReceiptLifecycleEvent lifecycleEvent,
 192        Exception exception)
 193    {
 3194        bool deadLettered = options.DeadLetterAfterAttempts is int threshold &&
 3195            handoff.DeliveryAttempt >= threshold;
 196
 3197        return new NcatAuditCompletionDeliveryResult(
 3198            deadLettered
 3199                ? NcatAuditCompletionDeliveryDisposition.DeadLetter
 3200                : NcatAuditCompletionDeliveryDisposition.Retryable,
 3201            deadLettered
 3202                ? "lifecycle-persistence-dead-lettered"
 3203                : "lifecycle-persistence-failed",
 3204            lifecycleEventId,
 3205            executionReceipt,
 3206            lifecycleEvent,
 3207            exception.GetType().Name);
 208    }
 209
 210    private static bool TryMapOutcome(
 211        string sourceOutcome,
 212        out GovernedOperationPersistenceOutcome persistenceOutcome)
 213    {
 26214        string normalized = string.Concat(sourceOutcome
 26215            .Where(char.IsLetterOrDigit)
 26216            .Select(char.ToLowerInvariant));
 217
 26218        persistenceOutcome = normalized switch
 26219        {
 15220            "committed" => GovernedOperationPersistenceOutcome.Committed,
 3221            "failed" => GovernedOperationPersistenceOutcome.Failed,
 3222            "rolledback" => GovernedOperationPersistenceOutcome.RolledBack,
 4223            "completedwithoutmutation" or "nomutation" => GovernedOperationPersistenceOutcome.CompletedWithoutMutation,
 1224            _ => default
 26225        };
 226
 26227        return normalized is "committed" or "failed" or "rolledback" or "completedwithoutmutation" or "nomutation";
 228    }
 229
 230    private static string CreateLifecycleEventId(string completionEntryId)
 231    {
 18232        byte[] digest = SHA256.HashData(Encoding.UTF8.GetBytes(completionEntryId.Trim()));
 18233        return string.Concat(LifecycleEventPrefix, Convert.ToHexString(digest).ToLowerInvariant());
 234    }
 235
 236    private static bool Equivalent(
 237        DecisionReceiptLifecycleEvent existing,
 238        DecisionReceiptLifecycleEvent candidate)
 239    {
 3240        if (existing.Stage != candidate.Stage ||
 3241            !string.Equals(existing.CorrelationId, candidate.CorrelationId, StringComparison.Ordinal) ||
 3242            !string.Equals(existing.DecisionReceiptId, candidate.DecisionReceiptId, StringComparison.Ordinal) ||
 3243            !string.Equals(existing.TraceId, candidate.TraceId, StringComparison.Ordinal) ||
 3244            !string.Equals(existing.OperationName, candidate.OperationName, StringComparison.Ordinal) ||
 3245            !string.Equals(existing.Outcome, candidate.Outcome, StringComparison.Ordinal))
 246        {
 0247            return false;
 248        }
 249
 3250        string[] keys =
 3251        [
 3252            SourceCompletionEntryIdMetadataKey,
 3253            HostAccountabilityMetadataKeys.OperationExecutionId,
 3254            HostAccountabilityMetadataKeys.ExecutionAttemptId,
 3255            HostAccountabilityMetadataKeys.DecisionAuditRecordId,
 3256            HostAccountabilityMetadataKeys.PersistenceOutcome,
 3257            HostAccountabilityMetadataKeys.MutationBatchId,
 3258            HostAccountabilityMetadataKeys.MutationRecordCount,
 3259            HostAccountabilityMetadataKeys.MutationManifestHash,
 3260            HostAccountabilityMetadataKeys.MutationManifestAlgorithm
 3261        ];
 262
 3263        return keys.All(key => string.Equals(
 3264            GetMetadata(existing.Metadata, key),
 3265            GetMetadata(candidate.Metadata, key),
 3266            StringComparison.Ordinal));
 267    }
 268
 269    private static string? GetMetadata(IReadOnlyDictionary<string, string> metadata, string key)
 270    {
 42271        return metadata.TryGetValue(key, out string? value) ? value : null;
 272    }
 273
 274    private static string? NormalizeOptional(string? value)
 275    {
 72276        return string.IsNullOrWhiteSpace(value) ? null : value.Trim();
 277    }
 278
 279    private static NcatAuditCompletionDeliveryResult Terminal(
 280        string reasonCode,
 281        string? failureType = null,
 282        string? lifecycleEventId = null)
 283    {
 17284        return new NcatAuditCompletionDeliveryResult(
 17285            NcatAuditCompletionDeliveryDisposition.Terminal,
 17286            reasonCode,
 17287            lifecycleEventId,
 17288            FailureType: failureType);
 289    }
 290}