download_data only resolves gateway-local references but is described as reading 'the Swarm network'

[crtahlin]

Symptom

download_data is described as "Download data from the Swarm network using a reference hash", but it only resolves references the provenance gateway itself stored. A reference that the public Swarm gateway serves in 185 ms returns 404 here.

Measured 2026-08-24:

# write via the public Swarm gateway
POST https://api.gateway.ethswarm.org/bzz            -> 201  {"reference":"34be0ab4…dab9"}

# read the same reference back
GET  https://api.gateway.ethswarm.org/bzz/34be0ab4…dab9/   -> 200 in 0.186s  "ax-903-control-probe"
GET  https://provenance-gateway.datafund.io/api/v1/data/34be0ab4…dab9
     -> 404 in 3.338s  {"detail":"Data not found for reference 34be0ab4…dab9"}

The content is demonstrably on Swarm and retrievable. Only this reader cannot see it.

Why an agent gets this wrong

The tool description promises the Swarm network. An agent handed any Swarm reference — from a manifest, a feed, a colleague, or its own earlier upload through a different path — will reasonably call download_data and conclude the data does not exist. "Data not found for reference …" reads as this content is gone, when it means I only index my own uploads.

That is a correctness trap rather than an inconvenience: the agent's next action is usually to re-upload, which spends a stamp to duplicate data already stored.

Suggestion

Either behaviour is defensible; the mismatch between them is not.

1. Preferred — fall back to a public Swarm gateway on local miss, so download_data means what it says.
2. Or — narrow the tool description to "data uploaded through this gateway", and change the 404 text to distinguish not stored here from not on Swarm.

Related — error hints that cannot resolve the error

Separately, several unrecoverable errors return _next: health_check. During the 2026-08-21 review, purchase_stamp failed with Insufficient funds … retryable: false and pointed the caller at health_check, which cannot add funds. An agent following _next loops without progress. Hints on terminal errors are more useful pointing at something that can change the outcome, or stating plainly that operator action is required.

Context: gateway-side write failures are tracked in datafund/swarm_connect#250; the AX review finding is ethersphere/DevRel#903.

[crtahlin]

Correction to the diagnosis above

I attributed the 404 to download_data only indexing the gateway's own uploads. Further testing shows a simpler and more serious cause: the gateway's Bee node is not connected to the Swarm network, so it cannot retrieve anything it did not store itself — and cannot publish either.

Evidence (2026-08-24), tracked as datafund/swarm_connect#250:

• deferred=false upload (pushes to network) → 504 after 30 s; deferred=true (local only) → 200 in 0.354 s
• A reference written via deferred=true reads back from the gateway in 65 ms but 404s from the public Swarm gateway after 9 s — it never propagated

So the read-scope question I raised is real but secondary. Once the node has network connectivity, a fallback may not even be needed for the case I tested. What still stands regardless of the node fault:

1. The tool description promises "the Swarm network" while the implementation is bounded by whatever this one node can reach. That gap should be closed by narrowing the description, adding a public-gateway fallback, or both.
2. "Data not found for reference …" cannot distinguish not stored here, not on Swarm, and this node cannot reach the network. Those need different responses from the caller, and today all three look identical.
3. The _next: health_check hint on terminal errors remains a dead end — and in this instance health_check reports ready: true and ✅ Gateway operational while no upload can propagate, so following the hint actively misleads.

Point 3 is the one worth acting on inside this repo: the MCP's health surface reports gateway liveness and wallet state but never Bee network reachability, so an agent is told everything is fine while every write is silently unretrievable by anyone else.