Add commercial evidence file verification report

Author: ammarheidari

README.md

@@ -74,7 +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 and retained file manifest coverage are available, checking file existence, non-empty size, SHA-256 validity, digest match, UTC observation time, unique retained paths, and coverage of promotion-required handoff items; verification reporting, retention ledger, integrity seal, publication attachments, promotion gate, command plan, status reporting, and final validation remain |
+| Commercial evidence file verification | Phase 39 in progress: retained file evidence item verification, retained file manifest coverage, and file verification blocker reporting are available, checking file existence, non-empty size, SHA-256 validity, digest match, UTC observation time, unique retained paths, promotion-required handoff coverage, and explicit verification blockers; retention ledger, integrity seal, publication attachments, promotion gate, command plan, status reporting, and final validation remain |
 
 ## Requirements
 

docs/PHASE39_COMMERCIAL_EVIDENCE_FILE_VERIFICATION.md

@@ -29,6 +29,20 @@ A retained file is verified only when the file exists, is non-empty, carries val
 
 The manifest is the first aggregate proof that retained file observations match the digest-covered handoff from artifact intake.
 
+## Unit 3 - File Verification Report
+
+`SigtranCommercialEvidenceFileVerificationReport` evaluates the retained file manifest and produces explicit blocker reasons:
+
+- Missing retained files.
+- Empty retained files.
+- Invalid SHA-256 values.
+- Digest mismatches.
+- Non-UTC observation times.
+- Duplicate retained paths.
+- Incomplete promotion handoff coverage.
+
+The report keeps verification gates auditable. A commercial release decision can now distinguish "not verified" from the specific retained file condition that blocked promotion.
+
 ## Validation
 
 Each unit in this phase is validated with:

docs/PHASE39_SUMMARY.md

@@ -6,7 +6,8 @@ Phase 39 prepares the SDK to verify retained commercial evidence files after art
 
 - Retained file evidence item that verifies existence, size, SHA-256 validity, digest match, and UTC observation time.
 - Retained file manifest that covers every promotion-required handoff item with verified unique retained files.
+- File verification report that exposes missing, empty, invalid digest, digest mismatch, non-UTC observation, duplicate path, and incomplete handoff blockers.
 
 ## Readiness Position
 
-The phase is in progress. Retained file evidence item verification and retained file manifest coverage are available. Verification reporting, retention ledger, integrity seal, publication attachments, promotion gate, command plan, status reporting, and final validation remain.
+The phase is in progress. Retained file evidence item verification, retained file manifest coverage, and blocker reporting are available. Retention ledger, integrity seal, publication attachments, promotion gate, command plan, status reporting, and final validation remain.

docs/PHASE_INDEX.md

@@ -43,7 +43,7 @@ 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 manifest complete |
+| 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; verification report complete |
 
 ## Current Commercial Gate
 

docs/SDK_ROADMAP.md

@@ -347,7 +347,7 @@ Status: Phase 38 is foundation-complete. Artifact intake target identity binds a
 - 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. Retained file manifest coverage now verifies that every promotion-required handoff item has a unique verified retained file. Verification reporting, retention ledger, integrity seal, publication attachments, promotion gate, command plan, status reporting, and final validation remain in progress.
+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. Retained file manifest coverage now verifies that every promotion-required handoff item has a unique verified retained file. File verification reporting now exposes missing, empty, invalid digest, digest mismatch, non-UTC observation, duplicate path, and incomplete handoff blockers. Retention ledger, integrity seal, publication attachments, promotion gate, command plan, status reporting, and final validation remain in progress.
 
 ## Recommended First Deliverable
 

src/Sigtran.NET.Tests/Program.cs

@@ -298,6 +298,7 @@
 Run("SIGTRAN commercial evidence artifact intake status summarizes foundation readiness", SigtranCommercialEvidenceArtifactIntakeStatusSummarizesFoundationReadiness);
 Run("SIGTRAN commercial evidence retained file verifies observed digest", SigtranCommercialEvidenceRetainedFileVerifiesObservedDigest);
 Run("SIGTRAN commercial evidence retained file manifest covers handoff items", SigtranCommercialEvidenceRetainedFileManifestCoversHandoffItems);
+Run("SIGTRAN commercial evidence file verification report identifies blockers", SigtranCommercialEvidenceFileVerificationReportIdentifiesBlockers);
 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);
@@ -5014,6 +5015,31 @@ static void SigtranCommercialEvidenceRetainedFileManifestCoversHandoffItems()
     Assert(!incomplete.IsReady, "missing retained files should block manifest readiness");
 }
 
+static void SigtranCommercialEvidenceFileVerificationReportIdentifiesBlockers()
+{
+    SigtranCommercialEvidenceRetainedFileManifest verifiedManifest = CreateDefaultCommercialEvidenceRetainedFileManifest();
+    SigtranCommercialEvidencePromotionHandoff handoff = verifiedManifest.Handoff;
+    SigtranCommercialEvidenceFileVerificationReport verifiedReport = SigtranCommercialEvidenceFileVerificationReports.Evaluate(verifiedManifest);
+
+    SigtranCommercialEvidenceRetainedFile[] mismatchFiles = verifiedManifest.Files.ToArray();
+    SigtranCommercialEvidencePromotionHandoffItem firstItem = handoff.Items[0];
+    mismatchFiles[0] = new(
+        firstItem.Kind,
+        firstItem.RetainedPath,
+        firstItem.Sha256,
+        new string('c', 64),
+        sizeBytes: 4096,
+        DateTimeOffset.UtcNow,
+        exists: true);
+    SigtranCommercialEvidenceFileVerificationReport mismatchReport = SigtranCommercialEvidenceFileVerificationReports.Evaluate(new(handoff, mismatchFiles));
+
+    Assert(verifiedReport.IsVerified, verifiedReport.Describe());
+    AssertEqual(0, verifiedReport.Blockers.Count, "verified retained file report blocker count");
+    Assert(!mismatchReport.IsVerified, "digest mismatch should block retained file report verification");
+    AssertEqual(1, mismatchReport.DigestMismatchCount, "retained file digest mismatch count");
+    Assert(mismatchReport.Blockers.Contains("retained-file-digest-mismatch"), "retained file report should expose digest mismatch blocker");
+}
+
 static SigtranCommercialEvidenceRetainedFileManifest CreateDefaultCommercialEvidenceRetainedFileManifest()
 {
     return SigtranCommercialEvidenceRetainedFiles.CreateVerifiedManifest(

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

@@ -136,6 +136,114 @@ public string Describe()
     }
 }
 
+/// <summary>
+/// Describes the retained commercial evidence file verification report.
+/// </summary>
+public sealed class SigtranCommercialEvidenceFileVerificationReport
+{
+    /// <summary>Creates a retained commercial evidence file verification report.</summary>
+    /// <param name="manifest">The retained file manifest under verification.</param>
+    /// <param name="blockers">The verification blockers discovered from the manifest.</param>
+    public SigtranCommercialEvidenceFileVerificationReport(
+        SigtranCommercialEvidenceRetainedFileManifest manifest,
+        IReadOnlyList<string> blockers)
+    {
+        Manifest = manifest ?? throw new ArgumentNullException(nameof(manifest));
+        ArgumentNullException.ThrowIfNull(blockers);
+        Blockers = blockers.ToArray();
+    }
+
+    /// <summary>The retained file manifest under verification.</summary>
+    public SigtranCommercialEvidenceRetainedFileManifest Manifest { get; }
+
+    /// <summary>The verification blockers discovered from the manifest.</summary>
+    public IReadOnlyList<string> Blockers { get; }
+
+    /// <summary>The number of observed files that do not exist.</summary>
+    public int MissingFileCount => Manifest.Files.Count(static file => !file.Exists);
+
+    /// <summary>The number of observed files that exist but are empty.</summary>
+    public int EmptyFileCount => Manifest.Files.Count(static file => file.Exists && !file.HasContent);
+
+    /// <summary>The number of observed files with invalid SHA-256 values.</summary>
+    public int InvalidDigestCount => Manifest.Files.Count(static file => !file.HasValidDigestValues);
+
+    /// <summary>The number of observed files whose valid digest does not match the expected digest.</summary>
+    public int DigestMismatchCount => Manifest.Files.Count(static file => file.HasValidDigestValues && !file.DigestMatches);
+
+    /// <summary>The number of observed files whose observation time is not normalized to UTC.</summary>
+    public int NonUtcObservationCount => Manifest.Files.Count(static file => !file.HasUtcObservationTime);
+
+    /// <summary>Whether the retained file verification report is complete and unblocked.</summary>
+    public bool IsVerified => Manifest.IsReady
+        && Blockers.Count == 0;
+
+    /// <summary>Formats a compact retained file verification summary.</summary>
+    /// <returns>The retained file verification summary.</returns>
+    public string Describe()
+    {
+        return $"commercialEvidenceFilesVerified={IsVerified} blockers={Blockers.Count} files={Manifest.Files.Count}";
+    }
+}
+
+/// <summary>
+/// Provides commercial evidence file verification report helpers.
+/// </summary>
+public static class SigtranCommercialEvidenceFileVerificationReports
+{
+    /// <summary>Evaluates a retained file manifest and returns a verification report.</summary>
+    /// <param name="manifest">The retained file manifest to evaluate.</param>
+    /// <returns>The retained file verification report.</returns>
+    public static SigtranCommercialEvidenceFileVerificationReport Evaluate(SigtranCommercialEvidenceRetainedFileManifest manifest)
+    {
+        ArgumentNullException.ThrowIfNull(manifest);
+
+        List<string> blockers = [];
+
+        if (!manifest.Handoff.IsReady)
+        {
+            blockers.Add("promotion-handoff-not-ready");
+        }
+
+        if (!manifest.CoversRequiredHandoffItems)
+        {
+            blockers.Add("retained-file-manifest-incomplete");
+        }
+
+        if (!manifest.UsesUniqueRetainedPaths)
+        {
+            blockers.Add("retained-file-path-duplicate");
+        }
+
+        if (manifest.Files.Any(static file => !file.Exists))
+        {
+            blockers.Add("retained-file-missing");
+        }
+
+        if (manifest.Files.Any(static file => file.Exists && !file.HasContent))
+        {
+            blockers.Add("retained-file-empty");
+        }
+
+        if (manifest.Files.Any(static file => !file.HasValidDigestValues))
+        {
+            blockers.Add("retained-file-digest-invalid");
+        }
+
+        if (manifest.Files.Any(static file => file.HasValidDigestValues && !file.DigestMatches))
+        {
+            blockers.Add("retained-file-digest-mismatch");
+        }
+
+        if (manifest.Files.Any(static file => !file.HasUtcObservationTime))
+        {
+            blockers.Add("retained-file-observation-not-utc");
+        }
+
+        return new(manifest, blockers);
+    }
+}
+
 /// <summary>
 /// Provides commercial evidence retained file helpers.
 /// </summary>