The serial clock was invisible to the save, the config and the port block #1488

Merged
jaylouisw merged 1 commit from fix/serial-clock-persists into main 2026-11-12 05:42:45 +00:00
Owner

The symptom

Serial WAN links landed yesterday with a rule enforced at cabling time: exactly one end of a V.35 pair supplies the clock, and a link with none — or with two — is refused. Save that lab and reopen it:

before saving:  clock 64000   validation clean      ping 100%   the line runs at 64 kbps
the document:   { name, type, speed, ip, mask, enabled, dhcp, description, autoconfig,
                  cage, media, speedCaps, poeOut, poeIn, maxSpeedMbps, poeOutDeclared,
                  duplex, vlan, lagId, role, dualRole, bridgeGroup, lldp, parent, encapVid }
                                     ^ no clockRateBps
after reopen:   clock undefined   E_SERIAL_NO_CLOCK   the cable is invalid, traffic stops

The cable now refuses a link that was working when the file was written.

And the port block was lying about the same line, twice:

r1# show interfaces Se0/0/0
Se0/0/0 (serial, 1.544M), MAC 02:00:00:00:00:02
  status: up, protocol: up
  ip: 10.9.0.1/24
  peer: r2/Se0/0/0
  speed: 2Mb/s (auto), link runs at 0Mb/s, duplex: full
                                     ^ a T1 rounded up, a 64 kbps line reported as zero

0Mb/s for a link that answers a ping is worse than no number: a reader concludes the line is dead. And nothing anywhere said which end clocks it, so the only fact that makes a serial link work was the one fact no surface showed. show running-config had no clock rate line either — a command that took effect and left no trace.

Measured

  • formatSpeedMbps() rounded to whole megabits: 1.544 → 2M, 0.064 → 0M, 0.1152 → 0M, 0.0096 → 0M.
  • serialize() writes 26 keys per port; clockRateBps was not among them, and Device.hydrate() had no branch to read it back.
  • show running-config printed speed and duplex for a forced port and nothing for a clocked one.

This is the fifth time the save path has dropped a per-port fact — spec (#1459), DHCP leases (#1465), LLDP neighbours (#1467), speedMbps/maxRangeM (#1405, #1321) — and the shape is identical every time: a fact added to the live object, the serializer left alone, and no test that round-trips that field.

What changed

  1. The document carries the clock. if (i.clockRateBps) doc.clockRateBps = i.clockRateBps; — written only when set, the same rule speedMbps/natRole/maxRangeM follow, so an ordinary board does not grow a clockRateBps: null line on every port in a 2,039-model catalogue. Device.hydrate() restores it, refusing a document that says "fast", -64000, and rounding 64000.7 the way the command does.
  2. The config says it. clock rate 64000 in the interface block, typed-only like everything else in running-config — so a backup of a WAN lab restores a clocked link rather than an invalid one.
  3. The port block tells the truth. speed: 1.544Mb/s (auto), link runs at 64Kb/s, DCE, clock rate 64000, duplex: full.
  4. Rates keep their unit. Anything under a megabit is spoken in kilobits — 64K, 115.2K, 9.6K — and fractions are kept above it (1.544M, 2.5G). Fixing the formatter fixes it everywhere it is used: speed refusals, the validator's messages, and every port block.

Evidence

test/serial-clock-survives-save.test.js — 32 checks, 32 passed / 0 failed; with the fix stashed, 14 failed, printing the old strings (speed: 2Mb/s (auto), link runs at 0Mb/s, 1.544 -> 2M (wanted 1.544M)).

It asserts the document carries the clock on the clocked port and no key at all on the DTE port or an ethernet port; a reopened lab keeps the clock, the 64 kbps line rate, a clean validation and a working ping; a document with the field stripped is exactly as invalid as the bug made it (E_SERIAL_NO_CLOCK); no clock rate clears both config and document; show interfaces prints the rated speed, the line rate, DCE, clock rate 64000 on the DCE only, and never 0Mb/s; ten rates across five units; three hand-edited-document cases; and the document is byte-identical after one, two and three load/save cycles.

Docs: docs/PHYSICAL_LAYER.md §2.1 gains a table of the three places the clock now lives and the before/after of each; docs/ARCHITECTURE.md gains "The fifth field the save path dropped, and the rate that said zero".

Merging the two feature PRs yesterday also moved four citations out of tolerance (_help(), openFlow(), _deliver() + a duplicate) — they now point at the definitions themselves, and check:citations is back to its single documented false positive.

Full suite: 242 suites, 9,019 assertions, 0 failed. Syntax 311 files.

## The symptom Serial WAN links landed yesterday with a rule enforced at cabling time: exactly one end of a V.35 pair supplies the clock, and a link with none — or with two — is refused. Save that lab and reopen it: ``` before saving: clock 64000 validation clean ping 100% the line runs at 64 kbps the document: { name, type, speed, ip, mask, enabled, dhcp, description, autoconfig, cage, media, speedCaps, poeOut, poeIn, maxSpeedMbps, poeOutDeclared, duplex, vlan, lagId, role, dualRole, bridgeGroup, lldp, parent, encapVid } ^ no clockRateBps after reopen: clock undefined E_SERIAL_NO_CLOCK the cable is invalid, traffic stops ``` The cable now refuses a link that was working when the file was written. And the port block was lying about the same line, twice: ``` r1# show interfaces Se0/0/0 Se0/0/0 (serial, 1.544M), MAC 02:00:00:00:00:02 status: up, protocol: up ip: 10.9.0.1/24 peer: r2/Se0/0/0 speed: 2Mb/s (auto), link runs at 0Mb/s, duplex: full ^ a T1 rounded up, a 64 kbps line reported as zero ``` `0Mb/s` for a link that answers a ping is worse than no number: a reader concludes the line is dead. And nothing anywhere said **which end clocks it**, so the only fact that makes a serial link work was the one fact no surface showed. `show running-config` had no `clock rate` line either — a command that took effect and left no trace. ## Measured - `formatSpeedMbps()` rounded to whole megabits: `1.544 → 2M`, `0.064 → 0M`, `0.1152 → 0M`, `0.0096 → 0M`. - `serialize()` writes 26 keys per port; `clockRateBps` was not among them, and `Device.hydrate()` had no branch to read it back. - `show running-config` printed `speed` and `duplex` for a forced port and nothing for a clocked one. This is the **fifth** time the save path has dropped a per-port fact — `spec` (#1459), DHCP leases (#1465), LLDP neighbours (#1467), `speedMbps`/`maxRangeM` (#1405, #1321) — and the shape is identical every time: a fact added to the live object, the serializer left alone, and no test that round-trips *that* field. ## What changed 1. **The document carries the clock.** `if (i.clockRateBps) doc.clockRateBps = i.clockRateBps;` — written only when set, the same rule `speedMbps`/`natRole`/`maxRangeM` follow, so an ordinary board does not grow a `clockRateBps: null` line on every port in a 2,039-model catalogue. `Device.hydrate()` restores it, refusing a document that says `"fast"`, `-64000`, and rounding `64000.7` the way the command does. 2. **The config says it.** `clock rate 64000` in the interface block, typed-only like everything else in running-config — so a backup of a WAN lab restores a clocked link rather than an invalid one. 3. **The port block tells the truth.** `speed: 1.544Mb/s (auto), link runs at 64Kb/s, DCE, clock rate 64000, duplex: full`. 4. **Rates keep their unit.** Anything under a megabit is spoken in kilobits — `64K`, `115.2K`, `9.6K` — and fractions are kept above it (`1.544M`, `2.5G`). Fixing the formatter fixes it everywhere it is used: `speed` refusals, the validator's messages, and every port block. ## Evidence `test/serial-clock-survives-save.test.js` — **32 checks, 32 passed / 0 failed**; with the fix stashed, **14 failed**, printing the old strings (`speed: 2Mb/s (auto), link runs at 0Mb/s`, `1.544 -> 2M (wanted 1.544M)`). It asserts the document carries the clock on the clocked port and *no key at all* on the DTE port or an ethernet port; a reopened lab keeps the clock, the 64 kbps line rate, a clean validation and a working ping; a document with the field stripped is exactly as invalid as the bug made it (`E_SERIAL_NO_CLOCK`); `no clock rate` clears both config and document; `show interfaces` prints the rated speed, the line rate, `DCE, clock rate 64000` on the DCE only, and never `0Mb/s`; ten rates across five units; three hand-edited-document cases; and the document is byte-identical after one, two and three load/save cycles. Docs: `docs/PHYSICAL_LAYER.md` §2.1 gains a table of the three places the clock now lives and the before/after of each; `docs/ARCHITECTURE.md` gains "The fifth field the save path dropped, and the rate that said zero". Merging the two feature PRs yesterday also moved four citations out of tolerance (`_help()`, `openFlow()`, `_deliver()` + a duplicate) — they now point at the definitions themselves, and `check:citations` is back to its single documented false positive. Full suite: 242 suites, 9,019 assertions, 0 failed. Syntax 311 files.
The serial clock was invisible to the save, the config and the port block
All checks were successful
CI / Classify the change (pull_request) Successful in 13s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 14s
CI / Test (Node 20) (pull_request) Successful in 3m15s
CI / Test (Node 18) (pull_request) Successful in 3m27s
CI / Server smoke test (pull_request) Successful in 32s
CI / Docker build (pull_request) Successful in 48s
CI / Test (Node 22) (pull_request) Successful in 3m7s
799ef1f542
Serial links landed with a rule enforced at cabling time: exactly one end of a
V.35 pair supplies the clock, and a link with none or with two is refused. The
clock itself lived on the interface object and nowhere else.

  * serialize() wrote 26 keys per port and clockRateBps was not one of them, so
    a saved serial lab reopened unclocked: its own cable then failed validation
    with E_SERIAL_NO_CLOCK and traffic stopped. The fifth time the save path has
    dropped a per-port fact (#1405, #1321, #1459, #1465, #1467) with the same
    shape every time - a fact added to the live object, the serializer left
    alone, and no test that round-trips that field;
  * show running-config printed speed and duplex for a forced port and nothing
    for a clocked one, so a backup of a WAN lab did not say which end is the DCE;
  * show interfaces printed "speed: 2Mb/s (auto), link runs at 0Mb/s" for a
    1.544 Mbps port on a 64 kbps line. formatSpeedMbps() rounded to whole
    megabits: 1.544 -> 2M, 0.064 -> 0M, 0.1152 -> 0M, 0.0096 -> 0M. Zero for a
    link that answers a ping is worse than no number.

  * engine/device.js: clockRateBps is written only when set, by the same rule as
    speedMbps/natRole/maxRangeM, and hydrate() restores it while refusing "fast",
    -64000 and rounding 64000.7 the way the command rounds it;
  * engine/cli.js: "clock rate 64000" in the interface block (typed-only, like
    the rest of running-config) and "DCE, clock rate 64000" in the port block;
  * engine/media.js: rates under a megabit are spoken in kilobits (64K, 115.2K,
    9.6K) and fractions are kept above it (1.544M, 2.5G) - one formatter, so the
    speed refusals and the validator's messages stop lying too.

test/serial-clock-survives-save.test.js: 32 checks, 32/0; with the fix stashed
14 fail and print the old strings. Covers the key present on the clocked port
and absent on the DTE and on ethernet ports, a reopened lab keeping its clock,
line rate, clean validation and working ping, a stripped document reproducing
E_SERIAL_NO_CLOCK, no clock rate clearing both surfaces, the printout character
for character including DCE on one end only and never 0Mb/s, ten rates across
five units, three hand-edited documents, and byte-identical documents across
three load/save cycles.

Merging the two feature PRs also moved four citations out of tolerance; they now
point at _help(), openFlow() and _deliver() themselves.

Suite 242 suites, 9019 assertions, 0 failed. Syntax 311 files.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-12 05:42:30 +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!1488
No description provided.