Merge pull request #9 from masarray/architecture/v1.4.0-beta.1

Introduce immutable runtime snapshots and PCAP replay for v1.4.0-beta.1

Author: masarray

.github/ISSUE_TEMPLATE/bug.yml

@@ -1,5 +1,5 @@
 name: Bug report
-description: Report a reproducible runtime, protocol, UI, or packaging defect.
+description: Report a reproducible runtime, protocol, UI, replay, or packaging defect.
 title: "[Bug]: "
 labels: [bug, triage]
 body:
@@ -11,7 +11,7 @@ body:
     id: version
     attributes:
       label: Process Bus Insight version
-      placeholder: 1.3.0-beta.2 or commit SHA
+      placeholder: 1.4.0-beta.1 or commit SHA
     validations:
       required: true
   - type: dropdown
@@ -20,6 +20,7 @@ body:
       label: Area
       options:
         - SV analyzer / waveform / phasor
+        - PCAP replay / runtime snapshot
         - GOOSE inspector
         - PTP / timing context
         - SCL validation
@@ -33,18 +34,18 @@ body:
     id: environment
     attributes:
       label: Environment
-      description: Windows version, Npcap version, adapter type, and capture path.
-      placeholder: Windows 11 x64; Npcap 1.x; Intel NIC via TAP
+      description: Windows version, Npcap version, adapter type, and capture/replay path.
+      placeholder: Windows 11 x64; Npcap 1.x; Intel NIC via TAP or sanitized PCAP replay
     validations:
       required: true
   - type: textarea
     id: reproduce
     attributes:
       label: Reproduction steps
       placeholder: |
-        1. Start capture...
+        1. Start capture or replay...
         2. Select stream...
-        3. Change publisher setting...
+        3. Change publisher setting or replay the sanitized file...
     validations:
       required: true
   - type: textarea

.github/workflows/candidate-package.yml

@@ -29,7 +29,7 @@ env:
 jobs:
   candidate:
     name: Build verified Windows x64 candidate
-    if: github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'stabilization/')
+    if: github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'stabilization/') || startsWith(github.head_ref, 'architecture/')
     runs-on: windows-latest
     timeout-minutes: 35
 

.github/workflows/release-package.yml

@@ -4,9 +4,9 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: Version label, for example 1.3.0-beta.2
+        description: Version label, for example 1.4.0-beta.1
         required: true
-        default: 1.3.0-beta.2
+        default: 1.4.0-beta.1
       publish_release:
         description: Create or update a GitHub Release
         required: true
@@ -25,7 +25,7 @@ on:
       release_notes_file:
         description: Markdown file used as release body
         required: true
-        default: docs/RELEASE_NOTES_v1.3.0-beta.2.md
+        default: docs/RELEASE_NOTES_v1.4.0-beta.1.md
   push:
     tags:
       - "v*"
@@ -130,7 +130,7 @@ jobs:
           $sha = "artifacts/release/SHA256SUMS.txt"
           $manifest = "artifacts/release/release-manifest.json"
           $notesFile = '${{ github.event.inputs.release_notes_file }}'
-          if ([string]::IsNullOrWhiteSpace($notesFile)) { $notesFile = 'docs/RELEASE_NOTES_v1.3.0-beta.2.md' }
+          if ([string]::IsNullOrWhiteSpace($notesFile)) { $notesFile = 'docs/RELEASE_NOTES_v1.4.0-beta.1.md' }
           if (-not (Test-Path $notesFile)) { throw "Release notes file not found: $notesFile" }
 
           $releaseArgs = @('release', 'create', $tag, $zip, $sha, $manifest, '--title', "Process Bus Insight $tag", '--notes-file', $notesFile, '--target', '${{ github.sha }}')

.github/workflows/runtime-architecture.yml

@@ -0,0 +1,90 @@
+name: Runtime architecture
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "src/ProcessBus.Iec61850.Raw/Runtime/**"
+      - "src/ProcessBus.Iec61850.Raw/Replay/**"
+      - "tests/ProcessBus.Tests/Pcap*Tests.cs"
+      - "tests/ProcessBus.Tests/AnalyzerRuntimeSnapshotSourceTests.cs"
+      - ".github/workflows/runtime-architecture.yml"
+  schedule:
+    - cron: "17 3 * * 4"
+  workflow_dispatch:
+    inputs:
+      iterations:
+        description: Number of deterministic architecture passes
+        required: true
+        default: "3"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: runtime-architecture-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  DOTNET_NOLOGO: true
+  DOTNET_CLI_TELEMETRY_OPTOUT: true
+
+jobs:
+  architecture:
+    name: Immutable snapshot and PCAP replay gate
+    runs-on: windows-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: 8.0.x
+
+      - name: Restore
+        run: dotnet restore .\ProcessBusSuite.sln
+
+      - name: Build
+        run: dotnet build .\ProcessBusSuite.sln -c Release --no-restore /p:ContinuousIntegrationBuild=true
+
+      - name: Repeat runtime architecture suite
+        shell: pwsh
+        run: |
+          $requested = '${{ github.event.inputs.iterations }}'
+          $iterations = 3
+          if (-not [string]::IsNullOrWhiteSpace($requested)) {
+              $parsed = 0
+              if (-not [int]::TryParse($requested, [ref]$parsed)) {
+                  throw "Invalid iterations value: $requested"
+              }
+              $iterations = [Math]::Clamp($parsed, 1, 20)
+          }
+
+          New-Item -ItemType Directory -Path .\TestResults\RuntimeArchitecture -Force | Out-Null
+          Write-Host "Runtime architecture iterations: $iterations"
+
+          for ($iteration = 1; $iteration -le $iterations; $iteration++) {
+              Write-Host "=== Runtime architecture pass $iteration/$iterations ==="
+              dotnet test .\tests\ProcessBus.Tests\ProcessBus.Tests.csproj `
+                  -c Release `
+                  --no-build `
+                  --filter "Category=RuntimeArchitecture" `
+                  --logger "trx;LogFileName=runtime-architecture-$iteration.trx" `
+                  --results-directory .\TestResults\RuntimeArchitecture
+
+              if ($LASTEXITCODE -ne 0) {
+                  throw "Runtime architecture pass $iteration failed."
+              }
+          }
+
+      - name: Upload runtime architecture evidence
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: runtime-architecture-${{ github.run_id }}
+          path: TestResults/RuntimeArchitecture/**
+          if-no-files-found: error
+          retention-days: 30

CHANGELOG.md

@@ -6,11 +6,35 @@ All notable changes are documented here. The project follows Semantic Versioning
 
 ### Planned
 
-- Golden PCAP replay corpus with sanitized multi-stream scenarios
+- Sanitized golden PCAP/PCAPNG replay corpus with broader multi-vendor scenarios
 - Further decomposition of the analyzer runtime and WPF workspace
 - Expanded SCL multi-vendor validation
 - Evidence export for FAT/SAT reports
 
+## [1.4.0-beta.1] - 2026-07-11
+
+### Added
+
+- Immutable selected-stream runtime generations with copied waveform, analog, identity, and diagnostic evidence
+- Atomic runtime snapshot publisher for coherent consumer reads
+- Classic Ethernet PCAP replay through the same raw decoder/analyzer path used by live Npcap capture
+- Microsecond and nanosecond PCAP timestamp variants in little-endian and big-endian formats
+- Bounded rejection for unsupported link types, invalid headers, oversized records, and truncated captures
+- Deterministic runtime-architecture tests covering replay timing, snapshot immutability, and three-stream isolation
+- Dedicated Runtime Architecture GitHub Actions gate with downloadable TRX evidence
+- Release-candidate packaging support for `architecture/*` branches
+
+### Changed
+
+- Release and documentation versioning use `1.4.0-beta.1`
+- Runtime architecture now exposes a coherent publication boundary instead of requiring consumers to retain mutable analyzer display models
+- Offline replay is explicitly treated as a reproducibility path, not a separate decoder or a traffic publisher
+
+### Limitations
+
+- PCAPNG is not yet supported by the first replay reader
+- The internal analyzer remains partly monolithic; complete per-stream runtime extraction and live UI migration continue in later v1.4 builds
+
 ## [1.3.0-beta.2] - 2026-07-10
 
 ### Added
@@ -58,6 +82,7 @@ All notable changes are documented here. The project follows Semantic Versioning
 
 - Hardened BER parsing, Npcap lifecycle, release version propagation, and public-repository packaging.
 
-[Unreleased]: https://github.com/masarray/DigSubAnalyzer/compare/v1.3.0-beta.2...HEAD
+[Unreleased]: https://github.com/masarray/DigSubAnalyzer/compare/v1.4.0-beta.1...HEAD
+[1.4.0-beta.1]: https://github.com/masarray/DigSubAnalyzer/compare/v1.3.0-beta.2...v1.4.0-beta.1
 [1.3.0-beta.2]: https://github.com/masarray/DigSubAnalyzer/compare/v1.3.0-beta.1...v1.3.0-beta.2
 [1.3.0-beta.1]: https://github.com/masarray/DigSubAnalyzer/releases/tag/v1.3.0-beta.1

Directory.Build.props

@@ -10,8 +10,8 @@
     <NeutralLanguage>en</NeutralLanguage>
 
     <!-- Public beta version. Release builds may override these properties from the tag. -->
-    <VersionPrefix Condition="'$(VersionPrefix)' == ''">1.3.0</VersionPrefix>
-    <VersionSuffix Condition="'$(VersionSuffix)' == ''">beta.2</VersionSuffix>
+    <VersionPrefix Condition="'$(VersionPrefix)' == ''">1.4.0</VersionPrefix>
+    <VersionSuffix Condition="'$(VersionSuffix)' == ''">beta.1</VersionSuffix>
     <Version Condition="'$(Version)' == ''">$(VersionPrefix)-$(VersionSuffix)</Version>
     <PackageVersion Condition="'$(PackageVersion)' == ''">$(Version)</PackageVersion>
     <AssemblyVersion Condition="'$(AssemblyVersion)' == ''">$(VersionPrefix).0</AssemblyVersion>

README.md

@@ -2,6 +2,7 @@
 
 [![CI](https://github.com/masarray/DigSubAnalyzer/actions/workflows/ci.yml/badge.svg)](https://github.com/masarray/DigSubAnalyzer/actions/workflows/ci.yml)
 [![Runtime Stability](https://github.com/masarray/DigSubAnalyzer/actions/workflows/runtime-stability.yml/badge.svg)](https://github.com/masarray/DigSubAnalyzer/actions/workflows/runtime-stability.yml)
+[![Runtime Architecture](https://github.com/masarray/DigSubAnalyzer/actions/workflows/runtime-architecture.yml/badge.svg)](https://github.com/masarray/DigSubAnalyzer/actions/workflows/runtime-architecture.yml)
 [![CodeQL](https://github.com/masarray/DigSubAnalyzer/actions/workflows/codeql.yml/badge.svg)](https://github.com/masarray/DigSubAnalyzer/actions/workflows/codeql.yml)
 [![GitHub Pages](https://github.com/masarray/DigSubAnalyzer/actions/workflows/pages.yml/badge.svg)](https://github.com/masarray/DigSubAnalyzer/actions/workflows/pages.yml)
 [![Release Package](https://github.com/masarray/DigSubAnalyzer/actions/workflows/release-package.yml/badge.svg)](https://github.com/masarray/DigSubAnalyzer/actions/workflows/release-package.yml)
@@ -12,9 +13,9 @@
 
 **Process Bus Insight** is a free, open-source, receive-only **IEC 61850 Process Bus analyzer for Windows**. It provides engineering visibility into **Sampled Values (SV)**, **GOOSE**, **PTPv2 timing context**, and **SCL expected-vs-observed validation** for FAT, SAT, commissioning, interoperability checks, and troubleshooting.
 
-The project is currently released as a **public beta**. Its design goal is field clarity without overstating measurement confidence: identify live publishers, inspect protocol evidence, isolate unhealthy streams, compare observed traffic against SCL, and capture defensible findings.
+The project is currently released as a **public beta**. Its design goal is field clarity without overstating measurement confidence: identify live publishers, inspect protocol evidence, isolate unhealthy streams, reproduce captured traffic offline, compare observed traffic against SCL, and capture defensible findings.
 
-> **Timing confidence:** normal Windows/Npcap timestamps are software based. Arrival timing is useful for screening and troubleshooting, but is not certification-grade jitter evidence unless the capture path is validated with appropriate hardware timestamping, TAP, or trusted timing equipment.
+> **Timing confidence:** normal Windows/Npcap timestamps and replayed capture timestamps are software evidence. Arrival timing is useful for screening and troubleshooting, but is not certification-grade jitter evidence unless the capture path is validated with appropriate hardware timestamping, TAP, or trusted timing equipment.
 
 ![Process Bus Insight analyzer overview](docs/screenshot/analyzer-overview.webp)
 
@@ -27,6 +28,8 @@ Current capabilities include:
 | Area | Capability |
 | --- | --- |
 | SV analyzer | Multi-stream discovery, APPID/svID/MAC/VLAN/confRev evidence, selected-stream workspace, raw decoded sample waveform, RMS, phasor, sequence diagnostics, shape/distortion indication, and selectable scope windows. |
+| Runtime snapshots | Immutable selected-stream generations containing copied identity, waveform, analog, phasor, shape, and diagnostic evidence for coherent consumer reads. |
+| PCAP replay | Bounded classic Ethernet PCAP replay through the same raw decoder/analyzer entry point used by live Npcap capture. |
 | GOOSE inspector | Publisher discovery, stNum/sqNum tracking, event timeline, typed `allData` decoding, change summaries, and SCL-assisted semantic context. |
 | PTP visibility | Passive PTPv2 message context, grandmaster/domain evidence where available, freshness wording, and timestamp-confidence boundaries. |
 | SCL validation | Load SCD/ICD/CID files and compare expected publishers/streams against observed APPID, destination MAC, VLAN, svID, confRev, and related evidence. |
@@ -40,6 +43,7 @@ Wireshark remains an essential packet-analysis tool. Process Bus Insight focuses
 - Is the observed APPID, MAC, VLAN, svID, or confRev consistent with the SCL design?
 - Is the problem owned by the stream, publisher, timing source, adapter, or capture path?
 - Are waveform, RMS, and phasor values coming from the same selected stream?
+- Can a sanitized capture reproduce the same decoder and runtime behavior away from site?
 - What evidence can be copied into a FAT/SAT finding without overclaiming timing accuracy?
 
 ## Download and run
@@ -54,7 +58,7 @@ Wireshark remains an essential packet-analysis tool. Process Bus Insight focuses
 Current public-beta package naming:
 
 ```text
-ProcessBusInsight-v1.3.0-beta.2-win-x64-portable.zip
+ProcessBusInsight-v1.4.0-beta.1-win-x64-portable.zip
 SHA256SUMS.txt
 release-manifest.json
 ```
@@ -66,19 +70,18 @@ See [`docs/QUICK_START.md`](docs/QUICK_START.md) for the field checklist.
 ## Architecture
 
 ```text
-Process Bus / TAP / Mirror Port
-        ↓
-Npcap raw Ethernet capture
-        ↓
-ProcessBus.Iec61850.Raw
-  SV / GOOSE / PTP decode and per-stream runtime
-        ↓
-ProcessBus.Core immutable display models
-        ↓
-ProcessBus.App.Wpf engineering workspaces
+Process Bus / TAP / Mirror Port ──> Npcap raw Ethernet capture ─┐
+                                                                ├─> ProcessBus.Iec61850.Raw
+Classic Ethernet PCAP ───────────> bounded replay reader ───────┘     SV / GOOSE / PTP decode
+                                                                           ↓
+                                                            immutable runtime generation
+                                                                           ↓
+                                                           WPF / tests / future export
 ```
 
-The selected SV stream is the source of truth for waveform, RMS, phasor, and stream details. Per-stream state must remain isolated; UI refresh must never combine values from different publishers. See [`docs/architecture/STREAM_RUNTIME.md`](docs/architecture/STREAM_RUNTIME.md).
+The selected SV stream is the source of truth for waveform, RMS, phasor, and stream details. Per-stream state must remain isolated; consumers must never combine values from different publishers. The v1.4 runtime snapshot boundary copies mutable analyzer collections before atomic publication. See [`docs/architecture/STREAM_RUNTIME.md`](docs/architecture/STREAM_RUNTIME.md) and [`docs/architecture/RUNTIME_SNAPSHOT_AND_REPLAY.md`](docs/architecture/RUNTIME_SNAPSHOT_AND_REPLAY.md).
+
+The first replay reader supports classic PCAP 2.4 with Ethernet link type 1 in little/big-endian microsecond or nanosecond variants. PCAPNG is not yet claimed.
 
 ## Build from source
 
@@ -106,8 +109,8 @@ dotnet run --project .\src\ProcessBus.App.Wpf\ProcessBus.App.Wpf.csproj -c Relea
 Create and verify a portable package:
 
 ```powershell
-.\scripts\publish-windows-portable.ps1 -Version "1.3.0-beta.2"
-.\scripts\verify-release-package.ps1 -PackageZip ".\artifacts\release\ProcessBusInsight-v1.3.0-beta.2-win-x64-portable.zip"
+.\scripts\publish-windows-portable.ps1 -Version "1.4.0-beta.1"
+.\scripts\verify-release-package.ps1 -PackageZip ".\artifacts\release\ProcessBusInsight-v1.4.0-beta.1-win-x64-portable.zip"
 ```
 
 Run the repository-quality gate:
@@ -122,9 +125,15 @@ Run only the deterministic runtime-stability suite:
 dotnet test .\tests\ProcessBus.Tests\ProcessBus.Tests.csproj -c Release --filter "Category=RuntimeStability"
 ```
 
+Run only the immutable snapshot and PCAP replay suite:
+
+```powershell
+dotnet test .\tests\ProcessBus.Tests\ProcessBus.Tests.csproj -c Release --filter "Category=RuntimeArchitecture"
+```
+
 ## Validation status
 
-The repository includes parser and regression tests, repeated deterministic multi-stream stability evidence, CI build/test evidence, CodeQL analysis, dependency review, release-package verification, and explicit repository-hygiene checks. Public-beta status does **not** imply vendor certification or measurement-grade timing validation.
+The repository includes parser and regression tests, repeated deterministic multi-stream stability evidence, immutable runtime/replay evidence, CI build/test evidence, CodeQL analysis, dependency review, release-package verification, and explicit repository-hygiene checks. Public-beta status does **not** imply vendor certification or measurement-grade timing validation.
 
 Before interpreting results, review:
 
@@ -140,8 +149,9 @@ Before interpreting results, review:
 - [`docs/USER_MANUAL.md`](docs/USER_MANUAL.md) — user workflow
 - [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — capture and interpretation issues
 - [`docs/architecture/STREAM_RUNTIME.md`](docs/architecture/STREAM_RUNTIME.md) — selected-stream and snapshot invariants
+- [`docs/architecture/RUNTIME_SNAPSHOT_AND_REPLAY.md`](docs/architecture/RUNTIME_SNAPSHOT_AND_REPLAY.md) — immutable generation and PCAP replay design
 - [`docs/validation/TESTED_CONFIGURATIONS.md`](docs/validation/TESTED_CONFIGURATIONS.md) — explicitly tested environments
-- [`docs/validation/V1.3.0_BETA2_FIELD_EVIDENCE.md`](docs/validation/V1.3.0_BETA2_FIELD_EVIDENCE.md) — maintained live/replay evidence form
+- [`docs/validation/V1.3.0_BETA2_FIELD_EVIDENCE.md`](docs/validation/V1.3.0_BETA2_FIELD_EVIDENCE.md) — maintained 60-minute live stability evidence
 - [`docs/RELEASE_PACKAGING.md`](docs/RELEASE_PACKAGING.md) — portable packaging design
 - [`ROADMAP.md`](ROADMAP.md) — product direction
 - [`SECURITY.md`](SECURITY.md) — vulnerability reporting and data-handling policy