bee-check 0.2.0

Retrievability checker for Ethereum Swarm references. Multi-vantage stewardship probes, per-chunk drill-down, and one-shot re-seed.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

# 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 */ ],
  "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>]`.

## 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.