bee-check 0.3.0

# bee-check report format (spec v1)

This document defines the JSON shape that `bee-check --output json`
emits and that `bee-check-web` will consume. Implementations in other
languages should match this exactly so reports are portable.

## Top-level

```jsonc
{
  "reference":   "c79394...bdc36a",  // 64- or 128-hex Swarm reference
  "status":      "retrievable",      // see Status below
  "vantages":    [ /* VantageResult, see below */ ],

  // Added in bee-check 0.3.0 — additive, no spec_version bump.
  // Both empty/absent when not used.
  "gateways":    [ /* GatewayResult, see below */ ],
  "resolution":  { /* Resolution,   see below */ },

  "chunks":      [ /* ChunkProbe,   see below */ ],  // omitted when --per-chunk not used
  "spec_version": 1
}
```

### Status

```jsonc
"retrievable"    // every vantage returned IsRetrievable=true
"unretrievable"  // every vantage either returned IsRetrievable=false or errored
"partial"        // mixed: some retrievable, some not
"error"          // every vantage produced an error (no retrievability answer at all)
```

Exit code is `0` when at least one vantage returned `retrievable=true`,
`2` otherwise.

## VantageResult

One per `--bee` URL, ordered by URL (lex).

```jsonc
{
  "bee_url":           "http://localhost:1633",
  "retrievable":       true,    // or false, or null when the call errored
  "elapsed_ms":        3004,
  "error":             null,    // omitted when null; non-null string when the call failed

  // Added in bee-check 0.2.0 — additive, no spec_version bump.
  // All three optional; absent if the corresponding GET /addresses
  // or GET /health call failed for the vantage.
  "overlay":           "7179856eb3c28642983d0e1b7f264693e407a2738593dec9fd59f2ee29046c9a",
  "bee_version":       "2.7.2-rc1-868c1d52",
  "proximity_to_root": 3
}
```

A vantage with `retrievable: null` AND `error: "..."` indicates the
`/stewardship/{ref}` call itself failed (network, 404, timeout, etc.).
A vantage with `retrievable: false` and no `error` means Bee said the
reference is not retrievable from that node's view.

`overlay` is the probed Bee's overlay address from `GET /addresses`.
The first 2 hex chars identify the node's neighborhood.
`bee_version` is the `version` field from `GET /health`.
`proximity_to_root` is the proximity order between the probe node's
overlay and the reference being checked — higher means the probe is
closer to where the chunk is stored; `0` means the probe is not in
the chunk's neighborhood at all.

## ChunkProbe

Emitted only when `--per-chunk` is used. One per chunk reachable from
the root manifest, up to `MAX_CHUNKS` (1000 in v1).

```jsonc
{
  "address":      "1a2b3c...ef",
  "neighborhood": "1a",    // first 2 hex chars (PO 0-7 → first byte)
  "per_vantage": {
    "http://localhost:1633": {
      "found":      true,
      "elapsed_ms": 412,
      "error":      null,
      // Added in bee-check 0.2.0 — optional.
      "proximity":  4
    },
    "https://b.example": {
      "found":      false,
      "elapsed_ms": 5012,
      "error":      "404: chunk not found",
      "proximity":  0
    }
  }
}
```

`proximity` (when present) is the proximity order between that
vantage's overlay and **this specific chunk's** address. Higher is
better; this is the per-chunk analog of `proximity_to_root` on the
vantage. Lets you see "this chunk's neighborhood is 0x1a; my probes
were at PO 0 and PO 3 from it" — i.e. neither probe is in the chunk's
neighborhood, which explains a miss without needing to inspect the
network.

The chunk list is **post-order BFS from the root**, deduplicated, and
capped. If the root chunk isn't a parseable manifest, the chunk list is
just `[<root>]`.

## GatewayResult

Added in bee-check 0.3.0. One per `--gateway` URL, ordered by URL.

```jsonc
{
  "url":         "https://api.gateway.ethswarm.org",
  "retrievable": true,    // 2xx HTTP status → true; 4xx/5xx → false; network err → null
  "elapsed_ms":  412,
  "status_code": 200,     // omitted when the call errored at network layer
  "error":       null     // non-null when status_code is omitted
}
```

Gateway probes call `HEAD {url}/bzz/{reference}/` and interpret the
HTTP status as a coarse retrievability signal: a public gateway only
returns 2xx if it could resolve and forward the content through the
network. Aggregates into the same top-level `status` as vantages —
"retrievable through any vantage or any gateway" is enough to call
the reference retrievable.

## Resolution

Added in bee-check 0.3.0. Present when the user supplied a mutable
input (a Swarm feed reference) and bee-check resolved it before
probing. Currently one variant:

```jsonc
{
  "kind":               "feed",
  "owner":              "1234...abcd",   // 40-hex Ethereum address
  "topic":              "5678...beef",   // 64-hex feed topic
  "resolved_reference": "c79394...bdc36a"
}
```

The CLI accepts `feed:OWNER:TOPIC` (or `feed:OWNER/TOPIC`) as a
positional input and resolves via `GET /feeds/{owner}/{topic}` on
the first `--bee` URL. The top-level `reference` field is then the
**resolved** chunk reference; the original input is recoverable
from `resolution`.

## Compatibility

- `spec_version` lets consumers refuse reports they don't understand.
- New fields may be added in a minor revision; consumers MUST ignore
  fields they don't recognize.
- Renames or removals bump `spec_version`.

## Implementation notes for other consumers

- **bee-check-web** consumes this shape. It also accepts user-uploaded
  JSON files in this format, so users can share a report by attaching
  the file rather than re-running the probe.
- **CLI piping**: `bee-check ... --output json | jq '.status'` is the
  canonical scripting pattern. Don't add CLI flags whose effect can't
  be inferred from the JSON.