UPSTREAM-DESIGN: the data path does read Link.state, and has since #1058 #1922

Merged
jaylouisw merged 1 commit from docs/1118-0146 into main 2026-11-18 01:57:58 +00:00
Owner

One claim in docs/UPSTREAM-DESIGN.md �1.1 is contradicted by the engine.

The doc said (measured at d399dff): marking a WAN link down gives an identical trace, because "the data path never reads Link.state", and _deliver() checks only iface.enabled and iface.peer; web/app.js "prints a State field in the link inspector that the engine ignores".

The code says (engine/simulator.js:3174, _deliver()):

const crossing = this._linkAt(dev.id, iface.name);
if (crossing && !crossing.isUp()) {
  this._emit({ type: 'drop', reason: 'link down', dev: dev.id, iface: iface.name, link: crossing.id });
  return;
}

Reproduced: two hosts through a switch pair, addressed, ping succeeds; sim.linkDown(mid) and the same ping fails with drop events whose reason is link down (this is what test/link-state.test.js pinning 69 assertions is about). web/app.js reads link.state at :2347 (inspector State row) and :2792 (canvas colours a down cable).

?? The defect �1.1 is about survives — routeTo() (engine/device.js:971) still returns one route and nothing asks for a second, so a dead primary is still a dead end. Only the reason changes: the walk stops at the cable with a visible drop instead of passing through it. The row and the paragraph now say that, and work-order row 26 (simulator.js:1595 _deliver(), "emit link-down") is marked done with the note that the reason rides on a drop event rather than a link-down event type of its own.

Also refreshed two adjacent �1.2 anchors (derivePortHardware 894→941, inferCage 786→828) — scripts/check-doc-citations.js goes from 3 suspects to 0.

Docs-only. Guards: syntax-check 401 files OK; docs-cli-transcript 4/4; docs-show-commands 7/7 (55 forms, 110 commands, 68 device refusals); help-completeness 8/8 (102 advertised commands); help-key-is-not-a-value 40/40; no-form-help-key 81/81; doc-catalog-counts 43/43; check-control-bytes clean; check-canonical-urls 3092 files OK.

One claim in `docs/UPSTREAM-DESIGN.md` �1.1 is contradicted by the engine. **The doc said** (measured at `d399dff`): marking a WAN link `down` gives an *identical trace*, because "the data path never reads `Link.state`", and `_deliver()` checks only `iface.enabled` and `iface.peer`; `web/app.js` "prints a State field in the link inspector that the engine ignores". **The code says** (`engine/simulator.js:3174`, `_deliver()`): ```js const crossing = this._linkAt(dev.id, iface.name); if (crossing && !crossing.isUp()) { this._emit({ type: 'drop', reason: 'link down', dev: dev.id, iface: iface.name, link: crossing.id }); return; } ``` Reproduced: two hosts through a switch pair, addressed, `ping` succeeds; `sim.linkDown(mid)` and the same `ping` fails with drop events whose reason is `link down` (this is what `test/link-state.test.js` pinning 69 assertions is about). `web/app.js` reads `link.state` at `:2347` (inspector State row) and `:2792` (canvas colours a down cable). ?? **The defect �1.1 is about survives** — `routeTo()` (`engine/device.js:971`) still returns one route and nothing asks for a second, so a dead primary is still a dead end. Only the *reason* changes: the walk stops at the cable with a visible drop instead of passing through it. The row and the paragraph now say that, and work-order row 26 (`simulator.js:1595 _deliver()`, \"emit `link-down`\") is marked done with the note that the reason rides on a `drop` event rather than a `link-down` event type of its own. Also refreshed two adjacent �1.2 anchors (`derivePortHardware` 894→941, `inferCage` 786→828) — `scripts/check-doc-citations.js` goes from **3 suspects to 0**. Docs-only. Guards: syntax-check 401 files OK; docs-cli-transcript 4/4; docs-show-commands 7/7 (55 forms, 110 commands, 68 device refusals); help-completeness 8/8 (102 advertised commands); help-key-is-not-a-value 40/40; no-form-help-key 81/81; doc-catalog-counts 43/43; check-control-bytes clean; check-canonical-urls 3092 files OK.
UPSTREAM-DESIGN: the data path does read Link.state, and has since #1058
All checks were successful
CI / Classify the change (pull_request) Successful in 7s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 9s
CI / Server smoke test (pull_request) Successful in 6s
CI / Docker build (pull_request) Successful in 19s
CI / Test (Node 20) (pull_request) Successful in 47s
CI / Test (Node 18) (pull_request) Successful in 55s
CI / Test (Node 22) (pull_request) Successful in 51s
CI / Arm auto-merge (pull_request) Successful in 8s
a716412d78
§1.1 measured the failover matrix at d399dff and concluded that marking a cable down
changes nothing: 'identical trace — the data path never reads Link.state', with
`_deliver()` said to check only `iface.enabled` and `iface.peer`.

engine/simulator.js:3174 does both of those and then asks the cable:
`const crossing = this._linkAt(dev.id, iface.name); if (crossing && !crossing.isUp())`
emits `{ type: 'drop', reason: 'link down' }`. Two hosts over a switch pair, cabled,
addressed, ping succeeds; `sim.linkDown(mid)` and the same ping drops with reason
`link down`. web/app.js reads the same field at :2347 (inspector State) and :2792
(canvas), so the 'State field the engine ignores' is doubly stale.

The conclusion §1.1 draws still holds — routeTo() returns one route and nothing asks
for a second, so a dead primary is still a dead end — so the row now says the trace
dies at the cable instead of passing through it. Work-order row 26 is the same change:
marked done, with the note that the reason rides on a `drop` event rather than a
`link-down` event type of its own.

Adjacent anchors in §1.2 refreshed (derivePortHardware 894->941, inferCage 786->828),
which takes scripts/check-doc-citations.js from three suspects to none.
jaylouisw force-pushed docs/1118-0146 from a716412d78
All checks were successful
CI / Classify the change (pull_request) Successful in 7s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 9s
CI / Server smoke test (pull_request) Successful in 6s
CI / Docker build (pull_request) Successful in 19s
CI / Test (Node 20) (pull_request) Successful in 47s
CI / Test (Node 18) (pull_request) Successful in 55s
CI / Test (Node 22) (pull_request) Successful in 51s
CI / Arm auto-merge (pull_request) Successful in 8s
to d4603d69a1
All checks were successful
CI / Classify the change (pull_request) Successful in 6s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 5s
CI / Server smoke test (pull_request) Has been skipped
CI / Docker build (pull_request) Has been skipped
CI / Test (Node 20) (pull_request) Successful in 47s
CI / Test (Node 18) (pull_request) Successful in 52s
CI / Test (Node 22) (pull_request) Successful in 49s
CI / Arm auto-merge (pull_request) Successful in 9s
2026-11-18 01:56:05 +00:00
Compare
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!1922
No description provided.