chore(go.d): retire legacy Go topology payloads (netdata#22614)

Author: ilyam8

.agents/skills/project-create-topology/SKILL.md

@@ -41,8 +41,9 @@ developer-facing and must stay in this project skill, not under
 ## Core Rules
 
 - Production payloads carry canonical topology facts for the aggregator and UI.
-- Go producers MUST use `src/go/pkg/topology/v1`. The non-v1
-  `src/go/pkg/topology` payload model is legacy for new producers.
+- Go producers MUST use `src/go/pkg/topology/v1`. The non-v1 root
+  `src/go/pkg/topology` payload model has been retired and MUST NOT be
+  reintroduced for production topology payloads.
 - Test-only projection code may reconstruct compatibility payload shapes to
   prove parity.
 - Never add compatibility reconstruction fields, old-schema adapter names, or

.agents/skills/project-writing-collectors/SKILL.md

@@ -478,8 +478,9 @@ Topology is its own data type — directed/undirected graphs of nodes and links.
 - **Live socket topology** (`src/collectors/network-viewer.plugin/`) — local L3/L4 sockets and their inferred connections.
 - **Streaming graph** (`src/streaming/`) — Netdata parent/child topology.
 - **Topology library** at `src/go/pkg/topology/v1` — production Go payload
-  helpers for new topology producers. The non-v1 `src/go/pkg/topology/` payload
-  model is legacy and must not be used for new topology work.
+  helpers for new topology producers. The non-v1 root
+  `src/go/pkg/topology/` payload model has been retired and must not be
+  reintroduced for topology work.
 
 Topology is consumed via Functions (`topology:*` family), not via metrics. The cardinality of network edges is too high for time-series storage and the use case is interactive lookup.
 

.codacy.yml

@@ -15,7 +15,7 @@ exclude_paths:
   - src/aclk/mqtt_websockets/**
   - TODO-netflow-code-organization.md
   - TODO-netflow-plugin-refactor.md
-  - src/go/pkg/topology/engine/parity/README.md
-  - src/go/pkg/topology/engine/parity/evidence/**
+  - src/go/pkg/l2topology/parity/README.md
+  - src/go/pkg/l2topology/parity/evidence/**
   - .agents/**
   - docs/netdata-ai/skills/**

src/go/pkg/topology/types.go src/go/pkg/l2topology/graph_types.gosrc/go/pkg/topology/types.go renamed to src/go/pkg/l2topology/graph_types.go

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-package topology
+package l2topology
 
 import "time"
 
@@ -54,88 +54,6 @@ type Link struct {
 	Metrics      map[string]any `json:"metrics,omitempty"`
 }
 
-// Presentation defines how the UI should render this topology.
-// Sent in the info response, not in data responses.
-
-type PresentationSummaryField struct {
-	Key     string   `json:"key"`
-	Label   string   `json:"label"`
-	Sources []string `json:"sources"`
-}
-
-type PresentationTableColumn struct {
-	Key   string `json:"key"`
-	Label string `json:"label"`
-	Type  string `json:"type,omitempty"`
-}
-
-type PresentationTable struct {
-	Label        string                    `json:"label"`
-	Source       string                    `json:"source"`
-	BulletSource bool                      `json:"bullet_source,omitempty"`
-	Order        int                       `json:"order,omitempty"`
-	Columns      []PresentationTableColumn `json:"columns"`
-}
-
-type PresentationModalTab struct {
-	ID    string `json:"id"`
-	Label string `json:"label"`
-	Type  string `json:"type,omitempty"`
-}
-
-type PresentationActorType struct {
-	Label           string                       `json:"label"`
-	ColorSlot       string                       `json:"color_slot"`
-	Opacity         float64                      `json:"opacity,omitempty"`
-	Border          bool                         `json:"border"`
-	Role            string                       `json:"role,omitempty"`
-	SizeByLinks     bool                         `json:"size_by_links,omitempty"`
-	ShowPortBullets bool                         `json:"show_port_bullets,omitempty"`
-	IconSVG         string                       `json:"icon_svg,omitempty"`
-	SummaryFields   []PresentationSummaryField   `json:"summary_fields"`
-	Tables          map[string]PresentationTable `json:"tables"`
-	ModalTabs       []PresentationModalTab       `json:"modal_tabs"`
-}
-
-type PresentationLinkType struct {
-	Label     string  `json:"label"`
-	ColorSlot string  `json:"color_slot"`
-	Opacity   float64 `json:"opacity,omitempty"`
-	Width     float64 `json:"width,omitempty"`
-	Dash      bool    `json:"dash,omitempty"`
-}
-
-type PresentationPortType struct {
-	Label     string  `json:"label"`
-	ColorSlot string  `json:"color_slot"`
-	Opacity   float64 `json:"opacity,omitempty"`
-}
-
-type PresentationPortField struct {
-	Key   string `json:"key"`
-	Label string `json:"label"`
-}
-
-type PresentationLegendEntry struct {
-	Type  string `json:"type"`
-	Label string `json:"label"`
-}
-
-type PresentationLegend struct {
-	Actors []PresentationLegendEntry `json:"actors"`
-	Links  []PresentationLegendEntry `json:"links"`
-	Ports  []PresentationLegendEntry `json:"ports,omitempty"`
-}
-
-type Presentation struct {
-	ActorTypes         map[string]PresentationActorType `json:"actor_types"`
-	LinkTypes          map[string]PresentationLinkType  `json:"link_types"`
-	PortTypes          map[string]PresentationPortType  `json:"port_types,omitempty"`
-	PortFields         []PresentationPortField          `json:"port_fields,omitempty"`
-	Legend             PresentationLegend               `json:"legend"`
-	ActorClickBehavior string                           `json:"actor_click_behavior"`
-}
-
 type FlowExporter struct {
 	IP           string `json:"ip,omitempty"`
 	Name         string `json:"name,omitempty"`
@@ -164,7 +82,7 @@ type IPPolicy struct {
 	LiveTopN        *LiveTopN `json:"live_top_n,omitempty"`
 }
 
-type Data struct {
+type Graph struct {
 	SchemaVersion string         `json:"schema_version"`
 	Source        string         `json:"source,omitempty"`
 	Layer         string         `json:"layer,omitempty"`

src/go/pkg/l2topology/mac_oui_lookup.go

@@ -7,8 +7,6 @@ import (
 	"sort"
 	"strings"
 	"sync"
-
-	"github.com/netdata/netdata/go/plugins/pkg/topology"
 )
 
 //go:embed mac_oui_vendors.tsv
@@ -116,7 +114,7 @@ func lookupTopologyVendorByMACInIndex(index topologyOUIVendorIndex, mac string)
 	return "", ""
 }
 
-func inferTopologyVendorFromMatch(match topology.Match) (vendor string, prefix string) {
+func inferTopologyVendorFromMatch(match Match) (vendor string, prefix string) {
 	candidates := make(map[string]struct{}, len(match.MacAddresses)+len(match.ChassisIDs))
 	for _, value := range match.MacAddresses {
 		if mac := normalizeMAC(value); mac != "" {

src/go/pkg/l2topology/mac_oui_lookup_test.go

@@ -3,11 +3,9 @@
 package l2topology
 
 import (
+	"github.com/stretchr/testify/require"
 	"strings"
 	"testing"
-
-	"github.com/netdata/netdata/go/plugins/pkg/topology"
-	"github.com/stretchr/testify/require"
 )
 
 func TestBuildTopologyOUIVendorIndex_IgnoresInvalidLinesAndKeepsFirstDuplicate(t *testing.T) {
@@ -49,7 +47,7 @@ func TestLookupTopologyVendorByMACInIndex_PrefersLongestPrefixAndNormalizesMAC(t
 }
 
 func TestInferTopologyVendorFromMatch_UsesDeterministicCandidateOrder(t *testing.T) {
-	match := topology.Match{
+	match := Match{
 		MacAddresses: []string{
 			"28:6f:b9:00:00:22",
 			"08:ea:44:11:22:33",

src/go/pkg/l2topology/parity/README.md

@@ -2,7 +2,7 @@
 
 ## Scope
 - Validate topology engine parity against imported Enlinkd fixtures and assertion inventories.
-- Evidence files live in `src/go/pkg/topology/engine/parity/evidence`.
+- Evidence files live in `src/go/pkg/l2topology/parity/evidence`.
 
 ## Prerequisites
 - Upstream checkout available at `/tmp/topology-library-repos/enlinkd`.
@@ -54,7 +54,7 @@ Outputs:
 
 ## Run Go Test Gates
 ```bash
-go test ./pkg/topology/engine/... ./plugin/go.d/collector/snmp ./tools/topology-parity-evidence -count=1
+go test ./pkg/l2topology/... ./plugin/go.d/collector/snmp ./tools/topology-parity-evidence -count=1
 ```
 
 Expected:
@@ -67,7 +67,7 @@ Expected:
 2. `suite` has failed scenarios:
    - Open `parity-summary.json`.
    - Inspect failing scenario IDs and manifests.
-   - Re-run targeted tests in `./pkg/topology/engine/parity`.
+   - 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`.

src/go/pkg/l2topology/topology_adapter.go

@@ -6,12 +6,10 @@ import (
 	"net/netip"
 	"strings"
 	"time"
-
-	"github.com/netdata/netdata/go/plugins/pkg/topology"
 )
 
-// TopologyDataOptions controls conversion from Result to topology.Data.
-type TopologyDataOptions struct {
+// GraphOptions controls conversion from Result to the internal graph projection.
+type GraphOptions struct {
 	SchemaVersion             string
 	Source                    string
 	Layer                     string
@@ -56,8 +54,8 @@ type endpointActorAccumulator struct {
 }
 
 type projectedSegments struct {
-	actors                        []topology.Actor
-	links                         []topology.Link
+	actors                        []Actor
+	links                         []Link
 	linksFdb                      int
 	bidirectionalCount            int
 	endpointLinksCandidates       int
@@ -221,9 +219,9 @@ func topologyInferenceStrategyConfigFor(strategy string) topologyInferenceStrate
 	}
 }
 
-// ToTopologyData converts an engine result to the shared topology schema.
-func ToTopologyData(result Result, opts TopologyDataOptions) topology.Data {
-	builder := newTopologyDataBuilder(result, opts)
+// ToGraph converts an engine result to the internal graph projection.
+func ToGraph(result Result, opts GraphOptions) Graph {
+	builder := newGraphBuilder(result, opts)
 	builder.prepareIndexes()
 	builder.collectBridgeTopologyInputs()
 	builder.buildDeviceActors()
@@ -232,5 +230,5 @@ func ToTopologyData(result Result, opts TopologyDataOptions) topology.Data {
 	builder.buildSegmentTopology()
 	builder.finalizeGraph()
 	builder.buildStats()
-	return builder.data()
+	return builder.graph()
 }

src/go/pkg/l2topology/topology_adapter_actor_collapse.go

@@ -5,11 +5,9 @@ package l2topology
 import (
 	"sort"
 	"strings"
-
-	"github.com/netdata/netdata/go/plugins/pkg/topology"
 )
 
-func collapseActorsByIP(actors []topology.Actor) []topology.Actor {
+func collapseActorsByIP(actors []Actor) []Actor {
 	if len(actors) <= 1 {
 		return actors
 	}
@@ -98,7 +96,7 @@ func collapseActorsByIP(actors []topology.Actor) []topology.Actor {
 		actors[rep] = merged
 	}
 
-	out := make([]topology.Actor, 0, len(actors))
+	out := make([]Actor, 0, len(actors))
 	for idx, actor := range actors {
 		if !keep[idx] {
 			continue
@@ -108,12 +106,12 @@ func collapseActorsByIP(actors []topology.Actor) []topology.Actor {
 	return out
 }
 
-func eliminateNonIPInferredActors(actors []topology.Actor, links []topology.Link) ([]topology.Actor, []topology.Link) {
+func eliminateNonIPInferredActors(actors []Actor, links []Link) ([]Actor, []Link) {
 	if len(actors) == 0 {
 		return actors, links
 	}
 	removedIdentityKeys := make(map[string]struct{})
-	filteredActors := make([]topology.Actor, 0, len(actors))
+	filteredActors := make([]Actor, 0, len(actors))
 	for _, actor := range actors {
 		if topologyActorIsInferred(actor) && len(normalizedTopologyActorIPs(actor)) == 0 {
 			for _, key := range topologyMatchIdentityKeys(actor.Match) {
@@ -127,7 +125,7 @@ func eliminateNonIPInferredActors(actors []topology.Actor, links []topology.Link
 		return actors, links
 	}
 
-	filteredLinks := make([]topology.Link, 0, len(links))
+	filteredLinks := make([]Link, 0, len(links))
 	for _, link := range links {
 		srcKeys := topologyMatchIdentityKeys(link.Src.Match)
 		dstKeys := topologyMatchIdentityKeys(link.Dst.Match)
@@ -154,7 +152,7 @@ func topologyIdentityKeysOverlap(keys []string, set map[string]struct{}) bool {
 	return false
 }
 
-func normalizedTopologyActorIPs(actor topology.Actor) []string {
+func normalizedTopologyActorIPs(actor Actor) []string {
 	if len(actor.Match.IPAddresses) == 0 {
 		return nil
 	}
@@ -175,7 +173,7 @@ func normalizedTopologyActorIPs(actor topology.Actor) []string {
 	return out
 }
 
-func compareTopologyActorCollapsePriority(left, right topology.Actor) int {
+func compareTopologyActorCollapsePriority(left, right Actor) int {
 	leftDevice := IsDeviceActorType(left.ActorType)
 	rightDevice := IsDeviceActorType(right.ActorType)
 	if leftDevice != rightDevice {
@@ -197,7 +195,7 @@ func compareTopologyActorCollapsePriority(left, right topology.Actor) int {
 	return strings.Compare(leftKey, rightKey)
 }
 
-func mergeTopologyActorMatch(base, other topology.Match) topology.Match {
+func mergeTopologyActorMatch(base, other Match) Match {
 	base.ChassisIDs = mergeTopologyStringLists(base.ChassisIDs, other.ChassisIDs)
 	base.MacAddresses = mergeTopologyStringLists(base.MacAddresses, other.MacAddresses)
 	base.IPAddresses = mergeTopologyStringLists(base.IPAddresses, other.IPAddresses)
@@ -274,7 +272,7 @@ func mergeTopologyActorAttributes(base, extra map[string]any) map[string]any {
 	return base
 }
 
-func topologyActorIsInferred(actor topology.Actor) bool {
+func topologyActorIsInferred(actor Actor) bool {
 	if strings.EqualFold(strings.TrimSpace(actor.ActorType), "endpoint") {
 		return true
 	}