# MVPS Implementation Guide — From Traceroute to Alarm

**Version:** 1.1  
**Last updated:** 2026-05-27  
**Status:** Companion document (not an Internet-Draft)

This guide is the **operational bridge** between the **12 MVPS Internet-Drafts**
and a working deployment. The Bundle draft (D-1) specifies *what* the JSON
envelope looks like; this document explains *how to assemble the full stack*
step by step and maps **every draft** to a build step, optional profile, or
capstone read.

---

## 12-draft coverage matrix

Validated against `docs/IETF_DRAFTS_INDEX.md` on 2026-05-27.

| # | Code | Handle | Role in this guide | Step / section | Validator |
|---|------|--------|-------------------|----------------|-----------|
| 1 | **D-1** | `ippm-mvps-bundle-00` | Core envelope | Steps 1–3 | `mvps-conformance` |
| 2 | **D-2** | `mvps-incremental-be-00` | Cell-aware minimax broker | Steps 5–6 | `validate_detection_latency_lemma.py` |
| 3 | **D-3** | `coherence-bfd-00` | Fast UDP path (50 ms) | Step 5 | `reference-impl/demo_interop.py` |
| 4 | **D-4** | `mvps-ddos-resilience-00` | Dual-mode aggregation | Step 6 | `validate_detection_latency_lemma.py` |
| 5 | **D-5** | `mvps-ai-coherence-00` | Optional: LLM semantic profile | § Optional A | `MVPS_LM_CBF_HOWTO.md` |
| 6 | **D-6** | `ippm-mvps-coherence-leadtime-00` | Optional: zero-day lead-time | § Optional B | `validate_lead_time_lemma.py` |
| 7 | **D-7** | `ippm-mvps-orbital-coherence-00` | Optional: LEO / ISL paths | § Optional C | `validate_orbital_error_exponent.py` |
| 8 | **TRUST** | `santos-ippm-mvps-trust-00` | Basic trust + admission | Step 4a | `validate_trust_theorems.py` (9/9) |
| 9 | **CWT** | `santos-ippm-mvps-cwt-00` | Coherent-Witness Trust (prod) | Step 4b | `validate_cwt_theorems.py` (12/12) |
| 10 | **D-15** | `iab-mvps-planetary-floor-00` | Capstone: planetary floor | § Capstones | `validate_planetary_floor.py` (9/9) |
| 11 | **D-16** | `iab-mvps-architecture-00` | Capstone: axiom unification | § Capstones | `validate_planetary_floor.py` (9/9) |
| 12 | **D-17** | `mvps-perfsec-coupling-00` | Joint CWT × BFD × DDoS sizing | Step 7 | `validate_perfsec_coupling.py` (12/12) |

**Verdict:** all 12 drafts are mapped. Steps 1–7 cover the **terrestrial core**
(D-1, D-2, D-3, D-4, TRUST, CWT, D-17). D-5/D-6/D-7 are **optional profiles**
on the same bundle. D-15/D-16 are **capstones** — read after the core path to
confirm the family closes mathematically; they do not add wire fields.

---

## What this document is — and is not

| This guide **is** | This guide **is not** |
|---|---|
| A step-by-step build recipe for implementers | A normative IETF specification |
| Links to drafts, code, validators, and receipts | A replacement for D-1 Appendix C/D |
| A single narrative from probe → bundle → trust → broker → alarm | A probing-protocol spec (use RIPE Atlas, scamper, etc.) |

Normative rules always live in the Internet-Drafts on
[datatracker.ietf.org](https://datatracker.ietf.org/). If this guide
conflicts with a draft, **the draft wins**.

---

## Where this document is published

This file follows the same two-layer publishing model as
`MVPS_LIVE_API_CONTRACT.md` and the proof companions:

| Layer | Path | URL (after deploy) |
|---|---|---|
| **Canonical (repo)** | `docs/MVPS_IMPLEMENTATION_GUIDE.md` | GitHub / local checkout |
| **Public mirror** | `frontend/static/download/MVPS_IMPLEMENTATION_GUIDE.md` | `https://catellix.com/static/download/MVPS_IMPLEMENTATION_GUIDE.md` |

Cross-linked from:

- `docs/IETF_DRAFTS_INDEX.md` — index entry under *Implementation guides*
- `mvps_bundle/README.md` — bundle-format quick start
- `reference-impl/README.md` — Coherence-BFD wire demo
- `frontend/static/v11-evidence.html` — optional download card (when synced)

**Not published on:** datatracker.ietf.org (that channel is reserved for
Internet-Drafts only). You *may* cite this URL in WG emails or draft
`-01` informative references.

---

## Architecture at a glance

```mermaid
flowchart LR
  subgraph measure["1. Measure"]
    V1[Vantage 1]
    V2[Vantage 2]
    VN[Vantage N]
    V1 --> TR[Coordinated traceroute]
    V2 --> TR
    VN --> TR
  end

  subgraph envelope["2. Envelope (D-1)"]
    TR --> BND[MVPS bundle JSON]
    BND --> FP[path_fingerprint]
    BND --> CAN[canonicalize]
  end

  subgraph trust["3. Trust (TRUST + CWT)"]
    CAN --> TRUST[Admission + HMAC]
    TRUST --> CWT[HMAC + witnesses]
  end

  subgraph fast["4. Fast path (D-3)"]
    V1 --> BFD[Coherence-BFD UDP]
    V2 --> BFD
    VN --> BFD
  end

  subgraph broker["5. Broker (D-2 + D-3 + D-4 + D-17)"]
    CWT --> BRK[Broker]
    BFD --> BRK
    BRK --> ALM[ALARM / BYZANTINE EVENT]
  end
```

Two parallel paths feed the broker:

1. **Slow path** — coordinated traceroute → MVPS bundle → TRUST admission → CWT envelope
2. **Fast path** — Coherence-BFD packets at 50 ms tick (sub-second detection)

D-2 supplies the **cell-aware minimax** estimator inside the broker (Steps 5–6).
D-17 tells you how to **dimension** both paths together so security does not
silently crush performance.

Optional profiles (same bundle, different axis definitions):

- **D-5** — AI/LLM semantic coherence (embeddings instead of RTT)
- **D-6** — zero-day lead-time lemmas on propagating signals
- **D-7** — LEO orbital paths with TLE-predicted topology

Capstones **D-15** and **D-16** compose all profiles into planetary floor and
architecture invariance — read after Steps 1–7, not during initial build.

---

## Prerequisites

- Python 3.10+ (reference code uses stdlib only)
- Repository checkout with `mvps_bundle/`, `reference-impl/`, `scripts/`
- At least **two vantages** with clocks synchronised within the
  coordination window (NTP/chrony; see D-1 §7.2)
- A shared destination prefix to probe

---

## Step 1 — Run coordinated traceroute

**Draft:** D-1 §7 (coordination window semantics)  
**Out of scope for D-1:** which probe tool you use

Each vantage runs traceroute (or equivalent) toward the same destination
**inside the coordination window** declared in the bundle:

```json
"coordination_window": {
  "start": "2026-05-17T18:00:00.000Z",
  "end":   "2026-05-17T18:00:00.500Z",
  "tolerance": "tight"
}
```

Collect per vantage:

- `vantage_id` — stable string identifier (e.g. `"V0"`, `"ams01"`)
- `start_timestamp` — ISO 8601 UTC when the trace began
- ordered hop list: `index`, `address`, optional `rtt_samples[]`

**Probe tools (examples, not normative):**

| Tool | Role |
|---|---|
| RIPE Atlas | Managed vantage network; export JSON → map to MVPS fields |
| scamper / warts | High-volume probing; map hop records to MVPS `Hop` objects |
| Custom ICMP/TCP traceroute | Full control over timing inside the window |

**Checklist before Step 2:**

- [ ] ≥ 2 vantages traced the same destination
- [ ] All traces fall inside `[start, end]` of the coordination window
- [ ] Hop indices start at 1 and are contiguous
- [ ] IPv6 addresses will be normalised per D-1 §5.2 (RFC 5952)

---

## Step 2 — Assemble the MVPS bundle

**Draft:** D-1 §5  
**Code:** `mvps_bundle/` package

Build one JSON object containing all vantage snapshots:

```python
from mvps_bundle import (
    Bundle, CoordinationWindow, Destination, Hop, RttSample, Snapshot,
    canonicalize_bundle, validate_bundle,
)

bundle = Bundle(
    bundle_id="11111111-1111-4111-8111-111111111111",  # UUID v4
    destination=Destination(address="192.0.2.1"),
    coordination_window=CoordinationWindow(
        start="2026-05-17T18:00:00.000Z",
        end="2026-05-17T18:00:00.500Z",
        tolerance="tight",
    ),
    snapshots=[
        Snapshot(
            vantage_id="V0",
            start_timestamp="2026-05-17T18:00:00.000Z",
            hops=[
                Hop(index=1, address="198.51.100.1",
                    rtt_samples=[RttSample(value_ms=1.234)]),
                Hop(index=2, address="198.51.100.42",
                    rtt_samples=[RttSample(value_ms=5.678)]),
                Hop(index=3, address="192.0.2.1",
                    rtt_samples=[RttSample(value_ms=12.345)]),
            ],
        ),
        # ... one Snapshot per vantage ...
    ],
)

canon = canonicalize_bundle(bundle.to_dict())
validate_bundle(canon)   # raises on structural errors
```

**Checklist:**

- [ ] `bundle_id` is a valid UUID
- [ ] Every snapshot has a unique `vantage_id`
- [ ] Field order will be fixed by `canonicalize_bundle()` (D-1 §5.1)
- [ ] Opaque hops (`*`) handled per D-1 §6.2 if present

---

## Step 3 — Compute path fingerprint

**Draft:** D-1 §6  
**Code:** `mvps_bundle.path_fingerprint()`

The fingerprint is a deterministic SHA-256 over the canonical hop
sequence toward the destination. Two independent implementations
must produce **bit-identical** output.

```python
from mvps_bundle import path_fingerprint

fp = path_fingerprint(
    destination_address="192.0.2.1",
    hops=[
        {"index": 1, "address": "198.51.100.1"},
        {"index": 2, "address": "198.51.100.42"},
        {"index": 3, "address": "192.0.2.1"},
    ],
)
# fp == 64 lowercase hex chars
```

**Verify against test vectors:**

```bash
mvps-conformance docs/drafts/track-a/test-vectors/
# exit 0 = bit-identical against all Appendix D vectors
```

---

## Step 4a — Trust profile and vantage admission (TRUST)

**Draft:** `draft-melegassi-santos-ippm-mvps-trust-00`  
**Validator:** `scripts/validate_trust_theorems.py` (9/9 PASS)

Before any detector consumes snapshots, enforce **H-TRUST** and **H-ADM**:

1. **Three-tier key hierarchy** — vantage key, operator key, session/bundle key
2. **Vantage admission** — only registered vantages enter the `N`-set (restores
   Theorem 9 applicability: `f < N/2` over an *admitted* set)
3. **Parser safety limits** — max bundle size, hop count, JSON depth (TRUST §8)
4. **Anti-replay fields** — per-snapshot sequence or nonce before ingest

Without TRUST, a Sybil attacker registering cheap fake vantages defeats
Byzantine bounds even if the path-fingerprint is correct.

```bash
python scripts/validate_trust_theorems.py
# expect: 9/9 PASS, exit 0
```

**Checklist:**

- [ ] Admission policy documented (TRUST §11.1)
- [ ] Ingest rate limits configured
- [ ] Unauthenticated snapshots rejected before D² computation

---

## Step 4b — Attach Coherent-Witness Trust (CWT)

**Draft:** `draft-melegassi-santos-ippm-mvps-cwt-00` (extends TRUST)  
**Proof companion:** `docs/MVPS_CWT_MATHEMATICAL_PROOF.txt`  
**Worked example:** CWT Appendix B (7-step verification)

CWT is the **production trust profile** for multi-vantage coalitions.
It adds witness cosignatures on top of TRUST's admission model:

1. Choose an **epoch** and **key-derivation** context (CWT §13)
2. Compute **HMAC-SHA256** over the canonical bundle bytes
3. Record **witness counters** from each signing vantage
4. Ship `{bundle, cwt_envelope}` to the collector/broker

On the broker side, acceptance requires **both**:

- CWT counter monotonicity within the epoch (T-RC-1 in D-17)
- Coherence-BFD sequence monotonicity on the fast path (see Step 5)

```bash
python scripts/validate_cwt_theorems.py
# expect: 12/12 PASS, exit 0
```

See CWT Appendix B for a concrete verification walk-through with
expected intermediate values.

**Checklist:**

- [ ] HMAC key derived with the normative HKDF info-string (CWT §13)
- [ ] Witness set covers ≥ the minimum coalition threshold (H-WIT)
- [ ] Replay window configured (counter + epoch reset rules per D-17 T-RC-1)

---

## Step 5 — Run the Coherence-BFD fast path

**Drafts:** D-3 (`coherence-bfd-00`) + D-2 (`incremental-be-00`, cell partition)  
**Code:** `reference-impl/`

Each vantage periodically emits Coherence-BFD UDP packets containing:

- Mandatory BFD-compatible header + **D² field** (4 bytes)
- Experimental TLVs in range `0xE0..0xE9`
- **AuthHMAC TLV last** (HMAC-SHA256 over mandatory + preceding TLVs)

Quick smoke test (loopback, no real network needed):

```bash
cd reference-impl
python coherence_bfd_wire.py    # wire-format self-test
python demo_interop.py            # 1 broker + 4 vantages, 8 seconds
```

Expected broker output includes:

```
>>> ALARM <<< D^2_minimax=...
~~~ BYZANTINE EVENT ~~~
[PASS] HMAC verified (dropped_auth=0)
```

**Timing defaults (software harness):**

| Parameter | Typical value | Draft ref |
|---|---|---|
| `T_tick` | 50 ms | D-3 §5 |
| `M` (consecutive ticks) | 3 | D-2 Theorem 9 |
| `τ_detect` | ~55 ms (V3 Echo variant) | D-3 §6 |

---

## Step 6 — Broker aggregation and DDoS mode

**Drafts:** D-2 (cell-aware minimax) + D-3 (state machine) + D-4 (volume-independent DDoS)

The broker implements D-2's **cell-aware minimax** estimator inside D-3's
state machine, with D-4's dual-mode aggregation:

1. Verifies HMAC on every incoming Coherence-BFD packet
2. Maintains per-vantage, per-cell **D²** state
3. Runs **max** vs **minimax** aggregation (D-4 dual mode):
   - Volumetric flood → both max and minimax high
   - Byzantine hiding → max high, minimax low → `BYZANTINE EVENT`
4. Emits `ALARM` only after **M** consecutive ticks above threshold

For DDoS resilience details and regime classification (A/B/C/D), see
D-4 §8 and `scripts/benchmark_fmvps_vs_ml.py` for scaling numbers.

```bash
python scripts/validate_detection_latency_lemma.py
# expect: 5/5 PASS — reconciles D-2/D-3/D-4 detection latency bounds
```

---

## Optional profile A — AI semantic coherence (D-5)

**Draft:** `draft-melegassi-mvps-ai-coherence-00`  
**Howto:** `docs/MVPS_LM_CBF_HOWTO.md`

Use when vantages are **LLM inference endpoints** rather than network probes.
D-5 replaces C_2/C_3 with embedding-space metrics (Wasserstein-2, CKA) but
inherits the same D² detector and phase machine from the core family.

**When to enable:** AI-serving surfaces, CBF (Coherent Belief Failure) detection,
Byzantine LLM outputs.

**Smoke test:**

```bash
python scripts/mvps_ollama_cbf_experiment.py --mock --probes 5 \
       --out evidence/mvps_lm_cbf_smoke.json
```

D-5 does **not** change the bundle wire format (D-1) or BFD wire format (D-3);
it changes how coherence axes are computed before D².

---

## Optional profile B — Zero-day lead-time (D-6)

**Draft:** `draft-melegassi-ippm-mvps-coherence-leadtime-00`  
**Lemma companion:** `docs/MVPS_ZERODAY_LEAD_TIME_LEMMA.txt`  
**Validator:** `scripts/validate_lead_time_lemma.py` (7/7 PASS)

Use when the operational goal is **response budget before public IoC** on
propagating, rank-low, monotone-growth events (zero-day propagation phase).

D-6 layers on top of an existing D-1..D-4 deployment — it does not replace
the broker, it characterises when the Mahalanobis detector **leads** the
per-vantage z-score detector.

```bash
python scripts/validate_lead_time_lemma.py
python scripts/validate_zeroday_lead_time.py
```

---

## Optional profile C — Orbital / LEO coherence (D-7)

**Draft:** `draft-melegassi-ippm-mvps-orbital-coherence-00`  
**Proof companion:** `docs/MVPS_ORBITAL_PROOF.txt`  
**Validator:** `scripts/validate_orbital_error_exponent.py` (11/11 PASS)

Use when vantages include **LEO satellite ISLs**. D-7 maps the same D-1 bundle
onto orbital paths with two adaptations only:

1. Mixed-medium causal lower bound for C_1 (vacuum vs fiber)
2. TLE-predicted topology component for C_3 (SGP4 propagator)

No new wire fields. Reuses D-1 envelope, D-3 fast path, and D-4 aggregation.

```bash
python scripts/validate_orbital_error_exponent.py
# expect: 11/11 PASS, exit 0
```

---

## Capstones — planetary floor and architecture (D-15, D-16)

**Drafts:**

- D-15 `draft-melegassi-iab-mvps-planetary-floor-00` — composes reactive-latency
  floors from D-1..D-7 into a single **Planetary Coherence Floor (PCF)**
- D-16 `draft-melegassi-iab-mvps-architecture-00` — proves all conformant
  profiles inherit the same theorem catalogue via axioms MVPS-A1..A5

These are **not build steps**. Read them after Steps 1–7 to confirm:

- Your deployment satisfies the five MVPS axioms (D-16)
- Your `(N, T_tick, media)` choice meets the planetary floor inequality (D-15)

```bash
python scripts/validate_planetary_floor.py
# expect: 9/9 PASS — axiom check for D-15 + D-16
```

Proof companions: `docs/MVPS_PCF_PROOF.txt`, `docs/MVPS_ARCH_PROOF.txt`.

## Step 7 — Dimension the joint stack (D-17)

**Draft:** `draft-melegassi-mvps-perfsec-coupling-00`  
**Validator:** `scripts/validate_perfsec_coupling.py`

Before production deployment, confirm the broker host can sustain the
**joint cost** of CWT verification + BFD processing at your target
`(N, T_tick)`:

```bash
python scripts/validate_perfsec_coupling.py
# expect: 12/12 PASS, exit 0
```

Key outputs (Regime C, N=10k vantages, T_tick=50 ms):

| Metric | Value | Theorem |
|---|---|---|
| Joint broker CPU | ~174% of one core | T-JCOST-1 |
| Apples-to-apples vs CWT-only | ~198× | T-JCOST-1 |
| Verification-DoS bound (with rate-limit) | capped at 10× baseline | T-VDOS-1 |
| Replay acceptance rule | AND(BFD seq, CWT counter) | T-RC-1 |

Receipts (machine-readable, pinned constants):

- `evidence/perfsec_joint_cost_receipt.json`
- `evidence/perfsec_verification_dos_receipt.json`

If your deployment exceeds Regime C, re-run the validator with your
`(N, T_tick, flood_factor)` and scale hardware accordingly.

---

## End-to-end verification checklist

### Core path (Steps 1–7) — run in order

```bash
# D-1: bundle conformance
mvps-conformance docs/drafts/track-a/test-vectors/

# TRUST: admission + Sybil bounds
python scripts/validate_trust_theorems.py          # 9/9

# CWT: witness coalition
python scripts/validate_cwt_theorems.py            # 12/12

# D-3: Coherence-BFD interop
python reference-impl/demo_interop.py

# D-2/D-3/D-4: detection latency reconciliation
python scripts/validate_detection_latency_lemma.py # 5/5

# D-17: joint perf/security dimensioning
python scripts/validate_perfsec_coupling.py       # 12/12

# v4.0 master theorem suite (recommended)
python scripts/validate_v4_against_all_attacks.py # 44/44
```

### Optional profiles — run if enabled

```bash
# D-5: AI semantic / CBF smoke
python scripts/mvps_ollama_cbf_experiment.py --mock --probes 5 \
       --out evidence/mvps_lm_cbf_smoke.json

# D-6: lead-time lemmas
python scripts/validate_lead_time_lemma.py         # 7/7
python scripts/validate_zeroday_lead_time.py

# D-7: orbital error exponent
python scripts/validate_orbital_error_exponent.py  # 11/11
```

### Capstones — run after core PASS

```bash
# D-15 + D-16: planetary floor + architecture axioms
python scripts/validate_planetary_floor.py         # 9/9
```

All core validators should exit 0. Receipts land in `evidence/`.

---

## Complete draft ↔ code map (all 12)

| Draft | Role | Code / script / doc |
|---|---|---|
| **D-1** Bundle | JSON envelope + fingerprint | `mvps_bundle/` |
| **D-2** BE-MVPS | Cell-aware minimax | `reference-impl/mvps_broker.py` |
| **D-3** Coherence-BFD | Fast wire + state machine | `reference-impl/coherence_bfd_wire.py` |
| **D-4** DDoS | Dual-mode max/minimax | `reference-impl/mvps_broker.py` |
| **D-5** AI-coherence | LLM semantic axes | `docs/MVPS_LM_CBF_HOWTO.md`, `scripts/mvps_ollama_cbf_experiment.py` |
| **D-6** Lead-time | Zero-day propagation lemmas | `scripts/validate_lead_time_lemma.py`, `scripts/validate_zeroday_lead_time.py` |
| **D-7** Orbital | LEO / TLE mapping | `scripts/validate_orbital_error_exponent.py` |
| **TRUST** | Admission + basic auth | `scripts/validate_trust_theorems.py` |
| **CWT** | Witness coalition trust | CWT Appendix B; `scripts/build_cwt_pcap.py`, `scripts/validate_cwt_theorems.py` |
| **D-15** Planetary floor | PCF composition | `scripts/validate_planetary_floor.py`, `docs/MVPS_PCF_PROOF.txt` |
| **D-16** Architecture | Axiom invariance | `scripts/validate_planetary_floor.py`, `docs/MVPS_ARCH_PROOF.txt` |
| **D-17** PerfSec coupling | Joint CWT×BFD×DDoS sizing | `scripts/validate_perfsec_coupling.py` |
| *(live UI)* | Real-time validation | `docs/MVPS_LIVE_API_CONTRACT.md`, `/v11-evidence.html` |

Full draft index: `docs/IETF_DRAFTS_INDEX.md`.

---

## FAQ

**Do I need a 13th Internet-Draft for this guide?**  
No. IETF practice is: normative drafts + examples + reference
implementation. This guide is the narrative glue, published as a
companion document at the URL above.

**Can I use only the bundle without BFD?**  
Yes for **path auditing** (fingerprint, cross-vantage comparison).
Sub-second **detection** requires the Coherence-BFD fast path (D-3).

**Do I need all 12 drafts to deploy?**  
No. **Minimum viable:** D-1 + TRUST + D-3 + D-2 + D-4 + D-17 (Steps 1–7).
Add D-5/D-6/D-7 only for AI, zero-day lead-time, or LEO profiles.
Read D-15/D-16 after the core path passes validation.

**Where do I cite this in a draft?**  
Informative reference in a `-01` revision, e.g.:
`[MVPS-IMPL-GUIDE] Melegassi, L., "MVPS Implementation Guide",
Catellix Research, May 2026, https://catellix.com/static/download/MVPS_IMPLEMENTATION_GUIDE.md`

---

## Changelog

| Date | Change |
|---|---|
| 2026-05-27 | v1.1 — 12-draft coverage matrix; TRUST step 4a; optional D-5/D-6/D-7; capstones D-15/D-16; full validator checklist |
| 2026-05-27 | v1.0 — initial release (7-step guide, publishing locations, verification checklist) |