fix(trace-topology): taprio GCL readback honours sched-entry cmd (S/H/R) (#390)

[avrabe]

Closes #390.

Problem

extract_taprio_gcl (crates/spar-trace-topology/src/fixtures/transform.rs) read every taprio schedule entry as an 802.1Qbv gate-control-list entry, using only gatemask and interval and never looking at cmd. iproute2's entry_cmd_to_str (tc/q_taprio.c) emits cmd as one of S (SetGates), H (Hold), R (Release). Only S entries are gate entries in the 802.1Qbv sense; H/R belong to 802.1Qbu/802.3br frame preemption and their gate mask is not a schedule state the Qcc YANG gate-control-list should carry.

It has not bitten because bin/gen-fixtures.rs installs only sched-entry S, so every entry read back is an S — which is exactly why the distinction should be written down rather than trusted to stay that way (a future preemption fixture would silently fold H/R masks into its GCL).

Change

In extract_taprio_gcl, dispatch on cmd before extracting a gate entry:

cmd	behaviour
"S"	gate-control entry — extract gatemask/interval as before
"H" / "R"	valid preemption entry, skipped (not folded into the GCL)
missing / non-string	error — absence must not read as an assumed "S"
other string	error, naming the unsupported token

The missing/unknown handling follows the same discipline already in this function (and the pmc/lldp transforms): absence must not read as the expected case, and an error names what it saw.

Oracle — non-vacuous by construction

Three lib tests, each proven to fail if its arm is removed (verified by neutering each in turn and observing red):

• tc_taprio_skips_preemption_hold_release_entries — an S/H/R/S schedule (the shape a preemption-configured port reads back) yields exactly the two S masks in order, and neither preemption mask (0x0f, 0xf0) appears. Drop the filter and this goes red (GCL length 4).
• tc_taprio_missing_cmd_is_an_error
• tc_taprio_unknown_cmd_is_an_error

extract_taprio_gcl is a pure function, so this is a real test of the preemption path rather than an assertion about code that cannot run — no VM required.

Requirement

REQ-TRACE-TOPOLOGY-013 (traces-to REQ-TRACE-TOPOLOGY-005) records the decision, with PROVEN (the three executed tests) separated honestly from ASSUMED/DEFERRED: gen-fixtures.rs still installs only sched-entry S, so the preemption path is proven on the pure transform, not end-to-end through the netns VM. A fixture that installs sched-entry H so the golden readback exercises the drop on real tc output is a heavier, separate step and is left to a successor.

Verification

• cargo test -p spar-trace-topology --lib fixtures::transform → 18 passed, 0 failed
• cargo fmt --all -- --check clean; cargo clippy -p spar-trace-topology --all-targets -- -D warnings clean
• rivet validate → PASS; REQ-TRACE-TOPOLOGY-013 parses and its traces-to resolves (no broken cross-refs)
• Independent clean-room subagent confirmed correctness, non-vacuity of all three tests, and no over-claim in the REQ.

🤖 Generated with Claude Code

---

Generated by Claude Code

[temper-pulseengine]

Automated review for PR #394

pulseengine/spar:feat/taprio-cmd-filter-390 → pulseengine/spar:main

Verdict: 💬 Comment

Summary: The pull request is approved as it addresses the issue of ensuring that extract_taprio_gcl reads a taprio schedule entry as an 802.1Qbv gate-control-list entry only when its cmd is 'S'. The changes include adding tests to verify the behavior and updating the requirements document to reflect this change.

Findings: 0 mechanical (rivet) · 2 from local AI model.

Findings (2):

1. artifacts/requirements.yaml:3684

   PROVEN (executed oracle, spar-trace-topology lib tests):
   

   The tests are executed and the behavior is verified.

2. artifacts/requirements.yaml:3690

   ASSUMED / DEFERRED:
   

   The requirement is not yet implemented in the fixture VM, but it will be addressed in a separate step.

---

Generated by a local AI model and post-validated against a strict JSON contract. Each finding includes the verbatim line being criticised — verify by reading the file at the cited location.

Reviewed at a93ed34

[github-actions]

Rivet verification gate

✅ 20/20 passed

	count
Passed	20
Failed	0
Skipped (no steps)	0

Filter: (and (= type "feature") (or (has-tag "v093") (has-tag "v0100")))

Failed artifacts

(none)

_{Updated automatically by tools/post_verification_comment.py. Source of truth: artifacts/verification.yaml.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!