Active optical networks and auto-design from an address list #8

Merged
jaylouisw merged 1 commit from feat/auto-design into main 2026-11-17 09:21:40 +00:00
Owner

What this changes

Adds active optical networks and an auto-design engine, which is what issue #6 asks for: a list of
addresses plus a head-end in, a sized topology and its runs out.

  • transceiver part kind — 5 optics (1000BASE-LX/ZX, 10GBASE-LR/ER, 25GBASE-LR) with launch
    power, sensitivity, overload, wavelength, reach.
  • budget.pointToPoint — an active link budgeted against the optic pair's launch − sensitivity
    instead of a PON class, with a separate reach check. The passive-loss maths is now shared with the
    PON path (computeOdn) so the two definitions cannot drift.
  • headend node type — an active plant's root. trace, validate, capacity and
    designForOnt key off the root's technology.
  • engine/demand.js — CSV/JSON demand with per-row rejection, dedupe, and no empty-cell→0 trap.
  • engine/design.js — PON per splitter ratio, active-over-a-tree, active home-run; validated,
    budgeted per ONT, costed, ranked, every rejection explained.
  • API + UI — POST /api/design/synthesise (with one-undo applyToProject),
    POST /api/import/demand, and an Auto-design panel that shows the comparison and applies the winner.

Why the objective is fibre-metres

Cable is priced roughly with its fibre count. Ranking by plain metres made a fat tree look cheap and
picked the wrong topology on any street longer than a few hundred metres. fibreMetres is the default
metric, cableM is reported alongside it, and a costs model switches the objective to money — and
the response says which objective it used.

Three defects the feature exposed (fixed here)

  1. capacity() multiplied the ratio of every splitter in the plant, so six 1:8 sites read as
    1:262144 and refused a good PON design. It now walks the tree and takes the deepest single path.
  2. cableFor returned the first cable in the (richest-first) ladder that fit, so every two-fibre
    branch was designed on 144-fibre cable.
  3. The feeder tree passed through splitter nodes, charging three splitter losses on the way to the
    third site. Each splitter site now has its own closure with the splitter on a 1 m tail.

How it was verified

npm test                    # 16 suites, 141 assertions, 0 failed
node scripts/smoke-http.js  # all checks passed
node scripts/audit-parts.js # 37 parts validate

Plus the real UI driven end to end in a browser: 24 addresses pasted, comparison rendered
("pon wins: 26987.7 fibre-metres"), applied to the project → 49 nodes / 48 spans, validation clean,
capacity 24 / 1024 ONTs, cascade 1:8.

A worked comparison on a 2 km street of 40 houses:

topology cable m fibre-m feasible
PON 1:8, 6 sites 4423.9 37221.8 yes
PON 1:16, 3 sites 4426.9 44786.3 yes
active tree, 1G-LX 2569.7 147657.8 yes
active tree, 10G-LR 2569.7 147657.8 no — 39 splices eat its 6.2 dB budget
active home-run 52273.8 621232.6 yes

What it deliberately does not do

Street/duct routing (straight-line × routeFactor, stated in every response — issue #7), geocoding
(no outbound requests), and active-equipment sizing (an active plant reports ports: null rather than
inventing a ceiling).

Checklist

  • One logical change (this is the active-network + auto-design slice, one PR)
  • No new runtime dependency
  • Tests for the success and the refusal in every new module
  • Counts regenerated (node scripts/count-parts.js) — 37 parts across 8 kinds
  • npm test green locally on Node 24; CI will confirm 18/20/22

Closes #6

## What this changes Adds active optical networks and an auto-design engine, which is what issue #6 asks for: a list of addresses plus a head-end in, a sized topology and its runs out. - **`transceiver` part kind** — 5 optics (1000BASE-LX/ZX, 10GBASE-LR/ER, 25GBASE-LR) with launch power, sensitivity, overload, wavelength, reach. - **`budget.pointToPoint`** — an active link budgeted against the optic pair's `launch − sensitivity` instead of a PON class, with a separate reach check. The passive-loss maths is now shared with the PON path (`computeOdn`) so the two definitions cannot drift. - **`headend` node type** — an active plant's root. `trace`, `validate`, `capacity` and `designForOnt` key off the root's technology. - **`engine/demand.js`** — CSV/JSON demand with per-row rejection, dedupe, and no empty-cell→0 trap. - **`engine/design.js`** — PON per splitter ratio, active-over-a-tree, active home-run; validated, budgeted per ONT, costed, ranked, every rejection explained. - **API + UI** — `POST /api/design/synthesise` (with one-undo `applyToProject`), `POST /api/import/demand`, and an Auto-design panel that shows the comparison and applies the winner. ## Why the objective is fibre-metres Cable is priced roughly with its fibre count. Ranking by plain metres made a fat tree look cheap and picked the wrong topology on any street longer than a few hundred metres. `fibreMetres` is the default metric, `cableM` is reported alongside it, and a `costs` model switches the objective to money — and the response says which objective it used. ## Three defects the feature exposed (fixed here) 1. `capacity()` multiplied the ratio of **every** splitter in the plant, so six 1:8 sites read as 1:262144 and refused a good PON design. It now walks the tree and takes the deepest single path. 2. `cableFor` returned the first cable in the (richest-first) ladder that fit, so every two-fibre branch was designed on 144-fibre cable. 3. The feeder tree passed **through** splitter nodes, charging three splitter losses on the way to the third site. Each splitter site now has its own closure with the splitter on a 1 m tail. ## How it was verified ``` npm test # 16 suites, 141 assertions, 0 failed node scripts/smoke-http.js # all checks passed node scripts/audit-parts.js # 37 parts validate ``` Plus the real UI driven end to end in a browser: 24 addresses pasted, comparison rendered ("pon wins: 26987.7 fibre-metres"), applied to the project → 49 nodes / 48 spans, validation clean, capacity `24 / 1024 ONTs, cascade 1:8`. A worked comparison on a 2 km street of 40 houses: | topology | cable m | fibre-m | feasible | |---|---|---|---| | PON 1:8, 6 sites | 4423.9 | 37221.8 | yes | | PON 1:16, 3 sites | 4426.9 | 44786.3 | yes | | active tree, 1G-LX | 2569.7 | 147657.8 | yes | | active tree, 10G-LR | 2569.7 | 147657.8 | **no** — 39 splices eat its 6.2 dB budget | | active home-run | 52273.8 | 621232.6 | yes | ## What it deliberately does not do Street/duct routing (straight-line × `routeFactor`, stated in every response — issue #7), geocoding (no outbound requests), and active-equipment sizing (an active plant reports `ports: null` rather than inventing a ceiling). ## Checklist - [x] One logical change (this is the active-network + auto-design slice, one PR) - [x] No new runtime dependency - [x] Tests for the success **and** the refusal in every new module - [x] Counts regenerated (`node scripts/count-parts.js`) — 37 parts across 8 kinds - [x] `npm test` green locally on Node 24; CI will confirm 18/20/22 Closes #6
feat: active optical networks and auto-design from an address list
All checks were successful
CI / Test (Node 18) (pull_request) Successful in 40s
CI / Test (Node 20) (pull_request) Successful in 48s
CI / Server smoke test (pull_request) Successful in 48s
CI / Test (Node 22) (pull_request) Successful in 51s
CI / Docker build (pull_request) Successful in 1m3s
4fab2b27ca
Glassforge planned a PON and nothing else. It now plans active optical networks, and it can
design a topology itself: give it a list of addresses and a head-end and it builds the
candidates, budgets every one, and ranks them.

Added:
- transceiver part kind (5 optics: 1000BASE-LX/ZX, 10GBASE-LR/ER, 25GBASE-LR) with launch
  power, sensitivity, overload, wavelength and reach.
- budget.pointToPoint: an active link budgeted between two optics. Same passive-loss model as
  the PON path (extracted as computeOdn, so the two cannot drift), second verdict is
  launch(min) - sensitivity, plus a reach check, overload detection and a refusal when the
  ends disagree on rate or wavelength.
- headend node type: the root of an active plant. trace/validate/capacity/designForOnt key off
  the root's technology; a PON may not carry a transceiver at the customer end, an active
  plant may not contain a splitter.
- engine/demand.js: CSV/JSON demand with header aliases, per-row rejection, dedupe, and no
  empty-cell-to-latitude-0.
- engine/design.js: PON per splitter ratio (cluster -> feeder tree -> tapered distribution
  tree), active-over-a-tree, active home-run. Deterministic, costed in cable metres,
  fibre-metres and drums, ranked with the reason for every rejection.
- POST /api/design/synthesise (optional applyToProject, one undo step) and POST
  /api/import/demand; UI Auto-design panel with the comparison table and rationale.
- docs/AUTO-DESIGN.md; SPEC/API/PARTS/README/CHANGELOG updated.

Fixed on the way, all three found by driving real designs:
- capacity() multiplied the ratio of EVERY splitter in the plant, so six 1:8 sites read as
  1:262144 and refused a good PON. It now takes the deepest single path.
- cableFor returned the first (richest) cable that fit, so every 2-fibre branch was designed
  on 144F cable. It now returns the smallest cable that carries the demand.
- the feeder tree passed through splitter nodes, charging three splitter losses on the way to
  the third site. Each site now has its own closure with the splitter on a 1 m tail.

16 suites / 141 assertions green; smoke and the live UI driven end to end.

Closes #6
jaylouisw deleted branch feat/auto-design 2026-11-17 09:21:42 +00:00
Sign in to join this conversation.
No reviewers
No labels
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/glassforge!8
No description provided.