docs(protocols): tighten application, link and root protocol prose (#719)

[JarryShaw]

• Searched for similar pull requests
• Followed the coding style (docstrings and comments only; no code touched)
• make test passes, and a test case covers the change (prose only: existing modules for the slice, tests/project and tests/test_docstring_contract.py pass, one module per process)
• 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?

• fix
• feat
• perf
• refactor
• test
• docs — documentation only
• ci
• chore

---

Description

Prose sweep (#719) for pcapkit/protocols/application/, pcapkit/protocols/link/ and protocol.py. Cuts timed context and narrative, keeps rationale and rejected-option reasoning, and fixes prose that disagreed with code: ARP._read_proto_resolve, _make_proto_resolve and _make_addr_resolve returns, and the httpv2.unpack note about a struct.error path that FieldBase.length now converts to ProtocolError. The ProtocolBase.register and Link.register Warns: contracts are unchanged in meaning.

Sphinx -n, fresh dirs, branch vs origin/main: 106 vs 106 warnings on these files after normalising paths and line numbers, 0 new.

AST guard (docstrings stripped, compared with origin/main):

file	identical
application/ftp.py, http.py, httpv1.py, httpv2.py, ngap.py, ospf.py, rarp.py	True (all 7)
link/arp.py, l2tp.py, l2tpv2.py, link.py, s_tag.py	True (all 5)
protocol.py	True

[JarryShaw]

Cross-review verdict on 742261b56: NEEDS CHANGES (ran on Opus; authored on Sonnet). Two small items. I confirmed both on the branch. Every behavioural rewrite in the PR holds.

1. protocol.py:733-734: ProtocolBase.register's Warns: says it warns "If code is already registered", with no condition. Re-registering the same class over a resolved entry counts as already registered, but it is silent. The Note in the same docstring already states the condition correctly, and so does Link.register (link/link.py:132-138). Add the "incumbent differs from the replacement" qualifier. The line predates this PR, but it is the last unconditional "when register warns" sentence in the slice.
2. application/__init__.py:30: # Deprecated / Base Classes sits above HTTP, which is a base class but is not deprecated. Change it to # Base Classes, as docs(protocols): tighten the internet-layer prose and cut timed context (#719) #1035 does for internet/__init__.py.

Confirmed by probe on this head:

• The register Note keeps "unresolved" and survives the decode write-back. No "warns once" wording anywhere in the slice.
• All four ARP return types.
• HTTP/2: 4,018 fuzzed frames across four parse paths raised no bare struct.error. The _guess_version suppression rationale is still stated, and its 15 tests pass.
• NGAP Criticality.get behaves as documented in all four cases, and _missing_ is attributed correctly.
• Dropping HTTP.make calls the versioned make unbound on the class, so it raises TypeError for every real call #452 is a legitimate cut. It was the bug report for the old behaviour, and the design reason survives.
• Counts check out: 81 / 4.9 MB / 115 unbound.

Found along the way, filed separately as #1041: HTTP/1 messages with no header fields cannot be parsed.

[JarryShaw]

Cross-review verdict on 4069a9849: GOOD TO GO (ran on Opus; authored on Sonnet). Both round-1 findings and both nits are fixed.

1. ProtocolBase.register Warns: (protocol.py:734-740) now says the warning fires only when the incumbent differs from the replacement, and that an unresolved ModuleDescriptor incumbent counts as different from the class it names. It makes no claim about timing. The reviewer re-ran the probe matrix on the built-in IPv4 EtherType entry:
   • registering the same class twice: 1 warning, then 0
   • registering a descriptor of the same class: 0
   • registering a different class: 1
   • registering after a decode: 0
2. application/__init__.py now reads # Base Classes, matching docs(protocols): tighten the internet-layer prose and cut timed context (#719) #1035.
3. http.py:353 is now a complete sentence and true in context. The source paths raise ProtocolError themselves, so the struct.error suppression only guards paths not yet known to.
4. The ospf.py:336-338 claim is right, and so is its subject. The sentence refers to future callers of _make_id_numbers itself, not to make(). _make_id_numbers(True) raises FieldValueError through its own parse_ip_address call at :348. I also confirmed separately that bare ipaddress.ip_address(True) returns 0.0.0.1.

All 14 files are AST-identical to main. Not verified: a docs build. Nit: one new ospf.py line is 86 columns.