# FreeRouting → Python porting plan

> Seed document. The routing agent expands this after studying the upstream
> Java source. Treat sections marked _(TBD from source study)_ as the first
> research deliverable.

## Ground truth: study the source

Port from the **actual FreeRouting Java source**, not from the Specctra spec
alone. The algorithm details (rip-up-and-retry ordering, cost functions,
45°/free-angle geometry, autoroute vs. optimize passes) live in the code.

```bash
# Cloned into ./reference (gitignored — we don't vendor GPL source into history)
git clone --depth 1 https://github.com/freerouting/freerouting reference/freerouting
```

Key upstream packages to map first (verify paths against the clone):

- `app/freerouting/designforms/specctra/` — DSN/SES read/write. This is the
  I/O boundary we must match byte-compatibly enough for `kicad-cli` to import.
- `app/freerouting/autoroute/` — the maze/rip-up router core.
- `app/freerouting/board/` — the routing board data model (items, traces, vias,
  nets, clearance matrix).
- `app/freerouting/geometry/planar/` — points, lines, tile shapes, the
  45°/free-angle geometry primitives.

## The contract (fixed)

Input: Specctra `.dsn`. Output: Specctra `.ses`. `kicad-cli pcb export
specctra-dsn` produces the input; `kicad-cli pcb import specctra-ses` consumes
the output. Match that I/O and the rest of `kicad-mcp` is unchanged.

## Phased roadmap

1. **DSN parser** — tokenize + parse the S-expression DSN into a typed board
   model (layers, components, padstacks, nets, keepouts, rules/clearances).
   First concrete, fully-testable module. Round-trip fixtures from `kicad-cli`.
2. **SES writer** — emit a minimal valid session file KiCad imports cleanly,
   starting with an empty/no-op route to prove the I/O loop end to end.
3. **Board model + geometry** — planar primitives and the item/net/clearance
   model the router operates on. _(TBD from source study.)_
4. **Autorouter core** — maze routing with rip-up-and-retry. Start grid-based
   Manhattan/45° for an MVP; converge toward FreeRouting's approach. _(TBD.)_
5. **Optimize pass** — via minimization, trace smoothing. _(TBD.)_
6. **CLI + kicad-mcp integration** — `freeroute board.dsn -o board.ses`, then
   swap it in behind `kicad_mcp/utils/freerouting_engine.py`'s JAR step.

## Validation strategy

For any `.dsn`, FreeRouting's JAR gives a reference `.ses`. Diff our output
against it (connectivity first — every ratsnest resolved — then geometry).
The JVM stays available as an oracle during development even though the
shipped product has no Java dependency.

## Conventions

`uv` for everything, src-layout, ruff, pytest. Author: Ryan Malloy. Keep
modules small and single-purpose. Tests alongside every parser/writer from
the first commit.