Add commercial evidence approval audit trail

Author: ammarheidari

README.md

@@ -76,7 +76,7 @@ The first production milestone is M3UA over a transport abstraction. SCCP, TCAP,
 | 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 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 in progress: approved run target identity, approval checklist, reviewer approval manifest, approval report writing, promotion package, publication handoff, and handoff gate are available, 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, and handoff blocker reporting; audit trail, command materialization, status reporting, and final validation remain |
+| Approved commercial run publication handoff | Phase 41 in progress: approved run target identity, approval checklist, reviewer approval manifest, approval report writing, promotion package, publication handoff, handoff gate, and approval audit trail are available, 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, and digest-covered audit lifecycle events; command materialization, status reporting, and final validation remain |
 
 ## Requirements
 

docs/PHASE41_APPROVED_COMMERCIAL_RUN_PUBLICATION_HANDOFF.md

@@ -93,6 +93,20 @@ This unit keeps RC and stable publication boundaries explicit before a final pub
 
 This unit gives release operators actionable blockers before package publication workflows are allowed to proceed.
 
+## Unit 8 - Approval Audit Trail
+
+`SigtranCommercialEvidenceApprovalAuditTrail` records digest-covered lifecycle events:
+
+- Run target.
+- Approval checklist.
+- Reviewer approval manifest.
+- Approval report.
+- Promotion package.
+- Publication handoff.
+- Handoff gate.
+
+This unit gives the approval path a retained audit chain that can be reviewed before package publication proceeds.
+
 ## Validation
 
 Each unit in this phase is validated with:

docs/PHASE41_SUMMARY.md

@@ -11,7 +11,8 @@ Phase 41 prepares the SDK to move from filesystem-backed evidence verification i
 - Approved run promotion package that collects approval report, integrity seal, publication attachments, and promotion gate artifact references with required digest coverage.
 - Publication handoff that connects an approved promotion package to channel policy, requester identity, UTC handoff time, and explicit publish intent.
 - Publication handoff gate that reports blockers for package readiness, publish intent, UTC timing, channel/version policy, and stable commercial readiness approval.
+- Approval audit trail that records digest-covered run target, checklist, manifest, report, package, handoff, and gate lifecycle events.
 
 ## Readiness Position
 
-The phase is in progress. Approved run target identity, approval checklist, reviewer approval manifest, approval report writing, promotion package, publication handoff, and handoff gate are available. Audit trail, command materialization, status reporting, documentation, and final validation remain.
+The phase is in progress. Approved run target identity, approval checklist, reviewer approval manifest, approval report writing, promotion package, publication handoff, handoff gate, and approval audit trail are available. Command materialization, status reporting, documentation, and final validation remain.

docs/PHASE_INDEX.md

@@ -45,7 +45,7 @@ This index is the complete phase map for Sigtran.NET. It links each phase to the
 | 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) | 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) | In progress; publication handoff gate complete |
+| 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) | In progress; approval audit trail complete |
 
 ## Current Commercial Gate
 

docs/SDK_ROADMAP.md

@@ -363,7 +363,7 @@ Status: Phase 40 is foundation-complete. Filesystem observation reads retained f
 - Record approval checklist, reviewer approvals, retained reports, promotion package, publication handoff, blocker gates, and audit trail.
 - Keep approval handoff separate from commercial publication: the SDK can prepare approval records, but publication remains blocked until a real approved run is retained.
 
-Status: Phase 41 is in progress. Approved run target identity now binds package version, source commit, operator identity, UTC run timing, retained artifact root, and filesystem-backed promotion execution. Approval checklist now requires verified filesystem promotion, ready report/ledger/seal/attachments, approved trace redaction, promotion approval, and reviewer approval records. Reviewer approval manifest now records release, security, and operations approvals with UTC timestamps and a deterministic checklist SHA-256 digest. Approval report writing now renders retained Markdown reports with run identity, checklist digest, reviewer roles, UTC write time, and report SHA-256 digest coverage. Approved run promotion package now collects approval report, integrity seal, publication attachment, and promotion gate artifact references with required digest coverage. Publication handoff now binds the approved package to requested channel, requester identity, UTC handoff time, explicit publish intent, and channel version policy. Publication handoff gate now reports blockers for package readiness, publish intent, UTC timing, channel/version policy, and stable commercial readiness approval. Audit trail, command materialization, status reporting, and final validation remain in progress.
+Status: Phase 41 is in progress. Approved run target identity now binds package version, source commit, operator identity, UTC run timing, retained artifact root, and filesystem-backed promotion execution. Approval checklist now requires verified filesystem promotion, ready report/ledger/seal/attachments, approved trace redaction, promotion approval, and reviewer approval records. Reviewer approval manifest now records release, security, and operations approvals with UTC timestamps and a deterministic checklist SHA-256 digest. Approval report writing now renders retained Markdown reports with run identity, checklist digest, reviewer roles, UTC write time, and report SHA-256 digest coverage. Approved run promotion package now collects approval report, integrity seal, publication attachment, and promotion gate artifact references with required digest coverage. Publication handoff now binds the approved package to requested channel, requester identity, UTC handoff time, explicit publish intent, and channel version policy. Publication handoff gate now reports blockers for package readiness, publish intent, UTC timing, channel/version policy, and stable commercial readiness approval. Approval audit trail now records digest-covered lifecycle events for run target, checklist, manifest, report, package, handoff, and gate. Command materialization, status reporting, and final validation remain in progress.
 
 ## Recommended First Deliverable
 

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 commercial evidence approval audit trail covers lifecycle", SigtranCommercialEvidenceApprovalAuditTrailCoversLifecycle);
 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);
@@ -5710,6 +5711,47 @@ static void SigtranCommercialEvidencePublicationHandoffGateReportsBlockers()
     }
 }
 
+static void SigtranCommercialEvidenceApprovalAuditTrailCoversLifecycle()
+{
+    string tempRoot = Path.Combine(Path.GetTempPath(), "sigtran-commercial-evidence-" + Guid.NewGuid().ToString("N"));
+    Directory.CreateDirectory(tempRoot);
+
+    try
+    {
+        SigtranCommercialEvidencePublicationHandoffGateResult gate = CreateReadyCommercialEvidencePublicationHandoffGateResult(tempRoot);
+
+        SigtranCommercialEvidenceApprovalAuditTrail trail = SigtranCommercialEvidenceApprovalAuditTrails.CreateDefault(
+            gate,
+            DateTimeOffset.UtcNow);
+        SigtranCommercialEvidenceApprovalAuditEvent firstEvent = trail.Events[0];
+        SigtranCommercialEvidenceApprovalAuditTrail blocked = new(
+            gate,
+            [new(firstEvent.Id, firstEvent.Kind, firstEvent.Actor, firstEvent.OccurredAtUtc, "not-a-digest", firstEvent.Description), .. trail.Events.Skip(1)]);
+
+        Assert(trail.IsReady, trail.Describe());
+        Assert(trail.UsesUniqueEventIds, "approval audit trail should use unique event ids");
+        Assert(trail.AllEventsReady, "approval audit trail events should be ready");
+        Assert(trail.CoversApprovalLifecycle, "approval audit trail should cover approval lifecycle");
+        Assert(!blocked.IsReady, "invalid audit event digest should block audit trail readiness");
+        Assert(!blocked.AllEventsReady, "blocked audit trail should expose event readiness failure");
+    }
+    finally
+    {
+        DeleteTempEvidenceRoot(tempRoot);
+    }
+}
+
+static SigtranCommercialEvidencePublicationHandoffGateResult CreateReadyCommercialEvidencePublicationHandoffGateResult(string tempRoot)
+{
+    return SigtranCommercialEvidencePublicationHandoffGates.Evaluate(
+        SigtranCommercialEvidencePublicationHandoffs.Create(
+            CreateReadyCommercialEvidenceApprovedRunPromotionPackage(tempRoot),
+            SigtranPublishChannelKind.Beta,
+            "release-manager",
+            DateTimeOffset.UtcNow),
+        commercialReadinessApproved: false);
+}
+
 static SigtranCommercialEvidenceApprovedRunPromotionPackage CreateReadyCommercialEvidenceApprovedRunPromotionPackage(string tempRoot)
 {
     return SigtranCommercialEvidenceApprovedRunPromotionPackages.CreateDefault(