# feat\(netflow-db\): pin MAAD oracle to maad main @ b7bbb7d · PR \#109 · flambo/atlantis

[View on GitCafe](https://git.cafe/flambo/atlantis/pull/109)

Repository: [flambo/atlantis](https://git.cafe/flambo/atlantis)

Visibility: public

State: merged

Source repository: flambo/atlantis

Source branch: maad/03-pin-bump

Target branch: maad/02-locality-direction

Head commit: b590ac31ce70a3734ec835b846055a8aea5799b3

[Discussion and reviews](https://git.cafe/flambo/atlantis/pull/109)

[Commits](https://git.cafe/flambo/atlantis/pull/109/commits?format=markdown)

[Files changed](https://git.cafe/flambo/atlantis/pull/109/diffs?format=markdown)

## Description

---

> [!NOTE]
> 🤖 **Claude Opus 5.5 on behalf of Oliver**

## ELI5

Updates our reference copy of the MAAD research code to the author's latest version and matches our Rust port to it.

## Why

Upstream [chris-misa/maad](https://github.com/chris-misa/maad) merged `atomic-full-sortout` into `main` and then fixed spectrum estimation ([b7bbb7d](https://github.com/chris-misa/maad/commit/b7bbb7dd119f9e050cb74239b89e472ad58ec5db)). Our conformance oracle was pinned to an older commit.

## What changes

- The documented oracle pin moves to maad `main` @ b7bbb7d, still with the one-line `deltaQ = 1/8` patch. The oracle is the separately cloned upstream checkout described in [`docs/code/maad-conformance.md`](https://github.com/flamboh/atlantis/blob/maad/03-pin-bump/docs/code/maad-conformance.md) (`/tmp/maad`); the `vendor/maad` gitlink is unchanged by this PR.
- Dimension rows are ordered q = 0, 1, 2 and carry `sd`, as upstream. D1's `sd` is `0`, meaning "not estimated".
- Spectrum port of b7bbb7d: compute the critical region (q_min, q_max) from τ, keep only α inside it, and treat equal consecutive α as still decreasing (tie tolerance 1e-12). The `mixed` fixture goes from 25 to 16 spectrum rows.
- Goldens regenerated; docs and fixtures README updated. MAAD contract and JSON schema versions bump, so pipeline databases with MAAD results must be regenerated as fresh products.

## Review path

1. `cargo test -p atlantis-netflow-db --test maad_conformance` — all five fixtures pass against the regenerated goldens.
2. Optional oracle check: build the patched oracle per the guide, build Rust with `./scripts/build_maad_fast.sh`, then run on a public fixture:

   ```sh
   python3 scripts/local/validate_maad.py \
     --rust target/release/netflow-db \
     --haskell /tmp/maad/MAAD \
     mixed=tools/netflow-db/tests/fixtures/maad-conformance/mixed/input.txt
   ```

   Expected: `mixed: PASS total=128 prefixes=17 rows=structure:33,spectrum:16,dimensions:3` and exit code 0.

## Edge cases and decisions

- `--auto-stop`, IPv6 input, and the new Hotelling T² / `--compare-structure` tests are not ported; none are part of the compared IPv4 output.
- Prefix selection, structure rows, and dimension values are unchanged; only spectrum filtering and dimension serialization change.
- On perfectly linear synthetic curves, Haskell's exact `a1 >= a2` stops early on last-bit noise in τ while Rust keeps all tied rows. Goldens and real windows agree; the validator still requires exact row counts, so use inputs with real spectrum curvature.
- The oracle cannot produce JSON for empty, singleton, or fully filtered sets; Rust returns an empty result. These cases are excluded from conformance runs.

## Verification

- Automated: `bun run format`, `bun run lint`, `bun run typecheck`, `bun run test:db` (includes `maad_conformance`).
- Validator: 25/25 IPv4 cases (5 public fixtures + 20 private real windows) pass against b7bbb7d.
- Validator on the public `mixed` fixture against a freshly built patched oracle (b7bbb7d + `deltaQ = 1/8`): output matched the expected line above, exit 0.
- Remaining manual verification: none required; the optional validator run above reproduces the oracle comparison.

---
Made by Claude Opus 5.5 (with Opus 5.5 subagents) via Claude Code.