Phase 4D-C5: add guarded live IEC 61850 control interoperability harness

.github/workflows/control-interop-harness-ci.yml

@@ -0,0 +1,92 @@
+name: Control Interop Harness CI
+
+on:
+  push:
+    branches:
+      - "agent/phase-4d-c5-control-interoperability"
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  control-interop:
+    name: Control Interop Harness / ${{ matrix.compiler }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            compiler: gcc
+          - os: ubuntu-latest
+            compiler: clang
+          - os: windows-latest
+            compiler: msvc
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Select compiler
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          if [ "${{ matrix.compiler }}" = "clang" ]; then
+            echo "CC=clang" >> "$GITHUB_ENV"
+            echo "CXX=clang++" >> "$GITHUB_ENV"
+          else
+            echo "CC=gcc" >> "$GITHUB_ENV"
+            echo "CXX=g++" >> "$GITHUB_ENV"
+          fi
+
+      - name: Configure C5 harness
+        shell: bash
+        run: cmake -S tools/control_interop_probe -B build-control-interop
+
+      - name: Build C5 harness
+        shell: bash
+        run: cmake --build build-control-interop --config Release --parallel
+
+      - name: Run offline safety self-test
+        shell: bash
+        run: ctest --test-dir build-control-interop -C Release --output-on-failure
+
+      - name: Stage Linux harness and contract
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          mkdir -p evidence/control-interop
+          ./build-control-interop/ariec61850_control_interop_probe --self-test \
+            | tee evidence/control-interop/self-test-${{ matrix.compiler }}.txt
+          ./build-control-interop/ariec61850_control_interop_probe --help \
+            > evidence/control-interop/help-${{ matrix.compiler }}.txt
+          ./build-control-interop/ariec61850_control_inventory_probe --self-test \
+            | tee evidence/control-interop/inventory-self-test-${{ matrix.compiler }}.txt
+          ./build-control-interop/ariec61850_control_inventory_probe --help \
+            > evidence/control-interop/inventory-help-${{ matrix.compiler }}.txt
+          cp build-control-interop/ariec61850_control_interop_probe \
+            evidence/control-interop/ariec61850_control_interop_probe-${{ matrix.compiler }}
+          cp build-control-interop/ariec61850_control_inventory_probe \
+            evidence/control-interop/ariec61850_control_inventory_probe-${{ matrix.compiler }}
+
+      - name: Stage Windows harness and contract
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          New-Item -ItemType Directory -Force -Path evidence/control-interop | Out-Null
+          $exe = 'build-control-interop/Release/ariec61850_control_interop_probe.exe'
+          $inventory = 'build-control-interop/Release/ariec61850_control_inventory_probe.exe'
+          & $exe --self-test | Tee-Object -FilePath evidence/control-interop/self-test-msvc.txt
+          & $exe --help | Out-File -Encoding utf8 evidence/control-interop/help-msvc.txt
+          & $inventory --self-test | Tee-Object -FilePath evidence/control-interop/inventory-self-test-msvc.txt
+          & $inventory --help | Out-File -Encoding utf8 evidence/control-interop/inventory-help-msvc.txt
+          Copy-Item $exe evidence/control-interop/ariec61850_control_interop_probe.exe
+          Copy-Item $inventory evidence/control-interop/ariec61850_control_inventory_probe.exe
+
+      - name: Upload C5 harness evidence and binary
+        uses: actions/upload-artifact@v4
+        with:
+          name: control-interop-harness-${{ matrix.compiler }}
+          path: evidence/control-interop
+          if-no-files-found: error

MIGRATION_CHECKLIST.md

@@ -22,8 +22,8 @@ behavioral oracle until laboratory interoperability is complete.
 - [x] Deterministic 8,000-frame / two-second SV host simulation at 4 kHz with independent exact-byte Python PCAP oracle on strict GCC/Clang embedded profiles.
 - [x] ESP32-P4 ESP-IDF v6.0.2 cross-compile/link acceptance for both the integration smoke app and real first-trial SV firmware.
 - [x] ESP32-P4 `FLASHABLE/READY` CI artifact gate: ESP-IDF manifest targets `esp32p4`, validates the `0x2000` bootloader / `0x8000` partition / `0x10000` application layout, retains BIN/ELF/map/flash metadata, and publishes verified SHA-256 checksums.
-- [ ] Real IED or vendor-simulator GOOSE/SV capture accepted.
-- [~] Real-time SV publisher timing-health validation: deterministic host/CI pacing implemented; physical ESP32-P4 evidence pending.
+- [ ] Real IED or vendor-simulator GOOSE/SV capture accepted in this migration evidence set.
+- [~] Real-time SV publisher timing-health validation: deterministic host/CI pacing implemented; physical process-bus work is maintained separately from the MMS-control branch.
 - [ ] Exception-free embedded codec build; the first ESP-IDF trial temporarily enables C++ exceptions for shared legacy validation/convenience APIs while the publisher hot path remains `noexcept`.
 
 ## Phase 2 — engineering file formats
@@ -115,19 +115,19 @@ behavioral oracle until laboratory interoperability is complete.
 - [x] URCB reservation, RptEna enable/disable, optional GI, and touched-state cleanup.
 - [x] Persistent report polling and Phase 4A monitor ingestion.
 - [x] Cleanup-required evidence and retry path after association loss.
-- [ ] BRCB EntryID resume, purge decisioning, and buffer-overflow recovery.
+- [x] BRCB retained-history replay, EntryID resume/rewind, PurgeBuf, replay-gap/overflow recovery, association ownership, ResvTms/Owner lifecycle, and recovery image v2 with legacy v1 restore.
 
 ### Phase 4C — built-in TCP and live read-only discovery
 
-- [~] Non-blocking Windows Winsock and POSIX TCP `MmsByteTransport` implementation.
-- [~] IPv4/IPv6 resolution, TCP_NODELAY, keepalive, partial-send, and peer-close handling.
-- [~] Deadline and cancellation-aware connect/send/receive readiness waits.
-- [~] Bounded live GetNameList pagination for domains, variables, and DataSets.
-- [~] Optional GetVariableAccessAttributes type probes.
-- [~] Optional GetNamedVariableListAttributes DataSet directory reads.
-- [~] Optional read-only RCB attribute inventory/state probes.
-- [~] Read-only `ariec61850_live_discover` human/JSON CLI.
-- [~] Discovery service allowlist regression proving no MMS Write request is emitted.
+- [x] Non-blocking Windows Winsock and POSIX TCP `MmsByteTransport` implementation.
+- [x] IPv4/IPv6 resolution, TCP_NODELAY, keepalive, partial-send, and peer-close handling.
+- [x] Deadline and cancellation-aware connect/send/receive readiness waits.
+- [x] Bounded live GetNameList pagination for domains, variables, and DataSets.
+- [x] Optional GetVariableAccessAttributes type probes.
+- [x] Optional GetNamedVariableListAttributes DataSet directory reads.
+- [x] Optional read-only RCB attribute inventory/state probes.
+- [x] Read-only `ariec61850_live_discover` human/JSON CLI.
+- [x] Discovery service allowlist regression proving no MMS Write request is emitted.
 
 ### Phase 4C.1 — live-model parity and physical read-only interoperability
 
@@ -152,20 +152,50 @@ behavioral oracle until laboratory interoperability is complete.
 - [x] Controlled OCR7SR12 timeout/recovery evidence accepted: healthy baseline, post-association response withholding, client request timeout observed, fresh direct recovery, and identical `934b555dff76a46f` structural fingerprint before/after recovery.
 - [x] Physical GetNameList pagination accepted on OCR7SR12: 9 queries, 4 paginated queries, 88 continuation requests; largest sequence 48 pages / 4,758 names / 47 continuations with final `moreFollows=false`.
 
+### Phase 4D-R — BRCB operational semantics
+
+- [x] Retained bounded history with independent delivery cursor.
+- [x] EntryID replay/resume and rewind-to-oldest semantics.
+- [x] PurgeBuf and explicit replay-gap handling.
+- [x] Association-aware reservation/ownership with ResvTms reconnect/expiry behavior.
+- [x] MMS BRCB operational object exposure and association-context propagation.
+- [x] TCP/reset/COTP-DR association-loss lifecycle bridge.
+- [x] Recovery image v2 preserves retained replay history/cursor/gap and restores legacy v1.
+- [~] Physical ESP32-P4 BRCB raw-partition geometry/latency/endurance/power-loss evidence remains a separate NVM gate.
+
+### Phase 4D-C — guarded IEC 61850 Control Model parity
+
+- [x] C1 association-aware, default-deny guarded-control safety state machine.
+- [x] C1 Direct normal, SBO normal, Direct enhanced, and SBO enhanced lifecycle semantics.
+- [x] C1 immutable selected sequence, ownership, timeout, Cancel, association-loss cleanup, and ctlNum 1..255 wrap.
+- [x] C2 exact live-TypeSpecification `Oper`, `SBOw`, and `Cancel` structure builder.
+- [x] C2 typed SPC/DPC/integer/unsigned/floating/step control values and conservative vendor-field rejection.
+- [x] C2 exact origin, ctlNum, T, optional operTm, Test, and two-bit Check construction with golden MMS Data evidence.
+- [x] C3 enhanced-security CommandTermination and LastApplError object correlation.
+- [x] C3 standard ControlError and AddCause 0..27 mapping with raw unknown-code preservation.
+- [x] C4 live ctlModel/GVAA/GetNameList/CF-timeout discovery over the production MMS association runtime.
+- [x] C4 Direct/SBO/SBOw/Oper/Cancel orchestration, asynchronous application-error grace window, non-fatal enhanced termination timeout, and no automatic command retry.
+- [x] C1-C4 integrated into the normal `ARIEC61850::core` build and GCC/Clang/MSVC CTest matrix.
+- [x] C5 guarded live-interoperability harness implemented with read-only default, explicit arm token, typed values, status-before/after reads, deterministic control-Write counting, JSON evidence, Wireshark filter hint, and offline safety self-test.
+- [x] C5 dedicated GCC/Clang/MSVC harness CI and build artifact workflow implemented.
+- [~] Physical/simulator C5 acceptance for Direct normal, SBO normal, Direct enhanced, SBO enhanced, negative LastApplError/AddCause, and association-loss cases is pending retained laboratory evidence.
+
 ### Later Phase 4 work
 
-- [ ] Direct and SBO control state machines.
-- [ ] Enhanced-security termination/error handling.
 - [ ] MMS file and fault-record transfer.
+- [ ] Dynamic DataSet define/delete parity and full dynamic RCB lifecycle parity where still missing from the C# surface.
 
 ## Phase 5 — simulator and applications
 
-- [ ] Deterministic IED simulation and read-only MMS server.
-- [ ] CLI parity and Windows Npcap abstraction.
-- [ ] Native Engineering Workbench, simulator, discovery, and SV publisher UI.
+- [ ] Deterministic IED simulation and read-only MMS server integration parity.
+- [ ] CLI/application parity and broader Windows Npcap abstraction where still required.
+- [ ] Native Engineering Workbench, simulator, discovery, and SV publisher UI parity where product scope still requires it.
 
 ## Safety gate
 
-SCL, COMTRADE, PCAP, and the Phase 4C/4C.1 live discovery surface are read-only. Active RCB
-mutation, control, dynamic DataSet mutation, file transfer, Npcap transmission, and real-time SV
-scheduling require separate explicit APIs, authorization, and physical-laboratory acceptance.
+SCL, COMTRADE, PCAP, and the Phase 4C/4C.1 discovery surface remain read-only. Phase 4D-C
+live control is an explicit, authorization-gated API and the C5 interoperability harness is
+read-only by default; it refuses a control Write without the exact laboratory arm token.
+Control, dynamic DataSet mutation, file transfer, Npcap transmission, and real-time process-bus
+scheduling require their own explicit APIs and evidence gates. Hosted CI does not constitute
+physical IED interoperability or IEC 61850 conformance certification.

MIGRATION_PLAN.md

@@ -1,64 +1,120 @@
 # ARIEC61850 C++ Migration Plan
 
 The migration follows deterministic protocol foundations first, then engineering formats,
-association/runtime behavior, live read-only interoperability, and finally active services and
-applications. The C# repository remains the behavioral oracle until same-target laboratory
-comparison is accepted.
+association/runtime behavior, live read-only interoperability, bounded active-service semantics,
+and finally physical interoperability plus application parity. The C# repository remains the
+behavioral oracle until same-target laboratory comparison is accepted.
 
 ## Completed foundation
 
 - Phase 0: C++20/CMake, strict warnings, BER, Ethernet/VLAN, PCAP.
 - Phase 1: MMS Data/UTC, GOOSE, Sampled Values, evidence and fuzzing.
-- Phase 2: read-only SCL and COMTRADE.
+- Phase 2: read-only SCL and COMTRADE foundations.
 - Phase 3: TPKT/COTP, Session, Presentation, ACSE, MMS Initiate and confirmed services.
 - Phase 4A: DataSet/RCB inventory, InformationReport decoding, continuity monitoring.
 - Phase 4B: transport-injected association and persistent report-subscription runtime.
+- Phase 4C/4C.1: built-in Windows/Linux TCP, live read-only discovery/model projection,
+  C#↔C++ structural/type parity, repeated physical read-only interoperability, timeout/recovery,
+  RCB/control-block deep-read evidence, and large-model GetNameList pagination.
 
-## Current delivery — Phase 4C and 4C.1
+## Completed software tranche — Phase 4D-R
 
-### Phase 4C
+BRCB operational semantics are implemented and regression-tested:
 
-- built-in non-blocking Windows/Linux TCP transport;
-- deadline/cancellation-aware connect, send, and receive;
-- bounded live domain, variable, DataSet, type, and RCB discovery;
-- strict read-only service allowlist.
+- bounded retained report history with an independent delivery cursor;
+- EntryID replay/resume and rewind-to-oldest;
+- PurgeBuf and replay-gap/overflow handling;
+- association-aware reservation/Owner/ResvTms lifecycle;
+- association identity propagation through MMS writes;
+- TCP/reset/COTP-DR association-loss cleanup;
+- replay-capable recovery image v2 with legacy-v1 restore.
 
-### Phase 4C.1
+Physical BRCB raw-partition geometry, latency, endurance budgeting and controlled power-loss
+acceptance remain a separate ESP32-P4 NVM evidence gate.
 
-- C#-compatible `live-ied-model-v1` hierarchy;
-- IED/LD/LN/DO/DA references, FC, type, DataSet, and RCB evidence;
-- conservative identity and CDC inference;
-- deterministic manifest/fingerprint;
-- C#↔C++ parity checker;
-- repeated physical read-only interoperability runner and evidence format.
+## Current delivery — Phase 4D-C5 guarded control interoperability
 
-### Acceptance work still required
+### C1 — safety state machine
 
-- GCC/Clang/MSVC and Security/Evidence workflow run on PR #14;
-- full branch CTest;
-- reachable IED/vendor-simulator run;
-- primary-vendor ten-cycle and timeout/reconnect evidence;
-- same-target C# and C++ parity review;
-- large-model pagination evidence when available.
+- `ctlModel` 0..4 parity with the C# oracle;
+- Direct normal, SBO normal, Direct enhanced and SBO enhanced lifecycle semantics;
+- association-aware ownership and default-deny authorization;
+- immutable selected sequence across ctlVal/origin/ctlNum/T/operTm/Test/Check;
+- selection timeout, association-loss cleanup and explicit Cancel;
+- ctlNum 1..255 wrap with zero excluded;
+- no automatic command retry.
 
-## Next implementation priority after Phase 4C.1 acceptance
+### C2 — exact MMS control structures
 
-### Phase 4D — guarded control foundation
+- live TypeSpecification-driven `Oper`, `SBOw` and `Cancel` construction;
+- conservative SPC/DPC/integer/unsigned/floating/step-position binding;
+- exact origin, ctlNum, T, optional operTm, Test and two-bit Check fields;
+- DPC network-bit-order parity and golden MMS Data vectors;
+- unknown vendor-specific fields are rejected instead of guessed.
 
-- Direct Operate and Select-Before-Operate state machines;
-- normal and enhanced security;
-- select, operate, cancel, ownership, timeout, and command termination;
-- LastApplError and AddCause;
-- default-deny authorization, operator confirmation, and full audit trail;
-- no automatic command retry.
+### C3 — enhanced-security completion and diagnostics
+
+- correlated CommandTermination handling;
+- LastApplError decoding with standard ControlError and AddCause 0..27 mapping;
+- raw unknown-code preservation;
+- exact controlled-object correlation;
+- ordinary ST/MX process reports cannot complete an enhanced command.
+
+### C4 — live guarded control session
+
+- live ctlModel Read and exact Oper/SBOw/Cancel GVAA discovery;
+- domain variable discovery and CF sboTimeout/operTimeout reads;
+- Direct Operate, SBO Read -> Oper, SBOw -> Oper and explicit Cancel orchestration;
+- asynchronous application-error grace window;
+- enhanced commands remain pending until correlated CommandTermination;
+- missing termination is a control timeout, not an automatic association fault;
+- C1-C4 are integrated into `ARIEC61850::core` and the normal GCC/Clang/MSVC CTest matrix.
+
+### C5 — controlled live interoperability harness
+
+- `ariec61850_control_interop_probe` is read-only by default;
+- any live control Write requires the exact `--arm IEC61850-LAB-CONTROL` token plus an explicit
+  object, action and value;
+- supported deliberate lab actions are `operate`, `select-operate`, and `select-cancel`;
+- status-before/status-after reads are captured when a suitable ST/MX object exists;
+- all control Write references are counted for deterministic no-retry evidence;
+- optional JSON evidence records ctlModel, CDC, status, Write list/count, report observations,
+  completion, raw ControlError/AddCause and mapped AddCause;
+- Wireshark filter guidance lets JSON evidence be reconciled with PCAP/PCAPNG;
+- a standalone CMake profile, Windows PowerShell build helper and GCC/Clang/MSVC CI artifacts
+  make the harness directly usable in a laboratory.
+
+Current software state:
+
+`SOFTWARE_READY_FOR_LAB`
+
+Physical/simulator evidence is still required before changing a tested profile to:
+
+`LAB_INTEROP_PASSED`
+
+The required procedure is documented in `docs/CONTROL_INTEROP_RUNBOOK.md`.
+
+## C5 laboratory acceptance order
+
+1. Read-only live ctlModel/GVAA/status discovery with zero control Writes.
+2. Direct normal: exactly one Oper Write plus status/process feedback.
+3. SBO normal: SBO Read -> exactly one Oper Write; separately Select -> Cancel.
+4. Direct enhanced: exactly one Oper Write -> correlated CommandTermination.
+5. SBO enhanced: one SBOw Write -> one Oper Write -> correlated CommandTermination.
+6. Safe negative LastApplError/AddCause case where the simulator/lab IED can provide it.
+7. Association loss during SBO selection and enhanced-termination wait.
+8. Reconcile JSON Write counts/references with retained PCAP and prove no automatic retry.
+
+Physical command testing must remain on an isolated/non-operational laboratory IED or simulator.
+Hosted CI does not issue a physical command and is not IEC 61850 conformance certification.
 
-Phase 4D must not begin physical command testing until Phase 4C.1 transport/model identity and
-same-target read-only parity are accepted.
+## Next implementation priorities after accepted C5 evidence
 
-### Later work
+1. MMS file and fault-record transfer parity.
+2. Dynamic DataSet define/delete and the remaining dynamic RCB lifecycle parity.
+3. Mutable SCL workspace/export and live-discovery-to-SCL reconstruction parity.
+4. Deterministic IED simulator/server integration needed for repeatable multi-client regression.
+5. CLI/application and native engineering-tool parity where product scope requires it.
 
-- BRCB EntryID resume, replay, purge, and overflow recovery;
-- dynamic DataSet lifecycle;
-- MMS file and fault-record transfer;
-- deterministic IED simulator/read-only server;
-- CLI parity, Windows Npcap abstraction, and native applications.
+Sampled Values / ESP32-P4 process-bus development is intentionally maintained separately from
+this MMS-control tranche.