A saved board is the lab that was saved: every port field survives the round trip (#1321) #1322

Merged
jaylouisw merged 1 commit from fix/port-roundtrip into main 2026-11-10 02:46:28 +00:00
Owner

A saved board is the lab that was saved: every port field survives the round trip.

Fixes #1321.

Found by asking where a guard compares a subset when the contract is the whole thing. Here it was worse than a weak
guard — nothing compared a device across a save at all.

Topology.fromJSON() rebuilt every port from four keys:

return { name: i.name, type: i.type, speed: i.speed, cage: i.cage };

Over the catalogue: 322 of 2,015 devices come back different from the ones that were saved.

lost on reload ports what it does
comboWith, comboRole 84 a combo pair stops knowing it shares one cage
hardware.maxSpeedMbps 1,028 a 115.2 kbps console reloads as a 1 Gbps port
hardware.poeOutDeclared 1,499 a port that declared its own PoE reloads looking like the engine guessed

It is not cosmetic — three behaviours change

A combo cage stops being one cage. Cabling a half while its sibling is in use is refused. After a reload the
sibling is null, so:

fresh:    refused
reloaded: accepted - a second cable went into an occupied cage

A console port gains a gigabit and invents a warning (maxSpeedMbps feeds W_SPEED_DOWNGRADE):

before reload: []
after reload:  ["Link … serial1 <-> … serial1 runs at 0M, below the 1G of serial1 and the 1G of serial1."]

A reloaded lab can no longer answer whether the engine guessed its PoE — which is exactly what poeOutDeclared
exists to answer.

Fixes

fromJSON passes the whole port document through; derivePortHardware() honours what the file states
(maxSpeedMbps, poeOutDeclared, maxRangeM, plus the combo relationship) and only computes what is missing — which
is what a spec needs and a saved board does not. The serializer writes the two computed hardware facts and writes
maxRangeM/comboWith/comboRole only when they hold something, so a board does not grow a null line per port
for facts it does not have.

Evidence

test/port-roundtrip.test.js — 17 checks: the sweep over 2,015 devices comparing every field of every port
including the nested hardware object; then the behaviours — a combo pair refuses the second cable before and
after
a reload with the sibling named, a console port keeps 0.1152 Mbps and produces the same speed-downgrade
verdict, a declared-PoE port reads as declared before and after while an inferred one does not start claiming
otherwise, and a document stripped to exactly the old writer's keys still loads with hardware derived.

With engine/topology.js, engine/device.js and engine/media.js reverted, 6 of the 17 fail — the sweep names
the first four models, the reloaded combo port reports (lost), the reloaded lab accepts the second cable, the console
port goes 0.1152 → 1000, and the invented warning appears.

examples/*.json regenerated with node examples/build-examples.js — the generated boards are asserted against their
generator, which failed until they were rebuilt.

docs/ARCHITECTURE.md: "A saved board is the lab that was saved".

Suite: 176 suites, 7,002 assertions, 0 failed.

A saved board is the lab that was saved: every port field survives the round trip. Fixes #1321. Found by asking where a guard compares a *subset* when the contract is the whole thing. Here it was worse than a weak guard — nothing compared a device across a save at all. `Topology.fromJSON()` rebuilt every port from four keys: ```js return { name: i.name, type: i.type, speed: i.speed, cage: i.cage }; ``` Over the catalogue: **322 of 2,015 devices come back different** from the ones that were saved. | lost on reload | ports | what it does | |---|---|---| | `comboWith`, `comboRole` | 84 | a combo pair stops knowing it shares one cage | | `hardware.maxSpeedMbps` | 1,028 | a 115.2 kbps console reloads as a **1 Gbps** port | | `hardware.poeOutDeclared` | 1,499 | a port that declared its own PoE reloads looking like the engine guessed | ## It is not cosmetic — three behaviours change **A combo cage stops being one cage.** Cabling a half while its sibling is in use is refused. After a reload the sibling is `null`, so: ``` fresh: refused reloaded: accepted - a second cable went into an occupied cage ``` **A console port gains a gigabit and invents a warning** (`maxSpeedMbps` feeds `W_SPEED_DOWNGRADE`): ``` before reload: [] after reload: ["Link … serial1 <-> … serial1 runs at 0M, below the 1G of serial1 and the 1G of serial1."] ``` **A reloaded lab can no longer answer whether the engine guessed its PoE** — which is exactly what `poeOutDeclared` exists to answer. ## Fixes `fromJSON` passes the whole port document through; `derivePortHardware()` honours what the file states (`maxSpeedMbps`, `poeOutDeclared`, `maxRangeM`, plus the combo relationship) and only computes what is missing — which is what a *spec* needs and a *saved board* does not. The serializer writes the two computed hardware facts and writes `maxRangeM`/`comboWith`/`comboRole` **only when they hold something**, so a board does not grow a `null` line per port for facts it does not have. ## Evidence `test/port-roundtrip.test.js` — **17 checks**: the sweep over 2,015 devices comparing every field of every port including the nested `hardware` object; then the behaviours — a combo pair refuses the second cable **before and after** a reload with the sibling named, a console port keeps `0.1152` Mbps and produces the same speed-downgrade verdict, a declared-PoE port reads as declared before and after while an *inferred* one does not start claiming otherwise, and a document stripped to exactly the old writer's keys still loads with hardware derived. With `engine/topology.js`, `engine/device.js` and `engine/media.js` reverted, **6 of the 17 fail** — the sweep names the first four models, the reloaded combo port reports `(lost)`, the reloaded lab accepts the second cable, the console port goes `0.1152 → 1000`, and the invented warning appears. `examples/*.json` regenerated with `node examples/build-examples.js` — the generated boards are asserted against their generator, which failed until they were rebuilt. `docs/ARCHITECTURE.md`: "A saved board is the lab that was saved". Suite: 176 suites, 7,002 assertions, 0 failed.
A saved board is the lab that was saved: every port field survives the round trip (#1321)
All checks were successful
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 15s
CI / Classify the change (pull_request) Successful in 21s
CI / Test (Node 20) (pull_request) Successful in 3m13s
CI / Test (Node 18) (pull_request) Successful in 3m25s
CI / Server smoke test (pull_request) Successful in 43s
CI / Docker build (pull_request) Successful in 1m4s
CI / Test (Node 22) (pull_request) Successful in 2m52s
79c2fc8aab
Found by asking where a guard compares a subset when the contract is the whole thing. Here it was worse than a weak
guard: nothing compared a device across a save at all.

Topology.fromJSON() rebuilt every port from four keys - {name, type, speed, cage} - and re-derived the rest.
Measured over the catalogue: 322 of 2,015 devices came back different from the ones that were saved.

  lost on reload           ports   what it does
  comboWith, comboRole        84   a combo pair stops knowing it shares one cage
  hardware.maxSpeedMbps    1,028   a 115.2 kbps console reloads as a 1 Gbps port
  hardware.poeOutDeclared  1,499   a port that declared its own PoE reloads looking like the engine guessed

Three behaviours change, not just three fields:

  * a combo cage stops being one cage. Cabling a half while its sibling is in use is refused; after a reload the
    sibling is null, the refusal stops happening, and a second cable goes into an occupied cage ("reloaded:
    accepted - a second cable went into an occupied cage");
  * a console port gains a gigabit and invents a warning. maxSpeedMbps feeds W_SPEED_DOWNGRADE: before reload [],
    after reload ["Link ... serial1 <-> ... serial1 runs at 0M, below the 1G of serial1 and the 1G of serial1."];
  * a reloaded lab can no longer answer whether the engine guessed its PoE, which is exactly what poeOutDeclared
    exists to answer.

Fixes: fromJSON passes the whole port document through instead of four keys; derivePortHardware() honours what the
file states (maxSpeedMbps, poeOutDeclared, maxRangeM, plus the comboWith/comboRole the port keeps) and only computes
what is missing, which is what a spec needs and a saved board does not; the serializer writes those two computed
hardware facts and the combo relationship, and writes maxRangeM/comboWith/comboRole only when they hold something,
so a board does not grow a null line per port for facts it does not have.

test/port-roundtrip.test.js: 17 checks. The sweep: 2,015 devices, every field of every port identical after a save
and reload, including the nested hardware object. Then the behaviours: a combo pair refuses the second cable before
AND after a reload (with the sibling named), a console port keeps 0.1152 Mbps and produces the same
speed-downgrade verdict, a port that declares poeOut reads as declared before and after while a port the engine
guessed for does not start claiming otherwise, and a document stripped back to exactly the keys the old writer
emitted still loads with hardware derived for every port.

With engine/topology.js, engine/device.js and engine/media.js reverted, 6 of the 17 fail - the sweep names the first
four models, the reloaded combo port reports "(lost)", the reloaded lab accepts the second cable, the console port
goes 0.1152 -> 1000, and the invented warning appears.

examples/*.json regenerated with `node examples/build-examples.js` (the generated boards are asserted against their
generator by test/examples-generated.test.js, which failed until they were rebuilt).

docs/ARCHITECTURE.md: "A saved board is the lab that was saved".

Suite: 176 suites, 7,002 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 02:46:23 +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!1322
No description provided.