docs(foundation): second-round pass over the foundation prose (#719)

[JarryShaw]

Please follow the guide below

• Searched for similar pull requests
• Followed the coding style (make pylint, make mypy, make isort) — N/A, the AST is unchanged (table below)
• make test passes, and a test case covers the change — not the whole suite: each of the 26 tests/foundation modules ran in its own process, plus tests/project and tests/test_docstring_contract.py, all passing
• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible — 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?

Tick the commit type your subject line carries.

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• chore — anything else

---

Description of your pull request and other information

Second-round #719 pass over every file under pcapkit/foundation/ (32 read, 20 changed). It only touches prose the code contradicts, plus leftover timed context:

• Reassembly strict. The docs said strict=False drops incomplete datagrams. A probe shows it still returns them, as one contiguous payload with the holes zero-filled. For IP, when the total length is unknown, it returns only the prefix up to the first hole. strict=True returns the received runs instead.
• Extractor. Rewrote the make_name steps, because no output format is ever inferred from fout. Rewrote record_header, because tracing never reads the header byteorder. In _cleanup, replaced the dangling _read_frame with the real re-entry path (a probe confirmed it). Completed the run and __init__ Warns/Raises lists.
• Flow tracing. The callback receives one Index when a flow is finalised, not a list of datagrams. make_fout raises only when fout exists but is not a directory. Index.packet holds one datagram per direction and acknowledgement number.
• Opt-in registration comments. Engine uses engine=, not name=, and a mistyped keyword leaves the class unregistered rather than registered under its own name.
• Smaller fixes. Removed "used to / older behaviour / all along / as of" phrasing. Corrected the TCP module class and the register_pcapng_block label. Fixed the PCAP-NG reST target, and changed the IPv4 timeout citation to RFC 1122. Where timed wording was cut, the rationale is kept in present tense: why register_engine checks Engine rather than EngineBase, why TransportProtocol['tcp|udp'] misses rather than composing into 3, and why the trace-format guard covers an engine that dissects nothing.

Sphinx -n, fresh output directories, foundation warnings only: main 144, branch 143. No new warnings; the dangling _read_frame reference is gone.

AST guard (every bare-string Expr stripped, branch vs origin/main):

File	Identical
pcapkit/foundation/engines/__init__.py	True
pcapkit/foundation/engines/engine.py	True
pcapkit/foundation/engines/pcap.py	True
pcapkit/foundation/engines/pcap_ct.py	True
pcapkit/foundation/engines/pyshark.py	True
pcapkit/foundation/extraction.py	True
pcapkit/foundation/reassembly/data/data.py	True
pcapkit/foundation/reassembly/data/ip.py	True
pcapkit/foundation/reassembly/data/tcp.py	True
pcapkit/foundation/reassembly/ip.py	True
pcapkit/foundation/reassembly/ipv4.py	True
pcapkit/foundation/reassembly/ipv6.py	True
pcapkit/foundation/reassembly/reassembly.py	True
pcapkit/foundation/reassembly/tcp.py	True
pcapkit/foundation/registry/protocols.py	True
pcapkit/foundation/traceflow/__init__.py	True
pcapkit/foundation/traceflow/data/data.py	True
pcapkit/foundation/traceflow/data/tcp.py	True
pcapkit/foundation/traceflow/tcp.py	True
pcapkit/foundation/traceflow/traceflow.py	True

[github-actions]

Coverage: 88.74% (unit tier, Python 3.14, b2aab951a, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	4	20	4	93.55%
pcapkit/const	18757	1035	2342	846	90.23%
pcapkit/corekit	1874	91	578	22	94.33%
pcapkit/dumpkit	136	0	40	0	100.00%
pcapkit/foundation	2422	143	842	34	92.62%
pcapkit/interface	112	7	40	5	92.11%
pcapkit/protocols	15653	187	3942	162	98.19%
pcapkit/toolkit	487	71	144	3	84.15%
pcapkit/utilities	429	4	122	4	98.55%
pcapkit/vendor	4409	2359	1006	158	42.84%

Per-file detail: the coverage-html artifact of this run.

[JarryShaw]

Cross-review verdict on b2aab951a: GOOD TO GO (ran on Sonnet; author Opus, two rounds)

Round 1, on b74e1851a:

• All 20 files are AST-identical to main once bare strings are stripped.
• strict, probed on gapped input:
  • IPv4 strict=True returns the received runs, and strict=False returns one zero-filled payload.
  • TCP behaves the same way.
• Engine registers through engine=. name= and typo keywords raise UnsupportedCall.
• The extraction, traceflow and engine claims were each probed and hold.
• 25 tests/foundation modules plus test_docstring_contract pass.

Round 2, on the four requested fixes:

• strict=False without a known IPv4 total length returns only the prefix before the first hole; probed via expire(). TCP has no such case.
• The Scapy comment is now a general statement, not a claim about the current engine.
• TransportProtocol is not an IntFlag, so ['tcp|udp'] raises KeyError, and the reg: drop TransportProtocol's IntFlag base once nothing builds a composite #808 reason is restored.
• EngineBase has no __init_subclass__(engine=). register_engine rejects a class that derives only from EngineBase with RegistryError, and the register_extractor_engine/reassembly/traceflow reject pcapkit's own built-in classes #513/fix(foundation): registrar error messages and type hints name the public class, not the Base the guard checks #1016 decision is restored.

UNVERIFIED: the Sphinx build was not run by the reviewer; the PR body reports 144→143 warnings.