DEVOURER_TX_REPORT=N: sampled CCX reports — deterministic coverage under the fw emission ceiling (#363 step 2)

[josephnef]

Step 2 of #363 (step 3, windowed RX receipts, remains).

What it does

The report knob becomes the sampling divisor N: SPE_RPT is requested on every Nth frame (0 = off, 1 = every frame — previous semantics unchanged), while the halmac SW_DEFINE tag still stamps every frame. Received-tag deltas are therefore exact multiples of N; any other delta is a dropped report (k·N = k−1 sampled reports lost, non-multiples are anomalies). On the 8812 report format (no tag echo) sampling only relieves the rate, via a new per-device counter.

Spec derived in #368: the CCX emission path saturates at ~1.3–1.4 k reports/s, so pick N ≥ fps/1300 and coverage of the sampled frames is deterministic instead of load-collapsed.

Measured (on air, 2.4 k fps)

run	coverage	achieved rpt/s	note
N=1 control	56.4%	1,329	the collapse persists — fifth independent ceiling measurement
N=2	100.0% of sampled (191,298/191,323)	1,107	zero lost, zero off-modulo anomalies
N=1 @ 1 k fps	99.9%, no tag gaps	749	old behaviour byte-for-byte; arq_e2e verdict stays acked_undelivered=0

Statistical-accounting check: the N=2 sampled ok-rate read 99.71% against a 99.99% ledger ground truth — pessimistic by the known ACK-loss asymmetry (ok=0-but-delivered), the safe direction for a delivery-accounting consumer.

Changes

• DeviceConfig::Tx::report bool → int (doc-tagged with the ceiling + the N ≥ fps/1300 rule); env parse clamps 0..255 (tag-unwrap ambiguity bound).
• J2/J3: tag every frame, request every Nth (both fields inside the checksummed span, re-checksum unchanged). J1: new _tx_ccx_ctr drives the cadence.
• tests/txrpt_coverage_attrib.py --sample-n — expected-delta accounting for sampled ledgers.
• tests/arq_e2e_delivery.sh — DRONE_REPORT_N passthrough.
• docs/scheduled-mac.md — the knob documented next to the measured envelope, favourable and adversarial numbers together.

Validation

Three fresh on-air runs (money/control/regression above); ctest 48/48; existing matrix scripts unaffected (they pin DEVOURER_TX_REPORT=1, whose semantics are unchanged).

🤖 Generated with Claude Code

[qodo-free-for-open-source-projects]

PR Summary by Qodo

DEVOURER_TX_REPORT as sampling divisor for deterministic CCX report coverage

✨ Enhancement 🧪 Tests 📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Change DEVOURER_TX_REPORT from boolean to sampling divisor N (0..255) to stay under CCX emission
 ceiling.
• Keep per-frame SW_DEFINE tagging on HalMAC chips; request reports every Nth frame for
 deterministic sampled coverage.
• Update coverage attribution tooling, e2e bench wiring, and docs with measured ceiling guidance.

Diagram

graph TD
  A["DEVOURER_TX_REPORT=N"] --> B["env_config.cpp"] --> C["DeviceConfig.tx.report (N)"] --> D["RtlJaguar* build_tx_block"] --> E{{"FW CCX report emit"}} --> F[("tx.report events")] --> G["txrpt_coverage_attrib.py"] --> H["scheduled-mac.md"]

  subgraph Legend
    direction LR
    _cfg["Config knob"] ~~~ _code["Code path"] ~~~ _fw{{"Firmware"}} ~~~ _data[("Event stream")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Auto-compute N from requested FPS (gap_us)

• ➕ Removes manual tuning; callers just set a target rate and get safe sampling.
• ➕ Avoids misconfiguration where N is too small and coverage collapses.
• ➖ FPS is not always known/constant (bursty traffic, external pacing), so auto-derived N can be wrong.
• ➖ Less explicit/reproducible for benches; changes behavior implicitly across workloads.

2. Adaptive sampling based on observed tag gaps / missed-rate

• ➕ Can react to real device/firmware ceilings and host load dynamically.
• ➕ Potentially maximizes coverage while staying under the emission ceiling.
• ➖ Control-loop complexity; risk of oscillation and harder-to-debug nondeterminism.
• ➖ Requires stable observation window and may lag during fast rate changes.

Recommendation: Keep the explicit divisor-N knob as implemented: it preserves deterministic, reviewable behavior and makes the sampled coverage invariant (HalMAC tag deltas are exact multiples of N) easy to validate. If needed later, add optional helper logic in bench scripts (not the device core) to suggest an N from gap_us/fps, rather than making runtime behavior implicit.

Files changed (9) +103 / -36

Enhancement (5) +48 / -18

DeviceConfig.hChange tx.report from bool to int with sampling semantics documentation +11/-2

Change tx.report from bool to int with sampling semantics documentation

• Updates DeviceConfig::Tx::report from bool to int defaulting to 0. Expands the docstring to define sampling divisor behavior, the CCX emission ceiling motivation, and the tag-delta invariant expected by consumers/tests.

src/DeviceConfig.h

RtlJaguarDevice.cppSample SPE_RPT on Jaguar1 using per-device counter +10/-4

Sample SPE_RPT on Jaguar1 using per-device counter

• Updates DEVOURER_TX_REPORT handling so SPE_RPT is set only on every Nth frame. Uses a new atomic counter to drive the cadence since the 8812 report format lacks SW_DEFINE tag echo, so sampling only reduces report rate (not attribution granularity).

src/jaguar1/RtlJaguarDevice.cpp

RtlJaguarDevice.hAdd atomic CCX sampling counter for Jaguar1 report cadence +5/-0

Add atomic CCX sampling counter for Jaguar1 report cadence

• Introduces _tx_ccx_ctr (atomic uint32) used to request CCX reports on every Nth frame when cfg.tx.report > 0. Comment clarifies Jaguar1’s lack of tag echo and the purpose of the counter.

src/jaguar1/RtlJaguarDevice.h

RtlJaguar2Device.cppTag every frame; sample SPE_RPT every Nth on Jaguar2 +11/-6

Tag every frame; sample SPE_RPT every Nth on Jaguar2

• Changes report request logic to always advance the SW_DEFINE tag per frame while only setting SPE_RPT when the per-frame tag counter modulo N hits zero. Keeps checksum recalculation behavior unchanged (idempotent).

src/jaguar2/RtlJaguar2Device.cpp

RtlJaguar3Device.cppTag every frame; sample SPE_RPT every Nth on Jaguar3 +11/-6

Tag every frame; sample SPE_RPT every Nth on Jaguar3

• Mirrors the Jaguar2 approach: SW_DEFINE tag increments every frame for continuous correlation, while SPE_RPT is asserted only every Nth frame. Preserves descriptor checksum recalculation and documents the emission-ceiling rationale and drop detection via off-modulo deltas.

src/jaguar3/RtlJaguar3Device.cpp

Tests (2) +45 / -15

arq_e2e_delivery.shPlumb DRONE_REPORT_N through to DEVOURER_TX_REPORT +2/-1

Plumb DRONE_REPORT_N through to DEVOURER_TX_REPORT

• Adds DRONE_REPORT_N (default 1) to control CCX report sampling for the drone-sim in the e2e delivery bench. Passes the value through to DEVOURER_TX_REPORT so benches can stay under the firmware emission ceiling at higher fps.

tests/arq_e2e_delivery.sh

txrpt_coverage_attrib.pyAdd --sample-n and sampled-coverage accounting +43/-14

Add --sample-n and sampled-coverage accounting

• Extends the analyzer to accept sample_n and compute expected sampled reports (submitted//N). Interprets tag deltas as multiples of N (k*N implies k-1 sampled reports lost) and flags non-multiples as anomalies; retains legacy coverage and gap histogram output for sample_n=1.

tests/txrpt_coverage_attrib.py

Documentation (1) +8 / -2

scheduled-mac.mdDocument DEVOURER_TX_REPORT sampling and N>=fps/1300 rule +8/-2

Document DEVOURER_TX_REPORT sampling and N>=fps/1300 rule

• Replaces the previous generic sampling guidance with the new semantics: DEVOURER_TX_REPORT=N requests a report every Nth frame while tagging every frame. Adds measured results (2.4k fps control vs N=2) and the rule of thumb to pick N to stay under the ~1.3–1.4k reports/s firmware ceiling.

docs/scheduled-mac.md

Other (1) +2 / -1

env_config.cppParse DEVOURER_TX_REPORT as integer sampling divisor (clamped) +2/-1

Parse DEVOURER_TX_REPORT as integer sampling divisor (clamped)

• Switches DEVOURER_TX_REPORT parsing from a boolean flag to env_long(). Clamps the parsed value to 0..255 and stores it into cfg.tx.report.

examples/common/env_config.cpp

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Sampling wrap breaks cadence ✓ Resolved 🐞 Bug ≡ Correctness

Description

Jaguar2/Jaguar3 gate SPE_RPT with _tx_rpt_tag (16-bit) modulo N, so the sampling phase resets
every 65,536 frames and produces off-modulo tag deltas even when no reports were dropped. This
violates the PR’s deterministic-sampling contract for long-running sessions (e.g., N=3 yields a
delta of 1 at wrap).

Code

src/jaguar2/RtlJaguar2Device.cpp[R1531-1534]

+    const uint16_t k = _tx_rpt_tag.fetch_add(1);
+    SET_TX_DESC_SPE_RPT_8822B(
+        out, k % static_cast<uint16_t>(_cfg.tx.report) == 0 ? 1 : 0);
+    SET_TX_DESC_SW_DEFINE_8822B(out, k & 0xff);

Evidence

The PR changes Jaguar2/Jaguar3 to sample reports using k % N == 0, but k comes from a uint16_t
counter. A uint16_t wrap causes the sampling condition to restart at 0, producing a short (or
otherwise non-N) interval across wrap for most N; the analyzer computes tag deltas modulo 256, so
this shows up as an off-modulo delta even with zero drops.

src/jaguar2/RtlJaguar2Device.cpp[1523-1535]
src/jaguar2/RtlJaguar2Device.h[251-253]
src/jaguar3/RtlJaguar3Device.cpp[2001-2013]
src/jaguar3/RtlJaguar3Device.h[251-253]
tests/txrpt_coverage_attrib.py[60-64]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Jaguar2/Jaguar3 decide whether to request a CCX report via `k % N == 0`, but `k` is taken from `_tx_rpt_tag`, which is only 16 bits. When it wraps (every 65,536 frames), the next sampled index is `0`, and the interval between requested reports across the wrap becomes `65536 % N` (not `N`), producing non-multiple-of-N tag deltas and false “dropped/anomaly” signals.
### Issue Context
- The low 8 bits of SW_DEFINE are echoed back in the report; the analyzer checks `(tag - prev_tag) % 256`.
- Sampling correctness depends on the request cadence being stable across long runs.
### Fix Focus Areas
- src/jaguar2/RtlJaguar2Device.h[251-253]
- src/jaguar3/RtlJaguar3Device.h[251-253]
- src/jaguar2/RtlJaguar2Device.cpp[1531-1534]
- src/jaguar3/RtlJaguar3Device.cpp[2009-2012]
### Implementation notes
- Change the counter used for sampling to `std::atomic<uint32_t>` (either widen `_tx_rpt_tag` or add a separate `_tx_rpt_ctr`).
- Keep SW_DEFINE as `k & 0xff` (still 8-bit), but compute `SPE_RPT` from the wide `k` so wrap is practically unreachable.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. expected miscounts sampled reports ✓ Resolved 📎 Requirement gap ≡ Correctness

Description

The sampled-ledger analyzer in tests/txrpt_coverage_attrib.py computes `expected = submitted //
sample_n`, which undercounts expected reports because sampling requests a report on frame 0 and then
every Nth frame (requiring ceiling division). This can inflate sampled coverage (even >100%), hide
dropped sampled reports, and distort loss attribution, violating the requirement that tooling
correctly interprets sampled ledgers.

Code

tests/txrpt_coverage_attrib.py[76]

+        expected = submitted // sample_n

Evidence

PR Compliance ID 2 requires analysis tooling to correctly interpret sampled ledgers, but the
analyzer’s sampled-path sets expected = submitted // sample_n (floor division). On the
device/firmware side, reports are requested when k % N == 0 with k starting at 0 (because
fetch_add(1) returns the pre-increment value), producing requests at indices 0, N, 2N, ...; this
implies there is at least one request for any non-empty run and, in general, the expected count
follows ceil(submitted / N) rather than floor division. Therefore the current computation can
undercount expected, making calculated sampled coverage erroneously high and masking losses.

Implement deterministic SPE_RPT sampling via DEVOURER_TX_REPORT=N and update analyzer for sampled ledgers
tests/txrpt_coverage_attrib.py[72-87]
tests/txrpt_coverage_attrib.py[72-89]
src/jaguar2/RtlJaguar2Device.cpp[1531-1534]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`tests/txrpt_coverage_attrib.py` miscomputes the expected number of sampled reports for `--sample-n > 1` by using floor division (`expected = submitted // sample_n`). Because the device requests a report on index/frame 0 and then every Nth frame (`0, N, 2N, ...`), the correct expected count is `ceil(submitted / N)` (with `submitted == 0` yielding `expected == 0`), otherwise sampled coverage can be overstated (even >100%) and losses can be masked.
## Issue Context
This script is used to validate deterministic sampling behavior (`DEVOURER_TX_REPORT=N`) and to attribute/report coverage and loss. Device-side sampling uses the condition `k % N == 0` with `k` starting at 0 (due to `fetch_add(1)` returning the pre-increment value), so any non-empty submission run produces at least one expected sampled report even when `submitted < N`.
## Fix Focus Areas
- tests/txrpt_coverage_attrib.py[72-89]
- src/jaguar2/RtlJaguar2Device.cpp[1531-1534]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. tx.report docs out-of-date ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

docs/aggregation.md still says DEVOURER_TX_REPORT sets SPE_RPT in every descriptor, but the PR
changes semantics to a sampling divisor N where reports are only requested every Nth frame. This can
mislead users configuring report sampling and interpreting coverage.

Code

src/DeviceConfig.h[R224-227]

+     * Value = sampling divisor N: 1 requests a report on EVERY frame, N > 1
+     * on every Nth (0..255). The CCX emission path saturates at ~1.3–1.4 k
+     * reports/s (docs/scheduled-mac.md), so above ~1.25 k fps pick
+     * N >= fps/1300 and coverage of the SAMPLED frames stays deterministic

Evidence

The docs explicitly claim SPE_RPT is set on every descriptor when the knob is enabled, but the
updated config comment and the Jaguar2/Jaguar3 descriptor build code implement divisor-based
sampling instead.

docs/aggregation.md[54-66]
src/DeviceConfig.h[215-232]
src/jaguar2/RtlJaguar2Device.cpp[1523-1534]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Documentation in `docs/aggregation.md` still describes `DEVOURER_TX_REPORT` / `tx.report` as a per-frame boolean that sets `SPE_RPT` on every descriptor. After this PR, `tx.report` is an integer sampling divisor N and `SPE_RPT` is only asserted every Nth frame.
### Issue Context
`src/DeviceConfig.h` now documents `tx.report` as “Value = sampling divisor N”. Jaguar2/Jaguar3 implement this by setting `SPE_RPT` based on `k % N == 0`.
### Fix Focus Areas
- docs/aggregation.md[54-66]
- src/DeviceConfig.h[215-232]
### Implementation notes
- Update the `docs/aggregation.md` section to describe: 0=off, 1=every frame, N>1=every Nth frame.
- Mention that HalMAC chips still stamp SW_DEFINE every frame (continuous tag) while SPE_RPT is sampled.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}