The command that knew why and said "timed out" #1486

Merged
jaylouisw merged 1 commit from fix/ping-says-why into main 2026-11-12 05:02:35 +00:00
Owner

The symptom

ping is the first command anyone types in a lab, and the one that most often fails. On a lab where the router's port is shut:

r1> ping 10.0.0.10 1
Type escape sequence to abort.
Sending 1, 100-byte ICMP Echos to 10.0.0.10, timeout is 2 seconds:
.
Success rate is 0 percent (0/1)
Request timed out (seq 0)

That is everything the console says. This is everything the engine knew, and returned:

replies: [{ seq: 0, success: false, reason: "peer port shut (R1 Gi0/0/0)" }]

Simulator.ping() has recorded a reason for every lost echo since #1431 ranked the causes by earliness — no route to 10.0.0.99, no ARP reply from 10.91.0.10, peer port shut (R1 Gi0/0/0), ACL 101 denied (in). _pingReplyLines() printed the timeout and threw the reason away.

So the most-used command in the simulator answered something went wrong to the question what went wrong — for exactly the beginner mistakes a simulator exists to teach: no address, no route, cable down, VLAN not allowed.

What was actually wrong

Not a missing fact. A missing sentence. The engine computed the reason, carried it in the answer, and the surface that a person reads dropped it. Same species as #1475 (the packet log printing flow-close instead of which flow ended) and #1473 (one ARP row where two boxes had answered): the model was right and the translation layer was silent, which is the hardest kind to notice because a plausible-looking line hides a missing one.

What changed

pingLossSentence() in engine/simulator.js counts the lost echoes by the reason already recorded, and hands them to dropsSentence() — the N drops (reasons) phrasing show interfaces has used since #1417, lifted out of cli.js into the engine so the two callers reach one function instead of two copies:

% Echoes lost: 4 drops (peer port shut (R1 Gi0/0/0) x4)
% Echoes lost: 1 drop (no ARP reply from 10.91.0.10)

Longest reason first, xN for a repeat, reasons past the third counted rather than hidden, and a reason carrying its own brackets (ACL 101 denied (in)) quoted — a reason printed inside the summary's brackets nests for a reader and closes the list early for a parser, which is what #1417 fixed one layer up.

The browser's Simulate dialog draws the same sentence from a mirror of the rule, next to the success rate.

Three deliberate silences, each a rule rather than an omission:

  • converging is not loss — a settling path keeps its own % Still converging: stp on s1 (ready at 30000 ms) and gets no loss line, no 0%;
  • no reason, no sentence — a failure the engine cannot attribute prints nothing beyond the timeout line; inventing a cause to look complete is the defect;
  • one line per command, not per echo — four lost echoes are one statement about the path, so the count lives in the sentence.

Evidence

test/ping-loss-reason.test.js, 32 checks:

with the fix:    32 passed, 0 failed
fix stashed:      7 passed, 25 failed   (naming the bare-timeout console output)

It covers: the reason appears verbatim and after the per-echo lines in the console's % voice; a four-echo failure produces one line and still four timeout lines; a shut port is named with its brackets quoted; a device with no address at all explains itself; a converged path gets no loss line; a reasonless failure and a blank reason invent nothing; show interfaces still reaches the phrasing through one function (asserted against the source, so a copy would fail); and the console and browser agree on ten cases including bracketed reasons, five distinct reasons, mixed success/loss, converging and empty.

Docs: docs/CLI.md new ### Why an echo never came back (before/after transcripts, the phrasing rules, the three silences); docs/ARCHITECTURE.md new ### The command that knew why and said "timed out".

Adding the helpers moved three citations in the docs by 41 lines — ethFrame(), openFlow(), _deliver() — so the numbers were moved with the code and now land exactly on the definitions their sentences name; npm run check:citations is back to its single documented false positive.

Full suite: 239 suites, 8880 assertions, 0 failed. Syntax 308 files OK.

## The symptom `ping` is the first command anyone types in a lab, and the one that most often fails. On a lab where the router's port is shut: ``` r1> ping 10.0.0.10 1 Type escape sequence to abort. Sending 1, 100-byte ICMP Echos to 10.0.0.10, timeout is 2 seconds: . Success rate is 0 percent (0/1) Request timed out (seq 0) ``` That is everything the console says. This is everything the engine knew, and returned: ``` replies: [{ seq: 0, success: false, reason: "peer port shut (R1 Gi0/0/0)" }] ``` `Simulator.ping()` has recorded a reason for every lost echo since #1431 ranked the causes by earliness — `no route to 10.0.0.99`, `no ARP reply from 10.91.0.10`, `peer port shut (R1 Gi0/0/0)`, `ACL 101 denied (in)`. `_pingReplyLines()` printed the timeout and threw the reason away. So the most-used command in the simulator answered *something went wrong* to the question *what went wrong* — for exactly the beginner mistakes a simulator exists to teach: no address, no route, cable down, VLAN not allowed. ## What was actually wrong Not a missing fact. A missing **sentence**. The engine computed the reason, carried it in the answer, and the surface that a person reads dropped it. Same species as #1475 (the packet log printing `flow-close` instead of which flow ended) and #1473 (one ARP row where two boxes had answered): the model was right and the translation layer was silent, which is the hardest kind to notice because a plausible-looking line hides a missing one. ## What changed `pingLossSentence()` in `engine/simulator.js` counts the lost echoes by the reason already recorded, and hands them to `dropsSentence()` — the `N drops (reasons)` phrasing `show interfaces` has used since #1417, lifted out of `cli.js` into the engine so the two callers reach **one function instead of two copies**: ``` % Echoes lost: 4 drops (peer port shut (R1 Gi0/0/0) x4) % Echoes lost: 1 drop (no ARP reply from 10.91.0.10) ``` Longest reason first, `xN` for a repeat, reasons past the third counted rather than hidden, and a reason carrying its own brackets (`ACL 101 denied (in)`) quoted — a reason printed inside the summary's brackets nests for a reader and closes the list early for a parser, which is what #1417 fixed one layer up. The browser's Simulate dialog draws the same sentence from a mirror of the rule, next to the success rate. Three deliberate silences, each a rule rather than an omission: * **converging is not loss** — a settling path keeps its own `% Still converging: stp on s1 (ready at 30000 ms)` and gets no loss line, no `0%`; * **no reason, no sentence** — a failure the engine cannot attribute prints nothing beyond the timeout line; inventing a cause to look complete is the defect; * **one line per command, not per echo** — four lost echoes are one statement about the path, so the count lives in the sentence. ## Evidence `test/ping-loss-reason.test.js`, 32 checks: ``` with the fix: 32 passed, 0 failed fix stashed: 7 passed, 25 failed (naming the bare-timeout console output) ``` It covers: the reason appears verbatim and after the per-echo lines in the console's `%` voice; a four-echo failure produces one line and still four timeout lines; a shut port is named with its brackets quoted; a device with no address at all explains itself; a converged path gets no loss line; a reasonless failure and a blank reason invent nothing; `show interfaces` still reaches the phrasing through one function (asserted against the source, so a copy would fail); and the console and browser agree on ten cases including bracketed reasons, five distinct reasons, mixed success/loss, converging and empty. Docs: `docs/CLI.md` new `### Why an echo never came back` (before/after transcripts, the phrasing rules, the three silences); `docs/ARCHITECTURE.md` new `### The command that knew why and said "timed out"`. Adding the helpers moved three citations in the docs by 41 lines — `ethFrame()`, `openFlow()`, `_deliver()` — so the numbers were moved with the code and now land exactly on the definitions their sentences name; `npm run check:citations` is back to its single documented false positive. Full suite: 239 suites, 8880 assertions, 0 failed. Syntax 308 files OK.
The command that knew why and said "timed out" (#1483)
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 12s
CI / Test (Node 20) (pull_request) Successful in 3m6s
CI / Test (Node 18) (pull_request) Successful in 3m18s
CI / Server smoke test (pull_request) Successful in 35s
CI / Docker build (pull_request) Successful in 44s
CI / Test (Node 22) (pull_request) Successful in 3m0s
5e2059f573
ping is the first command anyone types and the one that most often fails.
Simulator.ping() has recorded a reason for every lost echo since #1431 ranked
the causes by earliness - "no route to 10.0.0.99", "no ARP reply from
10.91.0.10", "peer port shut (R1 Gi0/0/0)", "ACL 101 denied (in)" - and
_pingReplyLines() printed "Request timed out (seq 0)" and threw it away. The
most-used command in the simulator answered "something went wrong" to the
question "what went wrong", for exactly the mistakes a simulator exists to
teach.

Not a missing fact but a missing sentence, the same species as #1475 (the log
printing a bare event type) and #1473 (one ARP row where two boxes answered).

  * engine/simulator.js: pingLossSentence() counts lost echoes by the reason
    already recorded and hands them to dropsSentence() - the "N drops
    (reasons)" phrasing show interfaces has used since #1417, lifted out of
    cli.js into the engine so both callers reach one function, not two copies.
    Longest reason first, xN for repeats, reasons past the third counted, and
    a reason carrying its own brackets quoted so the list stays one level deep;
  * engine/cli.js: the console prints it after the per-echo lines, in its own
    "% " voice; _dropSummary() now delegates to dropsSentence();
  * web/app.js: the Simulate dialog draws the same sentence from a mirror,
    beside the success rate;
  * three deliberate silences: converging is not loss (it keeps its own
    sentence and gets no zero percent), a failure with no recorded reason
    prints nothing extra rather than inventing a cause, and four lost echoes
    are one statement about the path rather than four.

test/ping-loss-reason.test.js: 32 checks. With the fix 32/0; with it stashed
7 passed, 25 failed, naming the bare-timeout output. Covers the reason verbatim
and its position, a four-echo failure producing one line and four timeouts, a
shut port named with brackets quoted, a device with no address, converging
excluded, reasonless and blank reasons inventing nothing, show interfaces
reaching the phrasing through one function (asserted against the source, so a
copy fails), and the console and browser agreeing on ten cases.

Adding the helpers moved ethFrame(), openFlow() and _deliver() 41 lines down,
so the three citations that name them moved with the code and now land on the
definitions themselves; npm run check:citations is back to its single
documented false positive.

Docs: docs/CLI.md "Why an echo never came back", docs/ARCHITECTURE.md "The
command that knew why and said 'timed out'".

Suite 239 suites, 8880 assertions, 0 failed. Syntax 308 files OK.
jaylouisw force-pushed fix/ping-says-why from 5e2059f573
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 12s
CI / Test (Node 20) (pull_request) Successful in 3m6s
CI / Test (Node 18) (pull_request) Successful in 3m18s
CI / Server smoke test (pull_request) Successful in 35s
CI / Docker build (pull_request) Successful in 44s
CI / Test (Node 22) (pull_request) Successful in 3m0s
to b27ac789d2
All checks were successful
CI / Classify the change (pull_request) Successful in 10s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 13s
CI / Test (Node 18) (pull_request) Successful in 3m12s
CI / Test (Node 20) (pull_request) Successful in 3m1s
CI / Server smoke test (pull_request) Successful in 25s
CI / Docker build (pull_request) Successful in 44s
CI / Test (Node 22) (pull_request) Successful in 3m4s
2026-11-12 04:59:31 +00:00
Compare
jaylouisw force-pushed fix/ping-says-why from b27ac789d2
All checks were successful
CI / Classify the change (pull_request) Successful in 10s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 13s
CI / Test (Node 18) (pull_request) Successful in 3m12s
CI / Test (Node 20) (pull_request) Successful in 3m1s
CI / Server smoke test (pull_request) Successful in 25s
CI / Docker build (pull_request) Successful in 44s
CI / Test (Node 22) (pull_request) Successful in 3m4s
to c28b1d4ccd
All checks were successful
CI / Classify the change (pull_request) Successful in 14s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 14s
CI / Test (Node 18) (pull_request) Successful in 3m21s
CI / Test (Node 20) (pull_request) Successful in 3m6s
CI / Server smoke test (pull_request) Successful in 25s
CI / Docker build (pull_request) Successful in 49s
CI / Test (Node 22) (pull_request) Successful in 3m8s
2026-11-12 05:00:04 +00:00
Compare
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-12 05:01:50 +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!1486
No description provided.