sync: record magatama switchblade port intelligence fix

2026-05-07 00:56:59 +02:00 · 2026-05-07 00:56:59 +02:00 · a0ea4ccbae
commit a0ea4ccbae
parent 57e20efe49
2 changed files with 169 additions and 1 deletions
--- a/sync/CURRENT.md
+++ b/sync/CURRENT.md
@ -1,6 +1,6 @@
 # Current TIP Sync State

-Updated: 2026-05-06 20:52 UTC
+Updated: 2026-05-06 22:55 UTC

 ## Active Policy

@ -27,6 +27,66 @@ When work touches TIP, Magatama, LLM Gateway, bridges, auth, or shared Erik infr

 ## Latest Work

+- MAGATAMA Switchblade port intelligence is now truly flowing end-to-end on 2026-05-06:
+  - live root cause:
+    - Switchblade itself already had the rich SG350 data (`description`, LLDP neighbor, peer port, octets), but MAGATAMA had still shown mostly flat port chips.
+    - verified live on Erik:
+      - the real Switchblade runtime is the PM2 app `switchblade` under `/opt/switchblade-app`, not the older `/opt/switchblade` tree.
+      - `GET http://127.0.0.1:3000/api/discovery/snmp` for `192.168.178.2` already returned rich rows such as:
+        - `GigabitEthernet3` → description `Aruba-1830-UNUSED`, neighbor `VN46KYC0G0`, peer port `11`
+        - `GigabitEthernet5` → description `Tashi-204`, neighbor `fritz.box`, peer `LAN:1`
+        - `GigabitEthernet25` → description `to Cisco Business 220 Series`, neighbor `Switch39688E`, peer `gi9`
+    - the remaining loss point was MAGATAMA’s own Switchblade sync/persistence path.
+  - MAGATAMA sync hardening:
+    - `scripts/switchblade_live_sync.ts`
+      - now prefers live SNMP discovery data when it is richer than `/api/devices/<ip>`
+      - now maps `description`, `peerDevice`, `peerPort`, `connectedHost`, `inOctets`, `outOctets` into rack device ports
+      - added optional debug snapshot dump support via `SWITCHBLADE_DEBUG_SNAPSHOT_FILE`
+      - sanitizes unreadable peer-port strings and drops synthetic high-index numeric pseudo-ports
+    - verified with a forced live run on Erik:
+      - `Top of Rack Switch` now exports `28` real SG350 ports into the rack snapshot instead of the earlier flattened/odd set
+      - sample verified payloads before POST:
+        - port 3 → `Aruba-1830-UNUSED` / `VN46KYC0G0` / `11`
+        - port 5 → `Tashi-204` / `fritz.box` / `LAN:1`
+        - port 25 → `to Cisco Business 220 Series` / `Switch39688E` / `gi9`
+  - MAGATAMA core hardening:
+    - `packages/core/src/routes/health-types.ts`
+      - `SwitchbladePortSnapshot` now preserves:
+        - `description`
+        - `vlan`
+        - `macCount`
+        - `peerDevice`
+        - `peerPort`
+        - `connectedHost`
+        - `transceiver`
+        - `inOctets`
+        - `outOctets`
+    - `packages/core/src/routes/health-support.ts`
+      - `normalizeSwitchbladePort()` now keeps those additional port fields instead of silently truncating them
+    - rebuilt locally and re-rsynced the new `packages/core/dist` to Erik
+  - dashboard/UI hardening:
+    - `packages/dashboard/public/index-v2.html`
+      - port chips already had custom tooltip support; now they also carry native `title=` fallback text
+      - this reduces the old “question mark / unclear hover” problem in browsers that do not immediately show the custom bubble
+  - live public verification after deploy:
+    - `GET https://magatama.fichtmueller.org/api/switchblade/snapshot`
+      - now contains enriched SG350 rack-port records with:
+        - `description`
+        - `peerDevice`
+        - `peerPort`
+        - `connectedHost`
+        - `inOctets`
+        - `outOctets`
+      - public snapshot timestamp verified:
+        - `receivedAt = 2026-05-06T22:51:59.247Z`
+    - `Top of Rack Switch` in the public snapshot now exposes meaningful peer/use-case data instead of only flat status counters
+  - operator impact:
+    - MAGATAMA can now answer the actual operational question per port:
+      - what is on this port
+      - what is it talking to
+      - what does the link look like
+    - this is now grounded in Switchblade live SNMP/LLDP data, not guesswork.
+
 - TIP/Blog lane separation was materially corrected on 2026-05-06:
  - root cause:
    - `TIP_LLM` was still ingesting blog-/writer-shaped rows from the canonical lane pool and shared transceiver corpora.
--- a/sync/history/2026-05-06-magatama-switchblade-port-intelligence-end-to-end.md
+++ b/sync/history/2026-05-06-magatama-switchblade-port-intelligence-end-to-end.md
@ -0,0 +1,108 @@
+# 2026-05-06 – MAGATAMA Switchblade Port Intelligence End-to-End
+
+## Summary
+
+The SG350 / Switchblade port-enrichment chain is now live end-to-end:
+
+- Switchblade SNMP + LLDP data is being consumed by MAGATAMA.
+- MAGATAMA no longer truncates the richer per-port fields in the core snapshot normalizer.
+- The public MAGATAMA snapshot now exposes meaningful rack-port metadata such as description, peer device, peer port, connected host, and byte counters.
+
+## Root Cause
+
+There were two separate issues:
+
+1. Switchblade runtime confusion
+   - the real live app on Erik is `/opt/switchblade-app` under PM2 app `switchblade`
+   - that live app already had richer SNMP discovery rows than what MAGATAMA showed
+
+2. MAGATAMA truncation
+   - `scripts/switchblade_live_sync.ts` needed to prefer richer SNMP discovery rows when they beat `/api/devices/<ip>`
+   - core normalization (`health-types.ts` / `health-support.ts`) still only preserved the minimal port shape and silently dropped the rest
+
+## Changes Applied
+
+### MAGATAMA sync
+
+File:
+- `magatama/scripts/switchblade_live_sync.ts`
+
+Changes:
+- prefer SNMP discovery rows when they contain richer port metadata
+- preserve and forward:
+  - `description`
+  - `peerDevice`
+  - `peerPort`
+  - `connectedHost`
+  - `inOctets`
+  - `outOctets`
+- sanitize unreadable peer-port strings
+- drop synthetic high-index numeric pseudo-ports
+- optional debug dump:
+  - `SWITCHBLADE_DEBUG_SNAPSHOT_FILE`
+
+### MAGATAMA core
+
+Files:
+- `magatama/packages/core/src/routes/health-types.ts`
+- `magatama/packages/core/src/routes/health-support.ts`
+
+Changes:
+- `SwitchbladePortSnapshot` now includes:
+  - `description`
+  - `vlan`
+  - `macCount`
+  - `peerDevice`
+  - `peerPort`
+  - `connectedHost`
+  - `transceiver`
+  - `inOctets`
+  - `outOctets`
+- `normalizeSwitchbladePort()` preserves those fields instead of collapsing back to the flat legacy subset
+
+### MAGATAMA dashboard
+
+File:
+- `magatama/packages/dashboard/public/index-v2.html`
+
+Changes:
+- port chips already used custom tooltip bubbles
+- added native `title=` fallback so the hover stays readable in browsers with inconsistent pseudo-element hover behavior
+
+## Live Verification
+
+Verified on Erik:
+
+- `GET http://127.0.0.1:3000/api/discovery/snmp`
+  - SG350 (`192.168.178.2`) already exposed rich rows like:
+    - port 3 → `Aruba-1830-UNUSED` / `VN46KYC0G0` / `11`
+    - port 5 → `Tashi-204` / `fritz.box` / `LAN:1`
+    - port 25 → `to Cisco Business 220 Series` / `Switch39688E` / `gi9`
+
+- forced live sync run with debug dump
+  - `Top of Rack Switch` exported `28` real ports after cleanup
+  - pre-POST payload on Erik contained:
+    - `description`
+    - `peerDevice`
+    - `peerPort`
+    - `connectedHost`
+    - `inOctets`
+    - `outOctets`
+
+- public MAGATAMA snapshot
+  - `GET https://magatama.fichtmueller.org/api/switchblade/snapshot`
+  - verified enriched SG350 port records are now present publicly
+  - public timestamp:
+    - `receivedAt = 2026-05-06T22:51:59.247Z`
+
+## Outcome
+
+MAGATAMA can now surface for the SG350:
+
+- what is on the port
+- what device it speaks to
+- the peer port when LLDP provides it
+- byte/error status
+- human-written port descriptions from Switchblade SNMP discovery
+
+This closes the earlier gap where Switchblade knew the data but MAGATAMA still rendered mostly flat port chips.