feat(network): NetworkHealth snapshot + write-readiness formula in ant-core (V2-1037)

[Nic-dorman]

Linear issue

V2-1037

Risk tier

• T0 — docs / tooling / CI / pure UX-output. Repo CI only.
• T1 — client-only, no network-facing behavior change. CI + prod compat smoke.
• T2 — node/client logic with behavioral surface, no protocol/format/economics change. Dev testnet + ADR.
• T3 — protocol / storage format / payments / routing. T2 evidence + adversarial testing.

Additive read-only API: two in-memory reads of existing node state, no network-facing behavior change, no node/protocol surface.

Compatibility

• Wire: none
• Storage: none
• API: additive — new NetworkHealth struct, REBOOTSTRAP_THRESHOLD const, Network::health(), Client::network_health(). No existing signature changes.

Semver impact

• breaking
• feature
• fix

Test evidence

• 6 new unit tests on NetworkHealth::from_counts covering the formula's observed failure modes: dead network (ant-sdk#232 shape: 1 connected / rt 0 → not ready), client-mode rt under-reporting (10 connected / rt 2 → ready, the false-negative caught live on the LAN devnet during V2-1027), exact-threshold boundaries on each signal, u32 saturation.
• cargo test -p ant-core --lib: 463 pass; 1 pre-existing, unrelated Windows-only failure (save_snapshot_to_unwritable_dir_does_not_panic assumes Unix root-write semantics; passes on Linux CI, fails on any Windows dev box).
• cargo clippy --all-targets --all-features -- -D warnings clean, cargo fmt --check clean.
• Formula semantics were verified live against a real network during V2-1027's devnet decay test (evidence on that ticket); this PR moves that computation down unchanged.

New dependency

none

ADR

n/a

Mitigation / rollback

Additive API with no consumers in this repo — revert the single commit; downstream consumers (antd V2-1027, ant-gui V2-1038, ant-ffi V2-649) only adopt it in their own PRs.

---

Context: this is the single write-readiness implementation for all embedded-client consumers, moved down from antd (WithAutonomi/ant-sdk#241). REBOOTSTRAP_THRESHOLD mirrors saorsa-core's private AUTO_REBOOTSTRAP_THRESHOLD until a release carries saorsa-core#153, which makes it public; a try_recover() rider over the newly-public maybe_rebootstrap() is deferred to the same release. last_store_ok tracking deliberately stays consumer-side.

🤖 Generated with Claude Code

[Nic-dorman]

Security Audit failure is inherited, not from this change: RUSTSEC-2026-0258 (h2 0.4.14, fixed in >=0.4.16) is in main's lockfile and this PR doesn't touch Cargo.lock. Same advisory is currently failing the audit on WithAutonomi/saorsa-core#153. A one-line cargo update -p h2 chore on main would clear it repo-wide.

🤖 Generated with Claude Code

[dirvine]

Review verdict: APPROVE (code) at 7bc685f2a5efe963e8bc415373c8931693a63692.

The health snapshot is a coherent best-effort readiness signal, uses cheap live in-memory counts, saturates exported counts safely, and has boundary coverage for both signals. Local verification: cargo test -p ant-core --lib — 463 passed. I found no diff-specific blocker.

Watch-outs: REBOOTSTRAP_THRESHOLD deliberately mirrors saorsa-core #153 and should be replaced by the upstream public constant once the dependency carries it. Current CI also has the repository-wide h2 security-audit failure and an Ubuntu Merkle E2E timeout/cancellation; neither is introduced by this diff.

[jacderida]

Approved. Additive read-only API with no consumers in this repo — Network::health() / Client::network_health() are two in-memory reads, and nothing calls them yet, so there is no behavioral surface on any existing path.

Verified the mirrored constant against the pinned dependency rather than the description: in saorsa-core 0.27.0 (the version in Cargo.lock), AUTO_REBOOTSTRAP_THRESHOLD is still private at dht_network_manager.rs:209 and equals 3, and maybe_rebootstrap is still private. So REBOOTSTRAP_THRESHOLD = 3 is correct against what ships today, and this PR does not depend on saorsa-core#153 — #153 is what will let the mirror be deleted, and the try_recover() rider that does depend on it is correctly deferred out of this PR.

Follow-up worth tracking: because this mirrors a private const, a future change to the saorsa-core value produces no compile error here — ant-core would silently disagree with the DHT. Worth deleting the mirror in favour of the real const once a release carries #153.

Rebased onto current main (7bc685f -> 9817bef, clean) to pick up #177 and #178, which clears both prior CI failures (RUSTSEC-2026-0258 in h2, and the 60m Merkle E2E cap). Verified locally on the rebased head: cargo fmt clean, clippy --all-targets --all-features -D warnings clean, cargo test -p ant-core --lib 463 passed / 0 failed including the 6 new NetworkHealth tests.