# 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.