[mickvandijke]

Adds a get-or-closer request, Kademlia's FIND_VALUE for chunks (ADR-0020). A node that holds the chunk answers Found with it; one that does not answers Closer with its closest known peers.

• ChunkMessageBody::{GetOrCloserRequest, GetOrCloserResponse} carry ChunkGetOrCloserRequest and ChunkGetOrCloserResponse (Found | Closer | Error). They are appended after every existing variant, so older discriminants keep their wire values; a new test pins them.
• Closer carries an opaque payload. saorsa-core encodes it and checks it as a FIND_NODE answer (feat(dht): expose lookup steps for caller-driven lookups saorsa-core#173), so the peer format is versioned in one place.
• GET_OR_CLOSER_AGENT_TOKEN (get-or-closer/1) and advertises_get_or_closer: a node built before this request drops it without a reply, so clients send it only to peers whose user agent carries the token.

Stack, merge and release in this order:

1. feat(dht): expose lookup steps for caller-driven lookups saorsa-core#173
2. this PR
3. feat(storage): answer get-or-closer requests (ADR-0020) ant-node#249
4. feat(read): read chunks through a get-or-closer lookup (ADR-0020) ant-client#221

This PR is rebased onto main (5.0.1). ant-node#249 and ant-client#221 pin it by git rev, so it must be released before they merge.

Linear issue

Closes V2-1358

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.

Compatibility

• Wire: two new ChunkMessageBody variants, appended at indices 14 and 15. Existing messages are unchanged.
  • A node built before them cannot decode them: natively it sends no reply, and over WebRTC Direct it closes the channel.
  • So nodes announce get-or-closer/1 in their user agent, and clients only send the request to peers that do.
• Storage: none.
• API: additive. New types, a constant and a function; ChunkMessageBody is #[non_exhaustive].

Semver impact

• breaking
• feature
• fix

Test evidence

• cargo test --all-features: 108 passed. New tests cover:

  • request and response round trips
  • discriminant wire values for GetRequest (2), PointerGetRequest (12) and the new variants (14, 15)
  • token detection

• cargo clippy --all-targets --all-features -- -D warnings: clean.

• End to end through ant-node and ant-client, as listed in those PRs.

• Dev testnet comparison against main, 2026-10-27, after the review fixes. Two 60-node DigitalOcean fleets with the same layout:

  • 30% symmetric NAT across 9 regions
  • per fleet, 4 uploaders (50 MiB; 2 merkle, 2 no-merkle), 2 native downloaders and 1 headless-Chromium WASM downloader
  • 60-minute windows
  • both fleets on current main, differing only by the four PRs

  Three runs:

  1. closed loop, as staging runs its clients
  2. the same, with the code swapped between the fleets' droplets
  3. the swapped fleets, with native downloads paced to one every 40 s, so both fleets serve the same reads

  stack vs main	run 1	run 2, swapped	run 3, swapped, matched load
  native download p50	−52% (19.7 → 9.4 s)	−47% (18.5 → 9.9 s)	−43% (18.4 → 10.5 s)
  native downloads completed	733 vs 350	707 vs 372	177 vs 176
  merkle upload p50	+7.0% (p < 0.001)	+1.7% (p = 0.36)	−6.2% (p = 0.001)
  no-merkle upload p50	−0.2% (p = 0.90)	+8.6% (p = 0.001)	+0.9% (p = 0.72)
  WASM download p50	−2.0% (p = 0.43)	−4.2% (p = 0.10)	−2.8% (p = 0.13)
  node dial failures, minutes 10–60 (run 3: whole window)	21 vs 0	0 vs 12	0 vs 2
  failed transfers	0	0	0

  • Native downloads are 43–52% faster on whichever droplets run the stack.
  • At equal read load nothing regresses. In a closed loop, the stack's fleet serves about twice the reads, and uploads beside them run about 4% slower. Staging runs its clients closed loop, so it will see that.
  • Node dial and connection failures follow one fleet's droplets, not the code. Every run's steady-state tail sits on the same droplets (B), whichever code they run. saorsa-core#173 changes no node-side DHT path.
  • Duplicate copies: nodes sent 1.45–1.52 bytes per native byte downloaded, against 1.31–1.35 for main. Before the review fixes it was 1.54–1.68. The rest is the 500 ms hedge.
  • Reports: ant-testnet/state/comparisons/v2-1358-review-fixes-{vs-main,swapped,swapped-matched}-60m-1027/README.md.

New dependency

none

ADR

ADR-0020: Kademlia-style chunk GET: return the chunk or closer peers. Measurements are in the ant-client investigation.

Mitigation / rollback

Inert until nodes answer and clients send the request; revert the commit.

🤖 Generated with Claude Code

[dirvine]

Code approval at the reviewed head

No introduced blocking defect found in this PR. Appended wire variants, pinned discriminants and exact capability-token matching are consistent with the linked implementations. The peers field is deliberately opaque; its existing 5 MiB outer envelope is not a substitute for the inner decoder bound.

Linked stack is NOT approved to ship: saorsa-core#173 needs its decoder size guard, and downstream pins must follow. Preserve dependency-order publication and revalidate CI before merge.

Reviewed commit: 69a031bacd106100376f1914718bfbd44bb1e955.

Review method: six substantive seats across the linked set, including a completed z-ai/glm-5.2 API review recovered from a worker that timed out after saving its response; coordinator source checks and local execution. Initial functional/security/test seats recommended approval. The coordinator probe, independent adjudicator, API seat and replacement concurrency/release seats corroborate the missing decoder bound. This is not unanimous approval. The API seat recommended client approval with concerns; the coordinator withholds it because the exact client pin still exposes the defect.

Local verification (macOS, rustc 1.96.0): core closer-peers 3 passed and DHT-manager regression 143 passed; protocol all-features 108 passed; node get-or-closer unit tests 3 passed and real-transport E2E 1 passed; client kad_read unit tests 10 passed and real-transport E2E 1 passed. Formatting passed in all four repositories. No production/testnet deployment or merge performed. Draft git pins were verified with cargo metadata --locked; this is not published dependency closure. ADR-0020 remains Proposed.

[dirvine]

Re-review — no change at reviewed head

Head is unchanged at 69a031ba; the first-round APPROVE still stands. Nothing new in this delta.

Verdict

APPROVE (unchanged). CI all green at this head (format, clippy, tests ubuntu/macos/no-default-features, docs, wasm, security, publish dry-run).

Panel: GLM 5.3 seat billing-failed (402) — this seat is 2/3 reviewed (GLM unavailable), Qwen 3.8 + DS4 concur.