soldermaskdocs

Layout and principles

soldermask/
  design.py  schema.py  priors.py        the model: prompt -> design. Five backends (claude-code, gemini,
                                          claude, groq, mercury), SOLDERMASK_BACKEND to choose; the default,
                                          claude-code, runs Claude Code headless on its own login with three
                                          of the MCP server's tools (search_parts, pins, check_design) and is
                                          the only backend whose schema lets a component carry `lcsc`
  __main__.py                             `python -m soldermask`, which is cli.main()
  wire.py                                 the second turn, opt-in (`--wire` on the command line and the
                                          evaluator; the app and the claude-code backend do not run it): the
                                          parts as ordered and their real pin names in front of the model,
                                          the nets against those
  resolve.py parts.py packages.py         parts against the catalogue, footprints;
                                          resolve.declare/pinout/addressable go the other way,
                                          from a chosen catalogue row to a design line and its pins
  jlcparts.py params.py                   the parts dataset read off disk; the parametric index
  jlcapi.py                               JLCPCB's own parts data through its signed open API: lookup by
                                          code, the library paged, the whole of it as a snapshot (the
                                          dump, then a detail record a code -- the parameters); the
                                          catalogue jlcparts.py reads, written from that snapshot in the
                                          mirror's own format by ingest() (`setup --parts`); the
                                          authority stock and price are reconciled against
  orderability.py                         can this board still be ordered?
  symbols.py easyeda.py alternates.py     KiCad symbols (fetched by setup: fetch_library), vendor
                                          footprints, substitutes
  eeformat.py                             EasyEDA's own format read -- pads, silk, pins, the 3D
                                          model's uuid and offset -- in place of easyeda2kicad (AGPL);
                                          a polygon pad keeps its outline (packages.Pad.poly), which
                                          the clearance, ERC and fab checks measure and the .kicad_pcb
                                          (a custom pad) and the Gerbers (a region) draw
  datasheets.py jev.py                    the sheet itself: fetched from the listing's link, read by
                                          pdftotext, its pin table transcribed once by the design stage's
                                          model; its names laid on the vendor's symbol (with_sheet_names),
                                          the two compared pin by pin -- a swap holds the pad back from
                                          wiring -- and a refused pin name looked up through it, last of
                                          all by Jev (a closed-question model, optional, taken at its floor)
  componentlib.py                         the component library: facts read once from 97 parts'
                                          datasheets (assets/components/<LCSC>.json), each with its
                                          page, a verbatim quote and an audit status; applied() hands
                                          out verified items only. designcheck.py (so every build's
                                          ERC), conditions.py and grade.py read it;
                                          tools/component_library.py writes and audits it.
                                          get() reads the shipped record first, then one the reader
                                          wrote into <cache>/components/
  datasheet_reader.py                     the datasheet read on demand, opt-in
                                          (SOLDERMASK_DATASHEET_READER=azure): the packet, read A
                                          (DeepSeek-V4.1-Flash, the full record, search/page tools)
                                          and read B (gpt-5.4, external parts, page images) at once,
                                          merged one item a part; read C (gpt-5.4-mini on the drawings
                                          at 300 dpi, off unless SOLDERMASK_READER_DRAW), a second
                                          reading of figure values only; the two rules that held on pilot 3's
                                          held-out half (module_internal, figure_agreement), the audit, stored in
                                          the cache with its provenance and every answer; reread() rebuilds a
                                          record from the stored answers; a per-read spend guard
                                          (SOLDERMASK_READER_MAX_USD). Called only by mcp.py's
                                          read_datasheet and `soldermask parts read`, never by a build
  erc.py  electrical.py                    electrical rule check; IPC-2221 and Ohm's law
  designcheck.py                          what the parts' datasheets and the buses between them
                                          require, as ERC rules: a pin over its absolute maximum
                                          (component library), an enable tied off, a USB-C sink
                                          with no Rd, an I2C line with no pull-up are errors;
                                          crystal load caps, the sheet's bypass and program parts
                                          and a fixed regulator's rail are warnings. Since 7 Nov:
                                          a motor supply with no bulk and an LED that cannot conduct
                                          are errors; bulk under a figure (driver, strip, servo), a
                                          dim LED, a crystal resistor on XIN, an ESP32 EN with no
                                          RC, an audio corner over 20 Hz and SWD without NRST are
                                          warnings, each citing its source. Since 8 Nov a diode wired
                                          backwards is an error (diode-direction) and one wired by bare
                                          pad numbers a warning (diode-pins). Also warnings: a rail outside
                                          a pin's recommended range (supply-range), a USB-C's CC pins on one
                                          shared pull-down (usb-c-cc-shared), an Rd that is not 5.1k
                                          (usb-c-rd). The rule names are the Violation kinds in
                                          designcheck.py. power_tree()
                                          reads each rail's source and loads back for check_design.
                                          Does not import grade.py, so the grader stays outside
  spice.py                                 the circuit switched on in ngspice before it is placed; sim.json for the scope.
                                          A World (sources behind leads, stepping loads, corners, LEDs lit
                                          through the pins that drive them) changes the deck for conditions.py
  conditions.py                           the board under the conditions it will meet, read off the design:
                                          plugged in through a lead, loads stepping, a cell draining, parts at
                                          their tolerance corners, an audio sweep; held to the library's and
                                          the catalogue's limits. Report only, a proof (8 Oct 2026). A build
                                          runs one piece of it: designcheck's audio-corner rule sweeps an
                                          audio coupling cap with conditions.audio() inside every build's
                                          ERC (since 8 Nov 2026); run(), the whole set, no build calls
  rubric.py                               the reviewer's rules graded on every board built and said as
                                          notes; the lines and the pro reference are assets/rubric.json
  roles.py physics.py                     each part's job read off its wiring (bypass cap and the pins it
                                          serves, a switcher's switch node, input and output caps and
                                          divider, a crystal and its load caps, an ESD part and the
                                          connector lines it guards, a USB or CAN pair), and what the
                                          placement and the copper make of it in physical units: loop
                                          inductance by Neumann's integral with a plane's return as its
                                          image, switch-node copper, pair skew and impedance; review()
                                          says, on every build, each check worse than three in four of
                                          people's boards (assets/physics.json) and stores board["physics"]
  layout_rules.py                         the datasheet's own layout rules (assets/layout_rules.json: quote,
                                          page, sheet, limit and where the limit is from) checked on every
                                          build: per-pin decoupling, a switcher's input cap, the exposed
                                          pad's vias or its no-solder policy, a via-free cap path.
                                          Advisory: notes, board["layout_rules"], verdict["layout_rules"];
                                          never verdict.passed. tools/layout_rules_check.py builds the store
  fabrules.py                             JLCPCB's published table (read 24 Sep 2026) checked on every
                                          board built: below-minimum / extra-cost / risk, the assembly
                                          service it needs; board["fab_rules"], gaps and notes
  placer.py dsn.py ses.py                 placement on either side of the board, antenna keepouts, the edge a design names for a part (edge_goal), the areas a design asks to keep clear and a board read from a file's own outline, holes and copper kept clear (board_zones), the anneal watched frame by frame; the Specctra DSN each version stores and the session reader (freerouting, retired from the build, reads and writes them for the research tools)
  mounting.py                             the mounting holes a design asks for (constraints.board.mounting_holes): one non-plated hole of no part a corner and a keepout ring round it, placed again when the board is sized; read off a prompt by from_prompt
  keepout.py                              copper kept out from under a connector's body (kind `connector`, or a USB,
                                          card-socket or DC-jack package by name) on the side it is mounted on: the
                                          body less a cut from each of its own pads to the body's edge; the DSN's
                                          keepouts, the .kicad_pcb's rule areas (which the A* router reads) and the
                                          pour's stitching vias all ask it -- and a power corridor's, which a
                                          router's netlist carries (Netlist.power_keepouts), and each area the
                                          design asks to keep clear (constraints.keepouts -> Netlist.keepouts,
                                          asked()), one a copper layer, refusing pads and pour as well
  anneal_terms.py blocks.py               what the anneal pays for past wirelength; functional blocks
  filegeom.py                             what a board's KiCad file draws besides its pads, as the router must
                                          see it: copper no pad owns, mask openings (owned by the one net whose
                                          pads they expose), a dropped footprint's copper, and the outline's
                                          edges; kicadpcb.read puts them on Netlist.obstacles and .outline, each
                                          shape and hole ending with the part whose footprint draws it, and
                                          router.problem keeps copper clear of them and inside the outline --
                                          a part's own moved with it, the rest only while every part is at
                                          Netlist.file_pose (router.carried, router.file_geometry_held);
                                          router.fixed_held() says which of the file's fixed geometry holds on a placement (all of it wherever no pad sits on it); fab_art() is the file's outline and exact copper and mask art as the
                                          fab files draw them (text read as a `box` for the router, not drawn);
                                          fab_holes() is every non-plated hole the board is drilled with
                                          (Package.holes and the file's, as the router meets them), which
                                          kicad.write, the NPTH drill file, the mask, board.json and the
                                          fab rules all draw from
  router.py                               Lightcycle, the build's default router and this tree's own (`lightcycle`): every net routed at
                                          once by negotiated congestion (PathFinder) on a fine grid, the rule
                                          held exactly at every cell -- the search is the `lightcycle` wheel's
                                          `route_board` (soldermask-org/lightcycle, pinned as
                                          LIGHTCYCLE, installed by `soldermask setup`);
                                          this builds the problem and reads the copper back as a ses.Routing;
                                          `violations()` measures that copper with nothing the search shares
  pairs.py                                differential pairs laid as pairs on the route a board ships
                                          with: the middle routed as one wide net, offset into two
                                          tracks, the two nets joined again (router._lay_pairs); each
                                          pair's row, laid or left as routed and why, rides the route
                                          pour.judge keeps (PourOutcome.pairs) and restate() puts the
                                          kept route's notes on the board; on four layers the middle
                                          goes on F.Cu, and on In2.Cu too with SOLDERMASK_PAIRS_IN2 (off).
                                          A pair left as routed can have its room negotiated with the
                                          board, routed again as one wide net (router._negotiate_pairs,
                                          SOLDERMASK_PAIRS_NEGOTIATE=1, off by default)
  widen.py                                a thin route grown back toward each net's width where the
                                          board has room (shared a step a round, shoulders on a free
                                          side), and the copper judged for heat: each narrow run's
                                          rise, the lesser of IPC-2221 and its conduction into the
                                          copper at its ends (`runs`), read by the verdict
  tandem.py                               placing and routing in one loop: every candidate routed by
                                          Lightcycle at once and ranked by what it did, and, where none
                                          reached every pin, three fresh anneals routed and ranked with
                                          them (the build does this when Lightcycle routes, the default;
                                          SOLDERMASK_TANDEM=0 stands it down); repair() grows the router's
                                          hot parts and re-anneals their neighbourhood, the instrument
                                          that lost to those fresh anneals, and the build does not call it
  abstract.py                             a board said at the size of its ideas: blocks round their anchors,
                                          the links between them, the rails, the router's hot spots -- as a few
                                          lines of text and back
  astar.py pour.py fillet.py              the A* router: first by name (constraints.rules.router `krt`,
                                          or SOLDERMASK_ROUTER), and the board's router whenever
                                          Lightcycle is not installed or cannot run it, with a gap saying
                                          so (workspace._route_once); the ground plane -- and a local
                                          one-layer zone for each high-current rail above it in
                                          priority, its pads accounted one by one, poured from the
                                          start on request (Netlist.power_pour, SOLDERMASK_POWER_POUR)
                                          and, by default, as a second build of a board whose copper
                                          alone failed, the build with fewer copper failures kept
                                          (workspace.POWER_FALLBACK, SOLDERMASK_POWER_FALLBACK=0 turns it
                                          off); tracks and rounded corners
  escape.py                               escape stubs: a straight track out of each pad the
                                          router's grid cannot end on, laid before each placement is
                                          routed. On by default (SOLDERMASK_ESCAPE=0 turns them off),
                                          and laid only on a board Lightcycle routes first: the A*
                                          router finds its own way out, and astar.refuses() does not
                                          count a stub as hand copper
  planes.py                               a four-layer board (constraints.board.layers): by default
                                          F.Cu signal, In1.Cu ground plane, In2.Cu signal, B.Cu signal
                                          (MODE "gnd"); SOLDERMASK_PLANES=gnd+power makes In2.Cu the
                                          busiest rail's plane. Which net each inner layer is (assign),
                                          the layers a router is handed (signal_layers), and what the
                                          notes say of it; the pour fills the planes, every surface pad
                                          of a plane net gets a via beside it first (pour.ground_sites)
  corridor.py                             a poured rail's zone as a corridor from its source to its
                                          loads (SOLDERMASK_POWER_SHAPE / Netlist.power_shape `tree`
                                          or `mould`; `hull` is pour.py's and the default): the source
                                          by pin name, switch, series part or connector, each load's
                                          current, a Steiner tree or physarum.rail()'s tubes sized
                                          leg by leg, rastered, clipped and traced to polygons, and
                                          the keepout every other net's router is handed; the layer
                                          that strands no pad without room for a stitching via first
  prune.py                                copper that joins nothing -- a via reaching its net on one
                                          layer or none, a track end touching nothing of its net --
                                          taken off the board pour.judge keeps, and kept off only if
                                          KiCad, refilled, loses no connection
  fold.py physarum.py                     a placement as a chord diagram; a slime mould routing it --
                                          set up, loop, read out; the loop runs in mould/ when it is built;
                                          rail() grows one power rail alone for corridor.py
  congestion.py corpus.py routability.py  the placer's picture of the board; every route kept; the model
  precedent.py                            what each corpus board is, and the one most like this design as a seed
  genome.py                               a placed board as one 64-bit word a part, exact to 0.1um, so a
                                          corpus unpacks into model columns with a shift and a mask
  gnn.py                                  the graph judge: message passing over genome.graph, with or without
                                          the mould's and the fold's readings; fit in torch, run in numpy
  learn.py                                `soldermask learn`
  gerber.py assembly.py                   Gerbers, drill, BOM, CPL
  silk.py                                 a part's silkscreen drawing -- the vendor's own, or drawn from the
                                          pads and body -- and where it lands; the Gerber, the .kicad_pcb and
                                          board.json all ask it, so they carry one drawing
  silkfont.py isofont.py insignia.py      the stroke font; ISO 3098 outlines; the maker's mark
  kicad.py kicadcli.py models3d.py        .kicad_pcb, kicad-cli DRC/render/ERC/netlist, vendor 3D models
  sheet.py kicad_sch.py                   the schematic sheet laid out (roles, flow, ports, labels, wires,
                                          text) and stored on the board; the .kicad_sch written from it
                                          and read back for what it connects
  kicadpcb.py                             a finished KiCad board read back as one to place and route;
                                          repair_imported() gives kicad-cli's imports their net table
  inventory.py                            stock and price at several quantities
  repair.py evaluate.py                   the repair loop; pass@1 on this task; the verdict as a poll (repair.poll)
  grade.py                                the model index's second judge: a finished board held against
                                          what its prompt asked, clause by clause, from the parts as
                                          ordered (catalogue row first, then the part's datasheet record
                                          before a clause is called unknown); pass, fail or unknown; declared
                                          or silent; board_from_kicad reads another tool's .kicad_pcb and
                                          BOM into the same Board (pinfunction names, rail voltages from
                                          net names); eight checks every board owes (powered, grounded,
                                          transistors, leds, diodes, floating, dissipation, shorted); MCU helpers
                                          (crystal, USB-C, native USB, strapping, isolation); mutants()
  copperjudge.py                          the copper half of that judge, from any tool's .kicad_pcb: layers
                                          the stack has and carries; whether fast pairs run coupled and
                                          matched; whether the path a stated current takes carries it (the
                                          net as a resistor network, solved, each run and via held to the
                                          verdict's heat limit). Used by the hard held-out tasks
  export.py render.py viewer.py           board.json, board.svg, the standalone viewer
  projects.py workspace.py diff.py        versions on disk and the project bundle; the one build sequence; design diffs
  edits.py                                a scoped edit, applied to what is already there
  platforms.py stackup.py                 the MCUs a board is built around; what it is made of
  version.py release.py config.py         the app's version; releases; where things live
  cli.py style.py skeleton.py             the command line; its colour, and the picture a
                                          terminal can show (inline image or braille); the
                                          board's skeleton drawn from board.json for that
  mcp.py                                  the pipeline as an MCP tool server: every stage ours or the
                                          caller's, one judge, no model call of its own (it sets
                                          config.model_calls() off; --model-calls lifts it) except
                                          read_datasheet under SOLDERMASK_DATASHEET_READER=azure; JSON-RPC
                                          on stdin/stdout, by hand; SOLDERMASK_MCP_LOG, a line a call
  tables.py                               a catalogue answer -- search rows, a pinout -- as lines a
                                          model reads for half the tokens of the JSON, and back
  gnm.py                                  a board's state as gnm text (a line a part, a line a net) and back:
                                          the token census's encoder, and place/score_placement/build
                                          answered in lines with the placement as gnm, and read as one
                                          (not genome.py, which is bits for a corpus)
  mcp_http.py                             the same server over Streamable HTTP for a client that is
                                          not on this machine: bearer keys (digests on disk), a
                                          projects directory a key, one build slot at a time, the
                                          precedent's placement withheld under a non-permissive
                                          licence; nothing ships
  app/
    __init__.py  serve(), the Flask factory, headers, compression; server_wrapper(), the ASGI app
                                          serve() hands Hypercorn, which holds every body to BODY_MAX
                                          (8 MB) but lets POST /api/projects/import carry a project zip up
                                          to api.BUNDLE_UPLOAD_MAX (256 MB) for a request that already
                                          carries the token, the login cookie or a trusted local client
    api.py pages.py                        the JSON API; the HTML pages
    benchmarks.py                          what /benchmarks reads off disk; it computes nothing
    jobs.py bus.py turns.py auth.py       background builds; the event bus (progress and the placing's frames are transient on it); a turn; access control
    templates/  static/                    Jinja pages; workbench.js, schematic.js, projects.js (the home:
                                          ledger, disc, foot), platforms.js (the MCU token), mesh.js (the
                                          vendor 3D models' wire format, decoded for the workbench and the
                                          standalone export), partcloud.js (the selected part as a point
                                          cloud in the details panel), benchmarks.js (/benchmarks), and the
                                          stylesheets (tokens.css under all of them, workbench.css,
                                          projects.css and platforms.css for the home, benchmarks.css,
                                          instrument.css for About and the project cards); vendor/
                                          (three.min.js and GLTFLoader.js, fetched by tools/fetch_three.py;
                                          fonts.css and the files it names: the three faces, tokens.css and
                                          tests/test_fonts.py say which is set in what)
mould/                                    the compiled cores (soldermask_mould): the mould's inner loop in
                                          Rust, the same loop as physarum.py's numpy, a lane a net, a thread a
                                          window, numpy carries it when it is not built; and the
                                          placer's anneal (src/anneal.rs), placer.anneal()'s loop draw for
                                          draw -- CPython's random stream, CPython's hypot, the cost summed
                                          in local()'s order -- so a seed places the same on either. The
                                          compiled anneal runs by default wherever the core is built
                                          (SOLDERMASK_ANNEAL `auto`; `python` forces the reference, `rust`
                                          makes a missing core an error); `pip install ./mould`
docs/  mkdocs.yml                          this manual; MkDocs builds it for the app's /docs
paper/                                    the write-ups: isonet.tex and mendicant.tex with their PDFs;
                                          fig/ is drawn by tools/paper_figures.py from .cache's JSON
landing/                                  the public site (Vercel, vercel.json): static pages, scripts and
                                          images, and the Python that writes their data from the tree --
                                          board.py (the hero board), art.py and golfcu.py (the PCBGolf
                                          entry's pictures and copper), shots.py (the app's screenshots,
                                          from a real build through the app into .cache/landing-shots/),
                                          about.py and retro.py (charts from the corpus and git), intro.py
                                          (the wordmark as a video)
.github/workflows/tests.yml               CI: tests/run.py on Python 3.11, 3.12 and 3.13 with the symbol
                                          library fetched and the mould built, Lightcycle installed only
                                          when a LIGHTCYCLE_TOKEN secret is set, then the mould's tests
                                          again on the numpy loop
pypi-name/                                a metadata-only release that holds the name `soldermask` on
                                          public PyPI; it installs no code
serve.py                                  `python serve.py` is `soldermask serve`, kept for old habits
build_backend.py                          setuptools, plus a copy of the top-level priors_blocks.json and
                                          priors_zener.json into soldermask/assets/ so a wheel carries them
mine_blocks.py import_footprints.py       the block miners (priors_blocks.json) and the footprint import
                                          (assets/footprints.json); see tests.md's Other tools
solderdocs/                             the same manual public at solderdocs.shwinnie.com: Fumadocs
                                        (Next.js, static export); scripts/sync-docs.mjs turns docs/
                                        into its content before every build, so the two cannot drift
bench/                                  the public routing and placement bench, started 26 Sep 2026:
                                          referee.py judges a routed or placed board against its task
                                          with kicad-cli and the standard library alone -- nothing from
                                          soldermask, which tests/test_referee.py holds -- taking only the
                                          entry's copper (or, on the placement track, where its parts
                                          went, turned over or not, read off their pads) onto the task,
                                          counting open connections apart from rule errors, and
                                          counting a rule error only when the entry's copper is in
                                          it, or, for a solder mask bridge, when the bare task lacks
                                          it (referee 0.3, 30 Sep 2026; it forgave only what the bare
                                          task's DRC reported, which KiCad 10.0.6 varies run to run);
                                          and a third track, `referee.py board` (12 Nov 2026), which judges
                                          any tool's whole board with no task: every connection made and
                                          no rule error, overlapping courtyards and a footprint's own
                                          drawing counted and not failed, its multilayer rules on a board
                                          of four layers or more;
                                          tasks.py makes tasks: a part's keepouts bound into its footprint
                                          so they move with it, and an author's board as a routing task
                                          (copper stripped, rewritten by kicad-cli, the canary stamped);
                                          index/tasks/ (27 Sep 2026) the model index's task specs, one
                                          file a prompt: its clauses asked-for and implied, and a check
                                          over soldermask/grade.py's Board; all 60 of the evaluator's prompts;
                                          review_template.html, the engineer review page's template
                                          (the held-out tasks live outside this repo, in
                                          ../soldermask-heldout, so no session here tunes on them)
tests/  tools/  deploy/                    the suite; snap.py, backfill_models.py, annotate_boards.py,
                                          enclosure.py (a two-part case for a built board, base and lid
                                          as STEP and STL with windows, holes and screw tabs, run in its
                                          own build123d venv, .cache/cad-venv),
                                          footprint_holes.py (the imported footprints' non-plated holes, and
                                          with --pads their pads, drills and slots as this pipeline's reader
                                          reads them, recovered from a source whose pads match, into
                                          assets/footprints.json),
                                          exa_boards.py, org_boards.py, fetch_kicad.py and kicad_boards.py
                                          (the board bank: found by question or by vendor, fetched over
                                          git, converted from Eagle/Altium/legacy through kicad-cli, kept;
                                          `--layers 4,6` fills the multilayer bank beside the two-layer one),
                                          graph_corpus.py and gnn_train.py (the corpus as graphs; the graph judge),
                                          pic.py, pic_place.py, pic_perturb.py, pic_report.py (a photonic
                                          chip read, placed by the channel fold, and judged by LiDAR);
                                        place_bench.py (the placer against the board's author, the
                                          literature's protocol: placed on the same outline, routed as traces
                                          by A* and freerouting, judged by kicad-cli, paired per board, placer
                                          variants as arms; suites `cypress` and `bank`) and azure_bench.py
                                          (its arms sharded onto rented machines and collected home);
                                        azure_build.py (one big Azure machine that builds as the laptop
                                          does: up, push the tree, caches and Lightcycle at its pinned tag,
                                          sync the code alone, ssh, get, status, down; for replay A/Bs and
                                          the speed work);
                                        antenna_ab.py (the placer's antenna-keepout term on and off, under
                                          the old search and the new, on a drive's own antenna boards: every
                                          anneal checked for copper in a zone, each board built as the drive
                                          built it, no model);
                                        physics_census.py (physics.report() on the replay's builds and on
                                          people's two-layer boards, author copper and placement, and the
                                          author's placement against the affinity census's anneals of the
                                          same netlist; fills by kicad-cli into .cache/physics_census/);
                                        affinity_census.py (the author's placement against one anneal of the
                                          same board, pair by pair in thirteen netlist roles -- decap, ESD,
                                          fine-pitch ring, edge and the rest -- each read past the board's own
                                          wirelength ratio; rows keep the anneal's placement);
                                        escape_oracle.py (the author's own escape copper on a fine-pitch
                                          board, walked out from the pads 1 or 3 mm and handed to A* as copper
                                          it may not move, against the bare board on the author's placement:
                                          the ceiling of an escape policy before one is trained; `_pour` arms
                                          pour ground as the product does, `ret` hands it escape_policy's);
                                        escape_data.py (every fine-pitch pad's escape in the bank as its author
                                          drew it, in the part's own frame, with where its net goes and a DRC
                                          flag; split by repository, the gate's repositories held out and their
                                          forks excluded; .cache/escape_data/);
                                        escape_policy.py (the first escape learner: another author's fan-out
                                          for the same package off the train split, matched on the whole pad
                                          layout at four turns and chosen for where this board's nets go;
                                          `self-test` scores it against held-out authors);
                                        escape_geom.py (an escape as a decision -- via, direction, exit -- and
                                          copper laid for it by A* at this rule round the part, pad by pad,
                                          legal by construction, or all of a part's pads at once by negotiated
                                          congestion (`negotiate`); escape_oracle's `dec`, `wpt` and `neg` arms);
                                        revision_pairs.py (preference pairs from the git history of the bank's
                                          boards: a later revision by the same designer that kept the parts and
                                          moved them, followed across renames, kept as it goes; `report` asks
                                          which rubric scalars move the way the rubric says is better, `moves`
                                          where the moved parts went, `fit` what weights the pairs support);
                                        rubric_reddit.py (what r/PrintedCircuitBoard's reviewers raise, counted per rule
                                          against the catalogue from a year of the sub's review threads; `--fetch` the
                                          repositories those threads link, pinned before the post; `--boards` writes
                                          them as battle/reddit/ for `rubric.py --calibrate`; a remark is a label only
                                          once a reader has confirmed it in review.json's `confirmed`);
                                        rubric_within.py (can the rubric order one board's own anneals); pair_annotator.py
                                          (trade-off pairs of a board's anneals for a person to choose between, and
                                          the fit that reads the choices back); crystal_ab.py (the crystal term
                                          under the router); deeppcb_board.py (a board DeepPCB shares, routed by ours);
                                        route_bench.py (routers against each other on one stored placement,
                                          one rule, one judge: the A* router and Lightcycle on the
                                          KRT-levers pilot's 300 held-out boards, kicad-cli at 0.127/0.127,
                                          the placement kept in the row so a later arm is judged on the
                                          same board); referee_bench.py (those 300 routed again with the
                                          copper kept under .cache/referee_bench/, each entry judged by
                                          router_ab's judge and by bench/referee.py on the one file);
                                        route_witness.py (witnesses from above: Lightcycle's referee failures
                                          routed again under a portfolio of settings, a pass counted only
                                          when its copper crosses no part's hole or copper);
                                        plane_bench.py (four layers against two on the referee bench's
                                          placements: the product's pour on two layers, its planes on
                                          four, and four signal layers, each judged by bench/referee.py
                                          against a task carrying the same zones; the two-layer row is
                                          the referee bench's own);
                                        route_limit.py (a floor under every router: per net, whether any
                                          legal copper at the judge's narrowest rule can join its pads on
                                          the 300's stored placements, leaning every choice the router's
                                          way; checked against both routers' passes and Lightcycle's copper;
                                          `--v2` runs it on the held-out tasks as placed, with the author's
                                          keepouts as exact polygons);
                                          flow_bound.py (the same question for every cut at once: cells
                                          with route_limit's room per side, nets as a fractional flow, and
                                          a weights certificate when no flow fits; on bench v2 tasks);
                                          referee_place_bench.py (place_bench's 100 bank boards the same way:
                                          the author's placement and today's placer through the referee's
                                          placement track, then routed by A* and Lightcycle and judged twice);
                                          bench_draft.py (the public routing set's first draft, under
                                          .cache/bench-draft/: the bare-clean tasks with a canary in the title
                                          block, provenance and licence class, Lightcycle's tuning flag,
                                          both routers as baselines, and the fingerprints to commit to);
                                          bench_v1.py and bench_v1_release.py (the public routing bench,
                                          version 1: the authors' boards chosen, built, routed by A*,
                                          Lightcycle and freerouting, judged, and assembled for publishing
                                          under .cache/bench-v1/release/); bench_v2.py (the held-out
                                          routing bench: tasks no router of ours was built on, every arm
                                          in its own process under one clock, the code frozen into the run
                                          directory first, under .cache/bench-v2/; `select-4l` picks the
                                          four-layer bench, .cache/bench-4l/, split into a development half
                                          and a held-out half run in .cache/bench-4l-test/);
                                          bench_4l_report.py (that held-out run's report, as its protocol
                                          states the analysis); layout_gym.py (the external layout
                                          benchmark: open-source KiCad boards of 4 to 10 layers re-laid
                                          at the author's placement and at ours, judged by kicad-cli under
                                          each board's own rules, under .cache/layout-gym/; scan, select,
                                          run, rejudge, report); gym_escape.py (escape stubs out of
                                          fine-pitch pads, laid before routing: a gym setting, not the
                                          build's); kicad_srj.py and
                                          tscircuit_route.mjs (a task as tscircuit's SimpleRouteJson,
                                          read by KiCad's own Python, and that router run on it in Node);
                                          sim_conditions.py (stored designs through conditions.py, and the
                                          score against the grader's targets and good boards);
                                          sim_bench.py (faults injected into stored designs, one at a
                                          time, and what the simulator and the design check catch;
                                          splits dev, held and sep); contracts.py (each part's
                                          datasheet record read as what it assumes and guarantees,
                                          checked at every tolerance corner, scored on sim_bench's
                                          faults; a research tool the build does not call);
                                          designcheck_replay.py (the same stored designs, resolved once
                                          and cached, through designcheck.py: the grader's targets, every
                                          new fire on a good board, and `mutate`, defects seeded into the
                                          good boards one class at a time); ab_drive.py (one MCP tool call
                                          answered as the server answers it, for a design-flow A/B: the
                                          drive id names the arm, and arm A runs the committed design
                                          check and component library);
                                          index_grade.py (a run's
                                          boards graded against bench/index/tasks/, and with --mutate the
                                          broken copies each check lets through, for review; --tasks-dir
                                          for the held-out set; --source kicad grades our builds from
                                          their files, --submission grades another tool's); index_review.py (the engineer review
                                          packet: a sample of tasks with each clause's evidence and the
                                          surviving mutants, into bench/index/review_template.html);
                                          index_agent.py (the index's neutral agent, Claude or Gemini: a model designs a
                                          board through a fresh MCP server per task, every API call's
                                          tokens priced, budgets on turns, tool calls, time and dollars,
                                          the first build judged by the verdict and the spec check);
                                          kicad_specctra.py (KiCad's own
                                          DSN export and SES import, run under KiCad's bundled Python);
                                          cypress_h2h.py (NVlabs Cypress against our placer on
                                          tandem_bench's 60 boards: export, round trip, judge;
                                          Cypress itself needs a CUDA machine);
                                          tandem_bench.py (the placer and router as one system:
                                          six anneals a board, the A*-first order the product had against
                                          Lightcycle's ranking and repair, and the repair against as
                                          many fresh anneals); lightcycle_view.py (Lightcycle routing a board live in 3D at
                                          127.0.0.1:8778 -- every net laid, ripped up and laid again, every
                                          round's conflicts, from the search's own feed, router.solve's `watch`;
                                          the PCBGolf viewer's scene); abstract_census.py (the board abstract's tokens
                                          beside gnm's and the JSON wire's, the census's 60 boards and counter);
                                        profile_build.py (where a build's seconds go: realise() in a scratch
                                          cache with a timer on every stage, subprocess and request; `--cli`
                                          for the whole command line; JSON under .cache/profile/);
                                        jev.py (TypeSafe's Jev -- a closed-question model with a calibrated
                                          probability, no generation -- asked three of the pipeline's own questions
                                          against stored data: `verify` how a design handles each clause of its
                                          prompt, `--inject` a clause it cannot carry; `resolve` which catalogue row
                                          is the part asked for, the resolver's own rows, `--rule` with its policy
                                          stated; `pins` which real pin a failed pin name meant; calls cached under
                                          .cache/jev/, the key from TYPESAFE_API_KEY or .env);
                                        datasheet_warm.py (the datasheet reader's warm-up: `scan` counts,
                                          per LCSC code, the distinct boards in the bank that use it --
                                          streamed out of the packed archive, PCBench and the reddit clones,
                                          a part number mapped to its one code -- into
                                          .cache/datasheet-warm/usage.json; `plan` ranks by those boards,
                                          then JLCPCB's basic parts, then the stored designs and BOMs (the
                                          user's projects too), keeps ICs and modules with a sheet link (the
                                          full library's for a part out of stock), names each part's sources,
                                          and calls nothing; `run --max-usd` reads them under a hard total,
                                          skips any part with a record, and logs each read's cost; `find`
                                          asks Exa for the maker's own PDF of a part whose catalogue copy is
                                          a scan or a page, kept only when it names the part and its maker,
                                          into .cache/datasheets/more_urls.json) and board_parts.py
                                          (the codes and part numbers a board, schematic or BOM names: KiCad
                                          6+ fields, KiCad 5 schematics, Eagle attributes, BOM columns);
                                        datasheet_check.py (does the sheet close what the vendor's data
                                          cannot: `fetch` every link for the parts the replay orders, with
                                          the cost of pulling all 613k; `pins` the 20 stored pin-name
                                          failures by the symbol, by the sheet, and by Jev given both;
                                          `audit` every ordered symbol against its sheet, pin by pin);
                                        the corpus and the board bank: azure_route.py (the bank routed on
                                          rented machines, the verdicts merged home), azure_astar.py and
                                          astar_relabel.py (the corpus labelled again by the A* router, each
                                          example's stored placement kept, on rented machines or here, with
                                          freerouting under the same judge as the control), azure_ab.py
                                          (both routers on more seeds or new boards, rented), search_kicad.py
                                          (.kicad_pcb files found by GitHub code search) and
                                          fetch_open_schematics.py (the HuggingFace open-schematics boards
                                          this pipeline can route);
                                        what ships or is served: rubric_reference.py (the professional
                                          reference in soldermask/assets/rubric.json), zener_blocks.py
                                          (priors_zener.json from Diode's Zener modules), fetch_three.py
                                          (three.js, pinned at r128, and its GLTFLoader into app/static/vendor/),
                                          gnn_summary.py and mendicant_summary.py (`--write` the JSON the
                                          /benchmarks page reads; no model trained), mcp_bench.py
                                          (a drive through the MCP server written up as the evaluator's
                                          results.json, for /benchmarks), paper_figures.py (paper/fig/ for
                                          the Mendicant paper, every number read from .cache), film_capture.py,
                                          record_film.py and record_phone.py (the PCBGolf film in tools/film/
                                          and a live viewer, recorded as 9:16 video under .cache/phone/);
                                        audits and controls: fab_check.py (stored builds against
                                          fabrules.py, rule by rule), bom_value_audit.py (each designator's
                                          value against the part its LCSC code names), sim_survey.py (the
                                          simulation stage over every stored design, read-only), mcp_replay.py
                                          (a drive's own designs built again through the MCP `build` with no
                                          model: a re-run's control), datasheet_rules.py (the precision rules
                                          for a reader's claims; datasheet_reader.py carries two of them) and
                                          cypress_modal.py (NVlabs Cypress built and run on Modal's CUDA for
                                          cypress_h2h.py);
                                        parametric_index.py, rubric.py, isofont.py and appicon.py; service templates.
                                        The other tools/*.py are single experiments: each one's question, run
                                          and result are in the CHANGELOG's Unreleased log (grep its name),
                                          and its own docstring says how to run it again

The pipeline is plain Python modules with no framework in them. workspace.realise() is the build sequence, and four callers use it and no copy of it: the app (app/turns.py), the command line (cli.py), the MCP server (mcp.py, and mcp_http.py through it) and the evaluator (evaluate.py). The CLI has since 11 Sep 2026; before that it ran its own copy and the two drifted four times. realise() hands back a Build, which unpacks to the five things a version stores and carries the placement, the copper, the report and the fill beside them for a caller that prints or checks more; tests/test_cli_build.py counts the calls. Anything that must hold for every board goes in realise() or in a function it calls, as verdict(), apply_constraints() and rubric.report() are.

Principles the code follows

Report, never hide. Every stage returns what it could not do, and that goes next to the result: gaps and notes on the netlist, unsupported from the model, the honest section on the command line, Advisories in the workbench. A silent except: continue is the thing to be most suspicious of in review.

Recall is not evidence. The model names functions and parts; pad numbers come from the symbol library, footprints from data, stock from the supplier. When something has to be borrowed — a pinout from a family, a footprint from a vendor — it is labelled assumed, not verified.

Check with something that did not make it. Gerbers are read back by gerbonara; the KiCad file is re-parsed and compared with the placement; with KiCad installed, its plot is compared with ours.

Measured, not chosen. Trace width, clearance, via size, decoupling values and block idioms come from a corpus of real boards; model orientation comes from the pads; the KiCad rotation sign was found by rendering all four and scoring them.

Repair must not launder. A dropped part costs more than an unresolved one, so deleting a problem never pays.

A model predicts; the oracle decides. The router orders the placements, not the model: where Lightcycle routes, tandem.rank routes every candidate and puts first the one that leaves fewest pins unreached, then least copper (since 26 Sep 2026, after the model's ranking of one board's own anneals measured at chance four times). The model's order is used only where Lightcycle cannot run or SOLDERMASK_TANDEM=0, and it never replaces the router. Its prediction is written beside the router's verdict on every board, a confident miss is said in words, and the route becomes the next training example. Whether the neural network beats the analytic baseline is a number in the model file, not an argument.

A wrong instrument is worse than none. The evaluator and the harness tests exist because two measurement faults have already cost real time.

Data is not code. projects/ is the user's work: immutable versions, atomic writes, migrations with backups, a trash instead of deletion, and it is not in git.

Conventions

  • Python 3.11+, type hints, dataclasses, docstrings that say why. Modules explain their coordinate frame at the top when they have one (mm, origin bottom-left, y up — except KiCad, which is y down).
  • Tests are plain scripts with a check() helper and a final N passed, M failed or n/m passed line; .venv/bin/python tests/run.py runs them all (the bare python may not be the venv's, and the system Python has no numpy).
  • The front end is plain JavaScript with globals on purpose (state, render, BOARD, scene2d), so tests/verify_3d.js, tests/verify_scene.py and schematic.js can reach it; no build step.
  • The copper view is a persistent scene: built once into static/live/overlay, mutated afterwards, torn down only for a different board. A gesture writes one attribute; nothing reads getBBox or getBoundingClientRect inside a move.
  • Files that another session or person may be editing are patched with exact-string replacements, not rewritten.

On this page