Add commercial evidence publication handoff gate

Author: ammarheidari

README.md

@@ -76,7 +76,7 @@ The first production milestone is M3UA over a transport abstraction. SCCP, TCAP,
 | Commercial evidence artifact intake | Phase 38 foundation-complete: artifact intake target identity, artifact source registration, SHA-256 digest coverage, redaction review, completeness evaluation, dossier reporting, promotion handoff, execution-to-dossier bridge, status reporting, and final validation are available, binding a stable intake id, reviewer identity, UTC receipt time, run-scoped dossier root, concrete source paths, unique retained dossier paths, retained digests, trace-bearing artifact approvals, explicit intake blockers, retained Markdown summary, digest-covered handoff, end-to-end intake assembly, and intake readiness status to a governed execution run; real artifact files are still required before commercial publication |
 | Commercial evidence file verification | Phase 39 foundation-complete: retained file evidence item verification, retained file manifest coverage, file verification blocker reporting, retention ledger modeling, integrity sealing, publication attachment planning, verified promotion gating, command planning, status reporting, final validation, and documentation alignment are available, checking file existence, non-empty size, SHA-256 validity, digest match, UTC observation time, unique retained paths, promotion-required handoff coverage, explicit verification blockers, reviewer identity, immutable retention, UTC retention windows, minimum duration, deterministic aggregate ledger digests, sealed ledger attachment coverage, trace-bearing redaction approval, commercial readiness report presence, explicit promotion approval, workflow-ready verification command order, and readiness status separation; real retained file evidence remains required before commercial publication |
 | Commercial evidence filesystem execution | Phase 40 foundation-complete: filesystem observation, manifest execution, verification report execution, artifact writing, ledger execution, seal execution, publication attachment execution, promotion execution, command materialization, status reporting, documentation, and final validation are complete, reading retained files from disk, computing real SHA-256 digests, reporting file existence and size, supporting retained-path-to-local-path overrides, building retained file manifests from real observations, exposing blocker-aware retained file reports from filesystem evidence, writing retained Markdown/TSV verification artifacts, creating retention ledgers from filesystem-backed reports, sealing those ledgers with deterministic aggregate SHA-256 digests, creating release dossier attachments with redaction approval gates, evaluating reviewer-approved promotion gates, and writing ordered execution scripts; commercial publication still requires a real approved commercial run |
-| Approved commercial run publication handoff | Phase 41 in progress: approved run target identity, approval checklist, reviewer approval manifest, approval report writing, promotion package, and publication handoff are available, binding package version, source commit, operator identity, UTC run timing, retained artifact root, filesystem-backed promotion execution, verified report, ready ledger/seal/attachments, redaction approval, promotion approval, release/security/operations reviewer approvals, UTC approval timestamps, checklist digest coverage, retained Markdown report output, report SHA-256 digest coverage, approved package references, requested publication channel, requester identity, UTC handoff time, explicit publish intent, and channel version policy; blocker gate, audit trail, command materialization, status reporting, and final validation remain |
+| Approved commercial run publication handoff | Phase 41 in progress: approved run target identity, approval checklist, reviewer approval manifest, approval report writing, promotion package, publication handoff, and handoff gate are available, binding package version, source commit, operator identity, UTC run timing, retained artifact root, filesystem-backed promotion execution, verified report, ready ledger/seal/attachments, redaction approval, promotion approval, release/security/operations reviewer approvals, UTC approval timestamps, checklist digest coverage, retained Markdown report output, report SHA-256 digest coverage, approved package references, requested publication channel, requester identity, UTC handoff time, explicit publish intent, channel version policy, and handoff blocker reporting; audit trail, command materialization, status reporting, and final validation remain |
 
 ## Requirements
 

docs/PHASE41_APPROVED_COMMERCIAL_RUN_PUBLICATION_HANDOFF.md

@@ -81,6 +81,18 @@ This unit gives the publication handoff a single approved package contract inste
 
 This unit keeps RC and stable publication boundaries explicit before a final publication gate evaluates the handoff.
 
+## Unit 7 - Publication Handoff Gate
+
+`SigtranCommercialEvidencePublicationHandoffGates` evaluates handoff blockers:
+
+- Promotion package readiness.
+- Explicit publish request.
+- UTC handoff time.
+- Channel acceptance of package version.
+- Stable commercial readiness approval when required.
+
+This unit gives release operators actionable blockers before package publication workflows are allowed to proceed.
+
 ## Validation
 
 Each unit in this phase is validated with:

docs/PHASE41_SUMMARY.md

@@ -10,7 +10,8 @@ Phase 41 prepares the SDK to move from filesystem-backed evidence verification i
 - Approval report writer that renders retained Markdown approval reports with SHA-256 digest coverage.
 - Approved run promotion package that collects approval report, integrity seal, publication attachments, and promotion gate artifact references with required digest coverage.
 - Publication handoff that connects an approved promotion package to channel policy, requester identity, UTC handoff time, and explicit publish intent.
+- Publication handoff gate that reports blockers for package readiness, publish intent, UTC timing, channel/version policy, and stable commercial readiness approval.
 
 ## Readiness Position
 
-The phase is in progress. Approved run target identity, approval checklist, reviewer approval manifest, approval report writing, promotion package, and publication handoff are available. Blocker gate, audit trail, command materialization, status reporting, documentation, and final validation remain.
+The phase is in progress. Approved run target identity, approval checklist, reviewer approval manifest, approval report writing, promotion package, publication handoff, and handoff gate are available. Audit trail, command materialization, status reporting, documentation, and final validation remain.

docs/PHASE_INDEX.md

@@ -45,7 +45,7 @@ This index is the complete phase map for Sigtran.NET. It links each phase to the
 | 38 | Commercial evidence artifact intake | [Phase 38 Commercial Evidence Artifact Intake](PHASE38_COMMERCIAL_EVIDENCE_ARTIFACT_INTAKE.md), [Phase 38 Summary](PHASE38_SUMMARY.md) | Foundation complete; real artifact files still required |
 | 39 | Commercial evidence file verification | [Phase 39 Commercial Evidence File Verification](PHASE39_COMMERCIAL_EVIDENCE_FILE_VERIFICATION.md), [Phase 39 Summary](PHASE39_SUMMARY.md) | Foundation complete; real retained file evidence required |
 | 40 | Commercial evidence filesystem execution | [Phase 40 Commercial Evidence Filesystem Execution](PHASE40_COMMERCIAL_EVIDENCE_FILESYSTEM_EXECUTION.md), [Phase 40 Summary](PHASE40_SUMMARY.md) | Foundation complete; commercial publication requires real approved retained run |
-| 41 | Approved commercial run publication handoff | [Phase 41 Approved Commercial Run Publication Handoff](PHASE41_APPROVED_COMMERCIAL_RUN_PUBLICATION_HANDOFF.md), [Phase 41 Summary](PHASE41_SUMMARY.md) | In progress; publication handoff complete |
+| 41 | Approved commercial run publication handoff | [Phase 41 Approved Commercial Run Publication Handoff](PHASE41_APPROVED_COMMERCIAL_RUN_PUBLICATION_HANDOFF.md), [Phase 41 Summary](PHASE41_SUMMARY.md) | In progress; publication handoff gate complete |
 
 ## Current Commercial Gate
 

docs/SDK_ROADMAP.md

@@ -363,7 +363,7 @@ Status: Phase 40 is foundation-complete. Filesystem observation reads retained f
 - Record approval checklist, reviewer approvals, retained reports, promotion package, publication handoff, blocker gates, and audit trail.
 - Keep approval handoff separate from commercial publication: the SDK can prepare approval records, but publication remains blocked until a real approved run is retained.
 
-Status: Phase 41 is in progress. Approved run target identity now binds package version, source commit, operator identity, UTC run timing, retained artifact root, and filesystem-backed promotion execution. Approval checklist now requires verified filesystem promotion, ready report/ledger/seal/attachments, approved trace redaction, promotion approval, and reviewer approval records. Reviewer approval manifest now records release, security, and operations approvals with UTC timestamps and a deterministic checklist SHA-256 digest. Approval report writing now renders retained Markdown reports with run identity, checklist digest, reviewer roles, UTC write time, and report SHA-256 digest coverage. Approved run promotion package now collects approval report, integrity seal, publication attachment, and promotion gate artifact references with required digest coverage. Publication handoff now binds the approved package to requested channel, requester identity, UTC handoff time, explicit publish intent, and channel version policy. Blocker gate, audit trail, command materialization, status reporting, and final validation remain in progress.
+Status: Phase 41 is in progress. Approved run target identity now binds package version, source commit, operator identity, UTC run timing, retained artifact root, and filesystem-backed promotion execution. Approval checklist now requires verified filesystem promotion, ready report/ledger/seal/attachments, approved trace redaction, promotion approval, and reviewer approval records. Reviewer approval manifest now records release, security, and operations approvals with UTC timestamps and a deterministic checklist SHA-256 digest. Approval report writing now renders retained Markdown reports with run identity, checklist digest, reviewer roles, UTC write time, and report SHA-256 digest coverage. Approved run promotion package now collects approval report, integrity seal, publication attachment, and promotion gate artifact references with required digest coverage. Publication handoff now binds the approved package to requested channel, requester identity, UTC handoff time, explicit publish intent, and channel version policy. Publication handoff gate now reports blockers for package readiness, publish intent, UTC timing, channel/version policy, and stable commercial readiness approval. Audit trail, command materialization, status reporting, and final validation remain in progress.
 
 ## Recommended First Deliverable
 

src/Sigtran.NET.Tests/Program.cs

@@ -321,6 +321,7 @@
 Run("SIGTRAN commercial evidence run approval report writer retains markdown", SigtranCommercialEvidenceRunApprovalReportWriterRetainsMarkdown);
 Run("SIGTRAN commercial evidence approved run promotion package covers required artifacts", SigtranCommercialEvidenceApprovedRunPromotionPackageCoversRequiredArtifacts);
 Run("SIGTRAN commercial evidence publication handoff enforces channel version policy", SigtranCommercialEvidencePublicationHandoffEnforcesChannelVersionPolicy);
+Run("SIGTRAN commercial evidence publication handoff gate reports blockers", SigtranCommercialEvidencePublicationHandoffGateReportsBlockers);
 Run("SIGTRAN status capabilities use domain documentation labels", SigtranStatusCapabilitiesUseDomainDocumentationLabels);
 Run("Native SCTP platform probe reports socket creation capability", NativeSctpPlatformProbeReportsSocketCreationCapability);
 Run("Native SCTP socket factory creates or reports unsupported platform", NativeSctpSocketFactoryCreatesOrReportsUnsupportedPlatform);
@@ -5666,6 +5667,49 @@ static void SigtranCommercialEvidencePublicationHandoffEnforcesChannelVersionPol
     }
 }
 
+static void SigtranCommercialEvidencePublicationHandoffGateReportsBlockers()
+{
+    string tempRoot = Path.Combine(Path.GetTempPath(), "sigtran-commercial-evidence-" + Guid.NewGuid().ToString("N"));
+    Directory.CreateDirectory(tempRoot);
+
+    try
+    {
+        SigtranCommercialEvidenceApprovedRunPromotionPackage package = CreateReadyCommercialEvidenceApprovedRunPromotionPackage(tempRoot);
+        SigtranCommercialEvidencePublicationHandoff beta = SigtranCommercialEvidencePublicationHandoffs.Create(
+            package,
+            SigtranPublishChannelKind.Beta,
+            "release-manager",
+            DateTimeOffset.UtcNow);
+        SigtranCommercialEvidencePublicationHandoff stable = SigtranCommercialEvidencePublicationHandoffs.Create(
+            package,
+            SigtranPublishChannelKind.Stable,
+            "release-manager",
+            DateTimeOffset.UtcNow);
+        SigtranCommercialEvidencePublicationHandoff noPublish = SigtranCommercialEvidencePublicationHandoffs.Create(
+            package,
+            SigtranPublishChannelKind.Beta,
+            "release-manager",
+            DateTimeOffset.UtcNow,
+            publishRequested: false);
+
+        SigtranCommercialEvidencePublicationHandoffGateResult approved = SigtranCommercialEvidencePublicationHandoffGates.Evaluate(beta, commercialReadinessApproved: false);
+        SigtranCommercialEvidencePublicationHandoffGateResult stableBlocked = SigtranCommercialEvidencePublicationHandoffGates.Evaluate(stable, commercialReadinessApproved: false);
+        SigtranCommercialEvidencePublicationHandoffGateResult noPublishBlocked = SigtranCommercialEvidencePublicationHandoffGates.Evaluate(noPublish, commercialReadinessApproved: false);
+
+        Assert(approved.CanProceedToPackagePublicationGate, approved.Describe());
+        AssertEqual(0, approved.Blockers.Count, "approved handoff blocker count");
+        Assert(!stableBlocked.CanProceedToPackagePublicationGate, "stable handoff should be blocked for prerelease version and readiness");
+        Assert(stableBlocked.Blockers.Contains("channel-version-rejected"), "stable handoff should expose channel version blocker");
+        Assert(stableBlocked.Blockers.Contains("stable-commercial-readiness-required"), "stable handoff should expose commercial readiness blocker");
+        Assert(!noPublishBlocked.CanProceedToPackagePublicationGate, "missing publish request should block handoff");
+        Assert(noPublishBlocked.Blockers.Contains("publish-not-requested"), "handoff gate should expose publish intent blocker");
+    }
+    finally
+    {
+        DeleteTempEvidenceRoot(tempRoot);
+    }
+}
+
 static SigtranCommercialEvidenceApprovedRunPromotionPackage CreateReadyCommercialEvidenceApprovedRunPromotionPackage(string tempRoot)
 {
     return SigtranCommercialEvidenceApprovedRunPromotionPackages.CreateDefault(

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

@@ -0,0 +1,86 @@
+namespace Sigtran.NET.Core.Utilities;
+
+/// <summary>
+/// Describes an approved commercial evidence publication handoff gate result.
+/// </summary>
+public sealed class SigtranCommercialEvidencePublicationHandoffGateResult
+{
+    /// <summary>Creates a publication handoff gate result.</summary>
+    /// <param name="handoff">The publication handoff under evaluation.</param>
+    /// <param name="commercialReadinessApproved">Whether commercial readiness was approved for the requested channel.</param>
+    /// <param name="blockers">The publication handoff blockers.</param>
+    public SigtranCommercialEvidencePublicationHandoffGateResult(
+        SigtranCommercialEvidencePublicationHandoff handoff,
+        bool commercialReadinessApproved,
+        IReadOnlyList<string> blockers)
+    {
+        Handoff = handoff ?? throw new ArgumentNullException(nameof(handoff));
+        CommercialReadinessApproved = commercialReadinessApproved;
+        ArgumentNullException.ThrowIfNull(blockers);
+        Blockers = blockers.ToArray();
+    }
+
+    /// <summary>The publication handoff under evaluation.</summary>
+    public SigtranCommercialEvidencePublicationHandoff Handoff { get; }
+
+    /// <summary>Whether commercial readiness was approved for the requested channel.</summary>
+    public bool CommercialReadinessApproved { get; }
+
+    /// <summary>The publication handoff blockers.</summary>
+    public IReadOnlyList<string> Blockers { get; }
+
+    /// <summary>Whether the publication handoff can proceed to the package publication gate.</summary>
+    public bool CanProceedToPackagePublicationGate => Blockers.Count == 0;
+
+    /// <summary>Formats a compact publication handoff gate summary.</summary>
+    /// <returns>The publication handoff gate summary.</returns>
+    public string Describe()
+    {
+        return $"commercialEvidencePublicationHandoffGateReady={CanProceedToPackagePublicationGate} blockers={Blockers.Count} channel={Handoff.Channel.FeedName}";
+    }
+}
+
+/// <summary>
+/// Provides approved commercial evidence publication handoff gate helpers.
+/// </summary>
+public static class SigtranCommercialEvidencePublicationHandoffGates
+{
+    /// <summary>Evaluates an approved commercial evidence publication handoff.</summary>
+    /// <param name="handoff">The publication handoff under evaluation.</param>
+    /// <param name="commercialReadinessApproved">Whether commercial readiness was approved for the requested channel.</param>
+    /// <returns>The publication handoff gate result.</returns>
+    public static SigtranCommercialEvidencePublicationHandoffGateResult Evaluate(
+        SigtranCommercialEvidencePublicationHandoff handoff,
+        bool commercialReadinessApproved)
+    {
+        ArgumentNullException.ThrowIfNull(handoff);
+        List<string> blockers = [];
+
+        if (!handoff.PromotionPackage.IsReady)
+        {
+            blockers.Add("promotion-package-not-ready");
+        }
+
+        if (!handoff.PublishRequested)
+        {
+            blockers.Add("publish-not-requested");
+        }
+
+        if (!handoff.HasUtcCreationTime)
+        {
+            blockers.Add("handoff-time-not-utc");
+        }
+
+        if (!handoff.ChannelAcceptsPackageVersion)
+        {
+            blockers.Add("channel-version-rejected");
+        }
+
+        if (handoff.RequiresCommercialReadiness && !commercialReadinessApproved)
+        {
+            blockers.Add("stable-commercial-readiness-required");
+        }
+
+        return new(handoff, commercialReadinessApproved, blockers);
+    }
+}