refactor: rename seeding/caching terminology to hosting in freenet-stdlib

[sanity]

Context

PR #3522 standardized freenet-core on "hosting" terminology for contracts a node stores locally, eliminating the confusing three-name situation (seeding/caching/hosting). However, freenet-stdlib types were out of scope and still use the old names.

Remaining renames needed in freenet-stdlib

• SystemMetrics.seeding_contracts → hosting_contracts
• NodeQuery::ProximityCacheInfo → NodeQuery::NeighborHostingInfo (or similar)

After stdlib is updated

• Republish freenet-stdlib to crates.io
• Update freenet-core to use the new field/variant names
• Update river and any other repos under freenet org that reference these types

Blocker

The local freenet-stdlib repo is at version 0.1.40 but crates.io shows 0.1.34 (latest 0.2.2). This version confusion should be resolved before making changes.

[AI-assisted - Claude]

[github-actions]

🤖 Auto-labeled

Applied labels:

• T-enhancement (98% confidence)
• E-medium (90% confidence)
• A-developer-xp (90% confidence)
• A-contracts (85% confidence)
• S-blocked (90% confidence)

Reasoning: This issue requests a refactor/rename in freenet-stdlib (seeding/caching → hosting), which is an improvement to existing code rather than a bug or new feature, so T-enhancement is appropriate. The work spans renaming types, republishing the crate, and updating consumers, which is moderate in complexity (E-medium). It affects developer-facing libraries and type definitions used by contracts and core, so A-developer-xp and A-contracts are relevant. The report explicitly calls out a blocker (version confusion between local and crates.io versions), so S-blocked applies.

Previous labels: none

If these labels are incorrect, please update them. This helps improve the auto-labeling system.

[sanity]

Issue Priority Assessment

Generated: 2026-03-12T22:24:42.212526756+00:00
Issue hash: bae76839

Value Assessment

Value Assessment

The issue is still relevant: the core repo continues to instantiate freenet_stdlib::client_api::SystemMetrics with the seeding_contracts field and the NodeQuery enum still exposes ProximityCacheInfo, so nothing in this tree has switched to the “hosting” terminology introduced in PR #3522. For example, crates/core/src/node/network_bridge/p2p_protoc.rs:1957 still sets SystemMetrics { seeding_contracts: … } when building diagnostics results, and the NodeQuery match arm in crates/core/src/client_events.rs:1877 continues to refer to ProximityCacheInfo while logging that the equivalent “NeighborHostingInfo” query is “not yet implemented.” Those usages compile today because the pinned freenet-stdlib = "0.2.2" in Cargo.toml:137 still defines the old names, so the rename simply hasn’t happened yet; the mismatch the issue describes is literally present in the running code.

From a user impact perspective, the inconsistency between the diagnostics API (contract metrics, node queries) and the “hosting”-focused language adopted elsewhere is a clarity problem for every contract writer or tooling consumer who has to interpret node diagnostics or send node queries. Right now the diagnostics response exposes “seeding contracts” while the ring, RPC code, and documentation around hosting/connections only talk about “hosting contracts,” so developers still need to remember the three-term dissonance that the original PR aimed to eliminate. That confusion affects anyone consuming SystemMetrics or NodeQuery via freenet-stdlib today, so it affects the full set of light clients and tools even though it doesn’t break functionality.

Strategically, the rename is exactly the follow-up that PR #3522 envisioned: after the core repo switched to hosting terminology, the consumer-facing freenet-stdlib API should reflect the same vocabulary so that all repositories under the freenet org stop talking about seeding, caching, and hosting as separate concepts. Completing this rename (and the associated “NeighborHostingInfo” query implementation) would remove a longstanding cognitive tax, keep river and other downstream repos in sync, and make future instrumentation and documentation easier to maintain because a single term now maps to the same concept everywhere.

This work is currently blocked by the freenet-stdlib release state noted in the issue description—there is a version confusion between the local checkout (0.1.40) and crates.io (0.1.34/0.2.2), so nobody can publish the renamed API until the publishing story is sorted. That makes this issue a blocker for any repo that wants to adopt the new names, but it isn’t time-critical beyond that; once the stdlib crate is republished with the renamed fields/variants, the remaining steps are deterministic (update core to use the new fields, then update river and other repos). Until the blocking publishing question is resolved, the change can’t proceed, so this issue should stay blocked but stays ready to move as soon as the crate reconciles its versions.

Cost Assessment

The terminology swap is still very much necessary: the SystemMetrics payload in the standard library is still exporting a seeding_contracts field and a ProximityCacheInfo query variant (freenet-stdlib/rust/src/client_api/client_events.rs:773 and :792), and freenet-core itself references both names (crates/core/src/node/network_bridge/p2p_protoc.rs:1935 sets SystemMetrics { seeding_contracts: … } and crates/core/src/client_events.rs:1864 still matches on NodeQuery::ProximityCacheInfo). Nothing in the current tree has adopted the new “hosting” terminology, so the issue is actionable, but the repo’s dependency graph already pulls freenet-stdlib 0.2.2 (Cargo.lock:1589) while the nearby ~/code/freenet/freenet-stdlib/rust/Cargo.toml is stuck on 0.1.40 (:3), so any change also has to resolve that version mismatch before a release can go out.

Scopewise, the rename touches the stdlib’s definition of SystemMetrics/NodeQuery, the diagnostics writer (crates/fdev/src/diagnostics.rs:176) and the freenet-ping integration test that prints the metric (apps/freenet-ping/app/tests/run_app.rs:153), plus the JSON/FlatBuffers serialization that backs those structures. On the core side, the NodeDiagnostics response builder at crates/core/src/node/network_bridge/p2p_protoc.rs:1935 needs to supply the new field name, and the still-unimplemented NodeQuery::ProximityCacheInfo branch in crates/core/src/client_events.rs:1864 must be renamed to whatever NeighborHostingInfo ends up being called. Because SystemMetrics is part of the wire API, all clients, logs, and future queries that deserialize NodeDiagnosticsResponse must be updated in lockstep, and the tiny ProximityCacheInfo match includes a warning message that will need its wording updated as well.

The non-code work is the heaviest part: the stdlib crate must bump its version, publish the renamed API to crates.io, and every repository that depends on those types (River and any other teams still using the diagnostics structures) needs to update their dependency and adjust their usage. That’s why the issue is currently blocked by the version confusion; we would have to decide whether to keep the 0.1.x tree in sync or merge everything into the 0.2.x release before pushing a new payload. The risk is that renaming serialized fields/variants breaks existing clients that read node diagnostics, so the release needs coordination and probably a short deprecation window. Finally, testing requires running the usual cargo fmt, cargo clippy --all-targets, and the freenet test suite (which exercise the diagnostics path) after the rename so we catch any missed references or serialization mistakes.

---

Generated by issue-prioritizer