audit(devices): 33 fibre devices read as copper, and no job ran the audit #2301

Merged
jaylouisw merged 2 commits from catalogue/1120-1852 into main 2026-11-20 19:08:34 +00:00
Owner

Does not close #130 or #803 — the two open device requests are blocked on their vendors, exactly as their threads record, and nothing here touches devices/.

docs/plans/catalogue-audit-agreement.md, steps 1-6. Two audits asked one question and answered it differently: scripts/audit-devices.js counted an optical cage with its own OPTICAL_CAGES = ['sfp','sfp+','sfp28','qsfp+','qsfp28'] at :16, while test/hardware-invariants.test.js kept a longer list of its own. engine/media.js already classifies every cage, and neither read it.

Its answer was 33, and the true answer was 0.

devices only cages present why the old list missed it
28 sc-apc / sc-upc — GPON ONT/ONU PON cages are not in the five-name list
3 fc-sfp28, fc-sfpdd, fc-qsfp28 — brocade/g720, dell/ds-6630b, hpe/sn3600b Fibre Channel cages are not in it either
2 rj45 only — watchguard/firebox-m290, microsemi/syncserver-s600 prose says "no SFP cages as shipped", then names an optional module the bay would take

The five names are the Ethernet cages. A Brocade SAN switch modelled with fc-sfpdd cages and a GPON ONT modelled with sc-apc are both fibre-ended; the list called every one of them copper, and the two module-bay descriptions are correct documentation of what ships.

What this does.

  1. engine/media.js: isOpticalCage(cage) — true for family optical (SFP through CFP2, and the SC/LC PON connectors) or fibre-channel (fc-sfp, fc-sfp28, fc-sfpdd, fc-qsfp28). combo is deliberately not optical: one cage position holding either an RJ45 or an SFP, and copper until a module is fitted.
  2. scripts/audit-devices.js: uses that predicate; strips the optional/unfitted-module clause before reading a claim; splits behind require.main so test/ can ask it anything; exports auditCatalog() and claimsOptics().
  3. One prose rule, not two: test/hardware-invariants.test.js imports claimsOptics and isOpticalCage instead of carrying a private copy of each. The denial strip now runs before the clause split — SFP: none was being split at the colon into a bare SFP and a dropped none.
  4. test/audit-agreement.test.js (11 checks): the three shapes that were wrong, the control that must still be caught (24-port 1G switch with 4 x 10G SFP+ uplinks over 24 RJ45 ports), and the catalogue-wide agreement between the audit's answer and the invariant's.
  5. package.json + docs/CI.md: audit:devices joins the test chain — a file CHANGELOG.md has advertised since it was written and no job ran. Measured 0.43 s. The file is kept, not deleted.
  6. Both verdicts name what they gated and what they only reported, so a green exit is not read as "nothing was found".

Measured.

node scripts/audit-devices.js    before: 33 optics findings   after: 0
                                 exit 0, "Gated: 0 hard defect(s). Reported, not gated: 0 ..."
node test/hardware-invariants.test.js        26 passed, 0 failed
node test/audit-agreement.test.js            11 passed, 0 failed
node scripts/audit-port-types.js             exit 0 — "Gated: 0 port(s) contradict their declared type.
                                             Reported, not gated: 2,704 port(s) (2,704 template
                                             port(s) whose connector nothing declares, 0 fibre port(s)
                                             drawn as copper)"
node scripts/run-tests.js                    413 suites, 13,685 assertions, 0 failed
node scripts/syntax-check.js                 493 files, all OK
node scripts/check-doc-citations.js          361 citations, no judged citation >40 lines from its code

No spec under devices/ changed and no engine rule changed a verdict: the one new export reads the table engine/media.js already owns. test/hardware-invariants.test.js gains a control-flow note above the one skip whose condition is now a named predicate (isOptical( is what test/skip-audit.test.js looks for), because the check is scoped to fibre cages by construction rather than exempting a device.

Does not close #130 or #803 — the two open device requests are blocked on their vendors, exactly as their threads record, and nothing here touches `devices/`. `docs/plans/catalogue-audit-agreement.md`, steps 1-6. Two audits asked one question and answered it differently: `scripts/audit-devices.js` counted an optical cage with its own `OPTICAL_CAGES = ['sfp','sfp+','sfp28','qsfp+','qsfp28']` at `:16`, while `test/hardware-invariants.test.js` kept a longer list of its own. `engine/media.js` already classifies every cage, and neither read it. **Its answer was 33, and the true answer was 0.** | devices | only cages present | why the old list missed it | |---|---|---| | 28 | `sc-apc` / `sc-upc` — GPON ONT/ONU | PON cages are not in the five-name list | | 3 | `fc-sfp28`, `fc-sfpdd`, `fc-qsfp28` — `brocade/g720`, `dell/ds-6630b`, `hpe/sn3600b` | Fibre Channel cages are not in it either | | 2 | `rj45` only — `watchguard/firebox-m290`, `microsemi/syncserver-s600` | prose says "no SFP cages **as shipped**", then names an optional module the bay would take | The five names are the Ethernet cages. A Brocade SAN switch modelled with `fc-sfpdd` cages and a GPON ONT modelled with `sc-apc` are both fibre-ended; the list called every one of them copper, and the two module-bay descriptions are correct documentation of what ships. **What this does.** 1. `engine/media.js`: `isOpticalCage(cage)` — true for family `optical` (SFP through CFP2, and the SC/LC PON connectors) or `fibre-channel` (`fc-sfp`, `fc-sfp28`, `fc-sfpdd`, `fc-qsfp28`). `combo` is deliberately **not** optical: one cage position holding either an RJ45 or an SFP, and copper until a module is fitted. 2. `scripts/audit-devices.js`: uses that predicate; strips the optional/unfitted-module clause before reading a claim; splits behind `require.main` so `test/` can ask it anything; exports `auditCatalog()` and `claimsOptics()`. 3. One prose rule, not two: `test/hardware-invariants.test.js` imports `claimsOptics` and `isOpticalCage` instead of carrying a private copy of each. The denial strip now runs **before** the clause split — `SFP: none` was being split at the colon into a bare `SFP` and a dropped `none`. 4. `test/audit-agreement.test.js` (11 checks): the three shapes that were wrong, the control that must still be caught (`24-port 1G switch with 4 x 10G SFP+ uplinks` over 24 RJ45 ports), and the catalogue-wide agreement between the audit's answer and the invariant's. 5. `package.json` + `docs/CI.md`: `audit:devices` joins the test chain — a file `CHANGELOG.md` has advertised since it was written and no job ran. Measured 0.43 s. The file is kept, not deleted. 6. Both verdicts name what they gated and what they only reported, so a green exit is not read as "nothing was found". **Measured.** ``` node scripts/audit-devices.js before: 33 optics findings after: 0 exit 0, "Gated: 0 hard defect(s). Reported, not gated: 0 ..." node test/hardware-invariants.test.js 26 passed, 0 failed node test/audit-agreement.test.js 11 passed, 0 failed node scripts/audit-port-types.js exit 0 — "Gated: 0 port(s) contradict their declared type. Reported, not gated: 2,704 port(s) (2,704 template port(s) whose connector nothing declares, 0 fibre port(s) drawn as copper)" node scripts/run-tests.js 413 suites, 13,685 assertions, 0 failed node scripts/syntax-check.js 493 files, all OK node scripts/check-doc-citations.js 361 citations, no judged citation >40 lines from its code ``` No spec under `devices/` changed and no engine rule changed a verdict: the one new export reads the table `engine/media.js` already owns. `test/hardware-invariants.test.js` gains a control-flow note above the one skip whose condition is now a named predicate (`isOptical(` is what `test/skip-audit.test.js` looks for), because the check is scoped to fibre cages by construction rather than exempting a device.
audit(devices): 33 fibre devices read as copper, and no job ran the audit
Some checks failed
CI / Classify the change (pull_request) Successful in 18s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 15s
CI / Arm auto-merge (pull_request) Has been cancelled
CI / Test (Node 22) (pull_request) Has been cancelled
CI / Server smoke and Docker build (pull_request) Has been cancelled
CI / Test (Node 20) (pull_request) Has been cancelled
CI / Test (Node 18) (pull_request) Has been cancelled
a8f261b5c0
scripts/audit-devices.js answered "does this description promise optics the ports
cannot deliver?" from its own OPTICAL_CAGES = ['sfp','sfp+','sfp28','qsfp+','qsfp28'].
Every Fibre Channel cage and every PON connector fell outside that list, so
brocade/g720, dell/ds-6630b and hpe/sn3600b (fc-sfpdd/fc-sfp28/fc-qsfp28) and 28
GPON ONTs on sc-apc read as copper: 33 findings, none of them a defect, against 0
from the invariant that gates the same rule.

- engine/media.js: isOpticalCage(cage), true for the 'optical' and 'fibre-channel'
  families in the cage table the engine already cables from. Both audits call it.
- scripts/audit-devices.js: uses it; strips the optional/unfitted-module clause
  before reading a claim (the denial strip now runs before the clause split, since
  "SFP: none" was split at the colon into a bare "SFP"); require.main guard;
  exports auditCatalog()/claimsOptics(); 33 -> 2 -> 0.
- test/hardware-invariants.test.js: imports the same claimsOptics and isOpticalCage
  instead of keeping a private copy and a private list. Same 26 checks, same answers.
- test/audit-agreement.test.js: 11 checks - the three shapes that were wrong, the
  control that must still be caught, and the catalogue-wide agreement (0 vs 0).
- package.json: audit:devices in the test chain (0.43 s) and as an npm script;
  docs/CI.md names it instead of leaving it a documented tool no job ran.
- audit-devices and audit-port-types verdicts name what they gated and what they
  only reported ("Gated: 0 ... Reported, not gated: 2,704").

Closes no issue: docs/plans/catalogue-audit-agreement.md, steps 1-6.
docs(plans): the catalogue-audit plan names the pull request that landed it (#2301)
All checks were successful
CI / Classify the change (pull_request) Successful in 16s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 12s
CI / Test (Node 18) (pull_request) Successful in 58s
CI / Test (Node 22) (pull_request) Successful in 55s
CI / Test (Node 20) (pull_request) Successful in 56s
CI / Server smoke and Docker build (pull_request) Successful in 18s
CI / Arm auto-merge (pull_request) Successful in 4s
d7d2bc5d7a
forgejo-actions scheduled this pull request to auto merge when all checks succeed 2026-11-20 19:06:40 +00:00
jaylouisw deleted branch catalogue/1120-1852 2026-11-20 19:08:37 +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!2301
No description provided.