Add commercial evidence filesystem manifest execution

Author: ammarheidari

README.md

@@ -75,7 +75,7 @@ The first production milestone is M3UA over a transport abstraction. SCCP, TCAP,
 | 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 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 in progress: filesystem observation is available, reading retained files from disk, computing real SHA-256 digests, reporting file existence and size, and mapping observations into the retained file verification model; manifest execution, report execution, artifact writing, ledger execution, seal execution, attachment execution, promotion execution, command materialization, status reporting, and final validation remain |
+| Commercial evidence filesystem execution | Phase 40 in progress: filesystem observation and manifest execution are available, reading retained files from disk, computing real SHA-256 digests, reporting file existence and size, supporting retained-path-to-local-path overrides, and building retained file manifests from real observations; report execution, artifact writing, ledger execution, seal execution, attachment execution, promotion execution, command materialization, status reporting, and final validation remain |
 
 ## Requirements
 

docs/PHASE40_COMMERCIAL_EVIDENCE_FILESYSTEM_EXECUTION.md

@@ -16,6 +16,18 @@ Public APIs use domain names such as `SigtranCommercialEvidenceFileSystemObserve
 
 The observer is the first executable bridge from retained dossier paths to real file verification.
 
+## Unit 2 - Filesystem Manifest Execution
+
+`SigtranCommercialEvidenceFileSystemManifestBuilder` observes every promotion handoff item and creates a retained file manifest from real filesystem observations:
+
+- Observes every handoff item.
+- Supports local filesystem path overrides keyed by retained dossier path.
+- Preserves retained path identity while reading from mounted or copied local files.
+- Builds `SigtranCommercialEvidenceRetainedFileManifest` from observed files.
+- Reports whether all handoff items were covered, all files existed, and all digests matched.
+
+This unit lets the verification pipeline evaluate a complete retained handoff using real files rather than synthetic in-memory retained file entries.
+
 ## Validation
 
 Each unit in this phase is validated with:

docs/PHASE40_SUMMARY.md

@@ -5,7 +5,8 @@ Phase 40 prepares the SDK to run commercial evidence file verification against r
 ## Completed Capabilities
 
 - Filesystem observer that computes SHA-256 digests from existing retained files and maps missing files into explicit non-verified retained file observations.
+- Filesystem manifest builder that observes every promotion handoff item, supports retained-path-to-local-path overrides, and builds a retained file manifest from real observations.
 
 ## Readiness Position
 
-The phase is in progress. Filesystem observation is available. Manifest execution, report execution, artifact writing, ledger execution, seal execution, attachment execution, promotion execution, command materialization, status reporting, and final validation remain.
+The phase is in progress. Filesystem observation and manifest execution are available. Report execution, artifact writing, ledger execution, seal execution, attachment execution, promotion execution, command materialization, status reporting, and final validation remain.

docs/PHASE_INDEX.md

@@ -44,7 +44,7 @@ This index is the complete phase map for Sigtran.NET. It links each phase to the
 | 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) | 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) | In progress; filesystem observation complete |
+| 40 | Commercial evidence filesystem execution | [Phase 40 Commercial Evidence Filesystem Execution](PHASE40_COMMERCIAL_EVIDENCE_FILESYSTEM_EXECUTION.md), [Phase 40 Summary](PHASE40_SUMMARY.md) | In progress; filesystem manifest execution complete |
 
 ## Current Commercial Gate
 

docs/SDK_ROADMAP.md

@@ -355,7 +355,7 @@ Status: Phase 39 is foundation-complete. Retained file evidence item verificatio
 - Build verification manifests, reports, retained artifacts, ledger, seal, attachments, promotion gate, and command materialization from observed files.
 - Keep filesystem execution separate from commercial publication: helpers can verify real files, but publication remains blocked until retained evidence comes from an approved commercial run.
 
-Status: Phase 40 is in progress. Filesystem observation now reads retained files from disk, computes real SHA-256 digests, records file existence and size, and maps observations into the retained file verification model. Manifest execution, report execution, retained artifact writing, ledger execution, seal execution, attachment execution, promotion execution, command materialization, status reporting, and final validation remain in progress.
+Status: Phase 40 is in progress. Filesystem observation now reads retained files from disk, computes real SHA-256 digests, records file existence and size, and maps observations into the retained file verification model. Filesystem manifest execution now observes every promotion handoff item, supports retained-path-to-local-path overrides, and builds retained file manifests from real observations. Report execution, retained artifact writing, ledger execution, seal execution, attachment execution, promotion execution, command materialization, status reporting, and final validation remain in progress.
 
 ## Recommended First Deliverable
 

src/Sigtran.NET.Tests/Program.cs

@@ -306,6 +306,7 @@
 Run("SIGTRAN commercial evidence file verification command plan orders execution", SigtranCommercialEvidenceFileVerificationCommandPlanOrdersExecution);
 Run("SIGTRAN commercial evidence file verification status summarizes readiness", SigtranCommercialEvidenceFileVerificationStatusSummarizesReadiness);
 Run("SIGTRAN commercial evidence filesystem observer computes retained file digest", SigtranCommercialEvidenceFileSystemObserverComputesRetainedFileDigest);
+Run("SIGTRAN commercial evidence filesystem manifest builder observes handoff files", SigtranCommercialEvidenceFileSystemManifestBuilderObservesHandoffFiles);
 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);
@@ -5196,10 +5197,92 @@ static void SigtranCommercialEvidenceFileSystemObserverComputesRetainedFileDiges
     }
     finally
     {
-        if (tempRoot.StartsWith(Path.GetTempPath(), StringComparison.OrdinalIgnoreCase) && Directory.Exists(tempRoot))
-        {
-            Directory.Delete(tempRoot, recursive: true);
-        }
+        DeleteTempEvidenceRoot(tempRoot);
+    }
+}
+
+static void SigtranCommercialEvidenceFileSystemManifestBuilderObservesHandoffFiles()
+{
+    string tempRoot = Path.Combine(Path.GetTempPath(), "sigtran-commercial-evidence-" + Guid.NewGuid().ToString("N"));
+    Directory.CreateDirectory(tempRoot);
+
+    try
+    {
+        byte[] artifactContent = "verified commercial artifact"u8.ToArray();
+        byte[] reportContent = "verified commercial readiness report"u8.ToArray();
+        SigtranCommercialEvidencePromotionHandoff handoff = CreateCommercialEvidencePromotionHandoffWithDigests(
+            ComputeSha256Hex(artifactContent),
+            ComputeSha256Hex(reportContent));
+        IReadOnlyDictionary<string, string> pathOverrides = MaterializeHandoffFiles(tempRoot, handoff, artifactContent, reportContent);
+
+        SigtranCommercialEvidenceFileSystemManifestExecution execution = SigtranCommercialEvidenceFileSystemManifestBuilder.Build(
+            handoff,
+            pathOverrides,
+            DateTimeOffset.UtcNow);
+
+        Assert(execution.IsReady, execution.Describe());
+        AssertEqual(handoff.Items.Count, execution.Observations.Count, "filesystem manifest observation count");
+        Assert(execution.CoversHandoffItems, "filesystem manifest should cover handoff items");
+        Assert(execution.AllObservedFilesExist, "filesystem manifest should observe existing files");
+        Assert(execution.AllObservedDigestsMatch, "filesystem manifest should match handoff digests");
+        Assert(execution.Manifest.IsReady, "filesystem retained manifest should be ready");
+    }
+    finally
+    {
+        DeleteTempEvidenceRoot(tempRoot);
+    }
+}
+
+static IReadOnlyDictionary<string, string> MaterializeHandoffFiles(
+    string tempRoot,
+    SigtranCommercialEvidencePromotionHandoff handoff,
+    byte[] artifactContent,
+    byte[] reportContent)
+{
+    Dictionary<string, string> paths = new(StringComparer.OrdinalIgnoreCase);
+
+    for (int i = 0; i < handoff.Items.Count; i++)
+    {
+        SigtranCommercialEvidencePromotionHandoffItem item = handoff.Items[i];
+        string path = Path.Combine(tempRoot, $"retained-{i:D2}.bin");
+        File.WriteAllBytes(path, item.RetainedPath == handoff.Report.ReportPath ? reportContent : artifactContent);
+        paths[item.RetainedPath] = path;
+    }
+
+    return paths;
+}
+
+static SigtranCommercialEvidencePromotionHandoff CreateCommercialEvidencePromotionHandoffWithDigests(
+    string artifactSha256,
+    string reportSha256)
+{
+    SigtranCommercialEvidenceArtifactDigestManifest digests = SigtranCommercialEvidenceArtifactDigests.CreateCovered(
+        CreateDefaultCommercialEvidenceArtifactSourceManifest(),
+        artifactSha256);
+    SigtranCommercialEvidenceRedactionReviewManifest reviews = SigtranCommercialEvidenceRedactionReviews.CreateApproved(
+        digests,
+        "release-review",
+        DateTimeOffset.UtcNow);
+    SigtranCommercialEvidenceArtifactCompletenessResult completeness = SigtranCommercialEvidenceArtifactCompleteness.Evaluate(reviews);
+    SigtranCommercialEvidenceDossierIntakeReport report = SigtranCommercialEvidenceDossierIntakeReports.CreateDefault(completeness);
+
+    return SigtranCommercialEvidencePromotionHandoffs.CreateDefault(
+        report,
+        reportSha256,
+        "release-review",
+        DateTimeOffset.UtcNow);
+}
+
+static string ComputeSha256Hex(byte[] content)
+{
+    return Convert.ToHexString(System.Security.Cryptography.SHA256.HashData(content)).ToLowerInvariant();
+}
+
+static void DeleteTempEvidenceRoot(string tempRoot)
+{
+    if (tempRoot.StartsWith(Path.GetTempPath(), StringComparison.OrdinalIgnoreCase) && Directory.Exists(tempRoot))
+    {
+        Directory.Delete(tempRoot, recursive: true);
     }
 }
 

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

@@ -0,0 +1,96 @@
+namespace Sigtran.NET.Core.Utilities;
+
+/// <summary>
+/// Describes filesystem-backed retained file manifest execution.
+/// </summary>
+public sealed class SigtranCommercialEvidenceFileSystemManifestExecution
+{
+    /// <summary>Creates filesystem-backed retained file manifest execution.</summary>
+    /// <param name="handoff">The promotion handoff that declares retained evidence files.</param>
+    /// <param name="observations">The filesystem observations.</param>
+    /// <param name="manifest">The retained file manifest created from the observations.</param>
+    public SigtranCommercialEvidenceFileSystemManifestExecution(
+        SigtranCommercialEvidencePromotionHandoff handoff,
+        IReadOnlyList<SigtranCommercialEvidenceFileSystemObservation> observations,
+        SigtranCommercialEvidenceRetainedFileManifest manifest)
+    {
+        Handoff = handoff ?? throw new ArgumentNullException(nameof(handoff));
+        ArgumentNullException.ThrowIfNull(observations);
+        Observations = observations.Count == 0 ? throw new ArgumentException("At least one filesystem observation is required.", nameof(observations)) : observations.ToArray();
+        Manifest = manifest ?? throw new ArgumentNullException(nameof(manifest));
+    }
+
+    /// <summary>The promotion handoff that declares retained evidence files.</summary>
+    public SigtranCommercialEvidencePromotionHandoff Handoff { get; }
+
+    /// <summary>The filesystem observations.</summary>
+    public IReadOnlyList<SigtranCommercialEvidenceFileSystemObservation> Observations { get; }
+
+    /// <summary>The retained file manifest created from the observations.</summary>
+    public SigtranCommercialEvidenceRetainedFileManifest Manifest { get; }
+
+    /// <summary>Whether every handoff item was observed from the filesystem.</summary>
+    public bool CoversHandoffItems => Handoff.Items.All(item => Observations.Any(observation =>
+        observation.RetainedFile.Kind == item.Kind
+        && observation.RetainedFile.RetainedPath == item.RetainedPath
+        && string.Equals(observation.RetainedFile.ExpectedSha256, item.Sha256, StringComparison.OrdinalIgnoreCase)));
+
+    /// <summary>Whether all observed files exist on the filesystem.</summary>
+    public bool AllObservedFilesExist => Observations.All(static observation => observation.Exists);
+
+    /// <summary>Whether all observed files match the handoff digests.</summary>
+    public bool AllObservedDigestsMatch => Observations.All(static observation => observation.DigestMatchesHandoff);
+
+    /// <summary>Whether the filesystem-backed manifest execution is ready for verification reporting.</summary>
+    public bool IsReady => CoversHandoffItems
+        && AllObservedFilesExist
+        && AllObservedDigestsMatch
+        && Manifest.IsReady;
+
+    /// <summary>Formats a compact filesystem manifest execution summary.</summary>
+    /// <returns>The filesystem manifest execution summary.</returns>
+    public string Describe()
+    {
+        return $"commercialEvidenceFileSystemManifestReady={IsReady} observations={Observations.Count} intake={Handoff.Report.Target.IntakeId}";
+    }
+}
+
+/// <summary>
+/// Builds retained commercial evidence file manifests from filesystem observations.
+/// </summary>
+public static class SigtranCommercialEvidenceFileSystemManifestBuilder
+{
+    /// <summary>Builds a retained file manifest by observing every promotion handoff item.</summary>
+    /// <param name="handoff">The promotion handoff that declares retained evidence files.</param>
+    /// <param name="pathOverrides">Optional local filesystem path overrides keyed by retained path.</param>
+    /// <param name="observedAtUtc">An optional UTC observation time.</param>
+    /// <returns>The filesystem-backed retained file manifest execution.</returns>
+    public static SigtranCommercialEvidenceFileSystemManifestExecution Build(
+        SigtranCommercialEvidencePromotionHandoff handoff,
+        IReadOnlyDictionary<string, string>? pathOverrides = null,
+        DateTimeOffset? observedAtUtc = null)
+    {
+        ArgumentNullException.ThrowIfNull(handoff);
+
+        SigtranCommercialEvidenceFileSystemObservation[] observations = handoff.Items
+            .Select(item => SigtranCommercialEvidenceFileSystemObserver.Observe(
+                item,
+                ResolvePath(item, pathOverrides),
+                observedAtUtc))
+            .ToArray();
+        SigtranCommercialEvidenceRetainedFileManifest manifest = new(
+            handoff,
+            observations.Select(static observation => observation.RetainedFile).ToArray());
+
+        return new(handoff, observations, manifest);
+    }
+
+    private static string? ResolvePath(
+        SigtranCommercialEvidencePromotionHandoffItem item,
+        IReadOnlyDictionary<string, string>? pathOverrides)
+    {
+        return pathOverrides is not null && pathOverrides.TryGetValue(item.RetainedPath, out string? path)
+            ? path
+            : null;
+    }
+}