N5.30 MMS Listener Skeleton Profile Foundation.

Author: masarray

README.md

@@ -233,5 +233,11 @@ Generate the first server-side virtual IED evidence profile:
 dotnet run --project .\apps\AR.Iec61850.Cli -- mms-server-readonly-profile --steps 5 --output .\.artifacts\out\mms-server-readonly.md --json .\.artifacts\out\mms-server-readonly.json
 ```
 
+MMS listener skeleton self-probe:
+
+```powershell
+dotnet run --project .\apps\AR.Iec61850.Cli -- mms-listener-skeleton-profile --port 0 --output .\.artifacts\out\mms-listener-skeleton.md --json .\.artifacts\out\mms-listener-skeleton.json
+```
+
 This is an offline alpha server model. It validates logical-device directory, logical-node directory, point reads, DataSet reads, RCB exposure, and read-only write rejection before a live TCP/MMS listener is added.
 

ROADMAP.md

@@ -4,6 +4,20 @@ ARIEC61850 is a clean-room Apache-2 IEC 61850 engineering stack for .NET. The pr
 
 ## Current source milestone
 
+### N5.30 - MMS listener skeleton profile foundation
+
+- Added `MmsReadOnlyListenerSkeleton`, a loopback TCP listener harness that exercises the server-side request lifecycle before the live MMS PDU decoder is attached.
+- Added `MmsReadOnlyListenerSkeletonProfile`, a typed evidence contract for bound endpoint, accepted connection count, request count, response status, write-guard verification, diagnostics, and probe steps.
+- Added `mms-listener-skeleton-profile`, a CLI command that starts an ephemeral loopback listener, runs deterministic read-only probes, and exports Markdown/JSON evidence.
+- Added deterministic unit tests for listener self-probe, invalid target handling, write guard verification, and Markdown evidence.
+- Kept the scope explicit: this is a transport/session skeleton and JSON-line probe harness, not a full MMS PDU listener yet.
+
+Validation command for the new milestone:
+
+```powershell
+dotnet run --project .\apps\AR.Iec61850.Cli -- mms-listener-skeleton-profile --port 0 --output .\.artifacts\out\mms-listener-skeleton.md --json .\.artifacts\out\mms-listener-skeleton.json
+```
+
 
 ### N5.28 - Sampled Values diagnostics profile foundation
 
@@ -112,13 +126,14 @@ A public release is allowed only when these gates are true:
 - Add stream registry, sample counter continuity, sample-rate detection, ASDU/layout checks, RMS, phasor, jitter/dropout, and PTP-correlation hooks.
 - Keep the current SV publisher/injector as a test harness for the analyzer.
 
-### N5.30 - Read-only MMS server alpha
+### N5.31 - TPKT/COTP/ACSE/MMS read-only listener alpha
 
-- Add TCP/TPKT/COTP/ACSE/MMS accept path.
-- Serve domains, variables, access attributes, and named variable lists from a simulator model.
+- Attach TPKT framing to the listener skeleton.
+- Add COTP connection confirm and ACSE associate response.
+- Add MMS initiate response and confirmed read-directory/read request dispatch.
 - Keep write/control disabled until read-only discovery and report readback are stable.
 
-### N5.31 - Simulator bridge
+### N5.32 - Simulator bridge
 
 - Map simulator profiles into MMS server model, GOOSE publisher profiles, and SV publisher profiles.
 - Add scenario scheduler for value changes, quality changes, timestamp faults, report triggers, GOOSE transitions, and SV disturbances.

apps/AR.Iec61850.Cli/Program.cs

@@ -51,6 +51,7 @@ public static async Task<int> RunAsync(string[] args)
                 "mms-engine-profile" => await MmsEngineProfileAsync(args[1..]).ConfigureAwait(false),
                 "mms-report-readiness-profile" => await MmsReportReadinessProfileAsync(args[1..]).ConfigureAwait(false),
                 "mms-server-readonly-profile" => MmsServerReadOnlyProfile(args[1..]),
+                "mms-listener-skeleton-profile" => await MmsListenerSkeletonProfileAsync(args[1..]).ConfigureAwait(false),
                 "mms-directory" => await MmsDirectoryAsync(args[1..]).ConfigureAwait(false),
                 "mms-model-discover" => await MmsModelDiscoverAsync(args[1..]).ConfigureAwait(false),
                 "mms-scl-export" => await MmsSclExportAsync(args[1..]).ConfigureAwait(false),
@@ -545,6 +546,78 @@ private static int MmsServerReadOnlyProfile(string[] args)
         return profile.IsReady && read.IsSuccess && dataSet.IsSuccess && !writeReject.IsSuccess ? 0 : 3;
     }
 
+    private static async Task<int> MmsListenerSkeletonProfileAsync(string[] args)
+    {
+        var options = CliOptions.Parse(args);
+        var port = options.GetInt("port", 0);
+        if (port is < 0 or > 65535)
+            throw new ArgumentException("--port must be 0..65535. Use 0 for an ephemeral loopback port.");
+
+        var host = options.Get("host", "127.0.0.1");
+        var steps = options.GetInt("steps", 0);
+        var timeoutMs = options.GetInt("timeout-ms", 5000);
+        if (timeoutMs <= 0)
+            throw new ArgumentException("--timeout-ms must be greater than 0.");
+
+        var profileName = options.Get("name", "ARIEC61850 Virtual IED");
+        var simulatorProfile = IedSimulatorProfile.CreateDefaultFeederProfile();
+        var engine = new IedSimulatorEngine(simulatorProfile);
+        var now = DateTimeOffset.UtcNow;
+        for (var i = 0; i < steps; i++)
+            engine.Step(now.AddMilliseconds(i * 20));
+
+        var snapshot = engine.CreateSnapshot(DateTimeOffset.UtcNow);
+        var serverProfile = new MmsReadOnlyServerModelBuilder().Build(
+            simulatorProfile,
+            snapshot,
+            new MmsReadOnlyServerProfileOptions
+            {
+                ServerName = profileName,
+                Port = port == 0 ? 102 : port,
+                IncludeSelfTest = true
+            });
+
+        var listener = new MmsReadOnlyListenerSkeleton(serverProfile);
+        var profile = await listener.RunSelfProbeAsync(new MmsReadOnlyListenerSkeletonOptions
+        {
+            Host = host,
+            Port = port,
+            ProbeTimeoutMilliseconds = timeoutMs
+        }).ConfigureAwait(false);
+
+        Console.WriteLine(profile.Summary);
+        Console.WriteLine("Mode: read-only TCP listener skeleton (loopback self-probe; JSON-line harness; no live MMS PDU decoder yet)." );
+        Console.WriteLine($"Bound endpoint: {profile.Host}:{profile.BoundPort}");
+        Console.WriteLine();
+        Console.WriteLine("Probe steps:");
+        foreach (var step in profile.ProbeSteps)
+            Console.WriteLine($"  {(step.IsTransportSuccess ? "OK" : "FAIL")} {step.Operation} {TextOrDash(step.Target)} serverSuccess={step.IsServerSuccess.ToString().ToLowerInvariant()} - {step.Message}");
+
+        if (profile.Diagnostics.Count > 0)
+        {
+            Console.WriteLine();
+            Console.WriteLine("Diagnostics:");
+            foreach (var diagnostic in profile.Diagnostics)
+                Console.WriteLine($"  {diagnostic.Severity} {diagnostic.Code}: {diagnostic.Message}");
+        }
+
+        if (options.TryGet("output", out var markdownPath) && !string.IsNullOrWhiteSpace(markdownPath))
+        {
+            EnsureOutputDirectory(markdownPath);
+            File.WriteAllText(markdownPath, profile.ToMarkdown());
+            Console.WriteLine($"Markdown MMS listener skeleton profile: {Path.GetFullPath(markdownPath)}");
+        }
+
+        if (options.TryGet("json", out var jsonPath) && !string.IsNullOrWhiteSpace(jsonPath))
+        {
+            EnsureOutputDirectory(jsonPath);
+            File.WriteAllText(jsonPath, JsonSerializer.Serialize(profile, new JsonSerializerOptions { WriteIndented = true }));
+            Console.WriteLine($"JSON MMS listener skeleton profile: {Path.GetFullPath(jsonPath)}");
+        }
+
+        return profile.IsReady ? 0 : 3;
+    }
+
     private static int InspectPcap(string[] args)
     {
         if (args.Length < 1)
@@ -5521,6 +5594,7 @@ private static void WriteUsage()
         Console.WriteLine("  mms-engine-profile <host-or-ip> [--port 102] [--timeout-ms 30000] [--max-report-probes N] [--read-datasets true] [--output profile.md] [--json profile.json]");
         Console.WriteLine("  mms-report-readiness-profile <host-or-ip> [--port 102] [--timeout-ms 120000] [--rcb LD/LN.BR.name] [--dataset LD/LLN0.DataSet] [--strict-rcb] [--allow-urcb-fallback true|false] [--duration-sec 60] [--gi true|false] [--output report-readiness.md] [--json report-readiness.json] [--session-json session-profile.json]");
         Console.WriteLine("  mms-server-readonly-profile [--port 102] [--name NAME] [--steps N] [--read LD/LN.DO.da] [--dataset LD/LLN0.DataSet] [--output mms-server.md] [--json mms-server.json]");
+        Console.WriteLine("  mms-listener-skeleton-profile [--host 127.0.0.1] [--port 0] [--timeout-ms 5000] [--steps N] [--output mms-listener.md] [--json mms-listener.json]");
         Console.WriteLine("  mms-directory <host-or-ip> [--port 102] [--timeout-ms 30000] [--ln-limit N] [--raw-limit N] [--show-points]");
         Console.WriteLine("  mms-model-discover <host-or-ip> [--port 102] [--timeout-ms 120000] [--max-report-probes 286] [--read-datasets true|false] [--read-types true|false] [--max-type-reads 256] [--type-read-source datasets|model|both] [--ied-name NAME] [--ap-name AP1] [--output .artifacts/out/ied-model-discovery]");
         Console.WriteLine("  mms-scl-export <host-or-ip> [--port 102] [--ied-name NAME] [--ap-name AP1] [--scl-export-profile safe-connection|standard-discovery|full-model|simulator-seed] [--write-connection-companion true] [--connection-output .artifacts/out/scl/live-ied.safe-connection.iid] [--ld-name-mode auto|keep] [--output .artifacts/out/scl/live-ied.generated.iid] [--read-datasets true] [--read-types true] [--max-type-reads 512] [--include-osi true]");
@@ -5557,6 +5631,7 @@ private static void WriteUsage()
         Console.WriteLine("  dotnet run --project apps/AR.Iec61850.Cli -- mms-engine-profile 192.0.2.10 --output .artifacts/out/engineering-profile.md --json .artifacts/out/engineering-profile.json");
         Console.WriteLine("  dotnet run --project apps/AR.Iec61850.Cli -- mms-report-readiness-profile 192.0.2.10 --output .artifacts/out/report-readiness.md --json .artifacts/out/report-readiness.json --session-json .artifacts/out/report-session-profile.json");
         Console.WriteLine("  dotnet run --project apps/AR.Iec61850.Cli -- mms-server-readonly-profile --steps 5 --output .artifacts/out/mms-server-readonly.md --json .artifacts/out/mms-server-readonly.json");
+        Console.WriteLine("  dotnet run --project apps/AR.Iec61850.Cli -- mms-listener-skeleton-profile --port 0 --output .artifacts/out/mms-listener-skeleton.md --json .artifacts/out/mms-listener-skeleton.json");
         Console.WriteLine("  dotnet run --project apps/AR.Iec61850.Cli -- mms-directory 192.0.2.10 --show-points --raw-limit 40");
         Console.WriteLine("  dotnet run --project apps/AR.Iec61850.Cli -- mms-model-discover 192.0.2.10 --max-report-probes 286 --read-types true --max-type-reads 256 --output .artifacts/out/ied-model-discovery");
         Console.WriteLine("  dotnet run --project apps/AR.Iec61850.Cli -- mms-scl-export 192.0.2.10 --ied-name IED1 --scl-export-profile safe-connection --ld-name-mode auto --output .artifacts/out/scl/demo-ied.generated.iid");

docs/ENGINE_MATURITY_MATRIX.md

@@ -13,7 +13,7 @@ This matrix is the public engineering checklist for growing ARIEC61850 from prot
 | GOOSE | Encode/decode/publish/subscribe basics | Expected-vs-observed diagnostics | SCL-bound forensic engine |
 | Sampled Values | Encode/decode/publish/injector basics | Subscriber/analyzer engine | RMS/phasor/timing/continuity diagnostics |
 | SCL | Parser/exporter/diff basics | Deep type-template and communication resolver | Station dataflow graph and mapping validator |
-| Simulation | Offline deterministic profile engine | Read-only MMS server adapter | Virtual IED with reports, GOOSE, SV scenarios |
+| Simulation | Offline profile + read-only server model + loopback TCP listener skeleton | TPKT/COTP/ACSE/MMS read-only listener alpha | Virtual IED with reports, GOOSE, SV scenarios |
 | File/log/setting | Not yet mature | Read-only client browser first | Typed ACSI services with guarded writes |
 | Security diagnostics | Not a base feature yet | Rule-based semantic checks | Explainable cyber/semantic findings without black-box claims |
 
@@ -95,4 +95,20 @@ Maturity impact: process-bus SV moves from visibility to actionable engineering
 ## Server-side milestone
 
 - MMS read-only server alpha: implemented as offline virtual IED profile + high-level service handler.
-- Next maturity gate: live TCP/TPKT/COTP/ACSE/MMS listener skeleton with read-only service mapping.
+- MMS listener skeleton profile: implemented as loopback TCP listener lifecycle + JSON-line probe harness + write guard evidence.
+- Next maturity gate: attach TPKT/COTP/ACSE/MMS decoding/encoding to the read-only listener while preserving the same service contract.
+
+
+## N5.30 — MMS Listener Skeleton Profile
+
+This milestone adds the first live transport boundary for the simulator-backed server model. The listener binds to a loopback TCP endpoint, accepts a client session, dispatches deterministic read-only service requests, verifies write rejection, and exports Markdown/JSON evidence.
+
+```text
+virtual IED profile
+→ read-only service handler
+→ TCP listener skeleton
+→ loopback probe
+→ listener evidence
+```
+
+Scope boundary: the harness intentionally uses a JSON-line probe protocol. The next milestone should replace the probe decoder with TPKT/COTP/ACSE/MMS request handling while keeping the same read-only service semantics.

docs/QUICK_START.md

@@ -211,3 +211,11 @@ dotnet run --project .\apps\AR.Iec61850.Cli -- mms-server-readonly-profile --ste
 
 This command needs no IED and no network adapter. It builds a virtual IED model from the simulator profile and exercises read-only directory, read, DataSet read, and write-guard probes.
 
+## MMS listener skeleton self-probe
+
+```powershell
+dotnet run --project .\apps\AR.Iec61850.Cli -- mms-listener-skeleton-profile --port 0 --output .\.artifacts\out\mms-listener-skeleton.md --json .\.artifacts\out\mms-listener-skeleton.json
+```
+
+This command starts a loopback TCP listener, sends deterministic read-only probe requests, verifies directory/read/DataSet responses, confirms write rejection, and exits. It is a listener/session lifecycle harness, not a full MMS PDU server yet.
+

docs/ROADMAP.md

@@ -112,13 +112,14 @@ A public release is allowed only when these gates are true:
 - Add stream registry, sample counter continuity, sample-rate detection, ASDU/layout checks, RMS, phasor, jitter/dropout, and PTP-correlation hooks.
 - Keep the current SV publisher/injector as a test harness for the analyzer.
 
-### N5.30 - Read-only MMS server alpha
+### N5.31 - TPKT/COTP/ACSE/MMS read-only listener alpha
 
-- Add TCP/TPKT/COTP/ACSE/MMS accept path.
-- Serve domains, variables, access attributes, and named variable lists from a simulator model.
+- Attach TPKT framing to the listener skeleton.
+- Add COTP connection confirm and ACSE associate response.
+- Add MMS initiate response and confirmed read-directory/read request dispatch.
 - Keep write/control disabled until read-only discovery and report readback are stable.
 
-### N5.31 - Simulator bridge
+### N5.32 - Simulator bridge
 
 - Map simulator profiles into MMS server model, GOOSE publisher profiles, and SV publisher profiles.
 - Add scenario scheduler for value changes, quality changes, timestamp faults, report triggers, GOOSE transitions, and SV disturbances.
@@ -139,6 +140,14 @@ ARIEC61850 engine repo
 
 Product repos can later consume the engine as project references or NuGet packages without pulling protocol logic into UI code.
 
+## N5.30 — MMS Listener Skeleton Profile
+
+The engine now has a loopback TCP listener skeleton for the read-only virtual IED service handler. It can be tested without hardware using `mms-listener-skeleton-profile`, and it validates listener bind, accepted connection, request dispatch, read-only service responses, write rejection, and Markdown/JSON evidence.
+
+```powershell
+dotnet run --project .\apps\AR.Iec61850.Cli -- mms-listener-skeleton-profile --port 0 --output .\.artifacts\out\mms-listener-skeleton.md --json .\.artifacts\out\mms-listener-skeleton.json
+```
+
 ## N5.29 — MMS Read-Only Server Alpha
 
 The engine now has an offline server-side model profile that converts the simulator profile into a read-only virtual IED. It can be tested without hardware using `mms-server-readonly-profile`, and it validates directory, read, DataSet read, RCB exposure, and write rejection.