# CLAUDE.md Reference document for future Claude sessions (and humans reading the repo cold). Captures what's actually built, the MCMS API quirks discovered along the way, and the things that don't work or were deliberately skipped. For run instructions and user-facing scope, see `README.md` — this file is the engineering counterpart. --- ## 1. What this app does Electron desktop client for operating a **Ciena MCMS 6.2** PON Manager fleet. Top-level **tabs** (Dashboard / ONU / OLT) switch between: - **Dashboard** — read-only network telemetry (see §15). - **ONU** — the fleet table + firmware-upgrade campaign + verify flows (the original purpose: bulk ONU firmware upgrades). - **OLT** — bulk OLT PON flooding-mode changes (private↔auto, see §14). Reference deployment: GNXS / Tibit MicroPlug ONUs running Interos Everest (EV051xxR / EV052xxR firmware family) behind Tibit OLTs. End-to-end operator workflow: 1. Connect with email + password against the MCMS web URL. 2. Browse the ONU fleet with rich filters (status, down-duration, version, equipment ID, PON mode). 3. Either select ONUs and continue to the upgrade campaign view, **or** delete stale ONUs (Deregistered / Dying Gasp / etc.) from MCMS. 4. In the campaign view: pick a firmware `.bin` already uploaded to `/files/onu-firmware/` (or upload one), preview the planned writes, and commit. The Preview step also runs a FEC pre-flight health check on every selected ONU. 5. On Execute, the plan is auto-saved as a CSV to `~/Downloads/`. 6. After the upgrade has had time to roll, open the saved CSV in the verify view to compare before/after and auto-save a verification CSV alongside. --- ## 2. Quickstart ```bash cd pon-fleet-upgrader npm install npm start # launch Electron npm run check # node --check on every JS file (cheap smoke test) ``` Environment: - `PON_FLEET_VERBOSE=0` — silence the per-request log lines in the Electron terminal. Default is verbose because the log dumps headers and full response bodies on non-2xx, which has been invaluable for debugging. DevTools: **Ctrl+Shift+I** (Cmd+Opt+I on macOS). Reload renderer after editing `renderer/`: **Ctrl+R**. --- ## 3. Architecture Standard Electron three-process model with strict isolation: ``` +-----------+ IPC invoke +-----------+ HTTPS +-----------+ | Renderer | ──────────────► | Main | ────────► | MCMS | | (browser) | via preload | (Node) | | (web UI) | +-----------+ ◄───────────── +-----------+ ◄──────── +-----------+ streaming events / responses ``` - **Renderer** (`renderer/app.js`, `index.html`, `app.css`) — vanilla DOM, no framework. Calls into `window.api.*` exposed by the preload. Has no Node access and never sees raw cookies. - **Preload** (`preload.js`) — `contextBridge` whitelist; the only bridge from renderer to main. Adding a new IPC channel requires touching this file. - **Main** (`main.js`) — owns the `McmsClient`, the cookie jar, file IO, and the Electron `dialog` / `app.getPath()` APIs. - **MCMS client** (`src/mcms-api.js`) — raw `https` + `tough-cookie`. No third-party HTTP client; the only npm dep is `tough-cookie`. See §5 for the quirks this client works around. - **Bank strategy** (`src/bank-strategy.js`) — pure logic for picking the inactive bank to write to. See §7. ### File layout ``` pon-fleet-upgrader/ ├── package.json # electron, tough-cookie, npm scripts ├── main.js # Electron main process + IPC handlers ├── preload.js # contextBridge whitelist ├── README.md # user-facing run docs ├── CLAUDE.md # this file ├── src/ │ ├── mcms-api.js # HTTPS client, FEC extractor, time helpers │ └── bank-strategy.js # inactive-bank + plan computation └── renderer/ ├── index.html # login / fleet / campaign / verify views ├── app.css # dark theme, status pill classes └── app.js # UI state, all renderer logic ``` ### IPC channel list All channels are `invoke`-style (request/response). A few additionally stream progress events back to the renderer. | Channel | Purpose | Streams | |---|---|---| | `api:login` / `api:logout` | session auth | — | | `api:listFleet` | ONU-CFG + ONU-STATE + OLT-STATE merged | — | | `api:fetchStates` | per-ONU state fallback if bulk failed | `states:progress` | | `api:listOnuConfigs` / `api:getOnuConfig` | direct CFG access | — | | `api:listOnuFirmware` / `api:uploadFirmware` | firmware inventory | — | | `api:planUpgrade` | dry-run plan for selected ONUs | — | | `api:executePerOnu` | Procedure 7 — per-ONU PUTs | `upgrade:progress` | | `api:executeBulkTask` | Procedure 8 — single AUTO-TASK-CFG | — | | `api:getTaskConfig` / `api:getUpgradeStatus` | poll helpers | — | | `api:deleteOnus` | bulk delete (CFG + best-effort STATE) | `delete:progress` | | `api:dashboardStats` | network telemetry aggregates (Dashboard tab) | — | | `api:listOlts` | OLT-CFG list + per-OLT NNI flood-mode summary | — | | `api:executeFloodChange` | bulk PON flooding-mode flip (GET→plan→PUT) | `olt-flood:progress` | | `api:fetchFecHealth` | pre-flight FEC pre/post + optical | `fec:progress` | | `api:savePlanCsv` | auto-save plan on Execute | — | | `api:saveCsvFile` | generic CSV writer | — | | `api:openCsvFile` | open dialog → return text | — | | `api:fetchOnuSnapshot` | verify-flow: state + cfg per ONU | `verify:progress` | --- ## 4. Features actually implemented ### Fleet view - Login with email / password, accept-self-signed-TLS toggle (essential for lab MCMS installs). - Bulk fleet load: `listAllOnuConfigs` + `listAllOnuStates` + `listAllOltStates`, all paginated via the `next` cursor at page size 100 (see §5). - Filters: text (name/address/serial), Equipment ID, PON mode, active version, exclude active version, model/version family, registration status (incl. "Down" aggregate and "Unknown" buckets), down-for-at-least-N-days. - Columns: serial, name/address, equipment ID, PON mode, **status** (colour-coded from OLT-STATE bucket), **last seen** (relative time from `ONU-STATE.Time`), active slot, active version, inactive version. - Bulk select / clear / select-all-matching. - **Delete** — `DELETE /v1/onus/configs//` per ONU at concurrency 5, then best-effort `DELETE /v1/onus/states//`. Two-step confirm (alert + typed `DELETE`). Streams progress per ONU. ### Campaign view - Firmware picker bound to `/files/onu-firmware/`, inferring version from filename (regex `[A-Z]{2}\d{5}[A-Z]?`). - Upload firmware via Electron `dialog.showOpenDialog`. - Execution mode toggle: **bulk task** (Procedure 8 — recommended) or **per-ONU PUT** (Procedure 7 — per-device feedback). - Scheduled-start datetime-local picker (converts local → UTC string `YYYY-MM-DD HH:MM:SS`). - **Dry-run preview** with FEC pre-flight: each selected ONU is re-fetched (`getOnuState`) at preview time, and the resulting FEC pill + optical levels + raw counters are rendered in a new column. - **CSV auto-save on Execute** — writes `~/Downloads/pon-upgrade---onus-.csv` the moment Execute is clicked, *before* any MCMS write. See §10. - Soft FEC gate in the Execute confirmation dialog: warns (but doesn't block) when any selected ONU is showing post-FEC errors or the pre==post buggy signature. ### Verify view (after-upgrade comparison) - **Open plan CSV…** — file dialog defaulted to `~/Downloads`. Parser is lenient — needs only an `ONU ID` column, everything else is optional. - For each ONU listed, fetches **both** ONU-STATE (fresh FEC + optical) and ONU-CFG (to confirm `FW Bank Ptr` flipped and the active version now equals the recorded target). Concurrency 8. - Renders a comparison table with target→active, "Applied?" badge, before/after FEC pills + counters, before/after optical RX/TX, and a one-line verdict per ONU. - **Auto-saves** the comparison to `~/Downloads/pon-verify--.csv` the moment the comparison finishes, so it sorts next to the original. - Side-panel summary: counts of applied/not-applied, fixed/improved, still-buggy, regressed, still-healthy. ### FEC health rules (`extractOnuHealth` in `src/mcms-api.js`) | Flag | Meaning | Trigger | |---|---|---| | `ok` | green | All four FEC counters present and 0 | | `pre` | yellow | Any pre-FEC counter > 0, all post-FEC = 0 | | `post` | red | Any post-FEC counter > 0 (uncorrected errors) | | `buggy` | blue | ONU pre>0 AND post>0 AND `post/pre >= 0.95` | | `nodata` | grey | No FEC counters found in STATS | | `error` | grey | Per-ONU fetch threw | **Buggy detection note.** Real-world example from a GNXS Everest ONU: `Pre-FEC BER = 22,388,041,291`, `Post-FEC BER = 22,379,111,198`. Those differ by 0.04%, which is well into "FEC isn't doing anything" territory. Exact-equality detection would miss this; the 0.95 ratio threshold catches it. The condition is intentionally one-sided — we treat ONU side as the bug source (the OLT side counters are computed by the OLT firmware which we trust). ### Optical thresholds From the PON Manager User Guide green-LED criteria (323-1961-302 p149): | Field | Green | Yellow | Red | |---|---|---|---| | ONU RX | ≥ −28 dBm | −28 to −30 dBm | < −30 dBm | | ONU TX | ≥ 3 dBm | — | < 3 dBm | Yellow is a margin band we added — the user guide is binary (≥ −30 vs < −30), but operators want a warning before the link is actually broken. --- ## 5. MCMS API quirks These are the gotchas worth knowing. Many were diagnosed empirically against MCMS 6.2 + Interos Everest 5.11/5.12. **If something behaves oddly, check this section first.** ### 5.1 User-Agent header is required Node's `https.request` doesn't send a User-Agent by default. **Some MCMS middleware dereferences `HTTP_USER_AGENT` without a guard and 500s when it's absent.** Reproducible via `curl -A '' https://mcms/api/v3/...`. → `src/mcms-api.js` sends `User-Agent: pon-fleet-upgrader/0.1.0` on every request. Do not remove. ### 5.2 CSRF cookie name is `__Host-csrftoken` MCMS 6.2 uses RFC 6265bis `__Host-` cookie prefix (Secure + Path=/). The cookie names are: - `__Host-csrftoken` - `__Host-sessionid` - `__Host-sessionexpire` Older MCMS builds shipped bare `csrftoken`. The client looks for both: ```js const csrf = jarCookies.find( (c) => c.key === 'csrftoken' || c.key === '__Host-csrftoken', ); ``` The token value still goes in the `X-CSRFToken` header (no prefix). ### 5.3 Pagination: use `next`, not `skip` `/v3/onus/configs/?skip=N` has been observed returning HTTP 500 on this MCMS build. Use the `next` cursor: pass the last document's `_id` as the `next` query param to get the page that *excludes* all IDs up to and including that one. → See `McmsClient._listPaginatedByNext`. ### 5.4 Bulk-list page size 100 `/v3/onus/configs/?limit=1000` times out at the Apache front-end on ~1500-ONU fleets, before Django even logs the request. Full ONU-CFG documents are ~30 KB each, so a 1000-row page is ~30 MB and the proxy gives up. → Default page size is 100. Each response is ~3 MB and lands in well under the proxy timeout. ### 5.5 Path prefix is `/api/v1/...` The dev guide writes "GET `/v1/users/authenticate/`" as shorthand. The real HTTP path is `/api/v1/users/authenticate/`. The client normalises this internally — pass either form. ### 5.6 Request body envelope PUT/POST bodies are wrapped: `{ "data": { ...payload } }`. The login endpoint accepts both wrapped and unwrapped on observed builds (the client tries wrapped first, falls back on 400). Everything else is strictly wrapped. ### 5.7 PUT is full-document replace, not patch `PUT /v1/onus/configs//` replaces the entire `ONU-CFG`. The client fetches the doc, mutates the FW fields in place, and PUTs the result. **Do not use PATCH** — MCMS PATCH endpoints are not used by this app and the dev guide is explicit about PUT-as-replace for CFG updates. ### 5.8 Timestamp format MCMS emits and accepts: `"YYYY-MM-DD HH:MM:SS[.ffffff]"` in **UTC** with a literal space separator (not ISO-8601 `T`). Used on: `ONU-STATE.Time`, alarm timestamps, `AUTO-TASK-CFG.Task.Scheduled Start Time`, query-param timestamps. → Helpers in `src/mcms-api.js`: `formatMcmsTime(date)` and `parseMcmsTime(str)`. The renderer also coerces the space-form to ISO before passing to `new Date()` to avoid Node's local-time interpretation. ### 5.9 Server-side filtering on `query`/`projection` is brittle Mongo-style server filters get rejected (or silently return nothing) when the URL-encoded JSON has spaces in field names, certain escape patterns, or projection paths that don't exist on every document version. **We load the full fleet and filter entirely client-side.** If you need server filtering, the safest pattern is no quotes around field names and `%20` for spaces (not `+`). The client's `_encodeQuery` uses `encodeURIComponent` for exactly this reason. ### 5.10 ONU registration status lives on OLT-STATE, not ONU-STATE The 9 registration buckets (Registered, Deregistered, Dying Gasp, Disabled, Disallowed Admin/Error/Reg ID, Unspecified, Unprovisioned) appear under `OLT-STATE["ONU States"][bucket] = [onuId, ...]`. See 323-1961-306 Procedure 2. → `listAllOltStates` pulls these, and `api:listFleet` builds a `onuId → { status, oltMac }` map from the buckets. On duplicates we prefer a non-Registered bucket (the interesting signal). ### 5.11 FEC counters live on ONU-STATE, not `/onus/stats/` `/v1/onus/stats//` is the time-series PM collection — `start-time` is required, returns historical samples. **The current FEC/optical values are already in ONU-STATE:** ``` state_collection.STATS["ONU-PON"]["RX Pre-FEC BER"] state_collection.STATS["ONU-PON"]["RX Post-FEC BER"] state_collection.STATS["ONU-PON"]["RX Optical Level"] # dBm state_collection.STATS["ONU-PON"]["TX Optical Level"] # dBm state_collection.STATS["OLT-PON"]["RX Pre-FEC BER"] state_collection.STATS["OLT-PON"]["RX Post-FEC BER"] ``` → The pre-flight fetch (`api:fetchFecHealth`) and the verify fetch (`api:fetchOnuSnapshot`) both call `getOnuState(id)` and extract via `extractOnuHealth`. The time-series stats endpoint is **not used** anywhere — earlier code that hit it has been removed. `extractOnuHealth` accepts both shapes: the bare state doc (`{STATS: ...}`) and the UI-helper wrapped form (`{state_collection: {STATS: ...}}`), since `/api/onu/summary` returns the wrapped shape. ### 5.12 Login body shape The PON Manager web app POSTs `{"data": {"email": ..., "password": ...}}` to `/v1/users/authenticate/`. Some build variants accept the unwrapped form too — the client tries wrapped first. --- ## 6. ONU-STATE schema cheat-sheet (observed, not specced) The MCMS dev guide doesn't formally document the ONU-STATE shape on this build. From observation on GNXS / Interos Everest ONUs: ```jsonc { "_id": "GNXS05057fee", // serial / device ID "Time": "2026-05-04 21:51:57.394127", // last update (UTC) "ONU": { "Equipment ID": "FT-XGS2110", "Vendor": "GNXS", "PON Mode": "GPON", "FW Bank Files": ["...bin", "...bin"], "FW Bank Versions": ["EV05110R", "EV05100R"], "FW Bank Ptr": 0, // active slot (0 | 1 | 65535) "FW Version": "EV05110R", "FW Upgrade Status": { /* progress, status, etc */ }, // ... }, "STATS": { "ONU-PON": { "RX Pre-FEC BER": 22388041291, "RX Post-FEC BER": 22379111198, "RX Optical Level": -17.544, // dBm "TX Optical Level": 5.532 // dBm }, "OLT-PON": { "RX Pre-FEC BER": 0, "RX Post-FEC BER": 0, "TX Optical Level": 5.6, "RX Optical Level": -18.3 }, "ONU-EnhancedFecPmHistData-32769": { // NOT used by extractor — "uncorrectable_code_words": 1829, // these are corrected/ "corrected_bytes": 181, // uncorrectable code-word "corrected_code_words": 181 // counts, not BER values }, // ... many more sub-objects } } ``` The renderer's display field `Equipment ID` is sometimes also on the CFG, not just the STATE — `equipmentId(cfg)` in `app.js` checks both paths. --- ## 7. Firmware bank semantics (Full version of the table in `README.md`.) ONU has two flash slots. `FW Bank Ptr` identifies the active one. MCMS triggers a firmware download by: 1. Writing the new file + version into the target slot's `FW Bank Files[slot]` / `FW Bank Versions[slot]`. 2. Setting `FW Bank Ptr` to that slot. The ONU then downloads, and on completion MCMS flips `FW Bank Ptr` to the new slot (so the ONU boots into the new image on its next reboot). The bank-strategy module always writes to the **inactive** slot. If `FW Bank Ptr` is unset (65535) it writes to slot 1, leaving slot 0 as the factory fallback. For the bulk-task path (Procedure 8), MCMS needs a single bank number per task. So if a selection has ONUs with different active banks, we bucket by `writeSlot` and create one task per bucket — each task has a Procedure-8-shaped `AUTO-TASK-CFG.Task Details.ONU.FW Bank Ptr`. --- ## 8. CSV file formats Both kinds of CSV the app produces are written with the same `writeCsvFile` helper in `main.js`: - Always UTF-8 BOM (Excel auto-detects encoding → Norwegian Æ/Ø/Å survive on Windows). - Always CRLF line endings. - Every cell quoted (defensive against commas in addresses, embedded quotes in operator-typed names, embedded newlines from copy/paste). - Saved to `app.getPath('downloads')` (`~/Downloads` on macOS/Linux, `C:\Users\\Downloads` on Windows). ### Plan CSV — `pon-upgrade--.csv` Auto-saved when Execute is clicked, **before** any MCMS write — so even if the API call fails mid-way there's a record of intent. Columns (20): ONU ID, Name, Address, PON Mode, Active slot (before), Write slot (target), Slot 0 version (before), Slot 1 version (before), Target version, Target file, FEC health, ONU RX Pre-FEC BER, ONU RX Post-FEC BER, OLT RX Pre-FEC BER, OLT RX Post-FEC BER, ONU RX Optical (dBm), ONU TX Optical (dBm), FEC sample time, Mode, Notes. The hint is derived from `--onus`. ### Verify CSV — `pon-verify--.csv` Auto-saved after the verify comparison finishes. Hint reuses the trailing descriptor of the source CSV (strip `pon-upgrade-` prefix and `.csv` suffix), so the verify file sorts next to its source in the filesystem. Columns (23): identifiers, Target version, Active version (after), Upgrade applied?, FEC health (before), FEC health (after), all four BER counters before+after (ONU + OLT, pre + post), ONU RX/TX optical before+after, After sample time, Verdict, Fetch error. ### Verdict strings (in the Verify CSV) | Verdict | Trigger | |---|---| | `fixed (was buggy)` | `buggy → ok` | | `still buggy (firmware bug persists)` | `buggy → buggy` | | `improved (no longer mirroring counters)` | `buggy → pre` | | `changed: now reporting genuine post-FEC errors` | `buggy → post` | | `still healthy` | `ok → ok` | | `improved` | `pre|post → ok` | | `improved (post→pre)` | post→pre | | `regressed (now post-FEC errors)` | `ok → post` | | `regressed (now buggy)` | `ok → buggy` | | `regressed (now marginal)` | `ok → pre` | | `regressed (pre→post)` | pre→post | | `still has post-FEC errors` | `post → post` | | `still marginal (pre-FEC only)` | `pre → pre` | | `upgrade NOT applied (active version unchanged)` | `cfg.activeVersion !== target` | | `fetch failed` | per-ONU snapshot threw | | `no current FEC data` | flag=nodata | **The raw before/after counter values are misleading on their own** because ONU FEC counters typically reset on the upgrade reboot. The verdict is computed from the **flag transition**, not the delta. --- ## 9. Known limitations / not implemented - **No task-progress polling.** Once a bulk task is submitted, MCMS owns the rollout and the app doesn't poll `/v3/tasks/states//`. Operators use the verify view (or the PON Manager UI) to confirm. - **No post-execute results CSV.** The plan CSV captures intent pre-write. Per-ONU success/failure (in Procedure 7 mode) and task submission errors (in Procedure 8 mode) are visible on screen but not dumped to disk. Add-on candidate. - **No offline / cached fleet snapshot.** Every `Load fleet` hits MCMS. - **`/v1/onus//upgrade/status/`** is referenced in some MCMS spec documents but returns 404 on this build. Fallback: poll `GET /v1/onus/configs//` and watch `FW Bank Versions` / `FW Bank Ptr` flip. - **PATCH not used** — MCMS requires full-document PUT for CFG updates (dev guide is explicit about this). - **Server-side query/projection not used** — see §5.9. - **No time-series PM data shown.** We use the live snapshot from ONU-STATE (§5.11). `GET /onus/stats//` exists but is not wired up. - **No retries on transient HTTP errors** beyond the per-ONU best-effort delete-state. Bulk delete and per-ONU PUTs surface errors per row but don't auto-retry. - **Schedule field is UTC only.** The datetime-local picker converts from the browser's local TZ. Operators in different TZs see different inputs producing the same `Scheduled Start Time` value in the task — intentional, but worth noting. --- ## 10. Conventions ### Adding a new IPC channel Touch three files in order: 1. **`src/mcms-api.js`** — add the method on `McmsClient` if it talks to MCMS. 2. **`main.js`** — `ipcMain.handle('api:foo', ...)`. Wrap errors via `toWireError` so the renderer never sees stack traces. 3. **`preload.js`** — add `foo: (opts) => call('api:foo', opts)` to the `window.api` contract. **The renderer cannot call channels not listed here.** 4. **`renderer/app.js`** — use `window.api.foo(...)`. For streaming progress events, also add an `onFooProgress(handler)` function in the preload (returns an unsubscribe function). ### CSS conventions Status colour classes (declared in `app.css`): | Class | Meaning | CSS var | |---|---|---| | `.status-ok` | success / healthy | `--ok` (green) | | `.status-warn` | margin / pre-FEC | `--warn` (yellow) | | `.status-err` | failure / post-FEC / regressed | `--danger` (red) | | `.status-info` | informational / buggy ONU | `--info` (blue) | | `.status-pending` | in-flight / unknown | `--fg-dim` (grey) | | `.muted` | secondary text | `--fg-dim` (grey) | `.fec-cell` and `#verify-table tbody td` override `white-space: nowrap` to allow stacked content (pill on top, counters underneath). ### Verbose logging `McmsClient(verbose: true)` (default in this app) logs every request: - Method + path + cookie names (cookie values redacted) - All outgoing headers (`X-CSRFToken` redacted) - On non-2xx: full response headers + full response body The combination is enough to diff against a working `curl` for "why is this 500?" investigations. **Turn off via `PON_FLEET_VERBOSE=0`** if logs are leaking secrets to a shared terminal. --- ## 11. Testing There's no formal test runner. Two cheap signals: 1. `npm run check` — `node --check` on every JS file. Catches syntax errors before launching Electron. 2. Inline `node -e '...'` fixtures for pure functions (FEC extractor, CSV roundtrip, verdict logic). Vendor the function bodies into the test snippet rather than importing from `renderer/app.js` — that file expects `window` / `document`. When refactoring `extractOnuHealth`, re-test against the GNXS real-world fixture (post=22379111198, pre=22388041291): it must flag as `buggy`. That ratio (0.9996) is the edge case the 95% threshold was designed to catch. --- ## 12. Reference documents Stored alongside the project in the parent `PON-API` folder: - `323-1961-306_mcms_6_2_rest_api_developer_guide.pdf` — REST API reference. Cited as "the dev guide". - `323-1961-302_mcms_6_2_pon_manager_user_guide.pdf` — UI guide. Procedures 7, 8, 38, 43 referenced from code comments. - `323-1963-105_mcms_6_2_onu_planning_guide.pdf` — ONU planning context (PON design, link budgets). Key procedure citations: - **Procedure 2** (REST API dev guide) — determining ONU registration status via OLT-STATE buckets. - **Procedure 7** (REST API dev guide) — per-ONU firmware upgrade via full-doc PUT. - **Procedure 8** (REST API dev guide) — bulk firmware upgrade via `AUTO-TASK-CFG`. - **Procedure 38** (PON Manager User Guide) — Resetting bit error rate values; identifies the four FEC counters in the UI. - **Procedure 43** (PON Manager User Guide) — Deleting an ONU. --- ## 13. History / non-obvious design choices - **CSV is auto-saved BEFORE the API write, not after.** Intentional: capture intent even if the write fails. A "results CSV" with per-ONU success/failure is an obvious add-on but not yet wired. - **Plan CSV uses 20 columns even for trivial cases.** Wide is fine for spreadsheets; narrow forces splits later. - **FEC pre-flight only runs on the selection, not the fleet.** Originally implemented to query the whole fleet at preview time, but operator preference is "right before commit, not for the entire fleet" — keeps `/v3/onus/states//` calls bounded to N selected. - **Buggy detection uses ratio, not equality.** See §4 — real observed buggy pairs aren't bit-identical (timing windows differ), so `post == pre` misses the case. `post / pre >= 0.95` catches it. - **Optical thresholds add a yellow margin band** beyond the user guide's binary green/red. Operators want a warning before a link actually fails. - **`__Host-` cookie prefix support was added retroactively** — initial code only matched `csrftoken`, causing intermittent 500s on session refresh. - **User-Agent header was the root cause of one prolonged debugging session.** Documented in §5.1 so we don't lose that knowledge. --- ## 14. OLT PON flooding mode (bulk private↔auto) Second bulk feature, added after the firmware upgrader. Lets an operator flip the PON flooding mode of OLT NNI services across many OLTs at once. ### The mutation rule (the whole feature in one fact) On Tibit OLTs, a service's flooding mode is encoded by the **presence or absence of one key** on its `OLT-CFG["NNI Networks"][i]` entry: - **`PON FLOOD ID` key present** (any value, including `0`) → **private** - **`PON FLOOD ID` key absent** → **auto** So private→auto is `delete entry['PON FLOOD ID']`; auto→private is `entry['PON FLOOD ID'] = 0`. Everything else on the entry (`TAG MATCH`, `Learning Limit`, …) and the rest of the OLT-CFG is preserved. This was confirmed empirically by diffing two paste-backs of the same OLT (`24:65:e1:cc:af:1e`, NNI `s0.c76.c0`) in private vs auto — the *only* difference was that key. The default action ships as: TAG MATCH = `s0.c76.c0`, mode `private` → `auto`. Both directions are wired so a change can be rolled back from the same UI. ### Data flow ``` listOlts ─► McmsClient.listAllOltConfigs ─► summarizeOltNniNetworks (pure) executeFloodChange ─► per-OLT: getOltConfig ─► planFloodChange (pure, no-mutate) ─► putOltConfig (full-doc PUT) ``` - **Pure helpers** live at the bottom of `src/mcms-api.js`: `floodModeOfNni`, `summarizeOltNniNetworks`, `tagPatternToRegex`, `planFloodChange`. `planFloodChange` clones the `NNI Networks` array and never mutates its input — it returns `{ newDoc, changes, unchanged }`. - **TAG MATCH pattern** supports exact strings, `*`/`""` (match all), and `*` globs (e.g. `s0.c76.*`). `tagPatternToRegex` escapes regex metachars then turns `*` into `.*`. - **`fromMode` guard**: only entries currently in `fromMode` are flipped; entries already in the target mode are recorded in `unchanged` (the per-OLT `noop` case), so re-running is idempotent. - **Concurrency 3** on the write path (vs 5 for ONU delete, 8 for state fetch) — OLT writes carry far more blast radius. - **PUT-as-replace**, same gotcha as ONU-CFG (§5.7): the handler GETs the live doc immediately before each PUT to avoid stomping a concurrent edit, then writes the whole document back. ### UI (OLT inspector view, `#view-olts`) Reached from the fleet view's "Open OLT inspector…" button. Filters by TAG pattern + current mode + OLT name; selecting an OLT queues every matching service on it. Two-step confirm (summary `confirm` + typed `APPLY`) before writing. Auto-saves a result CSV to `~/Downloads/pon-olt-flood-…csv` with per-OLT result, change detail, and skip reasons — same `writeCsvFile` helper and conventions as the upgrade/verify CSVs (§8). ### Testing the pure helpers `floodModeOfNni` / `summarizeOltNniNetworks` / `planFloodChange` are exported from `src/mcms-api.js` and have no DOM/Electron deps, so they're directly `require`-able in a `node -e` fixture. The invariants worth re-checking after any edit: (1) `planFloodChange` does **not** mutate its input, (2) re-applying the same change is a no-op, (3) non-matching NNI entries pass through untouched. --- ## 15. Tabbed navigation & Dashboard ### Tabs The topbar holds a `