A reopened lab forgot what its hardware was made of #1460

Merged
jaylouisw merged 1 commit from fix/spec-survives-load into main 2026-11-12 02:20:15 +00:00
Owner

Closes #1459

% OLT/gpon0/1 <-> PON Splitter 1:32/uplink: downstream at 1490 nm Path loss 31.3 dB exceeds the B+ budget
  of 28 dB by 3.3 dB. splitting costs 17.5 dB, fibre costs 13.2 dB      <- refused when drawn

save, set lengthM = 60000 in the file, reopen
-> validateTopology: ok true, 0 errors

A document states a device's identity, its ports and its configuration. Topology.fromJSON rebuilt the device spec from a hand-picked handful of keys and dropped everything else, so a reopened lab forgot what its hardware was made of:

  • the optical budget reads spec.splitRatio / spec.ponClass — a 1:32 splitter came back splitting nothing, and the 60 km run stopped being refused;
  • isPassiveTap() reads spec.passive — a passive tap came back as a box that learns MAC addresses.

The change

Device.serialize() writes the spec minus the keys the document already carries elsewhere (interfaces are saved port by port; description, notes, sourceUrl are catalogue prose that does not belong in a lab), and fromJSON merges that record underneath the document's own identity and ports.

After the change the same document reports the identical sentence the connect door refuses with — E_OPTICAL_BUDGET, severity error, 31.3 dB against a 28 dB budget, naming the splitter's 17.5 dB — and a new 60 km run drawn on the reopened board is refused again, because the ratio is no longer forgotten.

Deliberately unchanged

  • documents written before this rule still open: no spec, nothing to report, no wrong facts invented;
  • ports, names, addresses, configuration and links round-trip exactly as before;
  • the file does not grow: no interfaces inside spec, no prose.

Evidence

test/spec-survives-load.test.js, 32 checks: the splitter keeps splitRatio/insertionLossDb; a CWDM mux keeps its channelCount/channelPlan; a passive tap still answers isPassiveTap(); the over-budget document is reported as an error with the door's own numbers and clears the board's ok; a within-budget board stays clean; the door refuses a fresh over-budget run on the reopened topology and makes no cable; old documents (spec stripped) restore every device, port and cable with no loadIssues; and the saved spec carries neither ports nor prose.

Reverting engine/device.js + engine/topology.js fails 14/32.

Neighbours green: pon-splitter 33, hybrid-cord-use 64, cable-length 22, flows-survive-save-load 16, state-payload-complete 16, port-roundtrip 32, config-roundtrip 46, engine 12, acl-data 21.

Docs: docs/ARCHITECTURE.md § "A reopened lab forgot what its hardware was made of".

Closes #1459 ``` % OLT/gpon0/1 <-> PON Splitter 1:32/uplink: downstream at 1490 nm Path loss 31.3 dB exceeds the B+ budget of 28 dB by 3.3 dB. splitting costs 17.5 dB, fibre costs 13.2 dB <- refused when drawn save, set lengthM = 60000 in the file, reopen -> validateTopology: ok true, 0 errors ``` A document states a device's identity, its ports and its configuration. `Topology.fromJSON` rebuilt the device **spec** from a hand-picked handful of keys and dropped everything else, so a reopened lab forgot what its hardware was made of: * the optical budget reads `spec.splitRatio` / `spec.ponClass` — a 1:32 splitter came back splitting nothing, and the 60 km run stopped being refused; * `isPassiveTap()` reads `spec.passive` — a passive tap came back as a box that learns MAC addresses. ### The change `Device.serialize()` writes the spec minus the keys the document already carries elsewhere (`interfaces` are saved port by port; `description`, `notes`, `sourceUrl` are catalogue prose that does not belong in a lab), and `fromJSON` merges that record underneath the document's own identity and ports. After the change the same document reports the identical sentence the connect door refuses with — `E_OPTICAL_BUDGET`, severity error, 31.3 dB against a 28 dB budget, naming the splitter's 17.5 dB — and a *new* 60 km run drawn on the reopened board is refused again, because the ratio is no longer forgotten. ### Deliberately unchanged * documents written before this rule still open: no `spec`, nothing to report, no wrong facts invented; * ports, names, addresses, configuration and links round-trip exactly as before; * the file does not grow: no `interfaces` inside `spec`, no prose. ### Evidence `test/spec-survives-load.test.js`, **32 checks**: the splitter keeps `splitRatio`/`insertionLossDb`; a CWDM mux keeps its `channelCount`/`channelPlan`; a passive tap still answers `isPassiveTap()`; the over-budget document is reported as an error with the door's own numbers and clears the board's `ok`; a within-budget board stays clean; the door refuses a fresh over-budget run on the reopened topology and makes no cable; old documents (spec stripped) restore every device, port and cable with no `loadIssues`; and the saved `spec` carries neither ports nor prose. Reverting `engine/device.js` + `engine/topology.js` fails 14/32. Neighbours green: `pon-splitter` 33, `hybrid-cord-use` 64, `cable-length` 22, `flows-survive-save-load` 16, `state-payload-complete` 16, `port-roundtrip` 32, `config-roundtrip` 46, `engine` 12, `acl-data` 21. Docs: `docs/ARCHITECTURE.md` § *"A reopened lab forgot what its hardware was made of"*.
A reopened lab forgot what its hardware was made of (#1459)
All checks were successful
CI / Classify the change (pull_request) Successful in 11s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 14s
CI / Test (Node 20) (pull_request) Successful in 2m56s
CI / Test (Node 18) (pull_request) Successful in 3m9s
CI / Server smoke test (pull_request) Successful in 23s
CI / Docker build (pull_request) Successful in 46s
CI / Test (Node 22) (pull_request) Successful in 2m50s
ae6bbf2070
s1# (drawn on the board)
  % OLT/gpon0/1 <-> PON Splitter 1:32/uplink: downstream at 1490 nm Path loss
    31.3 dB exceeds the B+ budget of 28 dB by 3.3 dB. splitting costs 17.5 dB,
    fibre costs 13.2 dB

  save, set lengthM = 60000 in the file, reopen
  -> validateTopology: ok true, 0 errors

A document states a device's identity, its ports and its configuration.
Topology.fromJSON rebuilt the device spec - the physical facts it was built from
- from a hand-picked handful of keys and dropped everything else, so a reopened
lab forgot what its hardware was made of:

  * the optical budget reads spec.splitRatio and spec.ponClass, so a 1:32
    splitter came back splitting nothing and the 60 km run stopped being
    refused - the door was only shut by the ratio;
  * isPassiveTap() reads spec.passive, so a passive tap came back as a box that
    learns MAC addresses.

Device.serialize() now writes the spec facts the rules read - not the keys the
document already carries elsewhere (interfaces are saved port by port) and not
catalogue prose - and fromJSON merges that record underneath the document's own
identity and ports. Documents written before this rule still open: they have no
ratio to read, and nothing is invented for them.

Evidence: test/spec-survives-load.test.js, 32 checks; reverting engine/device.js
and engine/topology.js fails 14. Suite 230 suites, 8629 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-12 02:20:13 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1460
No description provided.