The clock moves when the board changes (#1331) #1332

Merged
jaylouisw merged 1 commit from fix/clock-moves into main 2026-11-10 03:52:28 +00:00
Owner

The clock moves when the board changes.

Fixes #1331.

Time in PacketForge is logical — runAtMs (the instant a question is asked at), link.stateSinceMs (when a cable
changed) and topo.lastChangeAtMs (when the board changed, the base of every convergence schedule). Three faults.

1. A config change did not move the clock

topo.markChange() was called from exactly one place: setLinkState(). Administratively disabling a port, re-enabling
it, or moving it between VLANs changes what the control plane must do — STP runs its timers again on every port behind
it — without recording when. Triangle of three CX 6000s, run time 40000:

before the change:      pending processes 0     (settled — correct)
after a port is shut:   pending processes 0     (wrong: it must re-converge)
lastChangeAtMs:         0

So a ping crosses a port that should be listening, and _stillConverging() — the honest reason a packet went nowhere
— has nothing to say.

2. Two answers to "when did the board change"

getConvergence() preferred this.reconvergeFromMs over topo.lastChangeAtMs. Nothing ever set the former except
setLinkState, which set both:

topo.lastChangeAtMs = 7000  ->  schedule from 7000
reconvergeFromMs = 100      ->  schedule from 100    (lastChangeAtMs still 7000)

3. An instant wearing a duration's clothes, and an instant out of a dead run

run time 5000, cable cut at 1200
  console: `state: down since 1200 ms`   → reads as "1200 ms ago"; it was 3800 ms ago
saved board: doc.lastChangeAtMs = 9000
  reopened tomorrow: schedule built from 9000 — an instant in a session that had ended

Fixes

  • Simulator.markTopologyChange(atMs) records the instant the operator stands at and marks STP dirty; the console
    calls it through _controlPlaneChanged() on the port-enable command, its negation, and every switchport form.
  • The shadow field is gone — one answer for one instant.
  • The console prints an instant as an instant: state: down, changed at 1200 ms (3800 ms ago), nothing when there is
    no run instant, and (not this run) rather than a negative age.
  • lastChangeAtMs is no longer written to the file; fromJSON derives it from the newest cable fault it carries. A
    cable's stateSinceMs still round-trips — that a cable is down, and since when, is board state; when the board last
    changed is run bookkeeping, like a MAC table.

Evidence

test/clock.test.js — 20 checks. Four config changes each move the clock to the run instant and leave the control
plane pending again, from a settled board; a cable still does; there is no second field; the schedule follows the
topology's clock; the console prints the instant and the age, nothing without a run instant, and (not this run)
rather than a negative age; the saved document carries no run instant while the faulted cable keeps its own; a
reloaded board derives the clock from the newest fault; over HTTP a port disabled through the API leaves no run
instant in the payload.

Two existing assertions in test/link-state.test.js were rewritten because the contract changed on purpose: it
asserted since 10000 ms (the wording that reads as a duration) and that the file carries lastChangeAtMs (the
instant out of a dead run).

With engine/cli.js, engine/simulator.js and engine/topology.js reverted, 9 of the 20 fail.

docs/ARCHITECTURE.md: "The clock".

Suite: 181 suites, 7,091 assertions, 0 failed.

The clock moves when the board changes. Fixes #1331. Time in PacketForge is logical — `runAtMs` (the instant a question is asked at), `link.stateSinceMs` (when a cable changed) and `topo.lastChangeAtMs` (when the board changed, the base of every convergence schedule). Three faults. ## 1. A config change did not move the clock `topo.markChange()` was called from exactly one place: `setLinkState()`. Administratively disabling a port, re-enabling it, or moving it between VLANs changes what the control plane must do — STP runs its timers again on every port behind it — without recording when. Triangle of three CX 6000s, run time 40000: ``` before the change: pending processes 0 (settled — correct) after a port is shut: pending processes 0 (wrong: it must re-converge) lastChangeAtMs: 0 ``` So a ping crosses a port that should be listening, and `_stillConverging()` — the honest reason a packet went nowhere — has nothing to say. ## 2. Two answers to "when did the board change" `getConvergence()` preferred `this.reconvergeFromMs` over `topo.lastChangeAtMs`. Nothing ever set the former except `setLinkState`, which set both: ``` topo.lastChangeAtMs = 7000 -> schedule from 7000 reconvergeFromMs = 100 -> schedule from 100 (lastChangeAtMs still 7000) ``` ## 3. An instant wearing a duration's clothes, and an instant out of a dead run ``` run time 5000, cable cut at 1200 console: `state: down since 1200 ms` → reads as "1200 ms ago"; it was 3800 ms ago saved board: doc.lastChangeAtMs = 9000 reopened tomorrow: schedule built from 9000 — an instant in a session that had ended ``` ## Fixes * `Simulator.markTopologyChange(atMs)` records the instant the operator stands at and marks STP dirty; the console calls it through `_controlPlaneChanged()` on the port-enable command, its negation, and every `switchport` form. * The shadow field is gone — one answer for one instant. * The console prints an instant as an instant: `state: down, changed at 1200 ms (3800 ms ago)`, nothing when there is no run instant, and `(not this run)` rather than a negative age. * `lastChangeAtMs` is no longer written to the file; `fromJSON` derives it from the newest cable fault it carries. A cable's `stateSinceMs` still round-trips — that a cable is down, and since when, is board state; when the board last changed is run bookkeeping, like a MAC table. ## Evidence `test/clock.test.js` — **20 checks**. Four config changes each move the clock to the run instant and leave the control plane pending again, from a settled board; a cable still does; there is no second field; the schedule follows the topology's clock; the console prints the instant and the age, nothing without a run instant, and `(not this run)` rather than a negative age; the saved document carries no run instant while the faulted cable keeps its own; a reloaded board derives the clock from the newest fault; over HTTP a port disabled through the API leaves no run instant in the payload. Two existing assertions in `test/link-state.test.js` were **rewritten because the contract changed on purpose**: it asserted `since 10000 ms` (the wording that reads as a duration) and that the file carries `lastChangeAtMs` (the instant out of a dead run). With `engine/cli.js`, `engine/simulator.js` and `engine/topology.js` reverted, **9 of the 20 fail**. `docs/ARCHITECTURE.md`: "The clock". Suite: 181 suites, 7,091 assertions, 0 failed.
The clock moves when the board changes (#1331)
All checks were successful
CI / Classify the change (pull_request) Successful in 20s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 24s
CI / Test (Node 20) (pull_request) Successful in 3m41s
CI / Test (Node 18) (pull_request) Successful in 3m51s
CI / Server smoke test (pull_request) Successful in 44s
CI / Docker build (pull_request) Successful in 1m25s
CI / Test (Node 22) (pull_request) Successful in 3m32s
37a55eaa29
Time in PacketForge is logical: runAtMs (the instant a question is asked at), link.stateSinceMs (when a cable
changed) and topo.lastChangeAtMs (when the board changed - the base of every convergence schedule). Three faults.

1. A config change did not move the clock. topo.markChange() was called from exactly one place, setLinkState(), so
   administratively disabling a port, re-enabling it, or moving it between VLANs changed what the control plane must
   do without recording when. Measured on a triangle of three CX 6000s at run time 40000: 0 pending processes before
   the change, 0 after, lastChangeAtMs 0. A ping crosses a port that should be listening, and _stillConverging() -
   the honest reason a packet went nowhere - has nothing to say.

2. Two answers to "when did the board change". getConvergence() preferred this.reconvergeFromMs over
   topo.lastChangeAtMs; nothing ever set the former except setLinkState, which set both. Measured: lastChangeAtMs
   7000, reconvergeFromMs 100 -> the schedule is built from 100.

3. An instant wearing a duration's clothes, and an instant out of a dead run. At run time 5000 with the cable cut at
   1200, the console printed "state: down since 1200 ms" - which reads as "1200 ms ago" and was 3800 ms ago. And the
   saved file carried lastChangeAtMs, so a board reopened tomorrow built its schedule from an instant belonging to a
   session that had ended.

Fixes:

  * Simulator.markTopologyChange(atMs) records the instant the operator stands at and marks STP dirty;
  * the console calls it through _controlPlaneChanged() on the port-enable command, its negation, and every
    switchport form - one helper, so a command added later either uses it or is caught by the test;
  * the shadow field is gone: getConvergence() reads topo.lastChangeAtMs, one answer for one instant;
  * the console prints an instant as an instant - "state: down, changed at 1200 ms (3800 ms ago)", nothing when there
    is no run instant, and "(not this run)" rather than a negative age when the instant is later than the run;
  * lastChangeAtMs is no longer written to the file, and fromJSON derives it from the newest cable fault it carries.
    A cable's stateSinceMs still round-trips: that a cable is down, and since when, is board state; when the board
    last changed is run bookkeeping, like a MAC table.

test/clock.test.js: 20 checks. Four config changes (port off, port on, switchport access vlan, switchport mode trunk)
each move the clock to the run instant and leave the control plane pending again, from a board that was settled; a
cable still does; there is no second field; the schedule follows the topology's clock; the console prints the instant
and the age, nothing when there is no run instant, and "(not this run)" rather than a negative age; the saved document
carries no run instant while the faulted cable keeps its own; a reloaded board derives the clock from the newest fault
and a clean board says nothing has changed; and over HTTP a port disabled through the API leaves no run instant in the
payload while a loaded document's faulted cable keeps its instant.

Two existing assertions were rewritten because the contract changed on purpose: link-state.test.js asserted "since
10000 ms" (the wording that reads as a duration) and asserted that the file carries lastChangeAtMs (the instant out
of a dead run).

With engine/cli.js, engine/simulator.js and engine/topology.js reverted, 9 of the 20 fail: the clock stays 0 after
every config change, the schedule is built from the shadow field, and the old wording is back.

docs/ARCHITECTURE.md: "The clock".

Suite: 181 suites, 7,091 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 03:52: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!1332
No description provided.