docs(portmap): correct the recycle-check cost - it is elevation-bound, not ~180 ms

[donislawdev]

What and why

The socket-layer work left a deferred perf follow-up: "resolver refresh is ~180 ms/rebuild (create_time recycle check)", with a plan to batch the create-times in one syscall. Before building that, I measured it — and the premise does not hold under the conditions that matter.

Measured 2026-07-24 (Win11, CPython 3.14, Chrome open), elevated and non-elevated (runas /trustlevel:0x20000):

	elevated (every real session)	non-elevated (--simulate on non-admin)
socket PIDs the recycle check is slow on	0 of 27	16 of 27
warm refresh (the recycle check)	0.16 ms	~90–180 ms
cold resolve('chrome')	36 ms	381 ms

The cost of create_time() is decided by one thing: whether OpenProcess succeeds — ~0.005 ms when it does, ~5.7 ms when it's denied (psutil then scans the whole system for that one PID). Denial is an elevation question, not the "hardened process / Chrome renderer" one the old note assumed — renderers don't own sockets, so they never reach this loop. The handoff's ~365/180 ms was measured non-elevated; my 381 ms non-elevated cold matches it.

Real impairment always runs elevated — WinDivert won't open without admin, so a non-admin START fails outright. So the recycle check is already cheap (0.16 ms warm / 36 ms cold) in every real session. The only non-elevated path that runs the resolver at all is --simulate (synthetic packets; the cost sits on the resolver thread, never the capture one).

Two docstrings had drifted apart — _psutil_created claimed 0.005 ms, info claimed ~5 ms — and each was right for a different elevation. This states it once, accurately.

Changes

• Docs only, no behaviour change. Corrected the _psutil_created and PortTable.info docstrings in beantester/portmap.py, and the matching PROJECT_NOTES line (in the private Doc repo, not this PR).
• Recorded the decision: batching the denied PIDs via NtQuerySystemInformation was measured and rejected — it speeds only the non-elevated --simulate warm check, does nothing for the elevated hot path, and nothing for the cold resolve (which name resolution dominates, not create_time). Written down so the next session doesn't re-open it.

Reviewer notes

• No CHANGELOG.md line: nothing a user notices (pure prose). Documented in CHANGELOG-INTERNAL.md, which also closes the "known perf follow-up" notes in two earlier entries.
• No new test: this changes no code path. The existing guard (tests/test_processes.py, the recycle-protection suite) still passes (31/31), and no test pinned the old prose.

Checklist

• python -m pytest tests passes locally. (tests/test_processes.py 31/31; docs-only change, no code path touched.)
• New behaviour has tests (see tests/ for the style). (No behaviour change — docstring/notes correction only.)
• UI text goes through i18n keys, with both lang/en.json and lang/pl.json updated. (No UI text.)
• User-facing changes noted in CHANGELOG.md; technical ones and new tests in CHANGELOG-INTERNAL.md, under [Unreleased]. (Internal-only, nothing a user notices.)
• Commits follow Conventional Commits (type(scope): summary).
• No version bump — the owner closes a version via VERSION.txt.

🤖 Generated with Claude Code