bee-check 0.1.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

# 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
}
```

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.

## 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
    },
    "https://b.example": {
      "found":      false,
      "elapsed_ms": 5012,
      "error":      "404: chunk not found"
    }
  }
}
```

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.