LINK-STATE: the saved lab has no lastChangeAtMs, so stop claiming it does #1571

Merged
jaylouisw merged 1 commit from docs/1116-0016 into main 2026-11-16 01:28:47 +00:00
Owner

docs/LINK-STATE.md said, under Persistence, that "the topology records "lastChangeAtMs": 10000", and a paragraph up top said the change instant "survives save/load".

The engine has said otherwise since #1331:

  • engine/topology.js:762 � lastChangeAtMs is deliberately NOT written: "an instant in a run, and a run ends". The serialized document has keys format,version,seq,devices,links,layout,flows and nothing else.
  • engine/topology.js:902 � fromJSON() derives the clock from the newest cable stateSinceMs.

Probe on a two-switch board, linkDown(l1, { atMs: 10000 }):

  • saved link: {"id":"l1",...,"state":"down","stateSinceMs":10000}
  • saved document: no lastChangeAtMs
  • Topology.fromJSON(saved).lastChangeAtMs -> 10000

The outage does come back (state: down is restored, the window is right), so only the "the file records the instant" claim was false. docs/ARCHITECTURE.md already described the derived clock; this page was the last one quoting the old document. Reworded both sentences to say what is written and what is derived.

Guards: syntax-check 327 files OK; control-bytes clean; doc-citations 350 citations, 5 suspects inside the 40-line allowance; doc-catalog-counts 24; docs-show-commands 7; help-completeness 8; help-key-works-in-every-prompt 9 pass; repo-paths 8 � unchanged before and after (docs-only edit).

`docs/LINK-STATE.md` said, under **Persistence**, that "the topology records `"lastChangeAtMs": 10000`", and a paragraph up top said the change instant "survives save/load". The engine has said otherwise since #1331: - `engine/topology.js:762` � `lastChangeAtMs` is *deliberately NOT written*: "an instant in a run, and a run ends". The serialized document has keys `format,version,seq,devices,links,layout,flows` and nothing else. - `engine/topology.js:902` � `fromJSON()` derives the clock from the newest cable `stateSinceMs`. Probe on a two-switch board, `linkDown(l1, { atMs: 10000 })`: - saved link: `{"id":"l1",...,"state":"down","stateSinceMs":10000}` - saved document: no `lastChangeAtMs` - `Topology.fromJSON(saved).lastChangeAtMs` -> `10000` The outage does come back (`state: down` is restored, the window is right), so only the "the file records the instant" claim was false. `docs/ARCHITECTURE.md` already described the derived clock; this page was the last one quoting the old document. Reworded both sentences to say what is written and what is derived. Guards: syntax-check 327 files OK; control-bytes clean; doc-citations 350 citations, 5 suspects inside the 40-line allowance; doc-catalog-counts 24; docs-show-commands 7; help-completeness 8; help-key-works-in-every-prompt 9 pass; repo-paths 8 � unchanged before and after (docs-only edit).
LINK-STATE: the saved lab has no lastChangeAtMs, so stop claiming it does
Some checks failed
CI / Classify the change (pull_request) Successful in 14s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 19s
CI / Test (Node 18) (pull_request) Failing after 3m31s
CI / Test (Node 20) (pull_request) Failing after 3m12s
CI / Server smoke test (pull_request) Has been skipped
CI / Docker build (pull_request) Has been skipped
CI / Test (Node 22) (pull_request) Failing after 3m1s
a7735c91e3
The Persistence section said "the topology records \"lastChangeAtMs\": 10000".
engine/topology.js:762 says the opposite in so many words - the field is
deliberately NOT written, because an instant in a run is not evidence once the
run ends - and fromJSON() derives the clock from the newest cable stateSinceMs
(topology.js:902). Probe: serialize() after linkDown(at 10000) has keys
format,version,seq,devices,links,layout,flows; the link carries state down and
stateSinceMs 10000; Topology.fromJSON() answers 10000. ARCHITECTURE.md already
described this; LINK-STATE.md was the last page still quoting the old document.
jaylouisw deleted branch docs/1116-0016 2026-11-16 01:28: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!1571
No description provided.