[josephnef]

Closes the last open M1 deliverable of #255, the UeRegistry per-UE state ("timing advance, and a per-UE RX-quality window built from M0's per-frame attribution"). Epic #254.

What

• src/cell/TimingAdvance.h: TaLoop, the DU's per-UE TA loop, moved unchanged from examples/cell/cell.h, which keeps a using.
• src/cell/UeRegistry.h: a UeContext per scheduled UE id: its TaLoop and its latest uplink-quality window (UeRxWindow: RSSI, SNR, EVM, noise floor of its own frames, attributed per transmitter by M0's UeRxAttribution, not the device-wide GetRxQuality).
  • A context comes with bind/admit and is dropped with release; context(ue) creates one for an id scheduled otherwise (a handover arrival before its admission); reset_context starts it over.
  • rx_frame() attributes an uplink frame; close_rx_window(ue_of) closes the window into each UE's context. The address-to-UE mapping is the caller's.
• DU (examples/cell): keeps its TA in the contexts instead of its own map, feeds each verified own-UE uplink into the attribution, and closes the window on its TA cadence (cell.ue_rx).
• One behaviour change: an id reused by another UE starts with a fresh TA. The old map kept the departed UE's TA for the next holder.
• Selftests (cell_m3): context lifetime with bind, re-join, release and reuse; reset; window attribution and foreign transmitters ignored.

Link adaptation still steers on the SNR the UE reports for the downlink. The uplink window is the DU's own per-UE measurement, which #566 (EVM over F1) can now draw on.

Rig (on this code): m1_cell_2ue passes (both UEs in slot both ways, 0 overlaps). Each UE's uplink window logged every 2 s: 20 frames median, RSSI −51 / −53 dBm, SNR 38 / 39 dB, EVM −33 / −31 dB. m3_cell_rach --leave-at passes (joined, released 51 sf after its last uplink), and so does m6_handover.

🤖 Generated with Claude Code

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

PR Summary by Qodo

Keep per-UE timing advance and uplink quality in UeRegistry

✨ Enhancement 🐞 Bug fix 🧪 Tests 📝 Documentation 🕐 20-40 Minutes

AI Description

• Give each scheduled UE a registry-owned TA loop and attributed uplink-quality window.
• Reset per-UE state on release and ID reuse, preventing a new UE from inheriting stale TA.
• Log per-UE uplink quality on the DU’s TA cadence and test context lifetimes and attribution.

Diagram

graph TD
  DU["Cell DU"] --> REG["UE registry"] --> CX["UE context"] --> TA["TA loop"]
  REG --> ATTR["RX attribution"]
  DU --> LOG["UE RX logs"]

Loading

High-Level Assessment

Registry ownership fits the existing UE binding and release lifecycle, while reusing the existing attribution logic and unchanged TA loop. Keeping a separate DU TA map would preserve the stale-state risk on ID reuse.

Files changed (6) +236 / -68

Enhancement (2) +97 / -13

main.cppWire DU timing advance and uplink quality through UeRegistry +30/-13

Wire DU timing advance and uplink quality through UeRegistry

• Replaces the DU’s TA map with registry contexts across uplink handling, scheduling, rollback, and handover cleanup. Feeds verified uplinks into attribution and logs closed per-UE quality windows on the TA cadence.

examples/cell/main.cpp

UeRegistry.hOwn per-UE contexts and receive windows +67/-0

Own per-UE contexts and receive windows

• Adds contexts containing a configured TA loop and the latest attributed uplink-quality window. Admission, release, explicit creation, and reset manage context lifetime; window closure maps transmitter addresses to UE IDs.

src/cell/UeRegistry.h

Refactor (2) +84 / -55

cell.hUse the library timing-advance loop +3/-55

Use the library timing-advance loop

• Removes the example-local TaLoop definition and aliases the unchanged implementation from the new library header.

examples/cell/cell.h

TimingAdvance.hMove TaLoop into the cell library +81/-0

Move TaLoop into the cell library

• Provides the existing median-based, bounded timing-advance loop as a reusable header for per-UE contexts.

src/cell/TimingAdvance.h

Tests (1) +33 / -0

cell_m3_selftest.cppTest context lifetime and uplink attribution +33/-0

Test context lifetime and uplink attribution

• Checks TA retention on re-admission, reset on release and ID reuse, and explicit context reset. Verifies per-transmitter window storage, foreign-transmitter filtering, and drain behavior.

tests/cell_m3_selftest.cpp

Documentation (1) +22 / -0

cell-m1.mdDocument registry-owned per-UE state +22/-0

Document registry-owned per-UE state

• Explains context lifetime, transmitter-attributed uplink windows, and how the DU logs them. Records rig results and clarifies that link adaptation still uses UE-reported downlink SNR.

docs/cell-m1.md

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

Code Review by Qodo

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

1. Rig results quoted without failing cases 📘 Rule violation ◔ Observability

Description

The new per-UE section of docs/cell-m1.md quotes only favourable rig outcomes (m1_cell_2ue
passing, RSSI, SNR and EVM values, passing joiner and handover runs) with no failing or degraded
case and no run count. It also says median next to the window, while the logged cell.ue_rx
values are means, so a reader would take these figures as the typical operating point.

Code

docs/cell-m1.md[R108-113]

+**Rig:** `m1_cell_2ue` passes on this code (both UEs in slot both ways, no
+overlaps). The DU logged each UE's uplink window every 2 s: 20 frames per
+window (median, both UEs), RSSI −51 / −53 dBm, SNR 38 / 39 dB, EVM −33 /
+−31 dB. The joiner's context (`m3_cell_rach --leave-at`: joined, then
+released 51 superframes after its last uplink) and handover arrivals
+(`m6_handover`) pass too.

Evidence

The added paragraph presents only passing rig results and single favourable measurements without an
adversarial counterpart, which the rule forbids. The cell.ue_rx event emits per-window means
(rssi_mean_dbm, snr_mean_db, evm_mean_db), so the median wording does not match the logged
statistic.

CLAUDE.md: Keep Cross-Cutting Documentation Focused and Balance Measurement Claims: CLAUDE.md: Keep Cross-Cutting Documentation Focused and Balance Measurement Claims: CLAUDE.md: Keep Cross-Cutting Documentation Focused and Balance Measurement Claims: CLAUDE.md: Keep Cross-Cutting Documentation Focused and Balance Measurement Claims: CLAUDE.md: Keep Cross-Cutting Documentation Focused and Balance Measurement Claims: CLAUDE.md: Keep Cross-Cutting Documentation Focused and Balance Measurement Claims: CLAUDE.md: Keep Cross-Cutting Documentation Focused and Balance Measurement Claims: CLAUDE.md: Keep Cross-Cutting Documentation Focused and Balance Measurement Claims
docs/cell-m1.md[108-113]
examples/cell/main.cpp[2835-2841]

Agent prompt

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

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
Issue description: `docs/cell-m1.md` quotes favourable rig results for the per-UE uplink window (RSSI, SNR, EVM, and passing m1/m3/m6 runs) without adversarial counterparts, and its 'median' wording does not match the logged means.
Fix Focus Areas:
- docs/cell-m1.md[108-113]
- examples/cell/main.cpp[2835-2841]
Recommended Fix: In the Rig paragraph, state the statistic actually logged (per-window mean) and the run count and conditions. Add the adversarial side: a failing or degraded case, or explicitly say none was measured. Remove the 'median' wording unless the code is changed to report a median.

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

---

2. UE quality stops when timing is off ✓ Resolved

Description

run_du places reg.close_rx_window() inside the timing-advance block even though its receive
callback feeds the window independently of ta_on. When CELL_TA=0, samples continue accumulating
but no window is closed or reported, and the attribution table eventually stops accepting new
transmitters.

---

3. Released UEs can regain stale state 🐞 Bug ≡ Correctness

Description

close_rx_window() calls the context-creating context(ue) for every retained transmitter window,
without checking whether that UE still has a context or clearing pending samples on release or
reset. If a UE leaves before the next close, its old frames can recreate its released context or
populate the quality window of a subsequent holder of the same ID.

Code

src/cell/UeRegistry.h[R95-98]

+      UeContext &c = context(ue);
+      c.rx = w;
+      c.have_rx = true;
+      out.emplace_back(ue, w);

Evidence

Release erases the context but leaves the separate attribution accumulator intact. The next snapshot
maps retained frames by transmitter ID and uses context(), which creates a missing context;
admission can also reset that ID before those frames are drained.

src/cell/UeRegistry.h[69-80]
src/cell/UeRegistry.h[88-100]
src/cell/UeRegistry.h[114-142]
src/cell/UeRxAttribution.h[119-145]
examples/cell/main.cpp[3064-3075]

Agent prompt

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

## Issue description
Pending RX samples survive context release and reset, and closing the window can recreate a released UE context or assign old samples to a reused ID.
## Fix Focus Areas
- src/cell/UeRegistry.h[79-101]
- src/cell/UeRegistry.h[114-142]
- examples/cell/main.cpp[1751-1758]
## Recommended Fix
Prevent window closure from creating absent contexts, and invalidate pending attribution for an ID when its holder is released or replaced. Feed samples only for currently eligible UE contexts.

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

---

View review recommended (1)

4. UE reports understate mixed-frame SNR ✓ Resolved

Description

run_du feeds raw SNR into UeRxAttribution, whose SNR sum and minimum include zero values even
though zero denotes an absent measurement. When an uplink-quality window contains frames without
SNR, the newly emitted mean is biased downward and its minimum becomes zero rather than the minimum
measured SNR.

---

Tip of the day

💡 Did you know, you can start a comment with 'qodo' or '@qodo' to chat about any finding

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[josephnef]

Review fixes pushed:

1. Rig results without failing cases or counts — the docs now give the run count (one each), the window counts (60 per UE), and say the 20 frames is the median of full windows, with the partial edge windows (9 and 4 frames) and why. They also name what wasn't run: a reused id within one window, which mixes both holders' frames, since the transmitter address is id-based.
2. UE quality stops with CELL_TA=0 — fixed. The window closes on its own timer, at the TA cadence, whether or not the TA loop runs.
3. Released UEs regain stale state — fixed. close_rx_window only fills contexts that still exist; it never creates one, so frames buffered before a release can't recreate it. Test: release between frames and the close → no context.
4. SNR biased by frames without one — fixed at the source, in UeRxAttribution (M0). SNR is folded only from frames that carry one, with its own count and a snr_valid flag, so the minimum is never the 0 placeholder. The log carries snr_ok. Test: 20 dB + none + 15 dB → mean 17.5, min 15.

Rig on this build: m1_cell_2ue passes; 121 uplink windows logged, with SNR valid.

[josephnef]

Qodo's re-review resolves #2 and #4. On the other two:

• Fix unreadable code in logs #3 — the rest of it is now fixed too. Besides never recreating a released context, the first window closed after a context begins is skipped (rx_fresh). It may hold the previous holder's frames, because a reused id has the same transmitter address. The cost is a new UE's first 2 s window. The test checks that the first window after admission is skipped and the next one reported.
• Small mods to build on android #1 — the docs carry the run counts, the partial edge windows, the median's basis, and the one case not run on the rig (a reused id within one window), now covered by the skip above.

Adding skip-qodo-gate.