Add cross-layer protocol evidence bundle

Author: ammarheidari

README.md

@@ -67,7 +67,7 @@ The first production milestone is M3UA over a transport abstraction. SCCP, TCAP,
 | Maintained peer lab runner | Phase 29 foundation-ready: runner workspace, execution input bundle, output artifact materialization, preflight, command manifest, evidence collection, digest generation, comparison handoff, workflow readiness, and status reporting contracts are available; commercial release still requires execution against a real maintained external peer |
 | Maintained peer lab runner operations | Phase 30 foundation-ready: file materialization plan rendering, execution log, command outcome, artifact verification, runner provenance, failure classification, retry policy, evidence package manifest, operator handoff, and operations status contracts are available; commercial release still requires execution against a real maintained external peer |
 | Native SCTP production hardening | Phase 31 foundation-complete: outbound stream/PPID framing, association lifecycle journal, reconnect schedule, send backpressure, cancellation/timeout, multi-homing readiness, fault recovery, transport diagnostics, production hardening readiness gate, and status reporting are available; production readiness still requires retained Linux SCTP and external peer evidence |
-| SCCP/TCAP/MAP evidence upgrade | Phase 32 in progress: shared protocol evidence vectors, byte-level mismatch validation, and SCCP/TCAP/MAP SMS evidence vectors are available; trace validation, mismatch correction, and evidence-backed readiness gates are next |
+| SCCP/TCAP/MAP evidence upgrade | Phase 32 in progress: shared protocol evidence vectors, byte-level mismatch validation, SCCP/TCAP/MAP SMS evidence vectors, and a cross-layer evidence bundle are available; trace validation, mismatch correction, and evidence-backed readiness gates are next |
 
 ## Requirements
 
@@ -225,7 +225,7 @@ Phase 28 completed the automation and evidence handoff layer above that foundati
 Phase 29 completed the maintained peer lab runner materialization layer, including deterministic runner workspace paths, execution input bundles, output artifact mapping, preflight checks, command manifests, evidence collection, digest generation, comparison handoff, workflow readiness, and status reporting for real lab execution.
 Phase 30 completed the maintained peer lab runner operationalization layer, including reviewable file materialization, structured execution logs, command outcomes, artifact verification, runner provenance, failure classification, retry policy, evidence package manifests, operator handoff reports, and operations status reporting for real lab execution.
 Phase 31 completed the native SCTP production hardening foundation, including outbound stream and PPID framing, association lifecycle journaling, reconnect scheduling, send backpressure, cancellation/timeout policy, multi-homing readiness, deterministic fault recovery, transport diagnostics snapshots, production hardening readiness gates, and status reporting.
-Phase 32 upgrades SCCP, TCAP, and MAP SMS toward evidence-backed behavior, with shared byte-level evidence vector validation plus SCCP, TCAP, and MAP SMS evidence vectors in place before trace validation, mismatch correction, and evidence-backed readiness gates.
+Phase 32 upgrades SCCP, TCAP, and MAP SMS toward evidence-backed behavior, with shared byte-level evidence vector validation, SCCP/TCAP/MAP SMS evidence vectors, and a cross-layer evidence bundle in place before trace validation, mismatch correction, and evidence-backed readiness gates.
 5. Harden MAP SMS with external interoperability vectors and operator-profile validation.
 6. Use completed interoperability tooling to run external lab validation, native SCTP verification, and release automation hardening.
 7. Complete commercial readiness gates and publish governed release candidates.

docs/PHASE32_SCCP_TCAP_MAP_EVIDENCE_UPGRADE.md

@@ -51,6 +51,18 @@ Each vector stores literal BER expected bytes and validates the current TCAP tra
 
 Each vector stores literal BER-shaped parameter bytes and validates the current MAP SMS encoder output. Tests decode every vector back into its operation model to tie byte evidence to decoded field behavior.
 
+## Unit 5 - Cross-Layer Evidence Bundle
+
+`SigtranProtocolEvidenceBundle` now aggregates SCCP, TCAP, and MAP SMS vectors into one validation report. It provides:
+
+- Required cross-layer vector count.
+- Surface-specific vector counts.
+- Duplicate vector id detection.
+- Aggregate validation pass count.
+- Complete and evidence-backed summary flags.
+
+This gives release and readiness gates one deterministic SDK-side evidence report before trace validation and external artifact comparison are applied.
+
 ## Validation
 
 Each unit in this phase is validated with:

docs/SDK_ROADMAP.md

@@ -284,7 +284,7 @@ Status: Phase 31 is foundation-complete. The outbound stream and PPID framing co
 - Report and correct mismatches before upgrading readiness claims from foundation-only to evidence-backed.
 - Keep external interoperability evidence as a commercial promotion gate.
 
-Status: Phase 32 is in progress. The shared protocol evidence vector and byte-level mismatch validation contract is available. SCCP has deterministic UDT, XUDT, LUDT, and UDTS evidence vectors. TCAP has deterministic Begin/Invoke/Dialogue and End/ReturnResult evidence vectors. MAP SMS has deterministic MO-ForwardSM, MT-ForwardSM, SendRoutingInfoForSM, ReportSM-DeliveryStatus, and AlertServiceCentre evidence vectors.
+Status: Phase 32 is in progress. The shared protocol evidence vector and byte-level mismatch validation contract is available. SCCP has deterministic UDT, XUDT, LUDT, and UDTS evidence vectors. TCAP has deterministic Begin/Invoke/Dialogue and End/ReturnResult evidence vectors. MAP SMS has deterministic MO-ForwardSM, MT-ForwardSM, SendRoutingInfoForSM, ReportSM-DeliveryStatus, and AlertServiceCentre evidence vectors. A cross-layer evidence bundle aggregates vector counts, duplicate-id checks, and validation pass/fail status.
 
 ## Recommended First Deliverable
 

src/Sigtran.NET.Tests/Program.cs

@@ -175,6 +175,7 @@
 Run("SIGTRAN commercial roadmap realignment status summarizes package-neutral completion", SigtranCommercialRoadmapRealignmentStatusSummarizesPackageNeutralCompletion);
 Run("SIGTRAN protocol interop vector catalog covers SCCP TCAP and MAP", SigtranProtocolInteropVectorCatalogCoversSccpTcapAndMap);
 Run("SIGTRAN protocol evidence validator reports byte mismatches", SigtranProtocolEvidenceValidatorReportsByteMismatches);
+Run("SIGTRAN protocol evidence bundle aggregates SCCP TCAP and MAP", SigtranProtocolEvidenceBundleAggregatesSccpTcapAndMap);
 Run("SIGTRAN protocol interop references require trace validation", SigtranProtocolInteropReferencesRequireTraceValidation);
 Run("SIGTRAN protocol interop artifact manifest requires reference SDK and comparison", SigtranProtocolInteropArtifactManifestRequiresReferenceSdkAndComparison);
 Run("SIGTRAN protocol interop comparison rules are commercial validation ready", SigtranProtocolInteropComparisonRulesAreCommercialValidationReady);
@@ -2821,6 +2822,21 @@ static void SigtranProtocolEvidenceValidatorReportsByteMismatches()
     Assert(mismatch.Mismatches[1].Actual is null, mismatch.Mismatches[1].Describe());
 }
 
+static void SigtranProtocolEvidenceBundleAggregatesSccpTcapAndMap()
+{
+    SigtranProtocolEvidenceBundleReport report = SigtranProtocolEvidenceBundle.Create();
+
+    AssertEqual(11, SigtranProtocolEvidenceBundle.RequiredVectorCount, "protocol evidence required vector count");
+    AssertEqual(11, report.VectorCount, "protocol evidence vector count");
+    AssertEqual(4, report.CountBySurface(SigtranProtocolInteropSurface.Sccp), "protocol evidence SCCP count");
+    AssertEqual(2, report.CountBySurface(SigtranProtocolInteropSurface.Tcap), "protocol evidence TCAP count");
+    AssertEqual(5, report.CountBySurface(SigtranProtocolInteropSurface.MapSms), "protocol evidence MAP SMS count");
+    AssertEqual(0, report.DuplicateVectorIds.Count, "protocol evidence duplicate ids");
+    Assert(report.IsComplete, report.Describe());
+    Assert(report.AllValidationPassed, report.Describe());
+    Assert(report.EvidenceBacked, report.Describe());
+}
+
 static void SigtranProtocolInteropReferencesRequireTraceValidation()
 {
     IReadOnlyList<SigtranProtocolInteropReference> references = SigtranProtocolInteropReferences.GetReferences();

src/Sigtran.NET/Core/Utilities/SigtranProtocolEvidenceBundle.cs

@@ -0,0 +1,105 @@
+using Sigtran.NET.Layers.MAP;
+using Sigtran.NET.Layers.SCCP;
+using Sigtran.NET.Layers.TCAP;
+
+namespace Sigtran.NET.Core.Utilities;
+
+/// <summary>
+/// Aggregates SCCP, TCAP, and MAP SMS protocol evidence validation results.
+/// </summary>
+public sealed class SigtranProtocolEvidenceBundleReport
+{
+    private readonly SigtranProtocolEvidenceVector[] _vectors;
+    private readonly SigtranProtocolEvidenceValidationReport[] _validationReports;
+    private readonly string[] _duplicateVectorIds;
+
+    /// <summary>Creates a protocol evidence bundle report.</summary>
+    /// <param name="vectors">The evidence vectors.</param>
+    /// <param name="validationReports">The validation reports.</param>
+    /// <param name="duplicateVectorIds">Duplicate vector ids found in the bundle.</param>
+    public SigtranProtocolEvidenceBundleReport(
+        IReadOnlyList<SigtranProtocolEvidenceVector> vectors,
+        IReadOnlyList<SigtranProtocolEvidenceValidationReport> validationReports,
+        IReadOnlyList<string> duplicateVectorIds)
+    {
+        _vectors = (vectors ?? throw new ArgumentNullException(nameof(vectors))).ToArray();
+        _validationReports = (validationReports ?? throw new ArgumentNullException(nameof(validationReports))).ToArray();
+        _duplicateVectorIds = (duplicateVectorIds ?? throw new ArgumentNullException(nameof(duplicateVectorIds))).ToArray();
+    }
+
+    /// <summary>The evidence vectors.</summary>
+    public IReadOnlyList<SigtranProtocolEvidenceVector> Vectors => _vectors.ToArray();
+
+    /// <summary>The validation reports.</summary>
+    public IReadOnlyList<SigtranProtocolEvidenceValidationReport> ValidationReports => _validationReports.ToArray();
+
+    /// <summary>Duplicate vector ids found in the bundle.</summary>
+    public IReadOnlyList<string> DuplicateVectorIds => _duplicateVectorIds.ToArray();
+
+    /// <summary>The total vector count.</summary>
+    public int VectorCount => _vectors.Length;
+
+    /// <summary>The number of passed validation reports.</summary>
+    public int PassedValidationCount => _validationReports.Count(static report => report.Passed);
+
+    /// <summary>Whether every validation report passed.</summary>
+    public bool AllValidationPassed => _validationReports.Length == _vectors.Length && _validationReports.All(static report => report.Passed);
+
+    /// <summary>Whether the bundle contains all required vectors without duplicate ids.</summary>
+    public bool IsComplete => VectorCount == SigtranProtocolEvidenceBundle.RequiredVectorCount && _duplicateVectorIds.Length == 0;
+
+    /// <summary>Whether the bundle is complete and every validation report passed.</summary>
+    public bool EvidenceBacked => IsComplete && AllValidationPassed;
+
+    /// <summary>Returns the vector count for a protocol surface.</summary>
+    /// <param name="surface">The protocol surface.</param>
+    /// <returns>The vector count for the requested surface.</returns>
+    public int CountBySurface(SigtranProtocolInteropSurface surface)
+    {
+        return _vectors.Count(vector => vector.Surface == surface);
+    }
+
+    /// <summary>Formats a compact bundle summary.</summary>
+    /// <returns>The bundle summary.</returns>
+    public string Describe()
+    {
+        return $"vectors={VectorCount}/{SigtranProtocolEvidenceBundle.RequiredVectorCount} passed={PassedValidationCount}/{_validationReports.Length} duplicates={_duplicateVectorIds.Length} complete={IsComplete} evidenceBacked={EvidenceBacked}";
+    }
+}
+
+/// <summary>
+/// Provides a cross-layer SCCP, TCAP, and MAP SMS evidence bundle.
+/// </summary>
+public static class SigtranProtocolEvidenceBundle
+{
+    /// <summary>The required cross-layer evidence vector count.</summary>
+    public const int RequiredVectorCount = 11;
+
+    /// <summary>Creates the current cross-layer evidence bundle report.</summary>
+    /// <returns>The current evidence bundle report.</returns>
+    public static SigtranProtocolEvidenceBundleReport Create()
+    {
+        SigtranProtocolEvidenceVector[] vectors =
+        [
+            .. SccpEvidenceVectors.GetVectors(),
+            .. TcapEvidenceVectors.GetVectors(),
+            .. MapSmsEvidenceVectors.GetVectors()
+        ];
+
+        SigtranProtocolEvidenceValidationReport[] reports =
+        [
+            .. SccpEvidenceVectors.ValidateEncoders(),
+            .. TcapEvidenceVectors.ValidateEncoders(),
+            .. MapSmsEvidenceVectors.ValidateEncoders()
+        ];
+
+        string[] duplicates = vectors
+            .GroupBy(static vector => vector.Id, StringComparer.Ordinal)
+            .Where(static group => group.Count() > 1)
+            .Select(static group => group.Key)
+            .OrderBy(static id => id, StringComparer.Ordinal)
+            .ToArray();
+
+        return new(vectors, reports, duplicates);
+    }
+}