A cable the loader cannot restore is dropped in silence, an undefined link state is adopted, a port can be cabled to itself, and serialize() hands out live endpoints #1323

Closed
opened 2026-11-10 02:57:24 +00:00 by jaylouisw · 0 comments
Owner

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 is 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 against the current loader:

1. two cables with one id            -> links in the document: 2 | links loaded: 1     (silent)
2. state "sideways"                  -> {"state":"sideways","isUp":false}             (adopted)
3. a cable to a missing device       -> links loaded: 1 of 2                          (silent)
4. a cable from a port to itself     -> loaded as a cable from a port to itself        (adopted)
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
                                        changes the board                              (aliased)

Why each of those is a lie rather than a tolerated edge

  • duplicate id. Links are kept in a map, so the second cable replaced the first: one cable in the file, two
    described, one lost, no message. Same family as #1315 (two boards, one file).
  • state: 'sideways'. The HTTP API refuses an unknown state with 422 E_BAD_STATE; the load path accepted
    anything. A cable then sits in a state that is neither up nor down nor blocked: isUp() is false, show interfaces reports a link that cannot carry, and nothing explains why.
  • a cable to a port that is not there, and a cable from a port to itself, both loaded or dropped without a
    word, so an imported lab can differ from the document it came from and the operator has no way to tell which
    cable went missing.
  • stateSinceMs: 'soon' became null — "not at any known time" — through Number(...) and JSON.
  • 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; a caller adjusting the document it was given adjusted the lab.

What must be true instead

  • every option connect() accepts round-trips exactly (tested, not assumed);
  • a cable that cannot be restored appears in loadIssues with a code and the engine's own sentence, and every
    state payload carries the list next to verdicts (the #1306 rule);
  • 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);
  • serialize() hands out copies, so a document can be edited without editing the board;
  • a clean document loads cleanly and quietly — loadIssues empty, nothing to explain.
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 is 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 against the current loader: ``` 1. two cables with one id -> links in the document: 2 | links loaded: 1 (silent) 2. state "sideways" -> {"state":"sideways","isUp":false} (adopted) 3. a cable to a missing device -> links loaded: 1 of 2 (silent) 4. a cable from a port to itself -> loaded as a cable from a port to itself (adopted) 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 changes the board (aliased) ``` ## Why each of those is a lie rather than a tolerated edge * **duplicate id.** Links are kept in a map, so the second cable replaced the first: one cable in the file, two described, one lost, no message. Same family as #1315 (two boards, one file). * **`state: 'sideways'`.** The HTTP API refuses an unknown state with `422 E_BAD_STATE`; the load path accepted anything. A cable then sits in a state that is neither up nor down nor blocked: `isUp()` is false, `show interfaces` reports a link that cannot carry, and nothing explains why. * **a cable to a port that is not there**, and **a cable from a port to itself**, both loaded or dropped without a word, so an imported lab can differ from the document it came from and the operator has no way to tell which cable went missing. * **`stateSinceMs: 'soon'`** became `null` — "not at any known time" — through `Number(...)` and JSON. * **`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; a caller adjusting the document it was given adjusted the lab. ## What must be true instead * every option `connect()` accepts round-trips exactly (tested, not assumed); * a cable that cannot be restored appears in `loadIssues` with a code and the engine's own sentence, and every state payload carries the list next to `verdicts` (the #1306 rule); * 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); * `serialize()` hands out copies, so a document can be edited without editing the board; * a clean document loads cleanly and quietly — `loadIssues` empty, nothing to explain.
Sign in to join this conversation.
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#1323
No description provided.