docs(protocols): tighten the transport-layer docstrings and cut timed context (#719)

[JarryShaw]

• Searched for similar pull requests
• Followed the coding style (no code touched)
• make test passes, and a test case covers the change (N/A: prose only; tests/protocols/transport and tests/project pass)
• 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

Transport-layer slice of the #719 prose sweep: pcapkit/protocols/transport/ (dccp.py and rsvp.py are empty, __init__.py needed nothing). Docstrings and comments only.

• Cut issue/PR citations and "used to / until" history from TCP, UDP and Transport notes; kept the rationale (Enum_Flags(0) vs cast, flags resolved before options, MPTCP option lengths, parse_ip_address, separate per-protocol registries).
• Fixed prose that disagreed with code: Transport._decode_next_layer (higher port is used when only it is registered), the NOP option title, and "Transport owns no __proto__" (it inherits the base one; TCP/UDP define their own).
• Sphinx -n: 19 warnings on main, 18 here for these files, none new (one ProtocolBase.read ref went away).

AST guard (docstrings stripped, vs origin/main):

file	identical
tcp.py	True
sctp.py	True
udp.py	True
transport.py	True

Part of #719.

[JarryShaw]

Cross-review verdict on aad7b163d: NEEDS CHANGES (ran on Opus; authored on Sonnet). One finding. The rest of the PR holds up.

The Warns: wording turned an accurate condition into a wrong one at transport.py:95 and sctp.py:615/:619. The new text says it warns when the key is "registered to a different protocol" and that "re-registering the same class is silent". The guard is incumbent is not protocol, and the built-in entries are stored as unresolved ModuleDescriptors, so re-registering the same class over a built-in entry does warn. I reproduced this on the PR head: TCP.register(80, HTTP) warns once (overwriting ModuleDescriptor(module='pcapkit.protocols.application.http', …)), and a second call is silent. SCTP PPID 60 ← NGAP behaves the same way. ProtocolBase.register (protocol.py:749-763) documents this case. Restore the old "fires only when the incumbent differs from the replacement", or say outright that an unresolved ModuleDescriptor incumbent counts as different.

Confirmed:

• No rationale lost. Every removed why survives: the Enum_Flags(0) vs cast note, flags resolved before options, the MPTCP lengths, parse_ip_address, PPID 66, the _make_port normalisation, the HTTP proxy binding.
• The three prose corrections are right: the _decode_next_layer higher-port fallback, the NOP retitle, and that TCP, UDP and SCTP each own a __proto__ while Transport.__proto__ is ProtocolBase.__proto__.
• Counts check out: 13 SCTP causes, PPIDs 60 and 66, DSS maximum 28.
• Every RFC 8684 section and figure number that survives checks out against the RFC text, §3.1–§3.5 and figures 5–14. The sentence the author dropped on suspicion was in fact correct, but it only narrated old history, so dropping it is fine.
• Citations: the removed citations are all timed context, and no GH- references are involved.

[JarryShaw]

Cross-review verdict on 67602de7f: GOOD TO GO (ran on Opus; authored on Sonnet). The round-1 finding is fixed.

The Warns: blocks are now true clause by clause. The reviewer checked each one with a fresh-process probe on this head:

• Built-in entries: re-registering the same class over one of these (an unresolved ModuleDescriptor) warns once. Repeating it is silent. This held for TCP 80 ← HTTP, UDP 80 ← HTTP and SCTP 60 ← NGAP.
• Different classes: swapping a different class in warns, and so does swapping the original back. Both are a change of object, which is the "differs" clause.
• Unregistered ports: these never warn.

Every value in all three tables starts as a ModuleDescriptor, so "warns once" holds for every built-in entry, not just some of them.

The new :class: references resolve. ModuleDescriptor is in __all__ (corekit/module.py:28) and has an autoclass on docs/source/pcapkit/corekit/module.rst. The register_apptype sentence is also true: it calls register once per transport named.

Scope: since round 1 the commit changed only sctp.py and transport.py, and against main the PR is still the four transport files. The docstring-stripped AST of all four matches main.

Unverified: no full Sphinx -n build was run this round. That the new references resolve is shown from the source, not from a build.

[JarryShaw]

Retracting the GOOD TO GO on 67602de7f: NEEDS CHANGES. The #1037 cross-review found a case that both reviews of this PR missed. I reproduced it on main.

transport.py:98-99 says re-registering a built-in entry "warns once". That holds only while the entry is still unresolved. On a lookup hit, ProtocolBase._lookup_next_layer writes the resolved class back into the registry (protocol.py:1759, registry[proto] = klass). After a single decode, the entry holds the class itself, and the first explicit register of that class is silent:

before decode: TCP.__proto__[80] -> ModuleDescriptor
TCP(<segment to port 80>).protochain -> TCP:HTTP/1.1
after decode:  TCP.__proto__[80] -> <class 'pcapkit.protocols.application.http.HTTP'>
TCP.register(80, HTTP) after decode -> 0 warnings

Suggested wording: "…counts as different from the class it names, so re-registering a built-in entry warns until a packet on that port is first decoded, which resolves the entry to the class; after that it is silent."

sctp.py:619-621 is fine as written, because it qualifies the incumbent as unresolved. So is ProtocolBase.register.

[JarryShaw]

Cross-review verdict on 044de9196: NEEDS CHANGES (ran on Opus; authored on Sonnet). The wording I proposed in the retraction was itself wrong, and the fix carried it in faithfully.

transport.py:98-101 says "…warns until a packet on that port is first decoded … after that it is silent". The reviewer probed each case in a fresh process:

• Register first, twice, with no decode in between: 1 warning, then 0. The first same-class register replaces the descriptor itself, so the warning fires at most once whatever resolves the entry first. "Until decoded" is false.
• "On that port" is wrong too: decoding a segment from port 80 to port 21 dispatches on 21 and leaves entry 80 unresolved, so the next register(80, HTTP) still warns. A non-HTTP payload to port 80 does resolve it, even though that parse falls back to Raw. Transport.analyze resolves entries through the same lookup.

Fix: stop describing when the entry resolves. End the sentence the way sctp.py:619-621 does, which has stayed true throughout: "…An unresolved ModuleDescriptor counts as different from the class it names." Drop the "so re-registering a built-in entry warns…" clause entirely. sctp.py and ProtocolBase.register (protocol.py:759) are both consistent with that.

[JarryShaw]

Cross-review verdict on 69eb8bfcf: GOOD TO GO (ran on Opus; authored on Sonnet). The resolution clause is gone, and every remaining sentence holds.

The Warns: block now says only that the warning fires when the incumbent differs from the replacement, and that an unresolved ModuleDescriptor counts as different from the class it names. It makes no claim about when an entry resolves. That is the claim rounds 2 and 3 got wrong: a first register, a decode and analyze can each resolve an entry.

The reviewer ran seven probes, each in a fresh process: register first, twice; decode first; a different class, then the original back; and a segment from port 80 to port 21. In every row the warning count matched whether the incumbent differed.

"The guard this shares with register_protocol" is also true. register_protocol (foundation/registry/protocols.py:218-219), Transport.register, SCTP.register and ProtocolBase.register each make the same incumbent is not protocol comparison. I checked all four.

Scope: the only change since round 3 is that deleted clause. The PR is one commit on main touching the four transport files, and their AST matches main once docstrings are stripped.