feat(tsn): Spar_TSN::Hi_Credit + Lo_Credit user-tunable CBS (v0.9.2) (#195)

Reviewer Tier A #8 — v0.8.1 hardcoded `hi_credit_bytes` and
`lo_credit_bytes` to `Spar_TSN::Max_Frame_Size` (default 1518 B)
when constructing CbsReservation. Real Qcc/YANG configs
(`ieee802-dot1q-bridge`, `tsn-stream`) carry these per traffic
class — making the CBS recovery term `loCredit/|sendSlope|`
constant + load-bearing on the bound for any tight AVB design.

Add two properties to Spar_TSN:
- `Hi_Credit` (aadlinteger units Size_Units; port, connection)
- `Lo_Credit` (aadlinteger units Size_Units; port, connection)

Property count: 129 → 131. Spar_TSN per-set count: 7 → 9.

Accessors `get_hi_credit_bytes` and `get_lo_credit_bytes` follow
the typed-first / string-fallback pattern of `get_max_frame_size_bytes`.

The wctt CBS arm reads them from bus_props; when unset, falls back
to `max_competing_frame_bytes` (preserves v0.8.1/v0.9.1 byte-identical
output). New `WcttCbsCredit` Info diagnostic fires when at least one
credit is explicit.

REQ-TSN-005 + TEST-TSN-CBS-CREDITS.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: avrabe

artifacts/requirements.yaml

@@ -1598,6 +1598,24 @@ artifacts:
     status: implemented
     tags: [analysis, arinc653, safety, v092]
 
+  - id: REQ-TSN-005
+    type: requirement
+    title: Spar_TSN::Hi_Credit + Lo_Credit user-tunable CBS credits
+    description: >
+      Spar_TSN::Hi_Credit and Spar_TSN::Lo_Credit (both
+      `aadlinteger units Size_Units`, applied to port and connection)
+      let users override the v0.8.1-default CBS credit bounds (which
+      were hardcoded to `max_competing_frame_bytes` for both, making
+      the CBS recovery term `loCredit/|sendSlope|` constant and
+      load-bearing on the bound for any tight AVB design). Real
+      Qcc/YANG configs (`ieee802-dot1q-bridge`, `tsn-stream`) carry
+      these per traffic class. v0.9.2 adds the property surface plus
+      the `WcttCbsCredit` Info diagnostic that fires when at least
+      one credit is explicit. Default unset → byte-identical to
+      v0.8.1/v0.9.1. Per the post-v0.9.0 reviewer's Tier A #8.
+    status: implemented
+    tags: [network, tsn, cbs, wctt, v092]
+
   # ── Track G: spar-insight discrepancy assistant (v0.9.0) ──────────
 
   - id: REQ-INSIGHT-001

artifacts/verification.yaml

@@ -2107,6 +2107,31 @@ artifacts:
       - type: satisfies
         target: REQ-ARINC-005
 
+  - id: TEST-TSN-CBS-CREDITS
+    type: feature
+    title: Spar_TSN::Hi_Credit + Lo_Credit user-tunable CBS credits
+    description: >
+      Verifies that `Spar_TSN::Hi_Credit` and `Spar_TSN::Lo_Credit`
+      register in the predeclared property tables (count 129 → 131,
+      Spar_TSN per-set 7 → 9), that `get_hi_credit_bytes` and
+      `get_lo_credit_bytes` accessors handle typed PropertyExpr +
+      string fallback paths and unit conversions, and that the wctt
+      CBS arm honours explicit credits in `CbsReservation::new` while
+      preserving v0.8.1 byte-identical output when both properties
+      are unset. The `WcttCbsCredit` Info diagnostic fires when at
+      least one of Hi_Credit / Lo_Credit is set on the bus.
+    fields:
+      method: automated-test
+      steps:
+        - run: cargo test -p spar-hir-def --lib -- standard_properties
+        - run: cargo test -p spar-network --lib -- tsn
+        - run: cargo test -p spar-analysis --lib -- wctt
+    status: passing
+    tags: [v0.9.2, network, tsn, cbs, wctt]
+    links:
+      - type: satisfies
+        target: REQ-TSN-005
+
   - id: TEST-INSIGHT-DISCREPANCY
     type: feature
     title: spar-insight CTF parser + 5-kind discrepancy detection

crates/spar-analysis/src/wctt.rs

@@ -58,8 +58,8 @@ use spar_network::extract::{
 use spar_network::tsn::{
     CbsReservation, ClassOfService, GateSchedule, cbs_residual_service, frame_quantization_ps,
     get_bandwidth_reservation_bps, get_class_of_service, get_frame_preemption, get_gate_schedule,
-    get_max_frame_size_bytes, get_sync_error_ps, is_express_stream, preemption_blocking_term_ps,
-    tas_residual_service_with_sync_error,
+    get_hi_credit_bytes, get_lo_credit_bytes, get_max_frame_size_bytes, get_sync_error_ps,
+    is_express_stream, preemption_blocking_term_ps, tas_residual_service_with_sync_error,
 };
 use spar_network::types::{NetworkGraph, NodeKind, SwitchType};
 
@@ -356,11 +356,22 @@ impl WcttAnalysis {
                         let link_rate_bps = read_output_rate_bps(bus_props).unwrap_or(0);
                         let max_competing_frame_bytes = get_max_frame_size_bytes(bus_props)
                             .unwrap_or(CBS_DEFAULT_COMPETING_FRAME_BYTES);
+                        // v0.9.2: explicit hi/loCredit override the v0.8.1
+                        // default (`max_competing_frame_bytes` for both),
+                        // letting users plug in real Qcc/YANG credit
+                        // numbers. Default unset = byte-identical to v0.8.1
+                        // / v0.9.1.
+                        let hi_credit_bytes =
+                            get_hi_credit_bytes(bus_props).unwrap_or(max_competing_frame_bytes);
+                        let lo_credit_bytes =
+                            get_lo_credit_bytes(bus_props).unwrap_or(max_competing_frame_bytes);
+                        let credits_explicit = get_hi_credit_bytes(bus_props).is_some()
+                            || get_lo_credit_bytes(bus_props).is_some();
                         let reservation = CbsReservation::new(
                             idle_slope_bps,
                             link_rate_bps,
-                            max_competing_frame_bytes,
-                            max_competing_frame_bytes,
+                            hi_credit_bytes,
+                            lo_credit_bytes,
                         );
                         if let Some(reservation) = reservation {
                             let beta = cbs_residual_service(
@@ -392,6 +403,23 @@ impl WcttAnalysis {
                                 path: stream_path.clone(),
                                 analysis: self.name().to_string(),
                             });
+                            if credits_explicit {
+                                diags.push(AnalysisDiagnostic {
+                                    severity: Severity::Info,
+                                    message: format!(
+                                        "WcttCbsCredit: stream '{}' at hop {}: explicit \
+                                         hi_credit={} B, lo_credit={} B (override default \
+                                         max_competing_frame={} B)",
+                                        stream_name,
+                                        hop_idx,
+                                        hi_credit_bytes,
+                                        lo_credit_bytes,
+                                        max_competing_frame_bytes,
+                                    ),
+                                    path: stream_path.clone(),
+                                    analysis: self.name().to_string(),
+                                });
+                            }
                             beta
                         } else if bus_preemption && stream.is_express {
                             // CBS reservation invalid → fall back to

crates/spar-hir-def/src/standard_properties.rs

@@ -517,6 +517,16 @@ const SPAR_TSN: &[(&str, &str)] = &[
     // accuracy. Default unset = 0 (legacy v0.8.1 behaviour).
     // Applies to bus and processor.
     ("Sync_Error", "aadlinteger units Time_Units"),
+    // CBS hi-credit / lo-credit (802.1Qav §34.5). Real Qcc/YANG configs
+    // (`ieee802-dot1q-bridge`, `tsn-stream`) carry these explicitly per
+    // traffic class. v0.8.1 hardcoded both to `Spar_TSN::Max_Frame_Size`
+    // (default 1518 bytes) which made the CBS recovery term
+    // `loCredit / |sendSlope|` constant and load-bearing on the bound
+    // for any tight AVB design. v0.9.2 adds explicit overrides; when
+    // unset the v0.8.1 default is preserved (byte-identical).
+    // Applies to port and connection.
+    ("Hi_Credit", "aadlinteger units Size_Units"),
+    ("Lo_Credit", "aadlinteger units Size_Units"),
 ];
 
 /// Helper: collect properties from a table into the result vector.
@@ -1098,14 +1108,16 @@ mod tests {
         assert!(is_standard_property_set("Spar_TSN"));
 
         let props = standard_properties_in_set("Spar_TSN");
-        assert_eq!(props.len(), 7);
+        assert_eq!(props.len(), 9);
         assert!(props.contains(&"Stream_ID"));
         assert!(props.contains(&"Class_of_Service"));
         assert!(props.contains(&"Gate_Control_List"));
         assert!(props.contains(&"Max_Frame_Size"));
         assert!(props.contains(&"Frame_Preemption"));
         assert!(props.contains(&"Bandwidth_Reservation"));
         assert!(props.contains(&"Sync_Error"));
+        assert!(props.contains(&"Hi_Credit"));
+        assert!(props.contains(&"Lo_Credit"));
 
         // Each property resolves to its expected type.
         assert_eq!(
@@ -1210,7 +1222,7 @@ mod tests {
     #[test]
     fn test_all_standard_properties_total_count() {
         let all = all_standard_properties();
-        // 12 + 13 + 14 + 14 + 8 + 25 + 4 + 13 + 5 + 4 + 5 + 4 + 1 + 7 = 129
+        // 12 + 13 + 14 + 14 + 8 + 25 + 4 + 13 + 5 + 4 + 5 + 4 + 1 + 9 = 131
         // (Timing + Communication + Memory + Deployment + Thread + Programming
         //  + Modeling + AADL_Project + Spar_Timing + Spar_Trace + Spar_Network
         //  + Spar_Migration + Spar_Power + Spar_TSN)
@@ -1222,7 +1234,7 @@ mod tests {
         //   Max_Frame_Size, Frame_Preemption (Track D Phase 2 v0.8.1 c1)
         //   +1 for Bandwidth_Reservation (Track D Phase 2 v0.8.1 c3, CBS).
         //   +1 for Sync_Error (v0.9.1 NC soundness, gPTP ε budget).
-        assert_eq!(all.len(), 129);
+        assert_eq!(all.len(), 131);
     }
 
     #[test]

crates/spar-network/src/lib.rs

@@ -57,6 +57,7 @@ pub use tsn::{
     CbsReservation, ClassOfService, CreditPool, GateSchedule, GateScheduleError, GateWindow,
     MIN_FRAGMENT_BYTES, PREEMPTION_HEADER_BYTES, cbs_residual_service,
     get_bandwidth_reservation_bps, get_class_of_service, get_frame_preemption, get_gate_schedule,
-    is_express_stream, preemption_blocking_term_ps, tas_residual_service,
+    get_hi_credit_bytes, get_lo_credit_bytes, is_express_stream, preemption_blocking_term_ps,
+    tas_residual_service,
 };
 pub use types::{NetworkGraph, NetworkLink, NetworkNode, NodeKind, SwitchType};

crates/spar-network/src/tsn.rs

@@ -313,6 +313,36 @@ pub fn get_max_frame_size_bytes(props: &PropertyMap) -> Option<u64> {
     parse_size_bytes(raw)
 }
 
+/// Read [`Spar_TSN::Hi_Credit`] as the CBS hiCredit upper bound in
+/// bytes. Per IEEE 802.1Qav §34.5, hiCredit is the maximum positive
+/// credit a class can accumulate before sending; it bounds the
+/// burst-out tolerance. AADL declares the property as `aadlinteger
+/// units Size_Units` so it lowers via the same machinery as
+/// `Max_Frame_Size`. Returns `None` when unset (callers default to
+/// the pre-v0.9.2 behaviour of `Max_Frame_Size`).
+pub fn get_hi_credit_bytes(props: &PropertyMap) -> Option<u64> {
+    if let Some(expr) = get_typed(props, "Hi_Credit") {
+        return extract_size_bytes(expr);
+    }
+    let raw = get_raw(props, "Hi_Credit")?;
+    parse_size_bytes(raw)
+}
+
+/// Read [`Spar_TSN::Lo_Credit`] as the CBS loCredit lower bound in
+/// bytes (declared as a positive magnitude — the AVB spec uses a
+/// negative value but spar stores the absolute byte count). Per
+/// IEEE 802.1Qav §34.5, loCredit gives the worst-case credit
+/// drain, which combined with `|sendSlope|` yields the recovery
+/// time `T_recovery = loCredit / |sendSlope|` that lands in the
+/// CBS rate-latency service curve. Returns `None` when unset.
+pub fn get_lo_credit_bytes(props: &PropertyMap) -> Option<u64> {
+    if let Some(expr) = get_typed(props, "Lo_Credit") {
+        return extract_size_bytes(expr);
+    }
+    let raw = get_raw(props, "Lo_Credit")?;
+    parse_size_bytes(raw)
+}
+
 /// Read [`Spar_TSN::Frame_Preemption`] — whether frames in this
 /// class can be pre-empted by Express traffic (802.1Qbu).
 pub fn get_frame_preemption(props: &PropertyMap) -> Option<bool> {