The log named a mechanism instead of saying what happened #1476

Merged
jaylouisw merged 1 commit from fix/event-legend into main 2026-11-12 04:11:50 +00:00
Owner

What was wrong

The packet log is the panel whose job is to explain what happened to a frame. Seventeen of the fifty-four event types the engine emits had no legend line, so they fell through to default: return e.type and the row read:

garp
vrrp
tap-inject-refused
flow-refused

Not an error, not a blank — a row that names a mechanism instead of saying what happened, in the one place a learner goes to find out. One of the seventeen was added the day before (the arp-conflict event in #1473), which is what made the cause obvious: nothing connected the engine's event vocabulary to the legend, so a new _emit({ type: … }) was silently a new bare token.

emitted types: 54      legend cases: 37      with no line: 17
arp-conflict  bgp-session  flow-close  flow-data  flow-open  flow-refused
flow-reset  forward  garp  lldp  nat-drop  nat-inbound  nat-outbound
split  tap  tap-inject-refused  vrrp

What changed

  • All seventeen get a sentence carrying the numbers and addresses the event actually has: a flow names both ends and its number, a VRRP election names the winner and the priority, a NAT refusal names the translation that failed, LLDP names who was discovered and on which port.
  • A case may only read fields its event carries. A sentence written against a remembered payload prints undefined in the panel meant to explain things, so the test reads each emit site's field list from the engine source and compares. It caught one immediately: flow-reset read e.proto, which that event does not carry — a reset is TCP by definition.
  • Duplicate addresses, NAT drops, refused tap injections and refused flows join the existing drop colour class instead of passing as ordinary chatter.
  • tap-inject-refused now carries a reason on the wire, so the log can say why the frame was not re-injected instead of only that it wasn't.
  • The legend is exposed as __pf.describeEvent, the same way the rest of the UI is exposed for tests.

The test that makes it stop happening

test/event-legend.test.js enumerates the vocabulary from engine/ rather than from a hand-written list: every _emit({ type: … }) and events.push({ type: … }) must have a case, no case may describe an event the engine no longer emits, no type may be described twice, and every real emit-site payload must render as a sentence rather than its bare type.

$ node test/event-legend.test.js                     # 54 event types, 105 emit sites
18 passed, 0 failed

$ git stash push web/app.js engine/simulator.js && node test/event-legend.test.js
8 passed, 10 failed     # and it names all seventeen missing types

The general rule, worth stating once: a view may not display a token it cannot explain. If the engine can emit it, the panel says what it means — and the connection between the two is a test, not a habit.

Neighbours green: ui-render 38, ui-dom-contract 19, ui-action-failures 13, arp-conflict 26, runtime-agreement 10, report-sweep 21. Syntax 304 files OK. Full suite: 236 suites, 8827 assertions, 0 failed.

Reviewer note: the describeEvent switch is a closure inside web/app.js, so the test loads the real file in a stub DOM exactly as test/ui-render.test.js does and reads the legend through window.__pf. Nothing in the test restates the vocabulary — delete a legend case and it names the type.

## What was wrong The packet log is the panel whose job is to explain what happened to a frame. Seventeen of the fifty-four event types the engine emits had no legend line, so they fell through to `default: return e.type` and the row read: ``` garp vrrp tap-inject-refused flow-refused ``` Not an error, not a blank — a row that names a mechanism instead of saying what happened, in the one place a learner goes to find out. One of the seventeen was added the day before (the `arp-conflict` event in #1473), which is what made the cause obvious: nothing connected the engine's event vocabulary to the legend, so a new `_emit({ type: … })` was silently a new bare token. ``` emitted types: 54 legend cases: 37 with no line: 17 arp-conflict bgp-session flow-close flow-data flow-open flow-refused flow-reset forward garp lldp nat-drop nat-inbound nat-outbound split tap tap-inject-refused vrrp ``` ## What changed - All seventeen get a sentence carrying the numbers and addresses the event actually has: a flow names both ends and its number, a VRRP election names the winner and the priority, a NAT refusal names the translation that failed, LLDP names who was discovered and on which port. - **A case may only read fields its event carries.** A sentence written against a remembered payload prints `undefined` in the panel meant to explain things, so the test reads each emit site's field list from the engine source and compares. It caught one immediately: `flow-reset` read `e.proto`, which that event does not carry — a reset is TCP by definition. - Duplicate addresses, NAT drops, refused tap injections and refused flows join the existing `drop` colour class instead of passing as ordinary chatter. - `tap-inject-refused` now carries a `reason` on the wire, so the log can say why the frame was not re-injected instead of only that it wasn't. - The legend is exposed as `__pf.describeEvent`, the same way the rest of the UI is exposed for tests. ## The test that makes it stop happening `test/event-legend.test.js` enumerates the vocabulary from `engine/` rather than from a hand-written list: every `_emit({ type: … })` and `events.push({ type: … })` must have a case, no case may describe an event the engine no longer emits, no type may be described twice, and every real emit-site payload must render as a sentence rather than its bare type. ``` $ node test/event-legend.test.js # 54 event types, 105 emit sites 18 passed, 0 failed $ git stash push web/app.js engine/simulator.js && node test/event-legend.test.js 8 passed, 10 failed # and it names all seventeen missing types ``` The general rule, worth stating once: **a view may not display a token it cannot explain.** If the engine can emit it, the panel says what it means — and the connection between the two is a test, not a habit. Neighbours green: `ui-render` 38, `ui-dom-contract` 19, `ui-action-failures` 13, `arp-conflict` 26, `runtime-agreement` 10, `report-sweep` 21. Syntax 304 files OK. Full suite: 236 suites, 8827 assertions, 0 failed. Reviewer note: the `describeEvent` switch is a closure inside `web/app.js`, so the test loads the real file in a stub DOM exactly as `test/ui-render.test.js` does and reads the legend through `window.__pf`. Nothing in the test restates the vocabulary — delete a legend case and it names the type.
The log named a mechanism instead of saying what happened (#1475)
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 10s
CI / Test (Node 20) (pull_request) Successful in 3m5s
CI / Test (Node 18) (pull_request) Successful in 3m18s
CI / Server smoke test (pull_request) Successful in 26s
CI / Docker build (pull_request) Successful in 51s
CI / Test (Node 22) (pull_request) Successful in 3m5s
edd262cbd4
The packet log renders every simulation event through one switch, and a type
it did not know fell through to `default: return e.type` - so the row read
`flow-refused`, or `vrrp`, or `tap`. Not an error, not a blank: a row that
names a mechanism instead of saying what happened, in the one place a learner
goes to find out. Seventeen of the fifty-four event types were in that state,
including the `arp-conflict` event added the day before, which is what showed
the cause: nothing connected the engine's event vocabulary to the legend, so a
new `_emit({ type: ... })` was silently a new bare token.

  * app.js: a sentence for all seventeen, carrying what each event really has -
    a flow names both ends and its number, a VRRP election names the winner and
    the priority, a NAT refusal names the translation that failed, LLDP names
    who was discovered and on which port. A case may only read fields its event
    carries (the test reads each emit site's field list from the engine source,
    which caught flow-reset reading e.proto it does not have). Duplicate
    addresses, NAT drops, refused tap injections and refused flows join the
    existing drop colour class instead of passing as ordinary chatter. The
    legend is exposed as __pf.describeEvent, as the rest of the UI already is;
  * simulator.js: tap-inject-refused carries the reason it was refused, so the
    log can say why rather than only that it was;
  * test/event-legend.test.js: the vocabulary is enumerated from engine/, not
    from a hand-written list - every _emit and events.push must have a case, no
    case may outlive its event, none described twice, and every real emit-site
    payload must render as a sentence. 18 checks; reverting app.js fails 10 and
    names all seventeen.

A view may not display a token it cannot explain: if the engine can emit it,
the panel says what it means, and the connection between them is a test rather
than a habit.

Neighbours green: ui-render 38, ui-dom-contract 19, ui-action-failures 13,
arp-conflict 26, runtime-agreement 10, report-sweep 21. Syntax 304 files OK.
Suite 236 suites, 8827 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-12 04:11:46 +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!1476
No description provided.