docs(protocols): tighten the internet-layer prose and correct stale claims (#719)

[JarryShaw]

• Searched for similar pull requests
• Followed the coding style (docstrings and comments only)
• Tests pass (tests/protocols/internet, tests/project, tests/test_docstring_contract.py); no code change, so no new test case
• Changelog entry: N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

• docs — documentation only

---

Description

Internet-layer half B of the #719 prose sweep (ah, hip, hopopt, internet, ipv4, ipv6_ext, ipv6_opts, ipv6_route, ipx). Cuts timed context, keeps rationale, and fixes prose that disagreed with the code:

• ipv4: the field table named a DSCP split the parser never performs; it now lists the tos.pre/del/thr/rel/ecn fields. EOOL/NOP cited RFC 719, now RFC 791.
• ipv6_ext: five stale file:line references and a non-existent PCAPNG.read_frame replaced by the real warn-and-clip sites.
• ah/ipx: wrong table field names and a wrong Returns type. ipv6_route: the src_ip/dst_ip overload-only discrepancy is recorded as deliberate (IPv6_Route.__post_init__ documents src_ip/dst_ip, which exist only in an @overload stub #505).
• Verbatim RFC quotes and AH's registry wording stay, because tests/test_docstring_contract.py and test_ah_unit.py pin them.

AST equal to origin/main once bare-string statements are stripped:

file	equal
ah.py	True
hip.py	True
hopopt.py	True
internet.py	True
ipv4.py	True
ipv6_ext.py	True
ipv6_opts.py	True
ipv6_route.py	True
ipx.py	True

Sphinx -n, fresh dirs, branch vs origin/main: 12 vs 12 warnings on these files, 0 new (whole log 1315 vs 1315 lines).

[JarryShaw]

Cross-review verdict on 1673a955e: NEEDS CHANGES (ran on Opus; authored on Sonnet). Two sentences that were true before the rewrite are now false. I re-checked both against the code.

1. ipv6_route.py:517-518 now says a check treating Hdr Ext Len as a total octet count "never matches". The removed check (7c83e5b72, fix(ipv6-route): compute Hdr Ext Len in 8-octet units on both sides #489) was (header.length - 8) % 16 != 0, and that check does match: it accepts lengths 8, 24, 40 and 56, which are the well-formed headers carrying 4, 12, 20 and 28 addresses, and rejects every other even value. The old wording was true: the check assumed the field was an octet count. Restore it, or say the check rejected most well-formed headers.
2. hopopt.py:364-365, and the same sentence in ipv6_opts.py, now say rounding up "would hide a misaligned area instead of failing". Nothing fails here. (total_length - 6) // 8 floors silently, and no alignment check runs before the Schema_HOPOPT(...) return. Drop "instead of failing", or state what the floor actually relies on: _make_hopopt_options has already aligned the header.

Confirmed with real parses and probes:

• The ipv4.py TOS table is right: info.tos holds pre/del/thr/rel/ecn at the stated widths, offset and protocol exist, and dsfield, frag_offset and proto do not. EOOL and NOP correctly cite RFC 791.
• ipv6_ext.py: no PCAPNG.read_frame exists, FieldBase.pack never warns, and bounded_option, bounded_area and PCAPNG.read each warn and clip. All seven old line references were stale. ExtensionHeader has 11 members.
• The ah/ipx field names and the IPX.make return type are right. LOCATOR_SET is conformant only by accident: nested Locator.len shadows the parameter in padding, and len is in 4-octet units where RFC Length is bytes #679 is closed, so the hip.py comment was stale.
• On ipv6_route.py, src_ip and dst_ip are declared only in the overload stub, and the "do NOT simplify" guard is intact.
• No rationale was lost.
• Tests, each run in a separate process: 86 passed and 170 subtests across test_docstring_contract, ah, ipv6_ext, ipv4, ipx, internet and the two hip_* modules. The rest of tests/protocols/internet/ is left to CI, because a single pytest over that directory grew past 12 GB.

[JarryShaw]

Cross-review verdict on ed6bda0e4: GOOD TO GO (ran on Opus; authored on Sonnet). Both round-1 findings are fixed, and each new sentence checks out against the code.

• ipv6_route.py:517-518, "a check that assumes it is a total octet count rejects most well-formed headers": true. Hdr Ext Len is one octet, so there are 128 well-formed even values. The old (L-8) % 16 check accepted only the 16 that are 8 mod 16 and rejected the other 112, which is 87.5%. "Assumes" is accurate too: subtracting 8 octets and then requiring a multiple of 16 octets only makes sense if L counts octets.
• hopopt.py:364 and ipv6_opts.py:356, "this division is exact and rounding up is unnecessary": true. Each file names its own helper, and each helper finishes with a pad that makes (total_length + 2) % 8 == 0 (hopopt.py:1375-1377, ipv6_opts.py:1364/:1395). Headers built through make() with mixed option sets always came out a multiple of 8 on the wire, with (HdrExtLen + 1) * 8 equal to the wire length.
• Scope: range-diff shows only these three comment hunks, and all nine files are AST-identical to main. Each test module was run in its own process: test_docstring_contract 7 passed, test_ipv6_ext_unit 31, test_ipv6_extension_unit 61. The rest of tests/protocols/internet/ is left to CI.