| 1 | # Topology Parity Runbook |
| 2 | |
| 3 | ## Scope |
| 4 | - Validate topology engine parity against imported Enlinkd fixtures and assertion inventories. |
| 5 | - Evidence files live in `src/go/pkg/l2topology/parity/evidence`. |
| 6 | |
| 7 | ## Prerequisites |
| 8 | - Upstream checkout available at `/tmp/topology-library-repos/enlinkd`. |
| 9 | - Run commands from `src/go`. |
| 10 | |
| 11 | ## Refresh Evidence |
| 12 | ```bash |
| 13 | go run ./tools/topology-parity-evidence --mode sync |
| 14 | ``` |
| 15 | |
| 16 | What it does: |
| 17 | - Verifies fixture source exists. |
| 18 | - Refreshes local fixture mirror. |
| 19 | - Regenerates: |
| 20 | - `enlinkd-fixture-inventory.csv` |
| 21 | - `enlinkd-test-method-inventory.csv` |
| 22 | - `enlinkd-assertion-inventory.csv` |
| 23 | |
| 24 | ## Verify Mirror Integrity |
| 25 | ```bash |
| 26 | go run ./tools/topology-parity-evidence --mode verify |
| 27 | ``` |
| 28 | |
| 29 | Expected: |
| 30 | - `verify complete` |
| 31 | - Fixture counts match upstream mirror and evidence inventory. |
| 32 | |
| 33 | ## Run Full Parity Suite |
| 34 | ```bash |
| 35 | go run ./tools/topology-parity-evidence --mode suite |
| 36 | ``` |
| 37 | |
| 38 | Outputs: |
| 39 | - `parity-summary.json` |
| 40 | - Scenario pass/fail totals. |
| 41 | - Mapped test/assertion coverage totals. |
| 42 | - Determinism check (`runs=2`, `byte_identical=true` expected). |
| 43 | |
| 44 | ## Run Behavior Oracle Diff (Go vs Enlinkd Golden) |
| 45 | ```bash |
| 46 | go run ./tools/topology-parity-evidence --mode oracle-diff |
| 47 | ``` |
| 48 | |
| 49 | Outputs: |
| 50 | - `behavior-oracle-diff.json` (machine-readable per-scenario diff report). |
| 51 | - `behavior-oracle-diff.md` (human-readable summary). |
| 52 | - Fixture-input evidence per scenario (walk file path + sha256 + size). |
| 53 | - In-scope pass criteria: zero diffs for device identity set, hostname identity, adjacency set, and metadata counts. |
| 54 | |
| 55 | ## Run Go Test Gates |
| 56 | ```bash |
| 57 | go test ./pkg/l2topology/... ./plugin/go.d/collector/snmp ./tools/topology-parity-evidence -count=1 |
| 58 | ``` |
| 59 | |
| 60 | Expected: |
| 61 | - All packages pass. |
| 62 | |
| 63 | ## Failure Triage |
| 64 | 1. `verify` fails: |
| 65 | - Confirm upstream checkout path exists. |
| 66 | - Re-run `--mode sync`, then `--mode verify`. |
| 67 | 2. `suite` has failed scenarios: |
| 68 | - Open `parity-summary.json`. |
| 69 | - Inspect failing scenario IDs and manifests. |
| 70 | - Re-run targeted tests in `./pkg/l2topology/parity`. |
| 71 | 3. Coverage totals regress: |
| 72 | - Check `assertion-mapping.csv` uniqueness and status values. |
| 73 | - Reconcile `not-applicable-approved.csv` with mapping rows using `not-applicable-approved`. |
| 74 | 4. Determinism fails: |
| 75 | - Re-run `suite` and compare generated summary files. |
| 76 | - Check sort/order logic in parity result builders and adapters. |