Add native SCTP production transport evidence

Author: ammarheidari

README.md

@@ -41,6 +41,7 @@ The current alpha track focuses on:
 - M3UA framing, parsing, routing, diagnostics, and ASP state handling.
 - Transport abstraction for SIGTRAN workloads.
 - Official layer contracts from SCTP through MAP SMS for dependency-injected applications.
+- Linux native SCTP production transport hardening with retained stream/PPID metadata validation evidence.
 - SCTP direction, including Linux native SCTP validation.
 - SCCP, TCAP, and MAP foundations for future standards-oriented layers.
 - Byte-level tests and protocol validation.
@@ -55,7 +56,7 @@ The current alpha track focuses on:
 | Area | Current Direction |
 | --- | --- |
 | M3UA | First production-oriented milestone; framing, parsing, routing, ASP state, diagnostics, and management flows are the main focus. |
-| SCTP | Transport abstraction is in place; Linux native SCTP validation is part of the production-readiness path. |
+| SCTP | Transport abstraction is in place; native Linux SCTP loopback evidence validates stream id, PPID, receive metadata, reconnect, metrics, and graceful shutdown. |
 | SCCP | Foundation work exists and is moving toward standards-oriented validation. |
 | TCAP | Foundation work exists and requires retained interoperability and MAP profile validation. |
 | MAP | SMS-oriented MAP foundations are part of the roadmap and require external validation before production claims. |
@@ -137,6 +138,7 @@ Start here:
 - [Layer contracts](docs/LAYER_CONTRACTS.md)
 - [M3UA implementation notes](docs/M3UA.md)
 - [SCTP transport](docs/SCTP_TRANSPORT.md)
+- [Phase 45 native SCTP production transport](docs/PHASE45_NATIVE_SCTP_PRODUCTION_TRANSPORT.md)
 - [SCCP](docs/SCCP.md)
 - [TCAP](docs/TCAP.md)
 - [MAP SMS profile](docs/MAP.md)

docs/PHASE45_NATIVE_SCTP_PRODUCTION_TRANSPORT.md

@@ -0,0 +1,83 @@
+# Phase 45 - Native SCTP Production Transport
+
+Phase 45 hardens the Linux native SCTP transport path so SDK traffic can carry real stream id and PPID metadata through the kernel SCTP stack and retain evidence from a repeatable Linux sample.
+
+## Goals
+
+- Use Linux SCTP metadata APIs for send and receive.
+- Preserve stream id, PPID, and unordered metadata in `ISctpTransport`.
+- Apply reconnect policy during native SCTP connect.
+- Enforce send backpressure before kernel send.
+- Track cancellation, operation timeout, lifecycle, recovery, queue metrics, and graceful shutdown.
+- Provide a repeatable Linux sample that captures PCAP, SDK trace, logs, reconnect attempts, metadata validation, comparison output, report, and digests.
+
+## Completed Units
+
+| Unit | Capability | Status |
+| --- | --- | --- |
+| 1 | lksctp-backed metadata send and receive | Complete |
+| 2 | `NativeSctpTransportOptions` for metadata, timeout, reconnect, and backpressure policy | Complete |
+| 3 | send queue and receive operation metrics | Complete |
+| 4 | native adapter timeout, cancellation, fault recovery, and diagnostics snapshots | Complete |
+| 5 | graceful shutdown lifecycle events | Complete |
+| 6 | connector retry trace for reconnect validation | Complete |
+| 7 | lab runner metadata validation for stream id and PPID | Complete |
+| 8 | Linux evidence script with PCAP, logs, trace, comparison, report, and digests | Complete |
+| 9 | unit tests for production options and reconnect attempt records | Complete |
+| 10 | README, SCTP docs, roadmap, and phase index alignment | Complete |
+
+## Production Transport Behavior
+
+`NativeSctpSocketAdapter` now sends `SctpOutboundMessage` values through lksctp `sctp_sendmsg`, preserving:
+
+- stream id
+- PPID
+- unordered flag
+
+Receive uses lksctp `sctp_recvmsg`, so `ISctpTransport.ReceiveAsync` returns `SctpReceiveResult` with kernel-provided metadata instead of a synthetic default.
+
+The adapter also exposes:
+
+- `GetQueueMetrics()`
+- `GetDiagnosticsSnapshot()`
+- `ShutdownAsync(...)`
+- latest backpressure and recovery decisions
+- association lifecycle entries
+
+## Linux Sample
+
+Run this from the repository root on a Linux host with kernel SCTP, `libsctp.so.1`, `tcpdump`, `tshark`, and .NET installed:
+
+```bash
+SIGTRAN_ARTIFACT_ROOT="$HOME/sigtran-lab/artifacts/phase45" \
+SIGTRAN_STREAM_ID=1 \
+SIGTRAN_PPID=3 \
+bash scripts/run-phase45-native-sctp-lab.sh
+```
+
+The script publishes the lab binary, starts `tcpdump`, runs a loopback M3UA exchange over real SCTP, intentionally starts the client before the server to validate reconnect, validates stream/PPID metadata from `sctp_recvmsg`, performs graceful shutdown, generates a TShark decode, writes a Markdown report, and computes SHA-256 digests.
+
+## Completion Criteria
+
+Phase 45 is complete when the code path builds, tests, packs, and the Linux sample produces:
+
+- PCAP under `pcap/`
+- SDK JSONL trace under `trace/`
+- lab and capture logs under `logs/`
+- TShark comparison output under `comparison/`
+- readiness report under `reports/`
+- digest manifest under `digests/`
+
+The report must show metadata validation, stream validation, PPID validation, at least one failed reconnect attempt, one successful reconnect attempt, metrics snapshots, and client/server graceful shutdown events.
+
+## Passing Evidence
+
+Run `phase45-native-sctp-20260701T103951Z` passed on the Linux VM `sigtrannet` with kernel `5.15.0-181-generic`.
+
+- Evidence report: `docs/evidence/PHASE45_NATIVE_SCTP_20260701T103951Z.md`
+- Evidence manifest: `docs/evidence/PHASE45_NATIVE_SCTP_20260701T103951Z.json`
+- Retained artifact root: `/home/ammar/sigtran-phase45-run/artifacts/phase45-native-sctp-20260701T103951Z`
+- PCAP SHA-256: `33c7708b66fba17b7f5e72ed30e06be3e1f8e01d27e60c25d8c7165fe5663f35`
+- SDK trace SHA-256: `abaa2a9153b10db6abd73050c85d26c820d16d892594e781e4ade9559e863c90`
+
+This evidence closes the native Linux SCTP loopback gate for Phase 45. Independent external peer interoperability remains a separate production gate.

docs/PHASE45_SUMMARY.md

@@ -0,0 +1,21 @@
+# Phase 45 Summary - Native SCTP Production Transport
+
+Phase 45 is evidence-complete for the production native SCTP transport path on a real Linux SCTP loopback lab and includes a repeatable Linux evidence runner.
+
+## Completed Capabilities
+
+- Added lksctp-backed `sctp_sendmsg` and `sctp_recvmsg` interop for real stream id, PPID, and unordered metadata.
+- Added `NativeSctpTransportOptions` to bind backpressure, timeout, reconnect, and metadata policy to native SCTP transports.
+- Added `SctpTransportQueueMetrics` for queued send messages, queued bytes, pending receives, sent/received counters, rejected sends, and graceful shutdowns.
+- Updated `NativeSctpSocketAdapter` to enforce backpressure, use cancellation/timeout budgets, record lifecycle events, expose diagnostics, and support graceful shutdown.
+- Updated `NativeSctpConnector` to apply reconnect policy and retain per-attempt connection records.
+- Updated `NativeSctpListener` to pass production transport options into accepted associations.
+- Updated the native SCTP lab runner to validate real recv metadata, reconnect behavior, queue metrics, lifecycle events, and graceful shutdown.
+- Added `scripts/run-phase45-native-sctp-lab.sh` to publish the sample, capture PCAP, run the lab, decode SCTP, generate a report, and write digests.
+- Added unit coverage for native transport options and connector reconnect attempt records.
+- Captured passing Linux SCTP evidence in `docs/evidence/PHASE45_NATIVE_SCTP_20260701T103951Z.md` and `docs/evidence/PHASE45_NATIVE_SCTP_20260701T103951Z.json`.
+- Updated README, SCTP transport docs, SDK roadmap, and phase index.
+
+## Readiness Position
+
+The SDK now has an evidence-backed Linux SCTP loopback transport path for stream id, PPID, receive metadata, reconnect observation, queue metrics, graceful shutdown, PCAP, trace, report, and digest retention. Stable production claims still depend on independent external peer interoperability and the wider release evidence gates.

docs/PHASE_INDEX.md

@@ -49,7 +49,8 @@ This index is the complete phase map for Sigtran.NET. It links each phase to the
 | 42 | Production package publication gate integration | [Phase 42 Production Package Publication Gate Integration](PHASE42_COMMERCIAL_PACKAGE_PUBLICATION_GATE_INTEGRATION.md), [Phase 42 Summary](PHASE42_SUMMARY.md) | Foundation complete; protected live publication run still required |
 | 43 | Stable commercial release gate | [Phase 43 Stable Production Release Gate](PHASE43_STABLE_COMMERCIAL_RELEASE_GATE.md), [Phase 43 Summary](PHASE43_SUMMARY.md) | Foundation complete; real stable publication evidence still required |
 | 44 | Layer contracts and package boundaries | [Phase 44 Layer Contracts](PHASE44_LAYER_CONTRACTS.md), [Phase 44 Summary](PHASE44_SUMMARY.md), [Layer Contracts](LAYER_CONTRACTS.md) | Complete; official layer interfaces and adapters are available |
+| 45 | Native SCTP production transport | [Phase 45 Native SCTP Production Transport](PHASE45_NATIVE_SCTP_PRODUCTION_TRANSPORT.md), [Phase 45 Summary](PHASE45_SUMMARY.md), [SCTP Transport](SCTP_TRANSPORT.md) | Evidence complete for Linux SCTP loopback; external peer remains separate |
 
 ## Current Production Gate
 
-The SDK can now define governed commercial evidence-producing execution, model intake of retained artifacts, verify retained files, execute filesystem-backed verification, prepare approved commercial run publication handoff records, integrate the approved handoff into the package publication gate with retained dry-run and guarded command outputs, lock the final stable release target, map the stable commercial dossier evidence required for checklist evaluation, evaluate approved stable commercial readiness areas, record a stable release decision for the next gate, plan protected stable tag creation, authorize protected stable publication inputs, prepare a guarded stable publish execution plan, retain a final stable commercial report, audit the stable gate lifecycle, report final stable gate status, and compose protocol layers through official contracts from SCTP to MAP SMS. External C SCTP peer evidence, peer-traffic benchmark evidence, internal timestamped RC signing evidence, and protected release workflow dry-run evidence are retained for the RC gate in `docs/evidence/COMMERCIAL_EVIDENCE_20260627.json`. Stable publication remains blocked until approved package publication run evidence, final stable release gate evidence, NuGet publication evidence, and any adopter-specific commercial evidence are complete.
+The SDK can now define governed commercial evidence-producing execution, model intake of retained artifacts, verify retained files, execute filesystem-backed verification, prepare approved commercial run publication handoff records, integrate the approved handoff into the package publication gate with retained dry-run and guarded command outputs, lock the final stable release target, map the stable commercial dossier evidence required for checklist evaluation, evaluate approved stable commercial readiness areas, record a stable release decision for the next gate, plan protected stable tag creation, authorize protected stable publication inputs, prepare a guarded stable publish execution plan, retain a final stable commercial report, audit the stable gate lifecycle, report final stable gate status, compose protocol layers through official contracts from SCTP to MAP SMS, and retain passing Linux native SCTP loopback evidence with metadata/reconnect artifacts. External C SCTP peer evidence, peer-traffic benchmark evidence, internal timestamped RC signing evidence, and protected release workflow dry-run evidence are retained for the RC gate in `docs/evidence/COMMERCIAL_EVIDENCE_20260627.json`. Stable publication remains blocked until approved package publication run evidence, final stable release gate evidence, NuGet publication evidence, and any adopter-specific commercial evidence are complete.

docs/SCTP_TRANSPORT.md

@@ -19,6 +19,8 @@ SctpPayloadMetadata metadata = new(
 
 The metadata contract is no longer limited to optional helpers. Existing `ISctpSocket` implementations continue to work for M3UA packet send/receive through `SctpSocketTransportAdapter`, while production transports should implement `ISctpTransport` directly so higher layers can opt into SCTP-specific behavior without binding to a concrete socket.
 
+On Linux, `NativeSctpSocketAdapter` now uses lksctp `sctp_sendmsg` and `sctp_recvmsg` for `ISctpTransport` operations. That path preserves outbound stream id, PPID, and unordered metadata and returns kernel-provided receive metadata through `SctpReceiveResult`.
+
 The development `TcpSctpAdapter` now implements `ISctpMetadataSocket`, `ISctpTransport`, and `ISctpAssociation` with default M3UA PPID metadata and exposes a health snapshot. It still uses TCP length-prefix framing and must not be treated as production SCTP.
 
 `SigtranTransportSamples.CreateLocalM3uaAspToSg()` provides a documented local TCP sample scenario that maps an ASP endpoint to an SG endpoint with M3UA PPID metadata. It is intended for demos and deterministic tooling only.
@@ -104,6 +106,21 @@ This contract is intentionally package-neutral. Platform-specific transports can
 
 Native transports should record the decision in diagnostics before reconnecting or closing the association.
 
+## Production Native SCTP Options
+
+`NativeSctpTransportOptions` binds the production behavior used by native SCTP transports:
+
+- `SctpBackpressurePolicy`
+- `SctpOperationTimeoutPolicy`
+- `SctpReconnectPolicy`
+- kernel metadata requirement
+
+`NativeSctpConnector` records `NativeSctpConnectionAttempt` entries for initial connect and reconnect attempts. The Phase 45 Linux sample uses those records as reconnect evidence.
+
+`NativeSctpSocketAdapter.GetQueueMetrics()` returns `SctpTransportQueueMetrics` for queued send messages, queued bytes, pending receives, sent/received counters, backpressure rejections, and graceful shutdown count.
+
+`NativeSctpSocketAdapter.ShutdownAsync(...)` moves the association through `ShuttingDown` and `Closed` lifecycle events and records graceful shutdown metrics.
+
 ## Transport Diagnostics
 
 `SctpTransportDiagnostics.CreateSnapshot(...)` creates an immutable diagnostic envelope from transport health, association lifecycle history, optional multi-homing readiness, optional backpressure decision, optional recovery decision, and optional active operation timeout budget.
@@ -197,6 +214,10 @@ The probe does not mark the transport production-ready by itself. It is the firs
 
 `NativeSctpListener` provides the server-side bind/listen/accept path for Linux native SCTP lab scenarios.
 
+`scripts/run-phase45-native-sctp-lab.sh` runs the production transport sample on Linux. It publishes the lab binary, captures PCAP with `tcpdump`, validates stream/PPID metadata from `sctp_recvmsg`, records reconnect attempts, writes queue metrics, performs graceful shutdown, decodes SCTP with TShark, generates a report, and computes SHA-256 digests.
+
+Run `phase45-native-sctp-20260701T103951Z` passed this script on a Linux VM and retained PCAP, trace, TShark decode, report, and digest evidence in `docs/evidence/PHASE45_NATIVE_SCTP_20260701T103951Z.md`.
+
 `NativeSctpLab.CreateFromEnvironment()` keeps native SCTP integration verification opt-in through `SIGTRAN_NATIVE_SCTP_LAB=1`.
 
 `NativeSctpReadiness.GetReport()` marks the Phase 8 native SCTP foundation complete while keeping production readiness blocked until Linux verification passes.

docs/SDK_ROADMAP.md

@@ -392,6 +392,16 @@ Status: Phase 43 is foundation-complete. The SDK can model the stable release ta
 
 Status: Phase 44 is complete. `ISctpAssociation`, `ISctpTransport`, `IMtp2Link`, `IMtp3Network`, `ISccpService`, `ITcapDialogues`, and `IMapSmsService` are available. Existing SCTP adapters and `M3uaTransportSession` support the official transport contract, `M3uaMtp3Network` exposes M3UA as MTP3, and SCCP/TCAP/MAP service classes compose through lower-layer interfaces. Production readiness still depends on retained native SCTP, external peer, benchmark, supply-chain, and stable publication evidence.
 
+## Phase 45 - Native SCTP Production Transport
+
+- Use Linux lksctp metadata APIs for real stream id, PPID, unordered flag, and receive metadata.
+- Add production transport options for backpressure, timeout, reconnect, and metadata policy.
+- Track send/receive queue metrics, lifecycle events, fault recovery decisions, and graceful shutdowns.
+- Validate reconnect behavior and metadata through a repeatable Linux sample.
+- Retain PCAP, logs, SDK trace, TShark comparison, report, and SHA-256 digests from the sample run.
+
+Status: Phase 45 is evidence-complete for native Linux SCTP loopback. The native SCTP adapter uses lksctp metadata calls, records queue metrics and diagnostics, enforces backpressure, supports graceful shutdown, and the connector records reconnect attempts. Run `phase45-native-sctp-20260701T103951Z` retained PCAP/log/trace/comparison/report/digest artifacts and validated stream id `1`, PPID `3`, receive metadata, reconnect, and graceful shutdown. Independent external peer interoperability remains a separate production gate.
+
 ## Recommended First Deliverable
 
 The first useful SDK release should be an alpha package focused on M3UA over a transport abstraction:

docs/evidence/PHASE45_NATIVE_SCTP_20260701T103951Z.json

@@ -0,0 +1,58 @@
+{
+  "runId": "phase45-native-sctp-20260701T103951Z",
+  "phase": 45,
+  "title": "Native SCTP Production Transport",
+  "host": "sigtrannet",
+  "vmAddress": "192.168.100.28",
+  "kernel": "5.15.0-181-generic",
+  "artifactRoot": "/home/ammar/sigtran-phase45-run/artifacts/phase45-native-sctp-20260701T103951Z",
+  "result": "PASS",
+  "streamId": 1,
+  "payloadProtocolIdentifier": 3,
+  "messageEvents": 14,
+  "metadataValidation": true,
+  "streamValidation": true,
+  "ppidValidation": true,
+  "reconnectFailedAttempts": 3,
+  "reconnectSuccessfulAttempts": 1,
+  "shutdownEvents": 2,
+  "metricsSnapshots": 4,
+  "artifacts": [
+    {
+      "kind": "pcap",
+      "path": "/home/ammar/sigtran-phase45-run/artifacts/phase45-native-sctp-20260701T103951Z/pcap/phase45-native-sctp-20260701T103951Z.pcap",
+      "sha256": "33c7708b66fba17b7f5e72ed30e06be3e1f8e01d27e60c25d8c7165fe5663f35"
+    },
+    {
+      "kind": "sdk-trace",
+      "path": "/home/ammar/sigtran-phase45-run/artifacts/phase45-native-sctp-20260701T103951Z/trace/phase45-native-sctp-20260701T103951Z.jsonl",
+      "sha256": "abaa2a9153b10db6abd73050c85d26c820d16d892594e781e4ade9559e863c90"
+    },
+    {
+      "kind": "tshark-decode",
+      "path": "/home/ammar/sigtran-phase45-run/artifacts/phase45-native-sctp-20260701T103951Z/comparison/phase45-native-sctp-20260701T103951Z-tshark.txt",
+      "sha256": "2352dfce5f929f4678c9194d7e9819d97086344eb7443db5793b4f5a1f053a95"
+    },
+    {
+      "kind": "run-report",
+      "path": "/home/ammar/sigtran-phase45-run/artifacts/phase45-native-sctp-20260701T103951Z/reports/phase45-native-sctp-20260701T103951Z-report.md",
+      "sha256": "e9bda8768130a2823195be5cd4e499e70045f5e8e55e3435f798e0e96d706858"
+    },
+    {
+      "kind": "tcpdump-log",
+      "path": "/home/ammar/sigtran-phase45-run/artifacts/phase45-native-sctp-20260701T103951Z/logs/phase45-native-sctp-20260701T103951Z-tcpdump.log",
+      "sha256": "63900285e2c7224d0d120d3642337715793ed8a012ed8b574dea2bd9e765e761"
+    },
+    {
+      "kind": "publish-log",
+      "path": "/home/ammar/sigtran-phase45-run/artifacts/phase45-native-sctp-20260701T103951Z/logs/phase45-native-sctp-20260701T103951Z-publish.log",
+      "sha256": "4146f251e8a70c35f48de67b0e1592b0ce465f2d26f1b4d5fba716e9a925d921"
+    },
+    {
+      "kind": "lab-log",
+      "path": "/home/ammar/sigtran-phase45-run/artifacts/phase45-native-sctp-20260701T103951Z/logs/phase45-native-sctp-20260701T103951Z-lab.log",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    }
+  ],
+  "scope": "Closes the native Linux SCTP loopback evidence gate for stream id, PPID, receive metadata, reconnect observation, metrics, graceful shutdown, and retained PCAP/log/trace/report/digest artifacts. Independent external peer interoperability evidence remains a separate gate."
+}