feat(s7comm): classify Job/Ack_Data function codes and record Ack error pairs (STORY-188)

CHANGELOG.md

@@ -9,6 +9,22 @@ Version numbers follow [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- S7comm function-code classification: `classify_job_ack_function` in
+  `src/analyzer/s7comm.rs` is a pure, total classifier over the Job/Ack_Data
+  parameter-block function-code byte, returning `S7ClassicFunction` (Setup
+  Communication, Read Var, Write Var with first-item `S7AreaCode`, the
+  Download and Upload triads, PLC Control with a byte-exact `PlcControlService`
+  decode, PLC Stop, `Unrecognized(fc)`, and `NoParameterBlock`). All reads are
+  bounded by `param_length`, so no decode reads into the data block
+  (BC-2.21.010-017, VP-052, VP-054, STORY-188). `S7commAnalyzer` also records
+  each bounds-valid Ack/Ack_Data `error_class`/`error_code` pair in a bounded, arrival-ordered
+  record (`ack_error_observations()`, capped at `MAX_S7_ACK_ERROR_OBSERVATIONS`
+  with a saturating `ack_error_observations_dropped()` count), each recorded
+  observation carries the frame's `pdu_reference`, and a per-(ROSCTR, error
+  class, error code) count map (`ack_error_counts()`, at most 131,072 keys)
+  counts every recorded pair, including those beyond the list cap, so a
+  non-zero error is never lost. No finding or stderr output is emitted for it
+  (BC-2.21.008 postcondition 4).
 - S7comm ISO-on-TCP framing groundwork: `parse_tpkt_header` in the new
   `src/analyzer/iso_on_tcp.rs` module parses the 4-byte RFC 1006 TPKT header
   (version byte, big-endian `u16` total length), returning `None` for

docs/demo-evidence/STORY-188/AC-001-002-setup-read.tape

@@ -0,0 +1,27 @@
+# STORY-188 AC-188-001/002: Setup Communication (0xF0) and Read Var (0x04) classification
+# Library story: demonstration vehicle is the story_188 test harness
+# (tests/s7comm_analyzer_tests.rs, mod story_188); no CLI surface until STORY-193.
+# Test: cargo test --test s7comm_analyzer_tests -- story_188::test_BC_2_21_010_setup story_188::test_BC_2_21_011
+
+Output AC-001-002-setup-read.gif
+Output AC-001-002-setup-read.webm
+
+Set FontFamily "Menlo"
+Set Theme "Dracula"
+Set Width 1200
+Set Height 560
+Set FontSize 14
+Set Padding 24
+Set Shell "bash"
+Set TypingSpeed 40ms
+
+Require cargo
+
+Type "# STORY-188 AC-188-001/002: Setup Communication (0xF0) and Read Var (0x04) classification"
+Enter
+Sleep 300ms
+
+Type "cargo test --test s7comm_analyzer_tests -- story_188::test_BC_2_21_010_setup story_188::test_BC_2_21_011 2>&1 | grep -E 'running [0-9]+ tests|story_188::|test result:'"
+Enter
+Wait
+Sleep 3s

docs/demo-evidence/STORY-188/AC-003-write-var-area.tape

@@ -0,0 +1,27 @@
+# STORY-188 AC-188-003: Write Var area-code extraction, descriptor boundary 11/12/13/14, exhaustive u8
+# Library story: demonstration vehicle is the story_188 test harness
+# (tests/s7comm_analyzer_tests.rs, mod story_188); no CLI surface until STORY-193.
+# Test: cargo test --test s7comm_analyzer_tests -- story_188::test_BC_2_21_012 area_exhaustive
+
+Output AC-003-write-var-area.gif
+Output AC-003-write-var-area.webm
+
+Set FontFamily "Menlo"
+Set Theme "Dracula"
+Set Width 1200
+Set Height 600
+Set FontSize 13
+Set Padding 24
+Set Shell "bash"
+Set TypingSpeed 40ms
+
+Require cargo
+
+Type "# STORY-188 AC-188-003: Write Var area-code extraction, descriptor boundary 11/12/13/14, exhaustive u8"
+Enter
+Sleep 300ms
+
+Type "cargo test --test s7comm_analyzer_tests -- story_188::test_BC_2_21_012 area_exhaustive 2>&1 | grep -E 'running [0-9]+ tests|story_188::|test result:'"
+Enter
+Wait
+Sleep 3s

docs/demo-evidence/STORY-188/AC-004-005-download-upload-triads.tape

@@ -0,0 +1,27 @@
+# STORY-188 AC-188-004/005: Download and Upload triads, disjointness (VP-054 proptest)
+# Library story: demonstration vehicle is the story_188 test harness
+# (tests/s7comm_analyzer_tests.rs, mod story_188); no CLI surface until STORY-193.
+# Test: cargo test --test s7comm_analyzer_tests -- story_188::test_BC_2_21_013 story_188::test_BC_2_21_014 vp054
+
+Output AC-004-005-download-upload-triads.gif
+Output AC-004-005-download-upload-triads.webm
+
+Set FontFamily "Menlo"
+Set Theme "Dracula"
+Set Width 1200
+Set Height 640
+Set FontSize 13
+Set Padding 24
+Set Shell "bash"
+Set TypingSpeed 40ms
+
+Require cargo
+
+Type "# STORY-188 AC-188-004/005: Download and Upload triads, disjointness (VP-054 proptest)"
+Enter
+Sleep 300ms
+
+Type "cargo test --test s7comm_analyzer_tests -- story_188::test_BC_2_21_013 story_188::test_BC_2_21_014 vp054 2>&1 | grep -E 'running [0-9]+ tests|story_188::|test result:'"
+Enter
+Wait
+Sleep 3s

docs/demo-evidence/STORY-188/AC-006-007-plc-control-stop.tape

@@ -0,0 +1,27 @@
+# STORY-188 AC-188-006/007: PLC Control service decode (incl. truncated/case/trailing) and PLC Stop
+# Library story: demonstration vehicle is the story_188 test harness
+# (tests/s7comm_analyzer_tests.rs, mod story_188); no CLI surface until STORY-193.
+# Test: cargo test --test s7comm_analyzer_tests -- story_188::test_BC_2_21_015 story_188::test_BC_2_21_016
+
+Output AC-006-007-plc-control-stop.gif
+Output AC-006-007-plc-control-stop.webm
+
+Set FontFamily "Menlo"
+Set Theme "Dracula"
+Set Width 1200
+Set Height 640
+Set FontSize 13
+Set Padding 24
+Set Shell "bash"
+Set TypingSpeed 40ms
+
+Require cargo
+
+Type "# STORY-188 AC-188-006/007: PLC Control service decode (incl. truncated/case/trailing) and PLC Stop"
+Enter
+Sleep 300ms
+
+Type "cargo test --test s7comm_analyzer_tests -- story_188::test_BC_2_21_015 story_188::test_BC_2_21_016 2>&1 | grep -E 'running [0-9]+ tests|story_188::|test result:'"
+Enter
+Wait
+Sleep 3s

docs/demo-evidence/STORY-188/AC-008-009-unrecognized-totality.tape

@@ -0,0 +1,27 @@
+# STORY-188 AC-188-008/009: unrecognized FC, empty and unsliceable block, 256-value totality, VP-052 proptest
+# Library story: demonstration vehicle is the story_188 test harness
+# (tests/s7comm_analyzer_tests.rs, mod story_188); no CLI surface until STORY-193.
+# Test: cargo test --test s7comm_analyzer_tests -- story_188::test_BC_2_21_017 vp052
+
+Output AC-008-009-unrecognized-totality.gif
+Output AC-008-009-unrecognized-totality.webm
+
+Set FontFamily "Menlo"
+Set Theme "Dracula"
+Set Width 1200
+Set Height 640
+Set FontSize 13
+Set Padding 24
+Set Shell "bash"
+Set TypingSpeed 40ms
+
+Require cargo
+
+Type "# STORY-188 AC-188-008/009: unrecognized FC, empty and unsliceable block, 256-value totality, VP-052 proptest"
+Enter
+Sleep 300ms
+
+Type "cargo test --test s7comm_analyzer_tests -- story_188::test_BC_2_21_017 vp052 2>&1 | grep -E 'running [0-9]+ tests|story_188::|test result:'"
+Enter
+Wait
+Sleep 3s

docs/demo-evidence/STORY-188/AC-010-ack-error-record.tape

@@ -0,0 +1,27 @@
+# STORY-188 AC-188-010: Ack/Ack_Data error record, count map, cap/dropped, pdu_reference, non-recording paths
+# Library story: demonstration vehicle is the story_188 test harness
+# (tests/s7comm_analyzer_tests.rs, mod story_188); no CLI surface until STORY-193.
+# Test: cargo test --test s7comm_analyzer_tests story_188::test_BC_2_21_008
+
+Output AC-010-ack-error-record.gif
+Output AC-010-ack-error-record.webm
+
+Set FontFamily "Menlo"
+Set Theme "Dracula"
+Set Width 1200
+Set Height 860
+Set FontSize 12
+Set Padding 24
+Set Shell "bash"
+Set TypingSpeed 40ms
+
+Require cargo
+
+Type "# STORY-188 AC-188-010: Ack/Ack_Data error record, count map, cap/dropped, pdu_reference, non-recording paths"
+Enter
+Sleep 300ms
+
+Type "cargo test --test s7comm_analyzer_tests story_188::test_BC_2_21_008 2>&1 | grep -E 'running [0-9]+ tests|story_188::|test result:'"
+Enter
+Wait
+Sleep 3s

docs/demo-evidence/STORY-188/AC-011-canonical-frames.tape

@@ -0,0 +1,27 @@
+# STORY-188 AC-188-011: canonical public-reference byte vectors (story_188::canonical)
+# Library story: demonstration vehicle is the story_188 test harness
+# (tests/s7comm_analyzer_tests.rs, mod story_188); no CLI surface until STORY-193.
+# Test: cargo test --test s7comm_analyzer_tests story_188::canonical
+
+Output AC-011-canonical-frames.gif
+Output AC-011-canonical-frames.webm
+
+Set FontFamily "Menlo"
+Set Theme "Dracula"
+Set Width 1200
+Set Height 640
+Set FontSize 13
+Set Padding 24
+Set Shell "bash"
+Set TypingSpeed 40ms
+
+Require cargo
+
+Type "# STORY-188 AC-188-011: canonical public-reference byte vectors (story_188::canonical)"
+Enter
+Sleep 300ms
+
+Type "cargo test --test s7comm_analyzer_tests story_188::canonical 2>&1 | grep -E 'running [0-9]+ tests|story_188::|test result:'"
+Enter
+Wait
+Sleep 3s

docs/demo-evidence/STORY-188/AC-ALL-story_188-green.tape

@@ -0,0 +1,27 @@
+# STORY-188 full story_188 module: 34/34 green
+# Library story: demonstration vehicle is the story_188 test harness
+# (tests/s7comm_analyzer_tests.rs, mod story_188); no CLI surface until STORY-193.
+# Test: cargo test --test s7comm_analyzer_tests story_188::
+
+Output AC-ALL-story_188-green.gif
+Output AC-ALL-story_188-green.webm
+
+Set FontFamily "Menlo"
+Set Theme "Dracula"
+Set Width 1200
+Set Height 1080
+Set FontSize 11
+Set Padding 24
+Set Shell "bash"
+Set TypingSpeed 40ms
+
+Require cargo
+
+Type "# STORY-188 full story_188 module: 34/34 green"
+Enter
+Sleep 300ms
+
+Type "cargo test --test s7comm_analyzer_tests story_188:: 2>&1 | grep -E 'running [0-9]+ tests|story_188::|test result:'"
+Enter
+Wait
+Sleep 3s

docs/demo-evidence/STORY-188/AC-FIXTURE-e2e-fc-classification-pcap.tape

@@ -0,0 +1,27 @@
+# STORY-188 fixture pcap end-to-end FC classification (supporting AC-188-001..008)
+# Library story: demonstration vehicle is the story_188 test harness
+# (tests/s7comm_analyzer_tests.rs, mod story_188); no CLI surface until STORY-193.
+# Test: cargo test --test s7comm_analyzer_tests story_188::test_BC_2_21_010_fc_classification_fixture
+
+Output AC-FIXTURE-e2e-fc-classification-pcap.gif
+Output AC-FIXTURE-e2e-fc-classification-pcap.webm
+
+Set FontFamily "Menlo"
+Set Theme "Dracula"
+Set Width 1200
+Set Height 520
+Set FontSize 13
+Set Padding 24
+Set Shell "bash"
+Set TypingSpeed 40ms
+
+Require cargo
+
+Type "# STORY-188 fixture pcap end-to-end FC classification (supporting AC-188-001..008)"
+Enter
+Sleep 300ms
+
+Type "cargo test --test s7comm_analyzer_tests story_188::test_BC_2_21_010_fc_classification_fixture 2>&1 | grep -E 'running [0-9]+ tests|story_188::|test result:'"
+Enter
+Wait
+Sleep 3s

docs/demo-evidence/STORY-188/AC-VP051-kani-slicing-safe.tape

@@ -0,0 +1,27 @@
+# STORY-188 VP-051 Kani harness: classify_job_ack_function parameter-slicing safety
+# (supporting evidence for AC-188-008/009 totality and no-panic slicing)
+# Test: cargo kani --tests --harness verify_classify_job_ack_function_param_slicing_safe
+
+Output AC-VP051-kani-slicing-safe.gif
+Output AC-VP051-kani-slicing-safe.webm
+
+Set FontFamily "Menlo"
+Set Theme "Dracula"
+Set Width 1200
+Set Height 560
+Set FontSize 14
+Set Padding 24
+Set Shell "bash"
+Set TypingSpeed 40ms
+Set WaitTimeout 120s
+
+Require cargo
+
+Type "# STORY-188 VP-051: Kani proof, classify_job_ack_function param slicing is panic-free"
+Enter
+Sleep 300ms
+
+Type "cargo kani --tests --harness verify_classify_job_ack_function_param_slicing_safe 2>&1 | grep -E 'VERIFICATION|Harness Summary|successfully verified|cover properties'"
+Enter
+Wait
+Sleep 3s