#Topology Parity Runbook

#Scope

• Validate topology engine parity against imported Enlinkd fixtures and assertion inventories.
• Evidence files live in src/go/pkg/l2topology/parity/evidence.

#Prerequisites

• Upstream checkout available at /tmp/topology-library-repos/enlinkd.
• Run commands from src/go.

#Refresh Evidence

go run ./tools/topology-parity-evidence --mode sync

What it does: - Verifies fixture source exists. - Refreshes local fixture mirror. - Regenerates: - enlinkd-fixture-inventory.csv - enlinkd-test-method-inventory.csv - enlinkd-assertion-inventory.csv

#Verify Mirror Integrity

go run ./tools/topology-parity-evidence --mode verify

Expected: - verify complete - Fixture counts match upstream mirror and evidence inventory.

#Run Full Parity Suite

go run ./tools/topology-parity-evidence --mode suite

Outputs: - parity-summary.json - Scenario pass/fail totals. - Mapped test/assertion coverage totals. - Determinism check (runs=2, byte_identical=true expected).

#Run Behavior Oracle Diff (Go vs Enlinkd Golden)

go run ./tools/topology-parity-evidence --mode oracle-diff

Outputs: - behavior-oracle-diff.json (machine-readable per-scenario diff report). - behavior-oracle-diff.md (human-readable summary). - Fixture-input evidence per scenario (walk file path + sha256 + size). - In-scope pass criteria: zero diffs for device identity set, hostname identity, adjacency set, and metadata counts.

#Run Go Test Gates

go test ./pkg/l2topology/... ./plugin/go.d/collector/snmp ./tools/topology-parity-evidence -count=1

Expected: - All packages pass.

#Failure Triage

1. verify fails:
   • Confirm upstream checkout path exists.
   • Re-run --mode sync, then --mode verify.
2. suite has failed scenarios:
   • Open parity-summary.json.
   • Inspect failing scenario IDs and manifests.
   • Re-run targeted tests in ./pkg/l2topology/parity.
3. Coverage totals regress:
   • Check assertion-mapping.csv uniqueness and status values.
   • Reconcile not-applicable-approved.csv with mapping rows using not-applicable-approved.
4. Determinism fails:
   • Re-run suite and compare generated summary files.
   • Check sort/order logic in parity result builders and adapters.