Guard the no-telemetry promise in the code, not just in the prose

[donislawdev]

Convention 36 - the shipped program reaches no network - was stated in four places and
checked in none. test_license_surface.py and test_windows.py both verify that we SAY
it. Nothing had ever looked at the code. For a tool that intercepts the user's traffic,
"it sends nothing anywhere" is the one promise where being wrong is not a bug.

Two layers, because neither contains the other

The obvious answer is an AST scan. That was the first design, and it picked the wrong
primitive: the interpreter already answers this question a layer down, through PEP 578
audit hooks. Measured on CPython 3.14.7:

what it catches	static (AST)	runtime (audit hook)
import urllib.request	yes	yes
__import__("url" + "lib.request")	no	yes
ctypes.windll.wininet	yes	yes, with the resolved name
a network library under a computed name	no	yes
code no test executes	yes	no
where a connection actually goes	no	yes, the event carries the address

So the static half answers "was it written" and the runtime half answers "what actually
happened". Dropping either leaves a whole shape of bypass open, which is why both ship.

The allowlists are measured, not guessed

• a CLI --simulate run with impairment armed: zero network events, zero forbidden
  imports, four local libraries
• building the whole GUI on the fake toolkit: zero network events
• host_identity(): exactly five events, all of them the documented route probe

Because the baseline is zero, the guard can assert the strongest shape there is: nothing,
except four entries that each carry a written reason. And because the audit event carries
the destination, it asserts 8.8.8.8:80 and 2001:4860:4860::8888:80 rather than merely
that a socket appeared - "a socket happened" would pass for a socket that shipped the
user's captured traffic somewhere.

What is checked

Static: no network client imported; socket and webbrowser used only where a registry
names a reason; ctypes limited to the ten local Windows libraries; no process spawned
(so no shelling out to curl or PowerShell); URL literals only in appinfo.py and
legal.py, with docstrings exempt because prose about a URL is not a URL.

Runtime: no unexpected network event, no forbidden import, no unexpected library, and
every connect naming a documented probe address.

The exception registry is exact in both directions. An entry naming code that has
moved fails like a call with no entry - permission nobody can point at any more is how an
allowlist becomes a blindfold.

Proof

Eight mutations against the real tree, 8/8 caught. Three are added to the mutation
registry so CI repeats them: a plain import, a network library through ctypes, and a
client imported under a computed name at runtime.

A permanent canary points the scanner at seven shapes it must reject plus one clean case
it must not, modelled on tests/test_public_text_guard.py - the file that earned this
project the lesson that a guard nobody has watched fail is indistinguishable from a guard
that reads nothing.

What it cannot prove, in the docstring rather than implied

• A C extension calling WinSock directly raises no socket event. psutil is such an
  extension: the hook covers third-party Python, not third-party C.
• The runtime layer only sees what it runs. It drives the CLI, not the GUI.
• A computed import inside a function nothing calls is invisible to both layers. That
  one was found by mutating rather than by thinking, and moving the same call onto a path
  the CLI runs gets it caught at once.
• The runtime library check is vacuous on the Linux leg - the socket half is real on both,
  but nothing loads a Windows library there, and the static half is what covers it.

This is a lock on the surface, not a proof of silence, and it says so.

Two findings the measurement produced

utils.host_identity has a socket.gethostbyname fallback that convention 36 never
mentioned, and a name resolution can put a query on the wire - the convention's reasoning
("a UDP connect sends no packet") does not cover it. Measured: it never runs here, because
the route probe answers first. It stays as an exception, to be measured another time, and
it is named in the registry with that reason rather than passed over silently.

Separately, the convention says "one socket.socket in beantester/" - true of the calls,
but import socket is in two modules (settings.py reads the machine's own services file
to label a port). A guard written from the convention alone would have had the wrong
allowlist on day one.

Checks

test_no_telemetry.py, test_mutation_registry.py, test_repo_conventions.py and
test_code_hygiene.py pass, plus ruff and mypy on the new file. Run on Windows and, for
the platform question above, in WSL.

🤖 Generated with Claude Code