Add commercial evidence filesystem integrity seal 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, manifest execution, verification report execution, artifact writing, and ledger 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, building retained file manifests from real observations, exposing blocker-aware retained file reports from filesystem evidence, writing retained Markdown/TSV verification artifacts, and creating retention ledgers from filesystem-backed reports; seal execution, attachment execution, promotion execution, command materialization, status reporting, and final validation remain |
+| Commercial evidence filesystem execution | Phase 40 in progress: filesystem observation, manifest execution, verification report execution, artifact writing, ledger execution, and seal 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, 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, and sealing those ledgers with deterministic aggregate SHA-256 digests; attachment execution, promotion execution, command materialization, status reporting, and final validation remain |
 
 ## Requirements
 

docs/PHASE40_COMMERCIAL_EVIDENCE_FILESYSTEM_EXECUTION.md

@@ -62,6 +62,17 @@ This unit gives release operators retained files they can attach to the commerci
 
 This unit connects real file verification output to the commercial evidence retention ledger.
 
+## Unit 6 - Integrity Seal Execution
+
+`SigtranCommercialEvidenceFileSystemIntegritySeals` creates an integrity seal from the filesystem-backed retention ledger:
+
+- Requires ready retention ledger execution.
+- Computes the deterministic aggregate SHA-256 ledger digest.
+- Verifies that the retained seal matches the current ledger.
+- Carries the seal id forward for attachment and promotion execution.
+
+This unit gives filesystem-backed evidence the same integrity seal contract used by the retained commercial evidence dossier.
+
 ## Validation
 
 Each unit in this phase is validated with:

docs/PHASE40_SUMMARY.md

@@ -9,7 +9,8 @@ Phase 40 prepares the SDK to run commercial evidence file verification against r
 - Filesystem verification report execution that evaluates real observations and exposes retained file blockers such as missing files.
 - Verification artifact writer that retains a Markdown verification report and tab-separated observation manifest on disk.
 - Retention ledger execution that creates ledger entries from filesystem-backed verification reports and written artifacts.
+- Integrity seal execution that signs the filesystem-backed ledger with a deterministic aggregate SHA-256 seal.
 
 ## Readiness Position
 
-The phase is in progress. Filesystem observation, manifest execution, report execution, artifact writing, and ledger execution are available. Seal execution, attachment execution, promotion execution, command materialization, status reporting, and final validation remain.
+The phase is in progress. Filesystem observation, manifest execution, report execution, artifact writing, ledger execution, and seal execution are available. 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 ledger execution 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 seal 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. Filesystem manifest execution now observes every promotion handoff item, supports retained-path-to-local-path overrides, and builds retained file manifests from real observations. Filesystem verification report execution now evaluates those manifests and exposes retained file blockers from real files. Verification artifact writing now retains a Markdown report and tab-separated observation manifest on disk. Retention ledger execution now creates ledger entries from filesystem-backed verification reports and written artifacts. 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. Filesystem verification report execution now evaluates those manifests and exposes retained file blockers from real files. Verification artifact writing now retains a Markdown report and tab-separated observation manifest on disk. Retention ledger execution now creates ledger entries from filesystem-backed verification reports and written artifacts. Integrity seal execution now seals filesystem-backed ledgers with deterministic aggregate SHA-256 digests. Attachment execution, promotion execution, command materialization, status reporting, and final validation remain in progress.
 
 ## Recommended First Deliverable
 

src/Sigtran.NET.Tests/Program.cs

@@ -310,6 +310,7 @@
 Run("SIGTRAN commercial evidence filesystem verification report identifies missing files", SigtranCommercialEvidenceFileSystemVerificationReportIdentifiesMissingFiles);
 Run("SIGTRAN commercial evidence filesystem artifact writer retains reports", SigtranCommercialEvidenceFileSystemArtifactWriterRetainsReports);
 Run("SIGTRAN commercial evidence filesystem retention ledger covers verified files", SigtranCommercialEvidenceFileSystemRetentionLedgerCoversVerifiedFiles);
+Run("SIGTRAN commercial evidence filesystem integrity seal matches ledger", SigtranCommercialEvidenceFileSystemIntegritySealMatchesLedger);
 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);
@@ -5328,6 +5329,38 @@ static void SigtranCommercialEvidenceFileSystemRetentionLedgerCoversVerifiedFile
     }
 }
 
+static void SigtranCommercialEvidenceFileSystemIntegritySealMatchesLedger()
+{
+    string tempRoot = Path.Combine(Path.GetTempPath(), "sigtran-commercial-evidence-" + Guid.NewGuid().ToString("N"));
+    Directory.CreateDirectory(tempRoot);
+
+    try
+    {
+        SigtranCommercialEvidenceFileSystemRetentionLedgerExecution ledgerExecution = CreateReadyCommercialEvidenceFileSystemRetentionLedgerExecution(tempRoot);
+
+        SigtranCommercialEvidenceFileSystemIntegritySealExecution sealExecution = SigtranCommercialEvidenceFileSystemIntegritySeals.Create(
+            ledgerExecution,
+            DateTimeOffset.UtcNow);
+
+        Assert(sealExecution.IsReady, sealExecution.Describe());
+        Assert(sealExecution.LedgerReady, "filesystem integrity seal should require ready ledger execution");
+        Assert(sealExecution.SealMatchesLedger, "filesystem integrity seal should match ledger digest");
+        Assert(sealExecution.Seal.HasValidAggregateDigest, "filesystem integrity seal should keep aggregate digest");
+    }
+    finally
+    {
+        DeleteTempEvidenceRoot(tempRoot);
+    }
+}
+
+static SigtranCommercialEvidenceFileSystemRetentionLedgerExecution CreateReadyCommercialEvidenceFileSystemRetentionLedgerExecution(string tempRoot)
+{
+    return SigtranCommercialEvidenceFileSystemRetentionLedgers.Create(
+        CreateReadyCommercialEvidenceFileSystemArtifactWriteResult(tempRoot),
+        "release-review",
+        DateTimeOffset.UtcNow);
+}
+
 static SigtranCommercialEvidenceFileSystemArtifactWriteResult CreateReadyCommercialEvidenceFileSystemArtifactWriteResult(string tempRoot)
 {
     SigtranCommercialEvidenceFileSystemVerificationExecution execution = CreateReadyCommercialEvidenceFileSystemVerificationExecution(tempRoot);

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

@@ -0,0 +1,64 @@
+namespace Sigtran.NET.Core.Utilities;
+
+/// <summary>
+/// Describes filesystem-backed commercial evidence integrity seal execution.
+/// </summary>
+public sealed class SigtranCommercialEvidenceFileSystemIntegritySealExecution
+{
+    /// <summary>Creates filesystem-backed integrity seal execution.</summary>
+    /// <param name="ledgerExecution">The filesystem-backed retention ledger execution.</param>
+    /// <param name="seal">The integrity seal created from the ledger.</param>
+    public SigtranCommercialEvidenceFileSystemIntegritySealExecution(
+        SigtranCommercialEvidenceFileSystemRetentionLedgerExecution ledgerExecution,
+        SigtranCommercialEvidenceIntegritySeal seal)
+    {
+        LedgerExecution = ledgerExecution ?? throw new ArgumentNullException(nameof(ledgerExecution));
+        Seal = seal ?? throw new ArgumentNullException(nameof(seal));
+    }
+
+    /// <summary>The filesystem-backed retention ledger execution.</summary>
+    public SigtranCommercialEvidenceFileSystemRetentionLedgerExecution LedgerExecution { get; }
+
+    /// <summary>The integrity seal created from the ledger.</summary>
+    public SigtranCommercialEvidenceIntegritySeal Seal { get; }
+
+    /// <summary>Whether the source ledger execution is ready.</summary>
+    public bool LedgerReady => LedgerExecution.IsReady;
+
+    /// <summary>Whether the seal digest matches the current ledger.</summary>
+    public bool SealMatchesLedger => Seal.MatchesLedgerDigest;
+
+    /// <summary>Whether filesystem-backed integrity seal execution is ready for publication attachment execution.</summary>
+    public bool IsReady => LedgerReady
+        && Seal.IsReady
+        && SealMatchesLedger;
+
+    /// <summary>Formats a compact filesystem integrity seal execution summary.</summary>
+    /// <returns>The filesystem integrity seal execution summary.</returns>
+    public string Describe()
+    {
+        return $"commercialEvidenceFileSystemIntegritySealReady={IsReady} sealId={Seal.SealId}";
+    }
+}
+
+/// <summary>
+/// Provides filesystem-backed commercial evidence integrity seal execution helpers.
+/// </summary>
+public static class SigtranCommercialEvidenceFileSystemIntegritySeals
+{
+    /// <summary>Creates an integrity seal from a filesystem-backed retention ledger execution.</summary>
+    /// <param name="ledgerExecution">The filesystem-backed retention ledger execution.</param>
+    /// <param name="sealedAtUtc">The UTC seal creation time.</param>
+    /// <returns>The filesystem-backed integrity seal execution.</returns>
+    public static SigtranCommercialEvidenceFileSystemIntegritySealExecution Create(
+        SigtranCommercialEvidenceFileSystemRetentionLedgerExecution ledgerExecution,
+        DateTimeOffset sealedAtUtc)
+    {
+        ArgumentNullException.ThrowIfNull(ledgerExecution);
+        SigtranCommercialEvidenceIntegritySeal seal = SigtranCommercialEvidenceIntegritySeals.CreateDefault(
+            ledgerExecution.Ledger,
+            sealedAtUtc);
+
+        return new(ledgerExecution, seal);
+    }
+}