Add maintained peer lab evidence gate

Author: ammarheidari

README.md

@@ -205,7 +205,7 @@ The roadmap is intentionally conservative:
 3. Harden SCCP with external interoperability vectors and trace validation.
 4. Harden TCAP with external interoperability vectors and MAP profile validation.
 
-Phase 27 tracks the maintained external peer lab contract, including package-neutral binding, host prerequisites, validated lab configuration, deterministic artifact planning, command planning, traffic vectors, and retained evidence gates.
+Phase 27 tracks the maintained external peer lab contract, including package-neutral binding, host prerequisites, validated lab configuration, deterministic artifact planning, command planning, traffic vectors, and digest-covered retained evidence 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/PHASE27_MAINTAINED_EXTERNAL_PEER_LAB.md

@@ -84,6 +84,18 @@ The command plan is intentionally package-neutral. Real deployments can map `ext
 
 The catalog flattens these vectors into an ordered expected message sequence so comparison reports can separate protocol mismatch from host or package setup issues.
 
+## Unit 8 - Evidence Promotion Gate
+
+`SigtranMaintainedPeerLabEvidenceReport` now separates planned execution from promotable evidence. Promotion requires:
+
+- Host prerequisites ready.
+- Lab configuration valid.
+- Every required artifact retained.
+- Every retained artifact digest-covered.
+- Trace comparison passed.
+
+This keeps commercial readiness honest: a command plan or artifact plan is not treated as proof until retained outputs and digests exist.
+
 ## Environment Contract
 
 The default binding exposes these variables:
@@ -125,4 +137,4 @@ dotnet run --project src\Sigtran.NET.Tests\Sigtran.NET.Tests.csproj
 dotnet pack src\Sigtran.NET\Sigtran.NET.csproj -c Release
 ```
 
-The tests verify that the default binding satisfies the maintained peer selection policy, public binding summaries remain package-neutral, host prerequisite reports identify missing lab capabilities, environment-derived lab configuration is validated before use, the artifact plan covers every required retained evidence path, the command plan covers every required execution step, and the traffic vector catalog yields a comparable expected message sequence.
+The tests verify that the default binding satisfies the maintained peer selection policy, public binding summaries remain package-neutral, host prerequisite reports identify missing lab capabilities, environment-derived lab configuration is validated before use, the artifact plan covers every required retained evidence path, the command plan covers every required execution step, the traffic vector catalog yields a comparable expected message sequence, and evidence promotion is blocked without complete digest-covered artifacts.

docs/SDK_ROADMAP.md

@@ -243,7 +243,7 @@ Status: Phase 26 is foundation-complete for package-neutral commercial roadmap r
 - Define host prerequisites, peer config, artifact naming, command scripts, traffic vectors, evidence promotion, readiness, and commercial gate alignment.
 - Keep selected package details outside public SDK type names.
 
-Status: Phase 27 has canonical `Sigtran.NET` naming, a package-neutral maintained peer lab binding catalog, host prerequisite readiness modeling, validated lab configuration contracts, deterministic retained artifact planning, an ordered command plan, and maintained peer traffic vectors. Commercial release remains blocked until the maintained peer lab produces passing digest-covered evidence.
+Status: Phase 27 has canonical `Sigtran.NET` naming, a package-neutral maintained peer lab binding catalog, host prerequisite readiness modeling, validated lab configuration contracts, deterministic retained artifact planning, an ordered command plan, maintained peer traffic vectors, and a digest-covered evidence promotion gate. Commercial release remains blocked until the maintained peer lab produces passing digest-covered evidence.
 
 ## Recommended First Deliverable
 

src/Sigtran.NET.Tests/Program.cs

@@ -42,6 +42,7 @@
 Run("SIGTRAN maintained peer lab artifact plan covers retained evidence paths", SigtranMaintainedPeerLabArtifactPlanCoversRetainedEvidencePaths);
 Run("SIGTRAN maintained peer lab command plan covers execution steps", SigtranMaintainedPeerLabCommandPlanCoversExecutionSteps);
 Run("SIGTRAN maintained peer lab traffic vectors expose comparable sequence", SigtranMaintainedPeerLabTrafficVectorsExposeComparableSequence);
+Run("SIGTRAN maintained peer lab evidence gate requires complete retained artifacts", SigtranMaintainedPeerLabEvidenceGateRequiresCompleteRetainedArtifacts);
 Run("SIGTRAN trace comparison reports ordered mismatches", SigtranTraceComparisonReportsOrderedMismatches);
 Run("SIGTRAN interoperability evidence promotion requires passing lab run", SigtranInteropEvidencePromotionRequiresPassingLabRun);
 Run("SIGTRAN interoperability lab CI profile is opt-in", SigtranInteropLabCiProfileIsOptIn);
@@ -832,6 +833,38 @@ static void SigtranMaintainedPeerLabTrafficVectorsExposeComparableSequence()
     Assert(comparison.Passed, comparison.Describe());
 }
 
+static void SigtranMaintainedPeerLabEvidenceGateRequiresCompleteRetainedArtifacts()
+{
+    SigtranMaintainedPeerLabConfiguration configuration = SigtranMaintainedPeerLabConfigurations.CreateDefault();
+    SigtranMaintainedPeerLabArtifactPlan artifactPlan = SigtranMaintainedPeerLabArtifactPlans.CreateDefault(configuration, "phase27-unit8");
+    IReadOnlyList<string> allPrerequisites = SigtranMaintainedPeerLabPrerequisites.GetDefault()
+        .Select(static prerequisite => prerequisite.Id)
+        .ToArray();
+
+    SigtranMaintainedPeerLabEvidenceReport ready = new(
+        artifactPlan,
+        SigtranMaintainedPeerLabPrerequisites.Evaluate(allPrerequisites),
+        configuration.Validate(),
+        SigtranMaintainedPeerLabEvidence.CreateDigestCoveredArtifacts(artifactPlan, "0123456789abcdef"),
+        comparisonPassed: true);
+
+    Assert(ready.PromotionReady, ready.Describe());
+    Assert(ready.HasRequiredArtifacts, ready.Describe());
+    Assert(ready.HasDigestCoverage, ready.Describe());
+
+    SigtranMaintainedPeerLabEvidenceReport missingDigest = new(
+        artifactPlan,
+        SigtranMaintainedPeerLabPrerequisites.Evaluate(allPrerequisites),
+        configuration.Validate(),
+        [new(SigtranMaintainedPeerLabArtifactKind.PacketCapture, "artifacts/external-peer/maintained/pcap/missing.pcap", retained: true)],
+        comparisonPassed: true);
+
+    Assert(!missingDigest.PromotionReady, missingDigest.Describe());
+    Assert(!missingDigest.HasRequiredArtifacts, missingDigest.Describe());
+    Assert(!missingDigest.HasDigestCoverage, missingDigest.Describe());
+    Assert(missingDigest.Describe().Contains("promotion=False", StringComparison.Ordinal), missingDigest.Describe());
+}
+
 static void SigtranTraceComparisonReportsOrderedMismatches()
 {
     SigtranInteropLabTemplate template = SigtranInteropPeerProfiles.CreateExternalPeerM3uaAspToSgTemplate();

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

@@ -0,0 +1,134 @@
+namespace Sigtran.NET.Core.Utilities;
+
+/// <summary>
+/// Describes one retained maintained external peer lab evidence artifact.
+/// </summary>
+public sealed class SigtranMaintainedPeerLabEvidenceArtifact
+{
+    /// <summary>Creates a retained maintained peer lab evidence artifact.</summary>
+    /// <param name="kind">The artifact kind.</param>
+    /// <param name="path">The retained artifact path.</param>
+    /// <param name="retained">Whether the artifact is retained.</param>
+    /// <param name="sha256">The optional SHA-256 digest.</param>
+    public SigtranMaintainedPeerLabEvidenceArtifact(
+        SigtranMaintainedPeerLabArtifactKind kind,
+        string path,
+        bool retained,
+        string? sha256 = null)
+    {
+        Kind = kind;
+        Path = string.IsNullOrWhiteSpace(path) ? throw new ArgumentException("Artifact path is required.", nameof(path)) : path;
+        Retained = retained;
+        Sha256 = string.IsNullOrWhiteSpace(sha256) ? null : sha256;
+    }
+
+    /// <summary>The artifact kind.</summary>
+    public SigtranMaintainedPeerLabArtifactKind Kind { get; }
+
+    /// <summary>The retained artifact path.</summary>
+    public string Path { get; }
+
+    /// <summary>Whether the artifact is retained.</summary>
+    public bool Retained { get; }
+
+    /// <summary>The optional SHA-256 digest.</summary>
+    public string? Sha256 { get; }
+
+    /// <summary>Whether the artifact is retained and digest-covered.</summary>
+    public bool IsPromotionReady => Retained && Sha256 is not null;
+}
+
+/// <summary>
+/// Describes maintained external peer lab evidence promotion output.
+/// </summary>
+public sealed class SigtranMaintainedPeerLabEvidenceReport
+{
+    private readonly SigtranMaintainedPeerLabEvidenceArtifact[] _artifacts;
+
+    /// <summary>Creates a maintained peer lab evidence report.</summary>
+    /// <param name="artifactPlan">The artifact plan.</param>
+    /// <param name="prerequisiteReport">The prerequisite report.</param>
+    /// <param name="configurationValidation">The configuration validation report.</param>
+    /// <param name="artifacts">The retained evidence artifacts.</param>
+    /// <param name="comparisonPassed">Whether trace comparison passed.</param>
+    public SigtranMaintainedPeerLabEvidenceReport(
+        SigtranMaintainedPeerLabArtifactPlan artifactPlan,
+        SigtranMaintainedPeerLabPrerequisiteReport prerequisiteReport,
+        SigtranMaintainedPeerLabConfigurationValidation configurationValidation,
+        IReadOnlyList<SigtranMaintainedPeerLabEvidenceArtifact> artifacts,
+        bool comparisonPassed)
+    {
+        ArgumentNullException.ThrowIfNull(artifactPlan);
+        ArgumentNullException.ThrowIfNull(prerequisiteReport);
+        ArgumentNullException.ThrowIfNull(configurationValidation);
+        ArgumentNullException.ThrowIfNull(artifacts);
+
+        ArtifactPlan = artifactPlan;
+        PrerequisiteReport = prerequisiteReport;
+        ConfigurationValidation = configurationValidation;
+        _artifacts = artifacts.ToArray();
+        ComparisonPassed = comparisonPassed;
+    }
+
+    /// <summary>The artifact plan.</summary>
+    public SigtranMaintainedPeerLabArtifactPlan ArtifactPlan { get; }
+
+    /// <summary>The prerequisite report.</summary>
+    public SigtranMaintainedPeerLabPrerequisiteReport PrerequisiteReport { get; }
+
+    /// <summary>The configuration validation report.</summary>
+    public SigtranMaintainedPeerLabConfigurationValidation ConfigurationValidation { get; }
+
+    /// <summary>The retained evidence artifacts.</summary>
+    public IReadOnlyList<SigtranMaintainedPeerLabEvidenceArtifact> Artifacts => _artifacts.ToArray();
+
+    /// <summary>Whether trace comparison passed.</summary>
+    public bool ComparisonPassed { get; }
+
+    /// <summary>Whether every required planned artifact is retained.</summary>
+    public bool HasRequiredArtifacts => ArtifactPlan.Items
+        .Where(static item => item.Required)
+        .All(item => _artifacts.Any(artifact => artifact.Kind == item.Kind && artifact.Retained));
+
+    /// <summary>Whether every retained artifact has digest coverage.</summary>
+    public bool HasDigestCoverage => _artifacts.Length > 0 && _artifacts.All(static artifact => artifact.IsPromotionReady);
+
+    /// <summary>Whether the maintained peer lab evidence is ready for commercial promotion.</summary>
+    public bool PromotionReady => PrerequisiteReport.Ready
+        && ConfigurationValidation.IsValid
+        && HasRequiredArtifacts
+        && HasDigestCoverage
+        && ComparisonPassed;
+
+    /// <summary>Formats a compact evidence report summary.</summary>
+    /// <returns>The evidence report summary.</returns>
+    public string Describe()
+    {
+        return $"run={ArtifactPlan.RunId} artifacts={_artifacts.Length} required={HasRequiredArtifacts} digests={HasDigestCoverage} comparison={ComparisonPassed} promotion={PromotionReady}";
+    }
+}
+
+/// <summary>
+/// Provides maintained external peer lab evidence helpers.
+/// </summary>
+public static class SigtranMaintainedPeerLabEvidence
+{
+    /// <summary>Creates a retained evidence artifact set from an artifact plan using one digest placeholder.</summary>
+    /// <param name="artifactPlan">The artifact plan.</param>
+    /// <param name="sha256">The digest used for all planned artifacts.</param>
+    /// <returns>The retained evidence artifacts.</returns>
+    public static IReadOnlyList<SigtranMaintainedPeerLabEvidenceArtifact> CreateDigestCoveredArtifacts(
+        SigtranMaintainedPeerLabArtifactPlan artifactPlan,
+        string sha256)
+    {
+        ArgumentNullException.ThrowIfNull(artifactPlan);
+        if (string.IsNullOrWhiteSpace(sha256))
+        {
+            throw new ArgumentException("Digest is required.", nameof(sha256));
+        }
+
+        return artifactPlan.Items
+            .Select(item => new SigtranMaintainedPeerLabEvidenceArtifact(item.Kind, item.Path, retained: true, sha256))
+            .ToArray();
+    }
+}