# Coherence-BFD Reference Implementation

Pure-Python reference implementation of the wire format and state
machine specified in:

- `draft-melegassi-coherence-bfd-00`
- `draft-melegassi-mvps-fast-incremental-00` (cell-aware minimax)
- `draft-melegassi-mvps-ddos-resilience-00` (dual-mode aggregation)

This satisfies IETF Section 7 / RFC 4101 requirements for an
interoperable reference implementation. Zero external dependencies
beyond the Python 3.10+ standard library.

## Files

| File | Purpose |
| ---- | ------- |
| `coherence_bfd_wire.py` | byte-level encoder/decoder for the §4 wire format (mandatory section + TLVs in Experimental range 0xE0..0xE9) |
| `mvps_vantage.py` | reference vantage (probe): measures local coherence, packs Coherence-BFD packets, pushes over UDP with HMAC-SHA256 |
| `mvps_broker.py` | reference broker: listens on UDP, verifies HMAC, runs cell-aware minimax with M-multiplier, emits ALARM and BYZANTINE EVENT |
| `demo_interop.py` | spawns 1 broker + 4 vantages on loopback, runs 8 seconds, asserts wire interop and detection |

## Quick start

```
python coherence_bfd_wire.py    # self-test of wire format
python demo_interop.py          # end-to-end 1-broker / 4-vantage demo
```

Expected outcome of `demo_interop.py`:

```
[broker]  ~~~ BYZANTINE EVENT ~~~ max=48.68 minimax=0.06 ...
[broker]  >>> ALARM <<< D^2_minimax=48.68 argmax_cell=1 after 3 ticks above threshold
[broker] received=480 dropped_auth=0 vantages_seen=4
[broker] final state = INIT
  [PASS] received > 0
  [PASS] HMAC verified (dropped_auth=0)
  [PASS] 4 vantages observed
  Result: PASS
```

## What this proves

1. The wire format of draft-melegassi-coherence-bfd-00 §4 round-trips
   correctly (mandatory + D^2 field + TLVs in Experimental range).
2. HMAC-SHA256 over the packet (mandatory + TLVs, AuthHMAC TLV last)
   verifies cleanly on the receiver.
3. The cell-aware minimax detector of Theorem 7 (fast-incremental)
   correctly distinguishes between volumetric attack (max high,
   minimax also high) and Byzantine hiding (max high, minimax low).
4. The M-multiplier of Theorem 9 (fast-incremental) confirms ALARM
   only after M=3 consecutive ticks above threshold, suppressing
   transient noise.

## What this does NOT prove

- Performance at scale (this is a clarity-first reference; for
  benchmarks see `scripts/benchmark_fmvps_vs_ml.py`).
- Behaviour under operational network traces (RIPE Atlas / CAIDA
  validation is open work).
- IPv6 transport (the broker binds AF_INET; a one-line change to
  AF_INET6 enables IPv6, left as exercise).

## License

Same license as the parent project.