Add maintained peer lab CI profile

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 digest-covered 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, manual self-hosted CI policy, 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

@@ -96,6 +96,17 @@ The catalog flattens these vectors into an ordered expected message sequence so
 
 This keeps commercial readiness honest: a command plan or artifact plan is not treated as proof until retained outputs and digests exist.
 
+## Unit 9 - CI Profile
+
+`SigtranMaintainedPeerLabCi` now defines the CI execution policy for the maintained peer lab:
+
+- Manual dispatch only.
+- Self-hosted Linux runner required.
+- Environment variables required for peer binding and SCTP endpoints.
+- Artifact upload patterns for PCAP, logs, config, traces, comparison, and reports.
+
+The profile is deliberately not safe for default pull request CI because it depends on native SCTP, packet capture permissions, retained artifacts, and a configured maintained peer package.
+
 ## Environment Contract
 
 The default binding exposes these variables:
@@ -137,4 +148,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, the traffic vector catalog yields a comparable expected message sequence, and evidence promotion is blocked without complete digest-covered artifacts.
+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, evidence promotion is blocked without complete digest-covered artifacts, and CI remains manual/self-hosted for real lab execution.

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, 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.
+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, a digest-covered evidence promotion gate, and manual self-hosted CI policy. Commercial release remains blocked until the maintained peer lab produces passing digest-covered evidence.
 
 ## Recommended First Deliverable
 

src/Sigtran.NET.Tests/Program.cs

@@ -43,6 +43,7 @@
 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 maintained peer lab CI profile is manual and self-hosted", SigtranMaintainedPeerLabCiProfileIsManualAndSelfHosted);
 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);
@@ -865,6 +866,20 @@ static void SigtranMaintainedPeerLabEvidenceGateRequiresCompleteRetainedArtifact
     Assert(missingDigest.Describe().Contains("promotion=False", StringComparison.Ordinal), missingDigest.Describe());
 }
 
+static void SigtranMaintainedPeerLabCiProfileIsManualAndSelfHosted()
+{
+    SigtranMaintainedPeerLabCiProfile profile = SigtranMaintainedPeerLabCi.CreateDefault();
+
+    AssertEqual("maintained-peer-lab", profile.Name, "maintained peer lab CI profile name");
+    Assert(profile.ManualDispatchOnly, profile.Describe());
+    Assert(profile.RequiresSelfHostedLinux, profile.Describe());
+    Assert(!profile.SafeForDefaultCi, profile.Describe());
+    Assert(profile.RequiredEnvironmentVariables.Contains(SigtranMaintainedPeerLabBindings.PackageEnvironmentVariable), "CI profile should require peer package variable");
+    Assert(profile.RequiredEnvironmentVariables.Contains("LOCAL_SCTP_PORT"), "CI profile should require local SCTP port");
+    Assert(profile.ArtifactPatterns.Any(static pattern => pattern.Contains("/pcap/", StringComparison.Ordinal)), "CI profile should upload PCAP artifacts");
+    Assert(profile.ArtifactPatterns.Any(static pattern => pattern.Contains("/comparison/", StringComparison.Ordinal)), "CI profile should upload comparison artifacts");
+}
+
 static void SigtranTraceComparisonReportsOrderedMismatches()
 {
     SigtranInteropLabTemplate template = SigtranInteropPeerProfiles.CreateExternalPeerM3uaAspToSgTemplate();

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

@@ -0,0 +1,96 @@
+namespace Sigtran.NET.Core.Utilities;
+
+/// <summary>
+/// Describes maintained external peer lab CI execution policy.
+/// </summary>
+public sealed class SigtranMaintainedPeerLabCiProfile
+{
+    /// <summary>Creates a maintained external peer lab CI profile.</summary>
+    /// <param name="name">The CI profile name.</param>
+    /// <param name="manualDispatchOnly">Whether the lab is manual-dispatch only.</param>
+    /// <param name="requiresSelfHostedLinux">Whether a self-hosted Linux runner is required.</param>
+    /// <param name="requiredEnvironmentVariables">The required environment variables.</param>
+    /// <param name="artifactPatterns">The retained artifact upload patterns.</param>
+    public SigtranMaintainedPeerLabCiProfile(
+        string name,
+        bool manualDispatchOnly,
+        bool requiresSelfHostedLinux,
+        IReadOnlyList<string> requiredEnvironmentVariables,
+        IReadOnlyList<string> artifactPatterns)
+    {
+        ArgumentNullException.ThrowIfNull(requiredEnvironmentVariables);
+        ArgumentNullException.ThrowIfNull(artifactPatterns);
+
+        Name = string.IsNullOrWhiteSpace(name) ? throw new ArgumentException("CI profile name is required.", nameof(name)) : name;
+        ManualDispatchOnly = manualDispatchOnly;
+        RequiresSelfHostedLinux = requiresSelfHostedLinux;
+        RequiredEnvironmentVariables = requiredEnvironmentVariables.Count == 0
+            ? throw new ArgumentException("At least one environment variable is required.", nameof(requiredEnvironmentVariables))
+            : requiredEnvironmentVariables.ToArray();
+        ArtifactPatterns = artifactPatterns.Count == 0
+            ? throw new ArgumentException("At least one artifact pattern is required.", nameof(artifactPatterns))
+            : artifactPatterns.ToArray();
+    }
+
+    /// <summary>The CI profile name.</summary>
+    public string Name { get; }
+
+    /// <summary>Whether the lab is manual-dispatch only.</summary>
+    public bool ManualDispatchOnly { get; }
+
+    /// <summary>Whether a self-hosted Linux runner is required.</summary>
+    public bool RequiresSelfHostedLinux { get; }
+
+    /// <summary>The required environment variables.</summary>
+    public IReadOnlyList<string> RequiredEnvironmentVariables { get; }
+
+    /// <summary>The retained artifact upload patterns.</summary>
+    public IReadOnlyList<string> ArtifactPatterns { get; }
+
+    /// <summary>Whether this profile is safe to run in default pull request CI.</summary>
+    public bool SafeForDefaultCi => !RequiresSelfHostedLinux && !ManualDispatchOnly;
+
+    /// <summary>Formats a compact CI profile summary.</summary>
+    /// <returns>The CI profile summary.</returns>
+    public string Describe()
+    {
+        return $"name={Name} manual={ManualDispatchOnly} selfHostedLinux={RequiresSelfHostedLinux} env={RequiredEnvironmentVariables.Count} artifacts={ArtifactPatterns.Count}";
+    }
+}
+
+/// <summary>
+/// Provides maintained external peer lab CI profile helpers.
+/// </summary>
+public static class SigtranMaintainedPeerLabCi
+{
+    /// <summary>Creates the default maintained external peer lab CI profile.</summary>
+    /// <returns>The default maintained external peer lab CI profile.</returns>
+    public static SigtranMaintainedPeerLabCiProfile CreateDefault()
+    {
+        return new(
+            "maintained-peer-lab",
+            manualDispatchOnly: true,
+            requiresSelfHostedLinux: true,
+            requiredEnvironmentVariables:
+            [
+                SigtranMaintainedPeerLabBindings.PeerIdEnvironmentVariable,
+                SigtranMaintainedPeerLabBindings.PackageEnvironmentVariable,
+                SigtranMaintainedPeerLabBindings.PackageVersionEnvironmentVariable,
+                SigtranMaintainedPeerLabBindings.ArtifactRootEnvironmentVariable,
+                "LOCAL_IP",
+                "LOCAL_SCTP_PORT",
+                "REMOTE_IP",
+                "REMOTE_SCTP_PORT",
+                "ROUTING_CONTEXT"
+            ],
+            artifactPatterns:
+            [
+                "artifacts/external-peer/**/pcap/*.pcap",
+                "artifacts/external-peer/**/logs/*.log",
+                "artifacts/external-peer/**/config/*.env",
+                "artifacts/external-peer/**/trace/*.jsonl",
+                "artifacts/external-peer/**/comparison/*.md",
+                "artifacts/external-peer/**/reports/*.md"
+            ]);
+    }
+}