[aferaudo]

Summary

• Aligns the E3SM-SPEC specification in docs/e3sm/spectrum/ with the current Spectrum grammar. The specification described an older grammar. Now:
  • the indication is Spectrum-Indication, with the sensing indication and a new cell configuration indication. That indication gives the carrier PRBs, the offset, the subcarrier spacing, point A, the slots per frame, the TDD pattern and the PCI. The RAN sends it about once a second, stamped on the monotonic clock;
  • the PRB block control has no samplingThreshold. The field referred to IQ captures, which the service model does not carry;
  • validityPeriod is in milliseconds, 1 to 3600000, in the PRB block and in the sensing policy;
  • clause 8 holds the full grammar;
  • the RAN function description is the text that the OpenAirInterface RAN sends.
• Annex A lists the revisions of the grammar and what each one does on the wire. Annex B is new: a complete exchange in APER and JSON, from the setup to the PRB block, plus an apply outcome.
• The integrator guide now points at OpenAirInterface 20bb1a934d. It covers the cell configuration indication. It also covers controls 3 and 4 of that RAN (sensing reservation, PUSCH slots), which the specification does not define.

The PR is one commit, 8dc4a0d, on top of main. The Word edition is built with the plain template of #142.

Type of change

• Bug fix
• New feature / enhancement
• New Service Model
• Refactor (no behavior change)
• Documentation
• Test / CI / packaging
• Other (explain):

Linked issue

No issue: the change follows the current grammar of the Spectrum service model.

Twin-repo coordination

libe3 is paired with dapps and dApp-openairinterface5g. We do not accept patches that break or reduce compatibility with the twin repositories.

• This PR does not change the E3 wire protocol or public ABI, OR a paired PR exists in each affected twin repo (link below).
• This PR does not change the wire format or a behavior a peer (OAI, Aerial, OCUDU) can observe, OR I added a row to the change ledger in docs/interop.md.

The second box is not ticked. libe3 itself does not change: no code, and no E3AP grammar. But the service model now differs from what the OpenAirInterface RAN and the dApp library encode today in two places:

• the removed samplingThreshold;
• the unit of validityPeriod.

Both matter only when a control carries one of these optional fields. Annex A gives the effect in APER, JSON and Protocol Buffers. I added no row to docs/interop.md, because its ledger tracks the behavior of libe3.

Paired PR(s): none yet. An implementation of these changes needs paired PRs in dApp-openairinterface5g and dapps.

Checks run

All on the tree of 8dc4a0d:

• The grammar compiles with asn1tools (APER and JER), and clause 8 holds it unchanged.
• I compared the grammar on the wire with the grammar of the OpenAirInterface RAN at 20bb1a934d, with asn1tools.
  • Every message type gives the same octets: the RAN function data, both indications, the dApp report, the xApp control (prbBlockedControl and configControl), the apply outcome, and a PRB block control and a sensing policy without optional fields.
  • A PRB block control or a sensing policy that carries an optional field differs. Annex A lists those cases.
• Annex B is the output of the generator against main's messages/asn1/V1/e3ap-1.0.0.asn1. Every message decodes back to the same value.
• The Word edition is built in the container of tools/oran_docx/Dockerfile.
  • It passes OOXML schema validation against tools/oran_docx/template.docx.
  • The LibreOffice PDF has 45 pages.
  • It has not been opened in Microsoft Word.
• reuse lint passes. A strict Doxygen build (LIBE3_DOCS_STRICT=ON, Doxygen 1.9.8, Ubuntu 24.04, the options of docs.yml) shows 0 warnings in docs/e3sm/spectrum/. Both ran locally in a container.
• scripts/check_commit_trailers.py --base origin/main --head HEAD passes.

Open points for review

1. Extension marker on the indication. Spectrum-Indication has no extension marker, so a third kind of indication would change the width of its alternative index. Should it get one now, while the change costs one bit?
2. Expiry. The RAN decodes validityPeriod and does not apply it, so a block or a policy does not expire. Should the field become a lease that the RAN enforces?
3. Unit of noiseFloorThreshold. Spectrum-ConfigControl gives no unit for it, and no codec implements the control.

🤖 Generated with Claude Code

[github-actions]

CI report — 8dc4a0d — ✅ all checks passed

Workflow	Result	Time	Run
Commit policy	✅ success (steps skipped — no code changes)	0m21s	#227
Docs	✅ success	0m34s	#29
Build libe3py wheels	⏭️ not started (no changed file matches its paths filter)	—	—
E2E dApp Integration	⏭️ not started (no changed file matches its paths filter)	—	—
E2E Topologies (multi-dApp / multi-RAN)	⏭️ not started (no changed file matches its paths filter)	—	—
Full-loop Latency Benchmark	⏭️ not started (no changed file matches its paths filter)	—	—
latrec portability	⏭️ not started (no changed file matches its paths filter)	—	—
MPMC Queue Benchmark	⏭️ not started (no changed file matches its paths filter)	—	—
Unit Tests	⏭️ not started (no changed file matches its paths filter)	—	—

Docs

Doxygen warnings

0 warning(s) in the files this pull request changes, which fail the check; 403 more elsewhere, which do not. The full list is in the job log and the doxygen-warnings artifact of the Docs workflow.

Gaps in files this pull request does not change, by file:

Warnings	File
53	include/libe3/types.hpp
37	include/libe3/sm_interface.hpp
35	include/libe3/e3_connector.hpp
34	include/libe3/e3_agent.hpp
32	include/libe3/e3_interface.hpp
29	include/libe3/c_api.h
19	src/c_api.cpp
17	include/libe3/logger.hpp
17	swig/libe3_swig.hpp
17	swig/e3_dapp_session.hpp

Ready to merge (fast-forward only)

A maintainer can land the reviewed commits with:

git fetch origin
git checkout main && git merge --ff-only 8dc4a0d4020600ead364c32299c3433492f69782 && git push origin main

Head: 8dc4a0d4020600ead364c32299c3433492f69782 (branch docs/e3sm-spectrum-grammar). If --ff-only fails as non-fast-forward, the branch must be rebased on the latest main.

One comment per PR, rewritten in place once every workflow for 8dc4a0d finished.