Add commercial evidence publication handoff

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, and promotion package 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, and approved package references for approval report, integrity seal, publication attachments, and promotion gate artifacts; publication handoff, 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, 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 |
 
 ## Requirements
 

docs/PHASE41_APPROVED_COMMERCIAL_RUN_PUBLICATION_HANDOFF.md

@@ -68,6 +68,19 @@ This unit turns approval data into a retained report artifact that later promoti
 
 This unit gives the publication handoff a single approved package contract instead of relying on loose references.
 
+## Unit 6 - Publication Handoff
+
+`SigtranCommercialEvidencePublicationHandoff` connects an approved run promotion package to publication channel intent:
+
+- Requested publication channel.
+- Requester identity.
+- UTC handoff creation time.
+- Explicit publish request flag.
+- Channel acceptance of package version.
+- Commercial readiness requirement visibility.
+
+This unit keeps RC and stable publication boundaries explicit before a final publication gate evaluates the handoff.
+
 ## Validation
 
 Each unit in this phase is validated with:

docs/PHASE41_SUMMARY.md

@@ -9,7 +9,8 @@ Phase 41 prepares the SDK to move from filesystem-backed evidence verification i
 - Reviewer approval manifest that records release, security, and operations approvals with UTC timestamps and a deterministic checklist digest.
 - 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.
 
 ## Readiness Position
 
-The phase is in progress. Approved run target identity, approval checklist, reviewer approval manifest, approval report writing, and promotion package are available. Publication handoff, 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, and publication handoff are available. Blocker gate, 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; promotion package 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 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, 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. Blocker gate, audit trail, command materialization, status reporting, and final validation remain in progress.
 
 ## Recommended First Deliverable
 

src/Sigtran.NET.Tests/Program.cs

@@ -320,6 +320,7 @@
 Run("SIGTRAN commercial evidence run approval manifest requires required roles", SigtranCommercialEvidenceRunApprovalManifestRequiresRequiredRoles);
 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 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);
@@ -5632,6 +5633,46 @@ static void SigtranCommercialEvidenceApprovedRunPromotionPackageCoversRequiredAr
     }
 }
 
+static void SigtranCommercialEvidencePublicationHandoffEnforcesChannelVersionPolicy()
+{
+    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);
+
+        Assert(beta.IsReadyForPublicationGate, beta.Describe());
+        Assert(beta.ChannelAcceptsPackageVersion, "beta channel should accept prerelease version");
+        Assert(!beta.RequiresCommercialReadiness, "beta channel should not require stable commercial readiness");
+        Assert(!stable.IsReadyForPublicationGate, "stable handoff should reject prerelease version");
+        Assert(!stable.ChannelAcceptsPackageVersion, "stable channel should not accept prerelease version");
+        Assert(stable.RequiresCommercialReadiness, "stable channel should require commercial readiness");
+    }
+    finally
+    {
+        DeleteTempEvidenceRoot(tempRoot);
+    }
+}
+
+static SigtranCommercialEvidenceApprovedRunPromotionPackage CreateReadyCommercialEvidenceApprovedRunPromotionPackage(string tempRoot)
+{
+    return SigtranCommercialEvidenceApprovedRunPromotionPackages.CreateDefault(
+        CreateReadyCommercialEvidenceRunApprovalReportWriteResult(tempRoot),
+        DateTimeOffset.UtcNow);
+}
+
 static SigtranCommercialEvidenceRunApprovalReportWriteResult CreateReadyCommercialEvidenceRunApprovalReportWriteResult(string tempRoot)
 {
     return SigtranCommercialEvidenceRunApprovalReportWriters.WriteReport(

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

@@ -0,0 +1,91 @@
+namespace Sigtran.NET.Core.Utilities;
+
+/// <summary>
+/// Describes a publication handoff for an approved commercial evidence run.
+/// </summary>
+public sealed class SigtranCommercialEvidencePublicationHandoff
+{
+    /// <summary>Creates an approved commercial evidence publication handoff.</summary>
+    /// <param name="promotionPackage">The approved run promotion package.</param>
+    /// <param name="channel">The requested publication channel.</param>
+    /// <param name="requestedBy">The requester identity.</param>
+    /// <param name="createdAtUtc">The UTC handoff creation time.</param>
+    /// <param name="publishRequested">Whether publication was explicitly requested.</param>
+    public SigtranCommercialEvidencePublicationHandoff(
+        SigtranCommercialEvidenceApprovedRunPromotionPackage promotionPackage,
+        SigtranPublishChannel channel,
+        string requestedBy,
+        DateTimeOffset createdAtUtc,
+        bool publishRequested)
+    {
+        PromotionPackage = promotionPackage ?? throw new ArgumentNullException(nameof(promotionPackage));
+        Channel = channel ?? throw new ArgumentNullException(nameof(channel));
+        RequestedBy = string.IsNullOrWhiteSpace(requestedBy) ? throw new ArgumentException("Requester is required.", nameof(requestedBy)) : requestedBy;
+        CreatedAtUtc = createdAtUtc.Offset == TimeSpan.Zero ? createdAtUtc : createdAtUtc.ToUniversalTime();
+        PublishRequested = publishRequested;
+    }
+
+    /// <summary>The approved run promotion package.</summary>
+    public SigtranCommercialEvidenceApprovedRunPromotionPackage PromotionPackage { get; }
+
+    /// <summary>The requested publication channel.</summary>
+    public SigtranPublishChannel Channel { get; }
+
+    /// <summary>The requester identity.</summary>
+    public string RequestedBy { get; }
+
+    /// <summary>The UTC handoff creation time.</summary>
+    public DateTimeOffset CreatedAtUtc { get; }
+
+    /// <summary>Whether publication was explicitly requested.</summary>
+    public bool PublishRequested { get; }
+
+    /// <summary>The package version covered by the handoff.</summary>
+    public string PackageVersion => PromotionPackage.ApprovalReport.Manifest.Checklist.Target.PackageVersion;
+
+    /// <summary>Whether the handoff creation time is normalized to UTC.</summary>
+    public bool HasUtcCreationTime => CreatedAtUtc.Offset == TimeSpan.Zero;
+
+    /// <summary>Whether the selected publication channel accepts the package version.</summary>
+    public bool ChannelAcceptsPackageVersion => Channel.AcceptsVersion(PackageVersion);
+
+    /// <summary>Whether the selected publication channel requires commercial readiness.</summary>
+    public bool RequiresCommercialReadiness => Channel.RequiresCommercialReadiness;
+
+    /// <summary>Whether the handoff is ready for publication gate evaluation.</summary>
+    public bool IsReadyForPublicationGate => PromotionPackage.IsReady
+        && PublishRequested
+        && HasUtcCreationTime
+        && ChannelAcceptsPackageVersion;
+
+    /// <summary>Formats a compact publication handoff summary.</summary>
+    /// <returns>The publication handoff summary.</returns>
+    public string Describe()
+    {
+        return $"commercialEvidencePublicationHandoffReady={IsReadyForPublicationGate} channel={Channel.FeedName} version={PackageVersion}";
+    }
+}
+
+/// <summary>
+/// Provides approved commercial evidence publication handoff helpers.
+/// </summary>
+public static class SigtranCommercialEvidencePublicationHandoffs
+{
+    /// <summary>Creates a publication handoff for an approved commercial evidence run.</summary>
+    /// <param name="promotionPackage">The approved run promotion package.</param>
+    /// <param name="channelKind">The requested publication channel kind.</param>
+    /// <param name="requestedBy">The requester identity.</param>
+    /// <param name="createdAtUtc">The UTC handoff creation time.</param>
+    /// <param name="publishRequested">Whether publication was explicitly requested.</param>
+    /// <returns>The approved commercial evidence publication handoff.</returns>
+    public static SigtranCommercialEvidencePublicationHandoff Create(
+        SigtranCommercialEvidenceApprovedRunPromotionPackage promotionPackage,
+        SigtranPublishChannelKind channelKind,
+        string requestedBy,
+        DateTimeOffset createdAtUtc,
+        bool publishRequested = true)
+    {
+        SigtranPublishChannel channel = SigtranPublishChannels.GetChannels().First(item => item.Kind == channelKind);
+        return new(promotionPackage, channel, requestedBy, createdAtUtc, publishRequested);
+    }
+}