feat(enrichment): harden ASN/locality enrichment, protobuf structure v2, lookup-table metrics

[randomizedcoder]

Summary

Three stacked commits, all new to main:

1. b8f9b0b feat(ipfeed): fold ipfeed-collector into xtcp2 + IP→ASN enrichment (pkg/ipasn, -enrichAsn).
2. db40c79 feat(locality): destination locality enrichment via native rtnetlink (pkg/localnet, enrich_socket_dest_locality, egress ifindex/ifname).
3. 62a4673 feat(enrichment): review-driven hardening of both, a full protobuf structure pass (schema v2), and Prometheus metrics for the lookup tables.

Draft while the ClickHouse v2 migration and the schema-version bump get a second pair of eyes.

Protobuf structure v2 — XtcpFlatRecordSchemaVersion 1 → 2

• xtcp_flat_record.proto now documents the allocation policy (metadata 1–299 · enrichment 300–399 · spare 400–999 · payload 1000+ one block per kernel subsystem · every tag ≤ 2047 stays 2 bytes on the wire). Enrichment block regrouped by subject; source-side range reserved.
• Payload field names mirror the kernel struct member they copy, and every payload field carries a trailing comment naming its kernel source. tools/proto-field-audit gains a guard so a payload field cannot land without one.
• Renamed (old numbers/names reserved): tcp_info_{snd,rcv}_wscale, tcp_info_fastopen_client_fail, tcp_info_rttvar, tcp_info_advmss, tcp_info_notsent_bytes, sk_mem_info_{rcvbuf,sndbuf}, vegas_info_{rttcnt,minrtt}, inet_diag_{cong,cong_enum,tos,tclass,shutdown,class_id,sockopt,cgroup_id}. Post-6.10 tcp_info members pre-assigned 1266–1276 by comment.
• XtcpConfig renumbered into blocks (gRPC-internal; nothing persists the binary form).
• Propagated to gen/*, ParquetRow/rowFromProto, recordfmt, ClickHouse Kafka table + per-version MVs (new _v2 table, explicit column aliases for _v0/_v1), k8s configMaps, hand-written SQL, docs.

Migration for existing ClickHouse deployments: build/containers/clickhouse/sql/migrations/v2.sql. Parquet consumers should branch on schema_version (see docs/record-versioning.md, docs/parquet-format.md).

Correctness fixes

• Locality classification: RTN_LOCAL uses the route's real prefix; multipath / RTA_VIA / RTA_NH_ID routes classify as gateway-reached; Self beats Subnet regardless of dump order; only RT_TABLE_MAIN/LOCAL read; unspecified dest → LOCALITY_UNSPECIFIED.
• Locality lifecycle: negative cache with backoff for failed namespaces, re-dump of loopback-only snapshots, capped new-namespace dumps per reconcile, NLM_F_DUMP_INTR retry, default refresh 60 s.
• ASN loader: only io.EOF ends a read; zero usable prefixes is ErrNoPrefixes; a bad reload never degrades the table in service; stat-gated ReloadIfChanged; index installed even when the first load fails so a late artifact is picked up on the tick.
• Collector: atomic Parquet write (.tmp + fsync + rename), 256 MiB body cap, six previously untested parsers now covered.

Lookup-table metrics (operational visibility)

Daemon, following the existing function/variable/type pattern under function="loadAsn":

metric	meaning
xtcp_gauges{...variable="prefixes"}	entries in the trie in service
xtcp_gauges{...variable="artifactBytes"}	size of the artifact it was built from
xtcp_gauges{...variable="loadedAt"}	Unix time of the last successful load
xtcp_histograms{...variable="build"}	read + build duration per successful load
xtcp_histograms{...variable="error"}	duration of a failed load attempt

Collector (-daemon -http-addr): OTel instruments bridged to Prometheus on /metrics next to /healthz and /readyz. New: ipfeed_source_records{source,provider}, ipfeed_artifact_records, ipfeed_artifact_size_bytes, ipfeed_write_duration_seconds, ipfeed_upload_duration_seconds, ipfeed_cycle_duration_seconds{outcome}. Operator table in cmd/ipfeed-collector/README.md.

Test plan

• go vet ./..., gofmt -l . clean; go test ./... green (-race on localnet, xtcpnl, ipasn, xtcp, telemetry, health)
• golangci-lint run — only the pre-existing govet unusedwrite in poller_pure_test.go
• go run ./tools/proto-field-audit clean incl. the new kernel-annotation check; nix run .#regen-protos leaves the tree clean
• nix build .#xtcp2-all (new goVendorHash)
• nix run .#test-microvm-lifecycle-x86_64-interface-naming → XTCP2_SELF_TEST_OVERALL_PASS, all 20 checks, including XTCP2_SELF_TEST_ASN_PASS (dest=8.8.8.8:53 asn=15169 owner=google prefixes=3) and XTCP2_SELF_TEST_IFNAME_PASS
• ClickHouse DDL validated with clickhouse local (Kafka engine stood in by a MergeTree table with the same columns), two scenarios:
  • fresh initdb.d install: epoch 0/1/2 rows route to _v0/_v1/_v2, Merge view shows all three, _v2 has 161 columns;
  • existing deployment on main's DDL with an epoch-1 row already stored, then migrations/v2.sql: the stored row survives with its old column names, new epoch 0/1/2 rows route correctly, SELECT schema_version, count() FROM xtcp.xtcp_flat_records GROUP BY 1 shows all epochs.
• Same against a real ClickHouse + Kafka compose stack (ProtobufList decode path)
• tcp-stress / minimal lifecycle flavors on a quiet host (the minimal flavor's 180 s deadline is starved on a loaded box)

Pre-existing reds on main independent of this PR: go-sec G104 ×4, s3parquet schema-drift check, xsync race flake.

🤖 Generated with Claude Code