Add stateful MAP SMS workflows

Author: ammarheidari

README.md

@@ -16,9 +16,9 @@ SIGTRAN.NET is currently in a **public release-candidate** track. Version
 `1.0.0-rc.1` has been published and restored from NuGet.org.
 
 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 MAP workflows, end-to-end independent-peer evidence,
+the SDK readiness APIs through a common verification catalog. Stateful M3UA,
+M2PA, SCCP, TCAP, and MAP SMS runtimes are available. Full stable-product
+readiness remains gated on end-to-end independent-peer evidence,
 operator-sized performance evidence, trusted signing, and stable release
 execution.
 
@@ -71,7 +71,7 @@ The current RC engineering track focuses on:
 | 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 | 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 | Concurrent `TcapDialogueManager` provides transaction correlation, Begin/Continue/End/Abort, tracked invokes, Result/Error/Reject outcomes, shared timeout scanning, bounded queues, cleanup, snapshots, and metrics. External peer evidence remains. |
-| MAP | SMS codec and facade foundations exist; stateful service workflows and external evidence remain. |
+| MAP | Stateful client/server SMS workflows cover SRI-SM, MO/MT ForwardSM, ReportSM-DeliveryStatus, and AlertServiceCentre with operation profiles, result/error correlation, typed dispatch, cancellation, and metrics. Independent peer evidence remains. |
 | Tooling | Byte-level tests, protocol diagnostics, trace comparison, and interoperability evidence are core project principles. |
 
 ---
@@ -159,7 +159,8 @@ Start here:
 - [Phase 49 SCCP stateful service](docs/PHASE49_SCCP_STATEFUL_SERVICE.md)
 - [TCAP](docs/TCAP.md)
 - [Phase 50 TCAP dialogue manager](docs/PHASE50_TCAP_DIALOGUE_MANAGER.md)
-- [MAP SMS profile](docs/MAP.md)
+- [MAP SMS service](docs/MAP.md)
+- [Phase 51 MAP SMS service](docs/PHASE51_MAP_SMS_SERVICE.md)
 - [Interoperability and tooling](docs/INTEROPERABILITY.md)
 - [Compatibility policy](docs/COMPATIBILITY.md)
 - [Quality and contribution rules](docs/QUALITY.md)

docs/COMMERCIAL_READINESS_REPORT.md

@@ -42,10 +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 and TCAP now provide stateful runtime implementations with routing,
-  reassembly, transaction correlation, invoke outcomes, timeout handling, and
-  cleanup. MAP SMS still requires stateful operation workflows, and the complete
-  stack requires independent end-to-end peer evidence.
+- SCCP, TCAP, and MAP SMS now provide stateful runtime implementations with
+  routing, reassembly, transaction correlation, typed application operations,
+  Result/Error/Reject outcomes, timeout handling, and cleanup. The complete
+  stack still 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

@@ -14,6 +14,7 @@ The direction is intentionally downward:
 | MTP3 network | `IMtp3Network` | `IMtp2Link` or an M3UA network adapter |
 | SCCP service | `ISccpService` | `IMtp3Network` |
 | TCAP dialogues | `ITcapDialogues` | `ISccpService` |
+| TCAP components | `ITcapComponentDialogues` | `ITcapDialogues` |
 | MAP SMS service | `IMapSmsService` | `ITcapDialogues` |
 
 Upper layers should depend on the public contract of the layer below them, not on concrete classes such as a specific socket adapter, session implementation, or lab runner.
@@ -36,9 +37,16 @@ can implement the same contract.
 
 `ISccpService` exposes SCCP Unitdata primitives over `IMtp3Network`. `SccpConnectionlessService` provides a connectionless UDT implementation.
 
-`ITcapDialogues` exposes Begin, Continue, End, and Receive dialogue primitives over `ISccpService`. `TcapDialogueService` provides a stateful dialogue service over SCCP Unitdata.
+`ITcapDialogues` exposes Begin, Continue, End, and Receive dialogue primitives
+over `ISccpService`. `ITcapComponentDialogues` extends that boundary with
+tracked invokes, correlated outcomes, inbound components, response primitives,
+and Abort. `TcapDialogueManager` implements both contracts.
 
-`IMapSmsService` exposes SMS-oriented MAP operations over `ITcapDialogues`. `MapSmsService` composes the existing MAP SMS TCAP builder with the dialogue contract.
+`IMapSmsService` exposes SMS-oriented MAP operations over `ITcapDialogues`.
+Fire-and-forget compatibility methods work with the base contract; correlated
+stateful methods require the `ITcapComponentDialogues` capability without
+depending on a concrete dialogue manager. `MapSmsServer` also consumes that
+component contract for typed inbound dispatch.
 
 ## Consumer Rule
 
@@ -49,7 +57,7 @@ ISctpTransport sctp = CreateProductionSctpTransport();
 using M3uaTransportSession m3uaSession = new(sctp);
 IMtp3Network mtp3 = new M3uaMtp3Network(m3uaSession);
 ISccpService sccp = new SccpConnectionlessService(mtp3, routingLabel);
-ITcapDialogues tcap = new TcapDialogueService(sccp);
+ITcapComponentDialogues tcap = new TcapDialogueManager(sccp);
 IMapSmsService map = new MapSmsService(tcap, calledParty, callingParty);
 ```
 

docs/MAP.md

@@ -1,12 +1,38 @@
-# MAP SMS Profile
+# MAP SMS Service
 
-Phase 5 builds MAP SMS operation models and BER bindings on top of the TCAP foundation.
+SIGTRAN.NET provides typed MAP SMS codecs, correlated client workflows, and an
+asynchronous inbound operation server over TCAP.
 
 ## Service Contract
 
-`IMapSmsService` is the official SMS-oriented MAP service boundary. It depends on `ITcapDialogues` and exposes operation-level methods for MO-ForwardSM, MT-ForwardSM, and SendRoutingInfoForSM.
+`IMapSmsService` is the official SMS-oriented MAP service boundary. It depends
+on `ITcapDialogues` and exposes all five supported operations:
 
-`MapSmsService` composes `MapSmsTcapClient` with the TCAP dialogue contract, allowing applications to inject alternate TCAP dialogue managers without changing MAP SMS code.
+- `sendRoutingInfoForSM`
+- `mo-ForwardSM`
+- `mt-ForwardSM`
+- `reportSM-DeliveryStatus`
+- `alertServiceCentre`
+
+The `Send*Async` methods retain fire-and-forget compatibility. The
+`Invoke*Async` methods require `ITcapComponentDialogues`, correlate the invoke
+with ReturnResult, ReturnError, Reject, timeout, or dialogue closure, and return
+`MapSmsOperationResult`.
+
+```csharp
+IMapSmsService map = new MapSmsService(
+    tcapDialogueManager,
+    remoteMapAddress,
+    localMapAddress);
+
+MapSmsOperationResult result =
+    await map.InvokeRoutingInfoForShortMessageAsync(request, ct: cancellationToken);
+
+if (result.ErrorCode == MapSmsErrorCode.UnknownSubscriber)
+{
+    // Apply the operator's subscriber-not-found policy.
+}
+```
 
 ## Operation Catalog
 
@@ -24,6 +50,21 @@ bool known = MapSmsOperationCatalog.TryGet(
     out MapSmsOperationMetadata metadata);
 ```
 
+`MapSmsOperationProfiles` binds each operation to its standardized local
+operation value, application-context-name, and default timeout. The built-in
+profiles use the TS 29.002 v3/v2 contexts:
+
+| Operation | Local code | Application context |
+| --- | ---: | --- |
+| `mt-ForwardSM` | 44 | `0.4.0.0.1.0.25.3` |
+| `sendRoutingInfoForSM` | 45 | `0.4.0.0.1.0.20.3` |
+| `mo-ForwardSM` | 46 | `0.4.0.0.1.0.21.3` |
+| `reportSM-DeliveryStatus` | 47 | `0.4.0.0.1.0.20.3` |
+| `alertServiceCentre` | 64 | `0.4.0.0.1.0.23.2` |
+
+The assignments follow
+[ETSI TS 129 002](https://www.etsi.org/deliver/etsi_ts/129000_129099/129002/03.06.00_60/ts_129002v030600p.pdf).
+
 ## Parameter Set
 
 `MapSmsParameterSet` is the shared BER context-specific parameter container used by the operation models.
@@ -153,6 +194,33 @@ byte[] tcapMessage = built.EncodedMessage;
 
 The facade hides TCAP transaction-id, invoke-id, dialogue portion, and component wrapping while keeping the encoded transaction available for lower-level routing.
 
+## Inbound Operation Server
+
+`MapSmsServer` dispatches decoded inbound invokes to operation-specific async
+handlers. It validates the operation and payload before calling application
+code, returns `MistypedComponent` for malformed parameters, returns
+`UnrecognizedComponent` when no profile or handler exists, maps handler
+responses to ReturnResult, ReturnError, or Reject, and reports processing
+metrics.
+
+```csharp
+MapSmsServer server = new(tcapDialogueManager);
+server.RegisterHandler(
+    MapSmsOperationCode.MtForwardShortMessage,
+    (request, ct) =>
+    {
+        MapMtForwardShortMessage mt =
+            request.GetMessage<MapMtForwardShortMessage>();
+        return ValueTask.FromResult(MapSmsOperationResponse.Result());
+    });
+
+await server.RunAsync(stoppingToken);
+```
+
+Only one application consumer should own the inbound TCAP component stream for
+an endpoint. `TcapDialogueManager` keeps correlated outbound outcomes on their
+invoke completion path, so they cannot accumulate in the inbound server queue.
+
 ## Evidence Vectors
 
 `MapSmsEvidenceVectors.GetVectors()` exposes deterministic byte-level vectors for MO-ForwardSM, MT-ForwardSM, SendRoutingInfoForSM, ReportSM-DeliveryStatus, and AlertServiceCentre operation parameters.
@@ -166,6 +234,11 @@ Each vector stores literal BER-shaped expected bytes and validates the current o
 
 ## Readiness
 
-`MapSmsReadiness.GetReport()` reports the current MAP SMS profile status. The foundation is complete when operation metadata, address primitives, ForwardSM codecs, SRI-SM, delivery status, AlertServiceCentre, errors/extensions, and the TCAP client facade are present.
+`MapSmsReadiness.GetReport()` reports twelve implemented service capabilities:
+operation metadata, address primitives, five operation codecs, errors and
+extensions, the TCAP facade, operation profiles, correlated client workflows,
+typed server dispatch, and operational controls.
 
-Production readiness remains false until external MAP SMS interoperability vectors and operator-profile validation are added.
+The in-process paired-stack tests exercise all five workflows and MAP error
+mapping. Production readiness remains false until independent end-to-end MAP
+SMS traces and operator-profile validation are retained.

docs/PHASE51_MAP_SMS_SERVICE.md

@@ -0,0 +1,47 @@
+# Phase 51 - MAP SMS Service
+
+## Objective
+
+Move MAP SMS from deterministic codecs and transaction builders to a stateful,
+interface-driven application service over the concurrent TCAP dialogue manager.
+
+## Delivered Runtime
+
+- `ITcapComponentDialogues` separates correlated component operations from the
+  concrete `TcapDialogueManager`.
+- `MapSmsService` executes and correlates SRI-SM, MO/MT ForwardSM,
+  ReportSM-DeliveryStatus, and AlertServiceCentre.
+- `MapSmsOperationResult` exposes Result, MAP Error, Reject, timeout, and
+  dialogue-close outcomes without leaking TCAP internals into application code.
+- `MapSmsServer` validates and decodes inbound invokes, dispatches typed async
+  handlers, and sends ReturnResult, ReturnError, or Reject.
+- `MapSmsOperationProfiles` supplies the TS 29.002 operation values,
+  application contexts, and default timeouts.
+- Cancellation aborts an outstanding dialogue where possible. TCAP timeout
+  correlation and bounded component queues remain owned by the lower layer.
+- Server metrics cover received, completed, errored, rejected, malformed, and
+  failed-handler operations.
+
+## Compatibility
+
+The original `Send*Async` methods and `MapSmsTcapClient` remain available.
+Legacy TCAP operation enum tokens retain their values for source and byte-vector
+compatibility. MAP profiles place their actual local operation values on the
+wire through explicit application-profile conversion.
+
+## Verification
+
+The paired-stack test composes:
+
+`MapSmsService -> TcapDialogueManager -> SccpConnectionlessService -> IMtp3Network`
+
+It sends all five operations across two independent stack instances, validates
+typed server decoding, checks four successful results, and verifies
+`absentSubscriberForSM` ReturnError mapping. The full solution build and test
+suite pass with zero warnings.
+
+## Remaining Gate
+
+This phase proves application behavior inside the SDK. Independent
+MAP/TCAP/SCCP/M3UA/SCTP peer traffic, PCAP field comparison, and operator
+profile evidence are intentionally assigned to the end-to-end traffic lab.

docs/PHASE51_SUMMARY.md

@@ -0,0 +1,15 @@
+# Phase 51 Summary
+
+Phase 51 is implementation-complete.
+
+- All five MAP SMS workflows have correlated client APIs.
+- Inbound invokes have typed asynchronous server dispatch.
+- MAP errors, TCAP rejects, timeouts, cancellation, and metrics are represented.
+- Standard operation codes and application-context OIDs are profile-driven.
+- Public APIs include XML documentation.
+- In-process end-to-end tests cover success and MAP error paths.
+- README, MAP guidance, architecture boundaries, roadmap, and readiness status
+  are synchronized.
+
+Independent peer evidence remains a Phase 52 gate and is not implied by this
+implementation milestone.

docs/PHASE_INDEX.md

@@ -55,7 +55,7 @@ This index is the complete phase map for Sigtran.NET. It links each phase to the
 | 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 | [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 | [Phase 50 TCAP Dialogue Manager](PHASE50_TCAP_DIALOGUE_MANAGER.md), [Phase 50 Summary](PHASE50_SUMMARY.md), [TCAP](TCAP.md) | Implementation complete; external peer evidence pending |
-| 51 | MAP SMS service | Planned | Pending |
+| 51 | MAP SMS service | [Phase 51 MAP SMS Service](PHASE51_MAP_SMS_SERVICE.md), [Phase 51 Summary](PHASE51_SUMMARY.md), [MAP SMS](MAP.md) | Implementation complete; independent peer evidence pending |
 | 52 | End-to-end SS7 traffic lab | Planned | Pending |
 | 53 | Operator-sized performance and resilience | Planned | Pending |
 | 54 | Production operations package | 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 MAP workflows, end-to-end M2PA and higher-layer
-independent peer traffic, operator-sized performance, production operations, a
+end-to-end M2PA and higher-layer independent peer traffic, operator-sized
+performance, production operations, a
 trusted release identity, and protected stable publication.

docs/SDK_ROADMAP.md

@@ -471,7 +471,13 @@ peer evidence remains in the end-to-end lab gate.
   AlertServiceCentre workflows.
 - Add MAP error mapping, operation profiles, cancellation, and operator samples.
 
-Status: Pending.
+Status: Implementation complete. `MapSmsService` now executes and correlates all
+five supported SMS operations through `ITcapComponentDialogues`.
+`MapSmsOperationProfiles` supplies standardized local operation values,
+application contexts, and timeouts. `MapSmsServer` performs typed inbound
+dispatch with Result/Error/Reject responses, cancellation, validation, and
+metrics. Paired-stack tests cover every operation and MAP error mapping.
+Independent end-to-end peer evidence remains in Phase 52.
 
 ## Phase 52 - End-To-End SS7 Traffic Lab