Add package publication request boundary

Author: ammarheidari

README.md

@@ -77,6 +77,7 @@ The first production milestone is M3UA over a transport abstraction. SCCP, TCAP,
 | 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 foundation-complete: approved run target identity, approval checklist, reviewer approval manifest, approval report writing, promotion package, publication handoff, handoff gate, approval audit trail, command materialization, status reporting, documentation, and final validation are complete, 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, handoff blocker reporting, digest-covered audit lifecycle events, and ordered approval workflow scripts; package publication still requires a real approved commercial run |
+| Commercial package publication gate integration | Phase 42 in progress: handoff-derived package publication request is available and binds package version, channel, requester identity, run id, promotion package id, UTC request time, and artifact-binding readiness; package publication remains blocked until artifact binding, credential readiness, evidence assembly, release guard, channel policy, gate execution, dry-run rehearsal, guarded commands, and status reporting are complete |
 
 ## Requirements
 
@@ -144,6 +145,7 @@ Start here:
 - [Complete phase index](docs/PHASE_INDEX.md)
 - [Commercial readiness report](docs/COMMERCIAL_READINESS_REPORT.md)
 - [Phase 35 commercial gate report](docs/PHASE35_COMMERCIAL_GATE_REPORT.md)
+- [Phase 42 package publication gate integration](docs/PHASE42_COMMERCIAL_PACKAGE_PUBLICATION_GATE_INTEGRATION.md)
 - [Alpha release checklist](docs/ALPHA_RELEASE.md)
 
 Architecture and protocol docs:

docs/PHASE42_COMMERCIAL_PACKAGE_PUBLICATION_GATE_INTEGRATION.md

@@ -0,0 +1,28 @@
+# Phase 42 - Commercial Package Publication Gate Integration
+
+Phase 42 connects an approved commercial evidence publication handoff to the package publication gate. It does not publish packages by itself. The phase prepares request, package artifact, credential, evidence, release guard, channel policy, gate execution, dry-run, command, and status contracts so a release workflow can decide whether publication is allowed from retained evidence.
+
+## Unit Plan
+
+| Unit | Capability | Status |
+| --- | --- | --- |
+| 1 | Package publication request derived from approved handoff gate | Complete |
+| 2 | Package artifact binding with package and symbols digests | Pending |
+| 3 | Credential readiness bridge for required publication secrets | Pending |
+| 4 | Publication evidence assembly from approved run and artifacts | Pending |
+| 5 | Release publish guard bridge | Pending |
+| 6 | Publication channel policy evaluation bridge | Pending |
+| 7 | Commercial package publication gate execution | Pending |
+| 8 | Dry-run publication rehearsal artifact | Pending |
+| 9 | Guarded publish command materialization and status | Pending |
+| 10 | Final documentation, README alignment, validation, commit, and push | Pending |
+
+## Current Capability
+
+`SigtranPackagePublicationRequest` turns a `SigtranCommercialEvidencePublicationHandoffGateResult` into a package publication request. The request preserves the package version, publication channel, requester identity, commercial evidence run id, approved promotion package id, and UTC request time.
+
+The request can only move to package artifact binding when the upstream handoff gate allows evaluation and the request time is normalized to UTC. This keeps package publication blocked when approval handoff evidence is incomplete.
+
+## Commercial Gate Position
+
+Phase 42 is still in progress. Unit 1 establishes the handoff-to-publication request boundary. Real package publication remains blocked until package artifacts, required credentials, retained evidence, release guard, channel policy, and the final publication gate all pass.

docs/PHASE42_SUMMARY.md

@@ -0,0 +1,11 @@
+# Phase 42 Summary - Commercial Package Publication Gate Integration
+
+Phase 42 is in progress. It connects approved commercial evidence handoff records to the package publication gate without enabling live publication prematurely.
+
+## Completed Capabilities
+
+- Package publication request that derives package version, channel, requester identity, run id, promotion package id, UTC request time, and artifact-binding readiness from an approved handoff gate.
+
+## Readiness Position
+
+Unit 1 is complete. The SDK can now represent the publication request boundary after commercial approval handoff. Package publication still requires artifact binding, credential readiness, evidence assembly, release guard evaluation, channel policy evaluation, final gate execution, dry-run rehearsal, guarded command materialization, status reporting, and retained real release evidence.

docs/PHASE_INDEX.md

@@ -46,7 +46,8 @@ This index is the complete phase map for Sigtran.NET. It links each phase to the
 | 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) | Foundation complete; package publication requires real approved commercial run |
+| 42 | Commercial package publication gate integration | [Phase 42 Commercial Package Publication Gate Integration](PHASE42_COMMERCIAL_PACKAGE_PUBLICATION_GATE_INTEGRATION.md), [Phase 42 Summary](PHASE42_SUMMARY.md) | In progress; handoff-derived publication request complete |
 
 ## Current Commercial Gate
 
-The SDK can now define governed commercial evidence-producing execution, model intake of retained artifacts, verify retained files, execute filesystem-backed verification, and prepare approved commercial run publication handoff records. RC publication remains blocked until retained execution-run, release-run, and commercial evidence artifacts are complete and approved. Stable publication remains blocked until external peer evidence, trusted timestamped signing, production performance evidence, retained release-run artifacts, real artifact file evidence, approved commercial run handoff, and the commercial evidence dossier are complete.
+The SDK can now define governed commercial evidence-producing execution, model intake of retained artifacts, verify retained files, execute filesystem-backed verification, prepare approved commercial run publication handoff records, and derive a package publication request from an approved handoff gate. RC publication remains blocked until retained execution-run, release-run, and commercial evidence artifacts are complete and approved. Stable publication remains blocked until external peer evidence, trusted timestamped signing, production performance evidence, retained release-run artifacts, real artifact file evidence, approved commercial run handoff, package publication gate integration, and the commercial evidence dossier are complete.

src/Sigtran.NET.Tests/Program.cs

@@ -322,6 +322,7 @@
 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 package publication request derives from approved handoff", SigtranPackagePublicationRequestDerivesFromApprovedHandoff);
 Run("SIGTRAN commercial evidence approval audit trail covers lifecycle", SigtranCommercialEvidenceApprovalAuditTrailCoversLifecycle);
 Run("SIGTRAN commercial evidence approval command materializer writes script", SigtranCommercialEvidenceApprovalCommandMaterializerWritesScript);
 Run("SIGTRAN commercial evidence approval handoff status summarizes final validation", SigtranCommercialEvidenceApprovalHandoffStatusSummarizesFinalValidation);
@@ -5713,6 +5714,34 @@ static void SigtranCommercialEvidencePublicationHandoffGateReportsBlockers()
     }
 }
 
+static void SigtranPackagePublicationRequestDerivesFromApprovedHandoff()
+{
+    string tempRoot = Path.Combine(Path.GetTempPath(), "sigtran-commercial-evidence-" + Guid.NewGuid().ToString("N"));
+    Directory.CreateDirectory(tempRoot);
+
+    try
+    {
+        SigtranCommercialEvidencePublicationHandoffGateResult gate = CreateReadyCommercialEvidencePublicationHandoffGateResult(tempRoot);
+
+        SigtranPackagePublicationRequest request = SigtranPackagePublicationRequests.Create(
+            gate,
+            DateTimeOffset.UtcNow);
+
+        Assert(request.IsReadyForArtifactBinding, request.Describe());
+        Assert(request.HasUtcRequestTime, "package publication request time should be UTC");
+        Assert(request.HandoffGateAllowsPackageEvaluation, "handoff gate should allow package publication evaluation");
+        AssertEqual("1.0.0-rc.1", request.PackageVersion, "publication request package version");
+        AssertEqual(SigtranPublishChannelKind.Beta, request.Channel.Kind, "publication request channel");
+        AssertEqual("release-manager", request.RequestedBy, "publication request requester");
+        AssertEqual("commercial-run-20260622-001", request.RunId, "publication request run id");
+        Assert(request.Describe().Contains("packagePublicationRequestReady=True", StringComparison.Ordinal), request.Describe());
+    }
+    finally
+    {
+        DeleteTempEvidenceRoot(tempRoot);
+    }
+}
+
 static void SigtranCommercialEvidenceApprovalAuditTrailCoversLifecycle()
 {
     string tempRoot = Path.Combine(Path.GetTempPath(), "sigtran-commercial-evidence-" + Guid.NewGuid().ToString("N"));

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

@@ -0,0 +1,73 @@
+namespace Sigtran.NET.Core.Utilities;
+
+/// <summary>
+/// Describes a package publication request derived from an approved commercial evidence handoff.
+/// </summary>
+public sealed class SigtranPackagePublicationRequest
+{
+    /// <summary>Creates a package publication request.</summary>
+    /// <param name="handoffGate">The approved commercial evidence handoff gate result.</param>
+    /// <param name="requestedAtUtc">The UTC publication request time.</param>
+    public SigtranPackagePublicationRequest(
+        SigtranCommercialEvidencePublicationHandoffGateResult handoffGate,
+        DateTimeOffset requestedAtUtc)
+    {
+        HandoffGate = handoffGate ?? throw new ArgumentNullException(nameof(handoffGate));
+        RequestedAtUtc = requestedAtUtc.Offset == TimeSpan.Zero ? requestedAtUtc : requestedAtUtc.ToUniversalTime();
+    }
+
+    /// <summary>The approved commercial evidence handoff gate result.</summary>
+    public SigtranCommercialEvidencePublicationHandoffGateResult HandoffGate { get; }
+
+    /// <summary>The UTC publication request time.</summary>
+    public DateTimeOffset RequestedAtUtc { get; }
+
+    /// <summary>The requested package version.</summary>
+    public string PackageVersion => HandoffGate.Handoff.PackageVersion;
+
+    /// <summary>The requested publication channel.</summary>
+    public SigtranPublishChannel Channel => HandoffGate.Handoff.Channel;
+
+    /// <summary>The requester identity from the handoff.</summary>
+    public string RequestedBy => HandoffGate.Handoff.RequestedBy;
+
+    /// <summary>The commercial evidence run identifier.</summary>
+    public string RunId => HandoffGate.Handoff.PromotionPackage.ApprovalReport.Manifest.Checklist.Target.RunId;
+
+    /// <summary>The approved promotion package identifier.</summary>
+    public string PromotionPackageId => HandoffGate.Handoff.PromotionPackage.PackageId;
+
+    /// <summary>Whether the request time is normalized to UTC.</summary>
+    public bool HasUtcRequestTime => RequestedAtUtc.Offset == TimeSpan.Zero;
+
+    /// <summary>Whether the upstream handoff gate allows package publication evaluation.</summary>
+    public bool HandoffGateAllowsPackageEvaluation => HandoffGate.CanProceedToPackagePublicationGate;
+
+    /// <summary>Whether the request is ready for package artifact binding.</summary>
+    public bool IsReadyForArtifactBinding => HasUtcRequestTime
+        && HandoffGateAllowsPackageEvaluation;
+
+    /// <summary>Formats a compact package publication request summary.</summary>
+    /// <returns>The package publication request summary.</returns>
+    public string Describe()
+    {
+        return $"packagePublicationRequestReady={IsReadyForArtifactBinding} version={PackageVersion} channel={Channel.FeedName} runId={RunId}";
+    }
+}
+
+/// <summary>
+/// Provides package publication request helpers.
+/// </summary>
+public static class SigtranPackagePublicationRequests
+{
+    /// <summary>Creates a package publication request from an approved commercial evidence handoff gate.</summary>
+    /// <param name="handoffGate">The approved commercial evidence handoff gate result.</param>
+    /// <param name="requestedAtUtc">The UTC publication request time.</param>
+    /// <returns>The package publication request.</returns>
+    public static SigtranPackagePublicationRequest Create(
+        SigtranCommercialEvidencePublicationHandoffGateResult handoffGate,
+        DateTimeOffset requestedAtUtc)
+    {
+        return new(handoffGate, requestedAtUtc);
+    }
+}