docs: address whitepaper review feedback (+ one code-driven HTL correction)

[sanity]

What this is

Draft response to an end-to-end review of the whitepaper. The review was largely praise ("genuinely good... unusually honest"), with a set of specific, mostly-cheap improvements. This PR implements the ones that are clearly right, plus one factual correction the review did not raise but that I found while checking the codebase. Nothing here is merged — it's for your read, especially the code-driven correction.

The PDF compiles cleanly (make → 26 pages, no undefined refs).

Branched from origin/main (the version the reviewer actually read — the local main checkout was 5 commits behind, which is why an earlier look "had no figures").

Reviewer-driven changes (each commit is one point)

Commit	Change	Why
Fig 6 caption	Reframe "stays above 1/d ⇒ good" as a qualitative consistency check; defer exponent fitting	Kleinberg's bound is exponent-sensitive both ways — too many long links degrade greedy routing as much as too few. "Above the reference" = more long-range mass than 1/d, not per se better.
§6.4	New paragraph: honest peers behind a shared prefix (campus NAT, CGNAT, cloud region) collapse to the same ring location	The Sybil analysis covers adversarial grinding but not the honest-collision direction, which strains gap-targeting, replication diversity, and the geographic-diversity assumption the app-layer defense itself leans on.
§5.5	One paragraph: the isotonic estimator conflates a neighbour's link quality with the quality of the topology behind it; aging window tracks the composite	Reviewer's exact point; the paper already had the aging-window mechanism, this just names what it's doing.
§7.4 + open-problem 6	"Durable storage of cold state": the platform makes no durability guarantee for cold contracts	Confirmed against core: storage is byte-budget LRU + demand-ordered eviction with no re-replication (a comment literally says loss "must be repaired by a re-PUT"). Cold state can be evicted from every host and lost — same property the original Freenet had.
§7.4	Reputation caveat on "merge is total"	Accumulate-only reputation fits; revocation/slashing/stake is spend-shaped and inherits the double-spend limitation — so part of the well-fit list has a foot in the poorly-fit class.
§7.5 #4	Promote the §6.4 Sybil circularity into open-problem 4	App-layer defenses are routed through the very layer they secure; the open-problems list undersold how load-bearing this is.
§7.5 #2	Add a property-based test harness (QuickCheck-style monoid-law + Property 1 checks) as a concrete near-term step	Turns the contract-author obligation from an honor system into a supported workflow. Framed as intended tooling, not as shipped (see "not in this PR").

⚠️ Code-driven correction (please scrutinise)

The paper's claim that request routing switches to a random walk above HTL 7 is factually wrong against current freenet-core. I traced every next-hop path: GET/PUT/SUBSCRIBE/UPDATE all forward greedily / performance-ranked; HTL is only a termination bound. The HTL-random-walk branch existed only in the CONNECT path and was removed in Nov 2025 (freenet-core #2065); the dead helper was deleted May 2026 (#4089). rnd_if_htl_above now survives solely as a config value read in one tracing::debug! line. The status table even marked this "Deployed."

Fixed in three places: §5.4 mechanism description, the §5.7 caveats (removed two references to a non-existent random-walk control), and the §7.2 status-table row. Also made the §5.7 / open-problem-1 sim-sweep framing honest.

Deliberately not in this PR

The routing scaling sweep — the reviewer's headline ask ("you have the harness, just run it"). This rests on a false premise. I traced the Turmoil harness: it is a correctness/liveness/convergence harness, not a scaling one. It doesn't measure hops-vs-N, N is a compile-time constant, there's no adaptive on/off toggle, the random-walk knob is dead (above), and organic topology formation stalls around N≈16 in the sim's time budget (N≥24 never finishes; the only way to N=40–80 injects a hand-wired topology that bypasses the routing you'd want to measure). So the sweep is genuine research/engineering — new hop-aggregation + a scaling fix — not a turn of an existing crank. The paper's modesty here is correct; I've adjusted it only so it doesn't imply the harness is turnkey-ready. Decision for you: invest in extending the harness (and the N≈16 formation ceiling may itself be a bug worth a look), or leave it deferred.

Building the property-test harness itself — that's freenet-stdlib/scaffold work, a separate PR in a different repo. Flagged here, not built.

[AI-assisted - Claude]

🤖 Generated with Claude Code