Put the coherent transceiver on real fiber

Every coherent example was back to back, so the impairment that dominates
any real span had never been in the loop. Measured: 5 km of ordinary fiber
costs 20 dB of SNR, and at 80 km 3698 of 3968 symbols are wrong — 93%,
against the 93.75% that blind guessing gives on 16-QAM. Not degraded, gone.

DispersionCompensator is one static all-pass filter on the received
baseband. It calls the fiber's own propagator with a negated distance
rather than writing the inverse transfer function out, because two copies
of a beta2 sign only stay equal until someone edits one of them. Spans
from 5 km to 1000 km return to back-to-back EVM with no penalty that grows
with distance, which is the whole argument for coherent detection: an
all-pass phase removes nothing, so a receiver that measures the field
still holds all of it.

Parametrised by accumulated D*L in ps/nm, not by D and length. A receiver
cannot know how the span was built and two links with the same total
behave identically; asking for both would invent a distinction that does
not exist on that side of the fiber.

Kept separate from the butterfly equaliser, and that ordering is measured
rather than quoted: on the dual-pol link over 80 km, growing the butterfly
from 7 taps to 65 leaves EVM at 2941% against 3030%, while the static
block ahead of a 7-tap filter restores 2.67%. A blind modulus criterion
has no gradient to follow once the constellation is a Gaussian blob.

Seven sabotages, seven caught: compensation sign, hardcoded wavelength,
ps/nm conversion off by 1000x, parameter ignored, compensation skipped,
I/Q swapped, symbol rate dropped from dispersive_spread.

README: the front page claimed equalisers and coherent detection were not
implemented, months after both landed. Corrected, along with the roadmap
and four new validation rows.

Mockup: regenerated from the new export, so the demonstrated link now runs
over the span too. Two defects found by rebuilding against real output —
the sensitivity sweep's 256-QAM curve never crossed the FEC threshold and
so was the one curve with no label, and the sweep overrode only one of the
two mappers. 17 blocks, 22 links, 33 components, contrast clean in both
grounds across all four dock tabs.

517 tests.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: ehsun-sh

DESIGN.md

@@ -79,7 +79,9 @@ edit time is meaningless if the types are invisible.
 The shown project is chosen so that **all five types appear on the canvas at
 once**. That is why it is a coherent link rather than an on-off-keyed one: only
 a coherent chain carries binary into symbols, symbols into two electrical
-drives, an optical field, two photocurrents back, and symbols out again.
+drives, an optical field, two photocurrents back, and symbols out again. It runs
+over 80 km of real fibre, because a simulator whose demonstration link has no
+fibre in it is showing the wrong thing.
 
 Accent is `--optical`, because the tool is an optical simulator. Semantic colour
 (`--good` / `--warn` / `--bad`) is kept separate from it and does not count as
@@ -124,6 +126,13 @@ the action taken dozens of times an hour.
 sized by the dock's *height*, not its width. A shorter dock wastes the width it
 has.
 
+**The canvas viewBox is 1000 x 420**, seven columns of 138px at a node width of
+116. The seventh column arrived with the span and its compensator; the
+alternative was to keep six and squeeze the spacing to 120, which leaves four
+pixels between adjacent blocks and reads as cramped. Widening also moved the
+aspect ratio to 2.38, closer to the 2.29 the canvas region actually has at
+1440px than the 2.10 it had before.
+
 Below 940px the palette and inspector collapse and a note says so. This is a
 desktop tool; the real build would dock them as overlays rather than dropping
 them, and the note says that too rather than pretending the narrow layout is the
@@ -174,6 +183,10 @@ found engine defects that the test suite missed:
   zero** however bad the link was, because that block emits decisions. The
   mockup now carries two analysers — soft measurement before the decoder, error
   count after — which is also how a bench does it.
+- The sensitivity sweep's 256-QAM curve **never crossed the FEC threshold** in
+  the swept range, so it was the one curve with no label — quietly contradicting
+  the rule in section 6 that each is labelled where it crosses. The range now
+  extends far enough that all four cross.
 
 ---
 
@@ -225,7 +238,8 @@ Two findings worth keeping:
 - The mockup shows a single-carrier link. The dual-polarization link is in
   [`examples/dualpol_link.py`](examples/dualpol_link.py) and is not on the
   canvas: at ~20 blocks the node text stops being readable at this canvas size,
-  and a schematic nobody can read is not a better demonstration.
+  and a schematic nobody can read is not a better demonstration. At 17 blocks
+  the current graph is already close to that ceiling.
 - No motion beyond the run pulse and the control transitions.
 - No empty, loading or error states — there is no session server yet to produce
   them.

README.md

@@ -13,9 +13,11 @@
 >
 > Two complete links run end to end and produce numbers that match theory.
 > **Direct detection:** PRBS → NRZ → CW laser → MZM → fiber (loss + dispersion) → PIN → filter →
-> eye/Q/BER. **Coherent:** PRBS → Gray-coded M-QAM → RRC shaping → IQ modulator → 90° hybrid with
-> balanced detection → carrier recovery → EVM/SNR and counted errors, up to 256-QAM, and dual
-> polarization at 256 Gb/s with a blind butterfly equaliser.
+> eye/Q/BER. **Coherent:** PRBS → Gray-coded M-QAM → RRC shaping → IQ modulator → **fiber** →
+> 90° hybrid with balanced detection → dispersion compensation → carrier recovery → EVM/SNR and
+> counted errors, up to 256-QAM, and dual polarization at 256 Gb/s with a blind butterfly
+> equaliser. The coherent chain now runs over a real span: 1000 km of fiber leaves nothing
+> recoverable at the photodiode, and the receiver returns it to back-to-back quality.
 > Every physics block is validated against a closed-form result in CI.
 >
 > Projects save to versioned JSON and sweeps are first-class, so a curve is one call rather than
@@ -26,7 +28,7 @@
 > realisation with the right Maxwellian statistics.
 >
 > **Not implemented yet:** cross-phase modulation and four-wave mixing between channels,
-> equalisers, coherent detection, and the GUI. See the [roadmap](#roadmap).
+> wavelength-selective filtering, and the GUI. See the [roadmap](#roadmap).
 >
 > This is not yet a useful simulator. It is a foundation with the expensive decisions made and
 > tested. Criticism of those decisions is worth more right now than any feature —
@@ -146,6 +148,59 @@ subtracting a constant or a line, and it puts a ceiling on SNR that no power bud
 search of Pfau et al. Both halves of that claim are [asserted](tests/test_dsp.py) — the second
 would be meaningless without the first.
 
+### Reaching past the bench
+
+Every coherent example above was back to back. `python examples/dispersion_link.py` puts the same
+32 GBd 16-QAM link through real fiber, with loss and nonlinearity switched off so that chromatic
+dispersion is the only thing acting:
+
+```
+            accumulated   spread          uncompensated              compensated
+  span          [ps/nm]  [symbols]      EVM       SNR    errors      EVM       SNR
+       0 km          0       0.0      1.68%    35.51 dB      0/3968     1.68%    35.51 dB
+       5 km         85       0.8     17.04%    15.37 dB      5/3968     1.67%    35.52 dB
+      20 km        340       3.3    217.64%    -6.75 dB   3336/3968     1.67%    35.56 dB
+      80 km       1360      13.4   2542.45%   -28.11 dB   3698/3968     1.68%    35.52 dB
+     400 km       6800      67.0   2686.86%   -28.58 dB   3692/3968     1.67%    35.55 dB
+    1000 km      17000     167.4   3390.48%   -30.61 dB   3697/3968     1.68%    35.51 dB
+```
+
+Read the uncompensated column first, because it is the reason this block exists. **Five kilometres
+— a metro hop — costs twenty decibels.** At 80 km the link is not degraded, it is gone: 3698 of
+3968 symbols wrong is 93%, and blind guessing on 16-QAM gives 93.75%. The whole coherent phase had
+been validated without ever meeting the impairment that dominates every real span.
+
+The compensated column is the argument for coherent detection in one line. **Back-to-back quality
+at every distance, with no penalty that grows with it.** Dispersion is an all-pass phase — it
+rearranges the field in time and removes nothing — so a receiver that measures the field still
+holds all of it, and one static filter puts it back. That is not error correction; it is inverting
+an invertible operation. A direct-detection receiver squares the field at the photodiode, destroys
+the phase, and can never do this at all, which is why it has to carry dispersion-compensating fiber
+in the line instead.
+
+The setting is sharp, and that is worth seeing rather than being told:
+
+| compensator set to | error | EVM | SNR |
+| ---: | ---: | ---: | ---: |
+| 76 km | −68 ps/nm | 13.64% | 17.30 dB |
+| 79 km | −17 ps/nm | 3.78% | 28.46 dB |
+| **80 km** | **0** | **1.68%** | **35.52 dB** |
+| 81 km | +17 ps/nm | 3.77% | 28.47 dB |
+| 84 km | +68 ps/nm | 13.64% | 17.30 dB |
+
+Being one kilometre out costs 7 dB. The symmetry of those flanks is also the sign check: a
+compensator applying its correction the wrong way round would put the nominal setting at *twice*
+the span, and the two sides would not match to three digits.
+
+**Why this is a separate stage from the butterfly equaliser.** Both are linear filters, so one
+adaptive filter could in principle do both jobs. It does not work. On the dual-polarization link
+over 80 km, growing the butterfly from 7 taps to 65 — the longest the block allows, and nine times
+the cost — leaves the link just as dead, because a blind modulus criterion has no gradient to
+follow once the constellation is smeared into a Gaussian blob. The static block ahead of a 7-tap
+filter restores back-to-back quality outright. Dispersion is static and *long*; polarization
+mixing is fast and *short*; one filter serving both would have to be both, which is the worst of
+each. That ordering is [asserted](tests/test_cd_compensation.py), not quoted.
+
 ### Dual polarization
 
 `python examples/dualpol_link.py` puts two independent 16-QAM tributaries on orthogonal
@@ -359,8 +414,8 @@ time window, and results are reproducible.
 | **0 — Foundations** ✅ | Signal model, context, port types, component base, registry, scheduler, `.oosim` project format, sweeps, CI | ~1 month |
 | **1 — MVP: linear link** *(essentially done)* | ✅ PRBS → NRZ → laser → MZM → fiber (α + CD) → PIN → filter → eye/Q/BER, validated end to end. **Python only, no GUI.** | ~2–3 months |
 | **1.5 — Nonlinear & amplified** ✅ | Adaptive-step SSFM, Kerr, EDFA with ASE, OSNR, PMD, APD | ~2 months |
-| **2 — Coherent transceiver** ✅ | Gray-coded M-QAM to 256, IQ modulator with bias and quadrature error, 90° hybrid, balanced detection, blind carrier phase recovery, dual polarization with a blind butterfly equaliser, root-raised-cosine shaping and matched filtering, differential quadrant encoding, EVM/MER, constellation diagram, validated against closed-form SER | ~3 months |
-| **3 — GUI & WDM** | Session server, React Flow graph editor, OSA · DWDM + XPM/FWM crosstalk, 400G/800G references, CuPy back-end | ~6 months |
+| **2 — Coherent transceiver** ✅ | Gray-coded M-QAM to 256, IQ modulator with bias and quadrature error, 90° hybrid, balanced detection, blind carrier phase recovery, dual polarization with a blind butterfly equaliser, root-raised-cosine shaping and matched filtering, differential quadrant encoding, receiver-side dispersion compensation over spans to 1000 km, EVM/MER, constellation diagram, validated against closed-form SER | ~3 months |
+| **3 — GUI & WDM** | Session server, React Flow graph editor, wavelength-selective filters and an OSA · DWDM + XPM/FWM crosstalk, 400G/800G references, CuPy back-end | ~6 months |
 | **4 — PIC** | Waveguides, ring resonators, MMI, MZI via integration with an existing S-matrix solver; PDK import | — |
 
 ¹ One developer, part-time. Estimates, not commitments.
@@ -383,6 +438,10 @@ Every physics block ships with a test against a closed-form result, run in CI
 | Gaussian pulse, CD only | `T₁/T₀ = √(1 + (z/L_D)²)`, `L_D = T₀²/\|β₂\|` | ✅ |
 | Chirped Gaussian | `T₁/T₀ = √((1 + Cβ₂z/T₀²)² + (β₂z/T₀²)²)` — pins the sign of β₂ | ✅ |
 | Dispersion compensation | `+D` then `−D` restores the input sample-for-sample | ✅ |
+| Receiver-side CD removal | Compensator is the propagator inverted; round trip exact to 1e-9 | ✅ |
+| CD compensation is all-pass | Energy conserved; a wrong sign lands exactly on twice the span | ✅ |
+| β₂ ∝ λ² | Compensating 1550 nm as 1310 nm leaves the predicted `1 − λ₁²/λ₂²` residual | ✅ |
+| **Span recovery** | 5 km to 1000 km return to back-to-back EVM; uncompensated 80 km is at chance | ✅ |
 | GVD | Energy conserved (Parseval); β₂ = −Dλ²/2πc per band | ✅ |
 | PRBS | Period `2ⁿ−1`; `2ⁿ⁻¹` marks; every n-bit window appears once | ✅ |
 | Ideal push-pull MZM | `P_out/P_in = cos²(πV / 2V_π)`; null depth equals the declared ER | ✅ |