Add commercial evidence retained file verification

Author: ammarheidari

README.md

@@ -74,6 +74,7 @@ The first production milestone is M3UA over a transport abstraction. SCCP, TCAP,
 | Commercial evidence readiness lockdown | Phase 36 foundation-complete: release target locking, protected secret readiness, evidence retention mapping, commercial evidence checklist, release preflight, protected release environments, dossier handoff, go/no-go gating, status reporting, and final validation are available; RC and stable publication remain blocked until retained commercial release evidence is complete |
 | Commercial evidence execution orchestration | Phase 37 foundation-complete: evidence execution run identity, stage catalog, operator command plan, execution environment contract, artifact collection manifest, digest/redaction verification, blocker classification, retry/resume policy, status reporting, and final validation are available; real retained execution artifacts are still required before commercial publication |
 | 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 in progress: retained file evidence item verification is available, checking file existence, non-empty size, SHA-256 validity, digest match, and UTC observation time; file manifest coverage, verification reporting, retention ledger, integrity seal, publication attachments, promotion gate, command plan, status reporting, and final validation remain |
 
 ## Requirements
 

docs/PHASE39_COMMERCIAL_EVIDENCE_FILE_VERIFICATION.md

@@ -0,0 +1,29 @@
+# Phase 39 Commercial Evidence File Verification
+
+Phase 39 turns digest-covered intake handoff records into retained file verification contracts. It does not create real commercial evidence by itself. It defines how retained artifact files are observed, matched to expected digests, checked for retention, sealed, and prepared for release evidence gates.
+
+Public APIs use domain names such as `SigtranCommercialEvidenceRetainedFiles`; phase numbers are intentionally kept out of source type names.
+
+## Unit 1 - Retained File Evidence Item
+
+`SigtranCommercialEvidenceRetainedFiles` records an observed retained file:
+
+- Checklist artifact kind.
+- Retained artifact path.
+- Expected SHA-256 digest from the promotion handoff.
+- Actual SHA-256 digest observed from the retained file.
+- Observed file size.
+- UTC observation time.
+- File existence state.
+
+A retained file is verified only when the file exists, is non-empty, carries valid SHA-256 values, has matching expected and actual digests, and uses a UTC observation time.
+
+## Validation
+
+Each unit in this phase is validated with:
+
+```powershell
+dotnet build src\Sigtran.NET.sln
+dotnet run --project src\Sigtran.NET.Tests\Sigtran.NET.Tests.csproj
+dotnet pack src\Sigtran.NET\Sigtran.NET.csproj -c Release
+```

docs/PHASE39_SUMMARY.md

@@ -0,0 +1,11 @@
+# Phase 39 Summary - Commercial Evidence File Verification
+
+Phase 39 prepares the SDK to verify retained commercial evidence files after artifact intake is complete.
+
+## Completed Capabilities
+
+- Retained file evidence item that verifies existence, size, SHA-256 validity, digest match, and UTC observation time.
+
+## Readiness Position
+
+The phase is in progress. Retained file evidence item verification is available. File manifest coverage, verification reporting, retention ledger, integrity seal, publication attachments, promotion gate, command plan, status reporting, and final validation remain.

docs/PHASE_INDEX.md

@@ -43,7 +43,8 @@ This index is the complete phase map for Sigtran.NET. It links each phase to the
 | 36 | Commercial evidence readiness lockdown | [Phase 36 Commercial Evidence Readiness Lockdown](PHASE36_COMMERCIAL_EVIDENCE_READINESS_LOCKDOWN.md), [Phase 36 Summary](PHASE36_SUMMARY.md) | Foundation complete; real commercial evidence still required |
 | 37 | Commercial evidence execution orchestration | [Phase 37 Commercial Evidence Execution Orchestration](PHASE37_COMMERCIAL_EVIDENCE_EXECUTION_ORCHESTRATION.md), [Phase 37 Summary](PHASE37_SUMMARY.md) | Foundation complete; real execution artifacts still required |
 | 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) | In progress; retained file item complete |
 
 ## Current Commercial Gate
 
-The SDK can now define governed commercial evidence-producing execution and model intake of retained artifacts when protected secrets are available. RC publication remains blocked until retained execution-run, release-run, and commercial evidence artifacts are complete. Stable publication remains blocked until external peer evidence, trusted timestamped signing, production performance evidence, retained release-run artifacts, real artifact file evidence, and the commercial evidence dossier are complete.
+The SDK can now define governed commercial evidence-producing execution, model intake of retained artifacts, and start retained file verification when protected secrets are available. RC publication remains blocked until retained execution-run, release-run, and commercial evidence artifacts are complete. Stable publication remains blocked until external peer evidence, trusted timestamped signing, production performance evidence, retained release-run artifacts, real artifact file evidence, and the commercial evidence dossier are complete.

docs/SDK_ROADMAP.md

@@ -341,6 +341,14 @@ Status: Phase 37 is foundation-complete. Evidence execution run identity binds a
 
 Status: Phase 38 is foundation-complete. Artifact intake target identity binds a stable intake id, reviewer identity, UTC receipt time, and run-scoped dossier root to a governed commercial evidence execution run. Artifact source registration maps every required expected execution artifact to a concrete source path and unique retained dossier path while rejecting floating `artifacts/latest` aliases. Digest coverage records SHA-256 values for every retained source and blocks invalid digest values. Redaction review requires approved reviewer records for trace-bearing retained artifacts. Completeness evaluation reports explicit source, digest, and redaction blockers. Dossier reporting renders a retained Markdown summary with run, intake, reviewer, counts, completion state, and blockers. Promotion handoff includes all digest-covered retained artifacts and the dossier intake report. Execution-to-dossier bridge assembles the intake pipeline from a governed execution run. Status reporting exposes completed capabilities, foundation readiness, real artifact evidence readiness, publication readiness, and current blockers. Final validation is complete. Commercial publication remains blocked until real artifact files are retained, digest-calculated, redaction-reviewed, and approved.
 
+## Phase 39 - Commercial Evidence File Verification
+
+- Verify retained commercial evidence files against promotion handoff digests.
+- Track file existence, size, observation time, digest match, retention, integrity sealing, publication attachment, promotion gate, and operator command contracts.
+- Keep file verification separate from real lab execution: verification contracts can evaluate retained files, but publication remains blocked until real files are present and approved.
+
+Status: Phase 39 is in progress. Retained file evidence item verification now checks existence, non-empty size, SHA-256 validity, digest match, and UTC observation time. File manifest coverage, verification reporting, retention ledger, integrity seal, publication attachments, promotion gate, command plan, status reporting, and final validation remain in progress.
+
 ## Recommended First Deliverable
 
 The first useful SDK release should be an alpha package focused on M3UA over a transport abstraction:

src/Sigtran.NET.Tests/Program.cs

@@ -296,6 +296,7 @@
 Run("SIGTRAN commercial evidence promotion handoff includes digests and report", SigtranCommercialEvidencePromotionHandoffIncludesDigestsAndReport);
 Run("SIGTRAN commercial evidence dossier intake bridge builds handoff from execution run", SigtranCommercialEvidenceDossierIntakeBridgeBuildsHandoffFromExecutionRun);
 Run("SIGTRAN commercial evidence artifact intake status summarizes foundation readiness", SigtranCommercialEvidenceArtifactIntakeStatusSummarizesFoundationReadiness);
+Run("SIGTRAN commercial evidence retained file verifies observed digest", SigtranCommercialEvidenceRetainedFileVerifiesObservedDigest);
 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);
@@ -4975,6 +4976,36 @@ static void SigtranCommercialEvidenceArtifactIntakeStatusSummarizesFoundationRea
     Assert(!blockers.Contains("status-final-validation-pending"), "final validation should no longer be a blocker");
 }
 
+static void SigtranCommercialEvidenceRetainedFileVerifiesObservedDigest()
+{
+    SigtranCommercialEvidencePromotionHandoff handoff = CreateDefaultCommercialEvidencePromotionHandoff();
+    SigtranCommercialEvidencePromotionHandoffItem item = handoff.Items[0];
+    SigtranCommercialEvidenceRetainedFile file = SigtranCommercialEvidenceRetainedFiles.CreateVerified(item, sizeBytes: 4096, DateTimeOffset.UtcNow);
+    SigtranCommercialEvidenceRetainedFile mismatch = new(
+        item.Kind,
+        item.RetainedPath,
+        item.Sha256,
+        new string('c', 64),
+        sizeBytes: 4096,
+        DateTimeOffset.UtcNow,
+        exists: true);
+
+    Assert(file.IsVerified, file.Describe());
+    Assert(file.HasContent, "retained file should have content");
+    Assert(file.HasValidDigestValues, "retained file should use SHA-256 values");
+    Assert(file.DigestMatches, "retained file digest should match expected digest");
+    Assert(!mismatch.IsVerified, "digest mismatch should block retained file verification");
+}
+
+static SigtranCommercialEvidencePromotionHandoff CreateDefaultCommercialEvidencePromotionHandoff()
+{
+    return SigtranCommercialEvidencePromotionHandoffs.CreateDefault(
+        CreateDefaultCommercialEvidenceDossierIntakeReport(),
+        new string('b', 64),
+        "release-review",
+        DateTimeOffset.UtcNow);
+}
+
 static SigtranCommercialEvidenceDossierIntakeReport CreateDefaultCommercialEvidenceDossierIntakeReport()
 {
     return SigtranCommercialEvidenceDossierIntakeReports.CreateDefault(CreateDefaultCommercialEvidenceArtifactCompletenessResult());

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

@@ -0,0 +1,115 @@
+namespace Sigtran.NET.Core.Utilities;
+
+/// <summary>
+/// Describes one retained commercial evidence file observation.
+/// </summary>
+public sealed class SigtranCommercialEvidenceRetainedFile
+{
+    /// <summary>Creates a retained commercial evidence file observation.</summary>
+    /// <param name="kind">The checklist artifact kind.</param>
+    /// <param name="retainedPath">The retained artifact path.</param>
+    /// <param name="expectedSha256">The expected SHA-256 digest from promotion handoff.</param>
+    /// <param name="actualSha256">The observed SHA-256 digest from the retained file.</param>
+    /// <param name="sizeBytes">The observed file size in bytes.</param>
+    /// <param name="observedAtUtc">The UTC observation time.</param>
+    /// <param name="exists">Whether the retained file exists.</param>
+    public SigtranCommercialEvidenceRetainedFile(
+        SigtranCommercialEvidenceChecklistKind kind,
+        string retainedPath,
+        string expectedSha256,
+        string actualSha256,
+        long sizeBytes,
+        DateTimeOffset observedAtUtc,
+        bool exists)
+    {
+        Kind = kind;
+        RetainedPath = string.IsNullOrWhiteSpace(retainedPath) ? throw new ArgumentException("Retained path is required.", nameof(retainedPath)) : retainedPath;
+        ExpectedSha256 = string.IsNullOrWhiteSpace(expectedSha256) ? throw new ArgumentException("Expected SHA-256 digest is required.", nameof(expectedSha256)) : expectedSha256;
+        ActualSha256 = string.IsNullOrWhiteSpace(actualSha256) ? throw new ArgumentException("Actual SHA-256 digest is required.", nameof(actualSha256)) : actualSha256;
+        SizeBytes = sizeBytes;
+        ObservedAtUtc = observedAtUtc.Offset == TimeSpan.Zero ? observedAtUtc : observedAtUtc.ToUniversalTime();
+        Exists = exists;
+    }
+
+    /// <summary>The checklist artifact kind.</summary>
+    public SigtranCommercialEvidenceChecklistKind Kind { get; }
+
+    /// <summary>The retained artifact path.</summary>
+    public string RetainedPath { get; }
+
+    /// <summary>The expected SHA-256 digest from promotion handoff.</summary>
+    public string ExpectedSha256 { get; }
+
+    /// <summary>The observed SHA-256 digest from the retained file.</summary>
+    public string ActualSha256 { get; }
+
+    /// <summary>The observed file size in bytes.</summary>
+    public long SizeBytes { get; }
+
+    /// <summary>The UTC observation time.</summary>
+    public DateTimeOffset ObservedAtUtc { get; }
+
+    /// <summary>Whether the retained file exists.</summary>
+    public bool Exists { get; }
+
+    /// <summary>Whether the expected and actual digests are valid SHA-256 hex values.</summary>
+    public bool HasValidDigestValues => IsSha256(ExpectedSha256)
+        && IsSha256(ActualSha256);
+
+    /// <summary>Whether the observed digest matches the expected digest.</summary>
+    public bool DigestMatches => string.Equals(ExpectedSha256, ActualSha256, StringComparison.OrdinalIgnoreCase);
+
+    /// <summary>Whether the retained file has a non-empty payload.</summary>
+    public bool HasContent => SizeBytes > 0;
+
+    /// <summary>Whether the observation timestamp is normalized to UTC.</summary>
+    public bool HasUtcObservationTime => ObservedAtUtc.Offset == TimeSpan.Zero;
+
+    /// <summary>Whether the retained file observation is verified.</summary>
+    public bool IsVerified => Exists
+        && HasContent
+        && HasValidDigestValues
+        && DigestMatches
+        && HasUtcObservationTime;
+
+    /// <summary>Formats a compact retained file summary.</summary>
+    /// <returns>The retained file summary.</returns>
+    public string Describe()
+    {
+        return $"commercialEvidenceRetainedFile={RetainedPath} verified={IsVerified} sizeBytes={SizeBytes}";
+    }
+
+    private static bool IsSha256(string value)
+    {
+        return value.Length == 64
+            && value.All(Uri.IsHexDigit);
+    }
+}
+
+/// <summary>
+/// Provides commercial evidence retained file helpers.
+/// </summary>
+public static class SigtranCommercialEvidenceRetainedFiles
+{
+    /// <summary>Creates a verified retained file observation from a promotion handoff item.</summary>
+    /// <param name="item">The promotion handoff item.</param>
+    /// <param name="sizeBytes">The observed file size in bytes.</param>
+    /// <param name="observedAtUtc">The UTC observation time.</param>
+    /// <returns>The retained file observation.</returns>
+    public static SigtranCommercialEvidenceRetainedFile CreateVerified(
+        SigtranCommercialEvidencePromotionHandoffItem item,
+        long sizeBytes,
+        DateTimeOffset observedAtUtc)
+    {
+        ArgumentNullException.ThrowIfNull(item);
+
+        return new(
+            item.Kind,
+            item.RetainedPath,
+            item.Sha256,
+            item.Sha256,
+            sizeBytes,
+            observedAtUtc,
+            exists: true);
+    }
+}