docs: scaffold Axyl glossary for cross-sphere terminology

[bdimitrov-netzine]

Summary

• Add doc/glossary.md: a glossary for terms that mean different things across code, on-chain, and networking spheres in Axyl (Network/Networking layer, Whitelist/Allowlist, Validator/Observer/Node, Round, Epoch, Batch, Bridge, CVV states), each entry grounded with a link to the actual code that defines that sense.
• Motivated by design-doc discussions repeatedly conflating "networking layer" meaning the whole node vs. the libp2p consensus crate (crates/consensus/network) — this page exists to disambiguate overloaded terms before they cause confusion in a design doc, PR description, or Slack thread.
• Link the new page from doc/README.md's "I want to understand how the system works" section.
• Includes a "Candidate terms" section (currently just Committee) and an "Adding a term" section describing when a term qualifies (two people using the same word to mean different things) and how to add one.

Test plan

• Skim doc/glossary.md and confirm the linked code references (line numbers, file paths) are accurate
• Confirm the new entry renders correctly from doc/README.md

[github-actions]

Security Scan - Code

Severity: HIGH, CRITICAL

No vulnerabilities found

View scan results

Report Summary

┌─────────────────────────────────────────────┬────────────┬─────────────────┬───────────────────┐
│                   Target                    │    Type    │ Vulnerabilities │ Misconfigurations │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ Cargo.lock                                  │   cargo    │        0        │         -         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ crates/testing/fuzz-targets/Cargo.lock      │   cargo    │        0        │         -         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ crates/testing/fuzz-targets/fuzz/Cargo.lock │   cargo    │        0        │         -         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ etc/state-sum/Cargo.lock                    │   cargo    │        0        │         -         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ etc/tps/package-lock.json                   │    npm     │        0        │         -         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ rayls-contracts/package-lock.json           │    npm     │        0        │         -         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ etc/chaos-network/Dockerfile                │ dockerfile │        -        │         0         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ etc/docker-network/Dockerfile               │ dockerfile │        -        │         0         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ etc/docker-replay/Dockerfile                │ dockerfile │        -        │         0         │
└─────────────────────────────────────────────┴────────────┴─────────────────┴───────────────────┘
Legend:
- '-': Not scanned
- '0': Clean (no security findings detected)

[github-actions]

Claude finished @bdimitrov-netzine's task in 3m 1s —— View job

---

PR Review

• Gather context and read changed files
• Verify code references (line numbers, file paths) in glossary
• Review content quality and structure
• Post review findings

---

This is a well-executed documentation PR. I verified every file path and line number in the glossary against the actual codebase — all are accurate. Here's the full breakdown:

Code reference verification

Glossary claim	Verified
Round type at types/src/primary/mod.rs:38	✓ pub type Round = u32; at line 38
Epoch type at types/src/committee.rs:19	✓ pub type Epoch = u32; at line 19
Batch struct at worker/sealed_batch.rs:63	✓ struct starts at line 63; all described fields (transactions, epoch, beneficiary, base_fee_per_gas, worker_id, seq) are present
NodeMode enum at consensus_bus.rs:146	✓ enum at line 146; all three variants match exactly
Observer description "follower not in the committee (staked or unstaked)" at consensus_bus.rs:151	✓ verbatim from the doc comment at line 151
Bullshark leader election at bullshark.rs:133	✓ if !r.is_multiple_of(2) || r < 2 at line 133
is_batch_producing() = CvvActive | Observer (excludes CvvInactive)	✓ matches!(self, NodeMode::CvvActive | NodeMode::Observer) at line 177; code comment at 173-175 matches the glossary's reasoning verbatim
Bridge Subscriber at bridge/src/subscriber.rs:43	✓ struct at line 43
check_whitelist, MINTING_MODULE_ADDRESS in native_erc20/precompile.rs	✓ both symbols present
All linked .md doc pages	✓ crates/rayls-network.md, crates/consensus/network.md, crates/index.md, index.md, SYNC.md, etc/validator/README.md, etc/observer/README.md all exist

Content quality

The glossary structure is well-designed: each entry lists senses by sphere, gives a canonical name to use, links to the defining code, and has a "Don't confuse with" guidance. The NodeMode / CVV states entry is particularly well-grounded — the batch-production exclusion of CvvInactive with its exact failure mode ("sealed batch wedges the worker on report_own_batch") matches the code comment at consensus_bus.rs:173-175 word-for-word.

The doc/README.md placement under "I want to understand how the system works" is correct.

Minor observations (nothing blocking)

1. Epoch in ## Ambiguous terms (glossary.md:85-100): The entry is placed under the ## Ambiguous terms heading but the text explicitly says "this isn't a case of two competing meanings." This is self-contradictory structurally. It could move to its own ## Related terms section, or keep a note in the header explaining that some entries are "easy to transpose" rather than genuinely ambiguous — the current explanation is good, the section heading just doesn't quite fit. Not blocking, but might confuse a reader skimming headings.

2. Bridge dedup claim (glossary.md:118): The glossary says the Subscriber "dedups" — the struct doc comment doesn't mention dedup explicitly (it says "wait until downloaded all transactions…then forward"). The HashSet import in the module suggests dedup likely does happen, but the claim isn't sourced to a specific line. Worth a quick inline comment pointing at where that happens (or trimming "dedups" if it's incidental).

3. Bullshark even-round nuance (glossary.md:81): "leaders are elected on even rounds only" — technically the check is on r = round - 1, so even-numbered leader rounds (2, 4, 6…) correspond to odd-numbered certificate rounds (3, 5, 7…). The statement is correct — it matches the code comment exactly — but a reader could misread it as certificate rounds. This is subtle and the linked line makes it easy to verify; just noting it in case the team wants to add a parenthetical.

Summary

All code references check out. The content is accurate, well-grounded in code rather than invented descriptions, and the governance model (criteria for adding entries, candidate list) is a good pattern. The three observations above are minor polish; none warrants blocking the merge.