Add stateful SCCP connectionless service

Author: ammarheidari

README.md

@@ -18,7 +18,7 @@ SIGTRAN.NET is currently in a **public release-candidate** track. Version
 Native Linux SCTP and external SCTP/M3UA peer evidence are retained and now feed
 the SDK readiness APIs through a common verification catalog. Stateful M3UA and
 M2PA runtimes are available. Full stable-product readiness remains gated on
-stateful SCCP/TCAP/MAP services, end-to-end independent-peer evidence,
+stateful TCAP/MAP services, end-to-end independent-peer evidence,
 operator-sized performance evidence, trusted signing, and stable release
 execution.
 
@@ -69,7 +69,7 @@ The current RC engineering track focuses on:
 | M3UA | Codec, routing, ASP state, long-running `IMtp3Network` runtime, bounded queues, heartbeat supervision, reconnect/failover hooks, diagnostics, and external peer evidence are available. |
 | SCTP | Native Linux SCTP evidence validates stream id, PPID, receive metadata, reconnect, metrics, graceful shutdown, and external peer traffic. |
 | M2PA | RFC 4165 codec and stateful `IMtp2Link` runtime provide alignment, proving, 24-bit sequencing, acknowledgement, retrieval retention, congestion handling, processor-outage recovery, metrics, and transport replacement. Independent peer evidence remains. |
-| SCCP | Connectionless codec and routing foundation exists; a stateful service layer and external evidence remain. |
+| SCCP | Stateful `ISccpService` supports UDT/XUDT/LUDT, GT translation, routing, bounded segmentation/reassembly, UDTS return policy, metrics, cancellation, and MTP3 receive ownership. External peer evidence remains. |
 | TCAP | BER and transaction foundations exist; production dialogue management and external evidence remain. |
 | MAP | SMS codec and facade foundations exist; stateful service workflows and external evidence remain. |
 | Tooling | Byte-level tests, protocol diagnostics, trace comparison, and interoperability evidence are core project principles. |
@@ -156,6 +156,7 @@ Start here:
 - [Phase 45 native SCTP production transport](docs/PHASE45_NATIVE_SCTP_PRODUCTION_TRANSPORT.md)
 - [Phase 46 evidence and readiness reconciliation](docs/PHASE46_EVIDENCE_READINESS_RECONCILIATION.md)
 - [SCCP](docs/SCCP.md)
+- [Phase 49 SCCP stateful service](docs/PHASE49_SCCP_STATEFUL_SERVICE.md)
 - [TCAP](docs/TCAP.md)
 - [MAP SMS profile](docs/MAP.md)
 - [Interoperability and tooling](docs/INTEROPERABILITY.md)

docs/COMMERCIAL_READINESS_REPORT.md

@@ -42,8 +42,10 @@ retained manifests instead of stale hard-coded flags.
 - M3UA and M2PA now provide stateful runtime implementations through
   `IMtp3Network` and `IMtp2Link`. Independent external M2PA peer evidence remains
   part of the end-to-end traffic lab gate.
-- SCCP, TCAP, and MAP SMS require stateful service/session implementations and
-  independent end-to-end peer evidence.
+- SCCP now provides a stateful UDT/XUDT/LUDT service with translation, routing,
+  reassembly, and UDT return policy. TCAP and MAP SMS still require stateful
+  session/workflow implementations, and the complete stack requires independent
+  end-to-end peer evidence.
 - The retained benchmark is not an operator-sized multi-host capacity or soak
   result.
 

docs/LAYER_CONTRACTS.md

@@ -56,3 +56,7 @@ IMapSmsService map = new MapSmsService(tcap, calledParty, callingParty);
 This keeps replacement points explicit. A production Linux SCTP transport, the
 provided M2PA-backed MTP2 link, or a different TCAP dialogue manager can be
 swapped in without changing the layers above the relevant interface.
+
+`ISccpService` owns stateful connectionless data and return indications while
+remaining independent of a concrete M3UA runtime. Its implementation can route
+UDT, XUDT, and LUDT traffic over any `IMtp3Network`.

docs/PHASE49_SCCP_STATEFUL_SERVICE.md

@@ -0,0 +1,64 @@
+# Phase 49 - SCCP Stateful Service Layer
+
+Phase 49 upgrades SCCP from codec-only building blocks to a long-running
+connectionless service over `IMtp3Network`.
+
+## Delivered Units
+
+| Unit | Delivery |
+| --- | --- |
+| 1 | Stateful `ISccpService` lifecycle and receive ownership |
+| 2 | Bounded data and service-return queues |
+| 3 | Unified request and indication models for UDT, XUDT, and LUDT |
+| 4 | Automatic connectionless message-format selection |
+| 5 | Longest-prefix global-title translation to DPC and SSN |
+| 6 | Thread-safe application route registration and resolution |
+| 7 | Bounded, expiring, ordered XUDT reassembly |
+| 8 | Return-on-error handling for unroutable UDT traffic |
+| 9 | Cancellation, deterministic stop, failure state, and metrics |
+| 10 | Loopback traffic tests, readiness integration, and documentation |
+
+## Service Flow
+
+```text
+TCAP or application
+        |
+    ISccpService
+        |
+SccpConnectionlessService
+  | translation | routing | reassembly | return policy |
+        |
+   IMtp3Network
+```
+
+`SccpConnectionlessService.StartAsync` creates the single owner of
+`IMtp3Network.ReceiveAsync`. Decoded messages are delivered to bounded channels,
+which apply backpressure instead of allowing unbounded allocation.
+
+## Outbound Selection
+
+`SccpDataRequest` can select UDT, XUDT, LUDT, or automatic mode. Automatic mode
+tries UDT first, uses segmented XUDT when configured and the payload fits within
+the 16-segment protocol limit, then falls back to LUDT.
+
+When a global-title translation matches, the called party is rewritten to a
+route-on-subsystem address and the translated point code becomes the MTP3 DPC.
+Rules use deterministic longest-prefix matching.
+
+## Inbound Policy
+
+Inbound UDT, XUDT, and LUDT messages are decoded into
+`SccpDataIndication`. Segmented XUDT contexts are keyed by source point code,
+segmentation reference, and encoded called/calling addresses. Context count,
+payload size, ordering, and inactivity lifetime are bounded.
+
+When routes are configured, unresolved traffic is not delivered. UDT traffic
+with return-on-error set is returned as UDTS with
+`NoTranslationForThisSpecificAddress`.
+
+## Evidence Boundary
+
+The executable tests validate stateful traffic and policy behavior through an
+independent in-process `IMtp3Network` peer. External SCCP traces, XUDTS/LUDTS
+coverage, and independent end-to-end MAP traffic remain part of the later
+traffic-lab evidence gate.

docs/PHASE49_SUMMARY.md

@@ -0,0 +1,13 @@
+# Phase 49 Summary
+
+Phase 49 is implementation-complete.
+
+`SccpConnectionlessService` now owns a cancellable MTP3 receive loop and exposes
+stateful data and return indications through `ISccpService`. It supports UDT,
+segmented XUDT, LUDT, global-title translation, application routing, bounded
+reassembly, return-on-error handling, bounded queues, metrics, and deterministic
+shutdown.
+
+The implementation gate is closed by build, full executable tests, and package
+creation. Independent SCCP peer evidence remains explicitly open for the
+end-to-end traffic lab.

docs/PHASE_INDEX.md

@@ -53,7 +53,7 @@ This index is the complete phase map for Sigtran.NET. It links each phase to the
 | 46 | Evidence and readiness reconciliation | [Phase 46 Evidence And Readiness Reconciliation](PHASE46_EVIDENCE_READINESS_RECONCILIATION.md), [Phase 46 Summary](PHASE46_SUMMARY.md) | Complete; retained SCTP/M3UA evidence is reflected by readiness APIs |
 | 47 | M3UA production runtime API | [Phase 47 M3UA Runtime](PHASE47_M3UA_RUNTIME.md), [Phase 47 Summary](PHASE47_SUMMARY.md), [M3UA](M3UA.md) | Complete; long-running ASP runtime implements IMtp3Network |
 | 48 | M2PA production path | [Phase 48 M2PA Production Path](PHASE48_M2PA_PRODUCTION_PATH.md), [Phase 48 Summary](PHASE48_SUMMARY.md), [M2PA](M2PA.md) | Implementation complete; external peer evidence pending |
-| 49 | SCCP stateful service layer | Planned | Pending |
+| 49 | SCCP stateful service layer | [Phase 49 SCCP Stateful Service](PHASE49_SCCP_STATEFUL_SERVICE.md), [Phase 49 Summary](PHASE49_SUMMARY.md), [SCCP](SCCP.md) | Implementation complete; external peer evidence pending |
 | 50 | TCAP dialogue manager | Planned | Pending |
 | 51 | MAP SMS service | Planned | Pending |
 | 52 | End-to-end SS7 traffic lab | Planned | Pending |
@@ -66,6 +66,6 @@ This index is the complete phase map for Sigtran.NET. It links each phase to the
 The retained verification catalog now reports native Linux SCTP, external SCTP
 peer traffic, M3UA interoperability, RC SBOM/provenance/API baseline, and
 prerelease publication evidence. Full product readiness remains blocked on the
-stateful SCCP/TCAP/MAP services, end-to-end M2PA and higher-layer
+stateful TCAP/MAP services, end-to-end M2PA and higher-layer
 independent peer traffic, operator-sized performance, production operations, a
 trusted release identity, and protected stable publication.

docs/SCCP.md

@@ -1,6 +1,7 @@
 # SCCP
 
-Phase 3 replaces the early SCCP proof-of-concept with standards-shaped connectionless SCCP primitives.
+SIGTRAN.NET provides standards-shaped connectionless SCCP codecs and a stateful
+service over `IMtp3Network`.
 
 ## Protocol Vocabulary
 
@@ -21,13 +22,30 @@ SccpProtocolClass protocolClass = new(
 byte encoded = protocolClass.Encode();
 ```
 
-The current SCCP work is still a foundation for standards-based encode/decode. Interoperability-sensitive consumers should wait for the Phase 3 readiness report before treating SCCP APIs as stable.
+The stateful implementation is available for controlled integration. External
+peer trace evidence remains required before broad interoperability claims.
 
 ## Service Contract
 
-`ISccpService` is the official SCCP service boundary consumed by TCAP. It depends on `IMtp3Network` and exposes SCCP Unitdata send/receive primitives without binding callers to a concrete MTP3 or M3UA implementation.
+`ISccpService` is the official SCCP service boundary consumed by TCAP. It
+depends on `IMtp3Network` and exposes lifecycle, UDT compatibility methods,
+general connectionless data requests and indications, and service-return
+indications.
 
-`SccpConnectionlessService` implements `ISccpService` for UDT traffic over an `IMtp3Network`.
+`SccpConnectionlessService` owns one lower-layer receive loop. Its bounded data
+and return queues provide asynchronous backpressure, and `StopAsync` cancels the
+receive owner deterministically.
+
+```csharp
+SccpConnectionlessService service = new(network, routingLabel);
+await service.StartAsync(ct);
+
+await service.SendAsync(
+    new SccpDataRequest(protocolClass, called, calling, tcapPayload),
+    ct);
+
+SccpDataIndication indication = await service.ReceiveAsync(ct);
+```
 
 ## Party Addresses
 
@@ -111,6 +129,10 @@ SccpExtendedUnitdataMessage segmented = new(
     segmentation);
 ```
 
+`SccpReassemblyBuffer` validates descending remaining-segment values and bounds
+context count, assembled payload size, and inactivity lifetime. The stateful
+service uses it automatically and emits only a complete logical indication.
+
 ## Long Unitdata
 
 `SccpLongUnitdataMessage` carries larger connectionless payloads with 16-bit pointer and length fields.
@@ -144,6 +166,11 @@ byte[] encoded = udts.Encode();
 
 Use UDTS when an incoming UDT cannot be delivered and the protocol class asks for return-on-error behavior.
 
+When at least one application route is configured, the stateful service rejects
+unresolved traffic. An unroutable UDT with return-on-error set is returned as
+UDTS with the original payload and reversed party addresses. Received UDTS
+messages are available through `ReceiveReturnAsync`.
+
 ## Evidence Vectors
 
 `SccpEvidenceVectors.GetVectors()` exposes deterministic byte-level vectors for UDT, XUDT segmentation, LUDT pointer layout, and UDTS return-cause behavior.
@@ -172,9 +199,17 @@ if (routes.TryResolve(calledParty, out SccpRoute? route))
 
 Global title routes use longest-prefix matching. SSN routes can optionally include a point code for more specific routing.
 
+`SccpGlobalTitleTranslationTable` performs outbound longest-prefix translation.
+Each rule maps a numeric prefix to DPC and SSN and can preserve or remove the
+original global title. The translated DPC is applied to the outbound MTP3
+routing label.
+
 ## Readiness
 
-`SccpReadiness.GetReport()` reports the current Phase 3 status. The SDK foundation is ready when MTP3 routing, party addressing, UDT/XUDT/LUDT codecs, segmentation, service messages, and routing APIs are present.
+`SccpReadiness.GetReport()` reports codec and stateful service capabilities. The
+SDK foundation is ready when MTP3 routing, party addressing, UDT/XUDT/LUDT
+codecs, segmentation, service messages, route APIs, stateful lifecycle,
+global-title translation, reassembly, and return policy are present.
 
 ```csharp
 SccpReadinessSnapshot report = SccpReadiness.GetReport();

docs/SDK_ROADMAP.md

@@ -446,7 +446,11 @@ end-to-end traffic lab gate.
   route policy.
 - Validate UDT, XUDT, LUDT, and service-return behavior.
 
-Status: Pending.
+Status: Implementation complete. `SccpConnectionlessService` now owns a
+cancellable `IMtp3Network` receive loop and exposes bounded stateful indications.
+It supports UDT/XUDT/LUDT selection, GT translation, application route policy,
+ordered bounded XUDT reassembly, UDTS return handling, metrics, and deterministic
+shutdown. Independent SCCP peer evidence remains in the end-to-end lab gate.
 
 ## Phase 50 - TCAP Dialogue Manager