A cable is restored or explained, and a document can be edited without editing the board (#1323) #1324

Merged
jaylouisw merged 1 commit from fix/link-restore-report into main 2026-11-10 02:58:19 +00:00
Owner

A cable is restored or explained, and a document can be edited without editing the board.

Fixes #1323.

The other half of the round trip (after #1321 for ports). Every option connect() accepts survives a save and
reload — that part was always true, and there was no test for it either. What was not true is what happens to a
cable the loader cannot restore: it was skipped by a bare catch, so a document with two cables could come back
with one and nothing anywhere said so.

Measured

1. two cables with one id            -> document: 2 cables | loaded: 1     (silent)
2. state "sideways"                  -> {"state":"sideways","isUp":false}  (adopted)
3. a cable to a missing device       -> loaded 1 of 2                     (silent)
4. a port cabled to itself           -> loaded as a cable from a port to itself
5. stateSinceMs "soon"               -> since: null  (a time that is not a time)
6. serialize().links[0].a === link.a -> true; writing to the returned document changed the board

Why each is a lie rather than a tolerated edge

  • Links are kept in a map, so a duplicate id meant the second cable replaced the first — one cable in the file,
    one lost, no message (same family as #1315).
  • The HTTP API refuses an unknown link state with 422 E_BAD_STATE; the load path accepted anything, so a cable
    sat in a state that is neither up nor down nor blocked: isUp() false, the console reporting a link that cannot
    carry, and nothing explaining why.
  • A cable to a port that is not there, and a port cabled to itself, were dropped or adopted without a word.
  • serialize() handed out its own endpoint records — the document the API, the UI, the example builder and every
    test fixture receives was the live board.

Fixes

fromJSON() checks each cable before building it (cableProblem()) and records what it could not restore in
topo.loadIssues; fullState() carries the list next to verdicts so every surface sees it (#1306); serialize()
copies its endpoints; a non-numeric stateSinceMs is 0 rather than a null masquerading as a timestamp.

Codes: E_LINK_DUPLICATE_ID, E_LINK_BAD_STATE (naming the states that exist), E_LINK_SELF_LOOP,
E_LINK_ENDPOINT_MISSING (naming the end), E_LINK_NOT_RESTORED (the engine's own sentence).

Evidence

test/link-roundtrip.test.js — 21 checks: eight kinds of cable (defaults, media+speed, half duplex, length, lag,
cut at 12.345 s, STP-blocked, a legacy type string) byte-identical after a save and reload; each impossible cable
reported with its code and a message naming what is wrong; a clean document loading with an empty loadIssues; the
handed-out document being a snapshot. Over HTTP: /load carries the reasons in state.loadIssues and
GET /api/topologies/:id carries them too.

With engine/link.js, engine/topology.js and server/index.js reverted, 13 of the 21 fail — no report for any
of the five impossible cables, and the reloaded document mutating the board.

docs/ARCHITECTURE.md: "A cable is restored or explained".

Suite: 177 suites, 7,023 assertions, 0 failed.

A cable is restored or explained, and a document can be edited without editing the board. Fixes #1323. The other half of the round trip (after #1321 for ports). Every option `connect()` accepts survives a save and reload — that part was always true, and there was no test for it either. What was **not** true is what happens to a cable the loader *cannot* restore: it was skipped by a bare `catch`, so a document with two cables could come back with one and nothing anywhere said so. ## Measured ``` 1. two cables with one id -> document: 2 cables | loaded: 1 (silent) 2. state "sideways" -> {"state":"sideways","isUp":false} (adopted) 3. a cable to a missing device -> loaded 1 of 2 (silent) 4. a port cabled to itself -> loaded as a cable from a port to itself 5. stateSinceMs "soon" -> since: null (a time that is not a time) 6. serialize().links[0].a === link.a -> true; writing to the returned document changed the board ``` ## Why each is a lie rather than a tolerated edge * Links are kept in a map, so a **duplicate id** meant the second cable replaced the first — one cable in the file, one lost, no message (same family as #1315). * The HTTP API refuses an unknown link state with `422 E_BAD_STATE`; the **load path accepted anything**, so a cable sat in a state that is neither up nor down nor blocked: `isUp()` false, the console reporting a link that cannot carry, and nothing explaining why. * A cable to a port that is not there, and a **port cabled to itself**, were dropped or adopted without a word. * `serialize()` handed out its own endpoint records — the document the API, the UI, the example builder and every test fixture receives **was** the live board. ## Fixes `fromJSON()` checks each cable before building it (`cableProblem()`) and records what it could not restore in `topo.loadIssues`; `fullState()` carries the list next to `verdicts` so every surface sees it (#1306); `serialize()` copies its endpoints; a non-numeric `stateSinceMs` is `0` rather than a null masquerading as a timestamp. Codes: `E_LINK_DUPLICATE_ID`, `E_LINK_BAD_STATE` (naming the states that exist), `E_LINK_SELF_LOOP`, `E_LINK_ENDPOINT_MISSING` (naming the end), `E_LINK_NOT_RESTORED` (the engine's own sentence). ## Evidence `test/link-roundtrip.test.js` — **21 checks**: eight kinds of cable (defaults, media+speed, half duplex, length, lag, cut at 12.345 s, STP-blocked, a legacy type string) byte-identical after a save and reload; each impossible cable reported with its code and a message naming what is wrong; a clean document loading with an empty `loadIssues`; the handed-out document being a snapshot. Over HTTP: `/load` carries the reasons in `state.loadIssues` and `GET /api/topologies/:id` carries them too. With `engine/link.js`, `engine/topology.js` and `server/index.js` reverted, **13 of the 21 fail** — no report for any of the five impossible cables, and the reloaded document mutating the board. `docs/ARCHITECTURE.md`: "A cable is restored or explained". Suite: 177 suites, 7,023 assertions, 0 failed.
A cable is restored or explained, and a document can be edited without editing the board (#1323)
All checks were successful
CI / Classify the change (pull_request) Successful in 17s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 19s
CI / Test (Node 18) (pull_request) Successful in 3m24s
CI / Test (Node 20) (pull_request) Successful in 3m21s
CI / Server smoke test (pull_request) Successful in 48s
CI / Docker build (pull_request) Successful in 1m1s
CI / Test (Node 22) (pull_request) Successful in 3m10s
ce5259f147
The other half of the round trip. Every option connect() accepts survives a save and reload - that part was always
true, and there was no test for it either. What was not true is what happens to a cable the loader CANNOT restore: it
was skipped by a bare catch, so a document with two cables could come back with one and nothing said so.

Measured:

  1. two cables with one id            -> document: 2 cables | loaded: 1     (silent)
  2. state "sideways"                  -> {"state":"sideways","isUp":false}  (adopted)
  3. a cable to a missing device       -> loaded 1 of 2                     (silent)
  4. a port cabled to itself           -> loaded as a cable from a port to itself
  5. stateSinceMs "soon"               -> since: null  (a time that is not a time)
  6. serialize().links[0].a === link.a -> true; writing to the returned document changed the board

Why each is a lie rather than a tolerated edge:

  * links are kept in a map, so a duplicate id meant the second cable replaced the first - one cable in the file,
    one lost, no message (same family as #1315);
  * the HTTP API refuses an unknown link state with 422 E_BAD_STATE, and the load path accepted anything, so a cable
    sat in a state that is neither up nor down nor blocked: isUp() false, the console reporting a link that cannot
    carry, and nothing explaining why;
  * a cable to a port that is not there, and a port cabled to itself, were dropped or adopted without a word;
  * serialize() handed out its own endpoint records - the document the API, the UI, the example builder and every
    test fixture receives WAS the live board.

Fixes: fromJSON() checks each cable before building it (cableProblem()) and records what it could not restore in
topo.loadIssues with a code and, where the engine refused it, the engine's own sentence; fullState() carries the list
next to verdicts so every surface sees it (#1306); serialize() copies the endpoints; a non-numeric stateSinceMs is 0
rather than a null masquerading as a timestamp.

Codes: E_LINK_DUPLICATE_ID, E_LINK_BAD_STATE (naming the states that exist), E_LINK_SELF_LOOP,
E_LINK_ENDPOINT_MISSING (naming the end), E_LINK_NOT_RESTORED (the engine's reason).

test/link-roundtrip.test.js: 21 checks. Eight kinds of cable (defaults, media+speed, half duplex, length, lag, cut at
12.345 s, STP-blocked, a legacy type string) are byte-identical after a save and reload. Each impossible cable is
reported with its code and a message that names what is wrong, the loss of a duplicate is reported rather than
silent, a clean document loads with an empty loadIssues, and the document handed out is a snapshot. Over HTTP: /load
carries the reasons in state.loadIssues and GET /api/topologies/:id carries them too.

With engine/link.js, engine/topology.js and server/index.js reverted, 13 of the 21 fail - no report for any of the
five impossible cables, and the reloaded document mutating the board.

docs/ARCHITECTURE.md: "A cable is restored or explained".

Suite: 177 suites, 7,023 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 02:57:54 +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!1324
No description provided.