# Changelog

All notable changes to bee-check will be documented in this file. The
format follows [Keep a Changelog]; the project adheres to
[Semantic Versioning].

[Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
[Semantic Versioning]: https://semver.org/spec/v2.0.0.html

## [Unreleased]

TBD.

## [v0.5.2]

Bug fixes from an audit pass.

### Fixed

- **Reference casing**: bare-hex input is now normalized to lowercase
  before being stored in the report. Previously, `bee-check ABC...`
  would emit `"reference": "ABC..."` while chunk addresses were
  lowercased, making two reports for the same content compare
  unequal by string match.
- **`--target-overlay <invalid>` is no longer silent**: a `warn!`
  fires (visible at the default log level) when the hex doesn't
  decode, so users see that the flag was ignored.
- **`--reseed` without `--stamp` now fails fast** before running the
  probe, instead of wasting a multi-vantage probe and then bailing
  with a stale error message at the end.

## [v0.5.1]

Quality-of-life: first-class verbose flag.

### Added

- **`-v` / `--verbose` flag** (repeatable). `-v` enables `info`,
  `-vv` enables `debug` (incl. every underlying bee-rs HTTP call —
  method, URL, status, elapsed), `-vvv` enables `trace` (per-chunk
  probe events). Default level remains `warn` so stderr stays
  quiet. `RUST_LOG` still overrides.
- Tracing instrumentation across `check_multi_vantage`,
  `check_gateways`, `drill_down`, `cold_download_all`, and
  `reseed`.

## [v0.5.0]

Cold-content end-to-end download probe plus a complete mdBook manual
at `ethswarm-tools.github.io/bee-check/`.

### Added

- **`--cold` flag.** For each `--bee`, streams `GET /bytes/{ref}`
  to EOF; for each `--gateway`, streams `GET /bzz/{ref}/`. Records
  `bytes_downloaded` + `elapsed_ms` per URL. Exercises the HTTP
  body transport — distinct from stewardship, which only walks the
  chunk graph. Catches cases where stewardship and a manual `/bzz`
  fetch disagree (e.g. content served from local store but not
  network-retrievable). Informational only; does not contribute to
  the top-level `status` aggregate.
- **Report shape.** New `cold_downloads: ColdDownloadResult[]`
  field, additive on `spec_version: 1`. See `SPEC.md`.
- **mdBook manual.** 27-chapter manual covering concepts (Swarm
  refs, stewardship, multi-vantage, proximity, manifests, postage),
  CLI guide, web UI guide, cookbook, reference, troubleshooting,
  glossary, and a what's-new index. Deployed to GH Pages from
  `book/` via `.github/workflows/book.yml`. Includes an SVG
  proximity-order diagram and an asciinema cast of a real session.
- Cross-links: README links to manual and SPA; SPA README links
  back; SPA footer gained Manual/CLI/SPA links.

## [v0.4.0]

Tier-2 work from the parity analysis vs check.ipfs.network — features
with no IPFS analog, leaning into Swarm's deterministic neighborhood
addressing.

### Added

- **Per-chunk timing histogram.** Alongside `chunks[]`, the report
  now carries `chunk_stats` with `per_vantage` and `per_neighborhood`
  roll-ups (total/found/missing + p50/p95/max latency in ms). The
  text renderer shows two tables; the per-neighborhood one sorts by
  p95 desc so the slowest neighborhoods float up. Reveals "every
  chunk in neighborhood 0x4a is slow regardless of vantage", which
  is impossible to see from a single end-to-end probe.
- **`--target-overlay HEX`** flag. Computes the proximity order
  between each vantage and the target overlay, sorts vantages
  closest-first, and surfaces a `tgtPO N` trailer in the text output.
  Answers "from a node near neighborhood X, is this retrievable?"
  without changing what we probe.

### Schema

Additive on `spec_version: 1`:
- `Report.chunk_stats` (`Option<ChunkStats>`)
- `VantageResult.target_proximity` (`Option<u32>`)

v0.3 and earlier reports still parse. See `SPEC.md`.

## [v0.3.0]

Tier-1 #2 + partial-#3 from the [parity analysis vs check.ipfs.network].
Adds a public-gateway HEAD probe (the closest analog to ipfs-check's
multi-source provider discovery, given Swarm has no provider records)
and Swarm-feed resolution (the analog of IPNS resolution).

### Added

- **Gateway HEAD vantage.** `--gateway URL` (repeatable) probes
  `HEAD {url}/bzz/{ref}/` and reports retrievability based on HTTP
  status. Defaults to `https://api.gateway.ethswarm.org` (Foundation
  forwarding gateway that returns proper 404s — note: the
  `gateway.ethswarm.org` apex currently fronts a static page that
  200s everything, so the `api.` subdomain is what to use).
  `--no-gateway` disables the default.
- **Swarm-feed resolution.** Positional input now accepts
  `feed:OWNER:TOPIC` (or `feed:OWNER/TOPIC`); resolves via
  `GET /feeds/{owner}/{topic}` on the first `--bee` before probing.
  The Report's `resolution` field records the original feed handle
  so the diagnostic is reproducible.
- **Top-level `gateways`** array on `Report` (additive on
  `spec_version: 1`), with `GatewayResult { url, retrievable,
  elapsed_ms, status_code, error }`.
- **Status aggregation** now unions vantages + gateways. A reference
  is `retrievable` only if every probe (Bee or gateway) said yes;
  it's `partial` if at least one of either said yes.

### Notes

- Gateway probing is **end-to-end**: a gateway 200 means "anyone
  could fetch this through that gateway right now", which is a
  meaningfully different signal than `/stewardship` (which is "from
  the probed Bee's view"). The two answers can legitimately disagree.
- `--reseed` continues to issue against the first `--bee` URL; it
  does not work through `--gateway`.

## [0.2.0] - 2026-05-15

Tier-1 perception-parity work with `check.ipfs.network`. The probe is
still "from this vantage" by design — but it now tells you *which*
vantage you're probing from, how close that vantage sits to the
reference's neighborhood, and whether a re-seed stamp is usable
before doing the operation.

### Added

- **Neighborhood inference.** Every vantage now reports `overlay`
  (from `GET /addresses`) and `proximity_to_root` — the proximity
  order between the probe node and the reference. Per-chunk drill-
  down adds a per-chunk `proximity` field, so a miss surfaces as
  `chunk 1a2b… (nb 1a) missing on http://b.example (PO 0)` — you can
  see at a glance that the probe wasn't in the chunk's neighborhood.
  This is the Swarm-native analog of ipfs-check's "we hit N providers"
  display.
- **Bee version per vantage** (`bee_version`, from `GET /health`)
  surfaces version skew across multi-vantage probes.
- **`--reseed` pre-flight stamp check.** Before issuing
  `PUT /stewardship/{ref}`, bee-check now calls `GET /stamps/{id}` on
  the target Bee and refuses to proceed if the batch is unknown or
  not usable; warns (but proceeds) if `batchTTL` is under 24h. Spirit-
  ual analog of ipfs-check's "stale records" hint.

### Schema

All new fields are additive on `spec_version: 1`. v0.1 reports
continue to parse; old consumers that ignore unknown fields keep
working. See `SPEC.md`.

### Internal

- New `bee_check::check_stamp` and `render_stamp_status` library
  surface.
- `VantageResult` and `ChunkVantage` gained optional fields. The
  text renderer adds a `· overlay 7179…6c9a (nb 71) · PO 3 · v2.7.2`
  trailer per vantage; chunk-miss rows show `(PO N)` per affected
  vantage.

## [0.1.0] - 2026-05-15

Initial release. A retrievability checker for Swarm references in the
spirit of `check.ipfs.network`, but built on plain HTTP via
[bee-rs](https://github.com/ethswarm-tools/bee-rs) — no libp2p, no
hosted backend required.

### Added

- **Multi-vantage probe.** `bee-check <ref> --bee URL [--bee URL ...]`
  fans `GET /stewardship/{ref}` calls out across one or more Bee
  nodes in parallel and aggregates the results.
- **Per-chunk drill-down.** `--per-chunk` BFS-walks the Mantaray
  manifest from the root, probes `GET /chunks/{addr}` on every
  vantage, and surfaces which chunks are missing on which node
  (with the first 2 hex chars of the chunk address as the expected
  neighborhood). Capped at 1000 chunks for v1.
- **Re-seed.** `--reseed --stamp <batch-id>` issues
  `PUT /stewardship/{ref}` against the first vantage after the probe
  completes.
- **Status aggregation.** A top-level
  `retrievable | unretrievable | partial | error` status summarises
  the vantage matrix. Exit code is `0` when at least one vantage
  returns retrievable, `2` otherwise.
- **JSON output** via `--output json`, conforming to the schema
  documented in `SPEC.md` (`spec_version: 1`). The forthcoming
  `bee-check-web` static SPA consumes the same shape.
- **Defaults.** `BEE_API_URL` env var supplies the default vantage
  when no `--bee` flag is provided, falling back to
  `http://localhost:1633`.

### Known limitations

- The probe is "from this vantage", not "globally retrievable" — see
  `README.md` for the semantics.
- Most public Swarm gateways don't expose `/stewardship/{ref}`; point
  `--bee` at a node whose API you can reach.
- `--reseed` requires a usable postage batch known to the probing
  node.
