Design: the gloss, dekink and corridor-coalescing pass (PNR_GLOSS)¶
Status: PNR_GLOSS is the runner’s own default since ladder-v2 (2026-10-06,
docs/decisions.md; --no-gloss restores the plain runner path), once a native-loop A/B on GCP
(section 10) showed no regression. Implemented on branch claude/gloss-port. The pass was
designed and built in Splanc’s engine (snapshot src18) and is ported here as a copy plus the
loop hunks; where
the port differs from the source, §9 says so. Code: hardware/pnr/pnr/gloss_geometry.py (pure
geometry, no KiCad) and hardware/pnr/pnr/gloss.py (KiCad adapter, workers, transactional
controller); the loop hooks are in pnr/native_loop.py and pnr/full_iteration.py, the ladder
stage in regression/run.py.
Owner request (2026-09-30): add a glossing and corridor coalescing phase to the router, under the same cost constraints as drive the current routing; remove unnecessary direction changes (“dekinking”); when several tracks of the same signal class run next to each other, place them parallel and directly adjacent to minimize dead space; run it within the PnR loop, and let the legalizer override its decisions if they are illegal or not DRC/ERC clean.
1. Summary¶
One phase, two passes in
pnr.native_loop.06g-glossruns after06-signalsand06b, before the refinement clock starts;07g-glossruns after the refinement cycles and the loop’s own cleanup, before08b.Four steps per pass, in this order:
normalize: merge collinear, zero-length and duplicate segments; the copper does not change.
dekink: inside each monotone run, use the path with the fewest bends at the same length.
gloss (pull-tight): the shortest homotopic octilinear path within a 1 mm tube, found with the router’s own A* and bend cost.
corridor: pack parallel legs of the same signal class to minimum legal pitch.
A second gloss and corridor sweep follows by default (
PNR_GLOSS_SWEEPS=2).What may change: only the centreline vertices of ordinary signal tracks between fixed anchors. Anchors, widths, layers, vias, nets, pad and neck copper and locked copper never change; power, plane, pair, length-match and (by default) SI nets are never touched; no new contact, crossing or via is created.
Cost: the router’s. Octilinear legs, chain cost
C = L + 0.15 mm × bends, the keyholerelaxrule (shorter, or the same length with fewer bends) and thealign_parallelslack of 0.2 mm for corridor moves and adjacency tie-breaks. Legality is the native shape checker’s (Oracle).Legalizer override, four layers (§5): every transaction is re-checked on the applied board and gated by native checks including a cold KiCad DRC; a phase-end gate bisects or reverts the pass; the loop’s own
gate()can keep the pre-pass board; later legalizers rip up glossed copper like any other.Off by default. With
PNR_GLOSSunset,pnr.glossis never imported and no label, event, progress key, router key or code key depends on it (§6).
2. Eligible copper and anchors¶
A net is eligible only if all of these hold (each is an existing engine predicate):
# |
Condition |
|---|---|
E1 |
|
E2 |
not in |
E3 |
not an |
E4 |
the effective KiCad netclass is |
E5 |
no arcs of the net on the layer |
Per eligible (net, layer), in nm integers: segments are split at T points; anchors (never moved) are vertices in a same-net pad or via, vertices of degree other than 2, width changes, ends of frozen segments and vertices in a same-net filled zone. A chain is a maximal path between two anchors. Frozen segments are never edited: locked copper, neck and terminal zones (a pad with a terminal contract or a required entry width, and its neck length), every track a DRC violation of the pre-pass board names, and every track of a net with an unconnected item. The frozen and guard sets come from the pre-pass board and its DRC report only, so they do not depend on which items KiCad happens to name.
3. Legality of an edit (L1-L8)¶
An edit replaces the old sub-path(s) of a chain (several chains for corridor) by new ones with the same anchors. It is legal only if:
# |
Check |
|---|---|
L1 |
every new segment passes |
L2 |
no new contact with same-net copper beyond the chain’s own anchors (exact shapes, zero clearance): the contact graph and the pad partition cannot change |
L3 |
homotopy: the old path closed with the reversed new path winds 0 times around every other item’s test point (pads, vias, track ends, keepout and outline vertices, holes): no obstacle changes side, so no crossing is created |
L4 |
anchors, widths, layer, vias and net identical; every new leg octilinear; rounded to 1 nm and checked again |
L5 |
no interior turn sharper than 90 deg and no new acute angle at an anchor (no acid traps) |
L6 |
a pad-entry witness end segment stays a witness |
L7 |
proximity guards never lose distance: G1 diff-pair copper (cap 3 × the pair gap), G2 the pads of open nets (1 mm; at 06g also their tracks and vias), G3 any foreign copper for SI chains (3 × width) |
L8 |
locality: gloss vertices within 1 mm of the old chain; dekink inside the run’s parallelogram; corridor shift at most 2 mm |
With functional groups (§7), an edit is also legal only if no pair of different groups gains
parallel run at minimum pitch beyond max(allowance, run before).
4. Acceptance¶
normalize: the copper union is identical (XOR at most 2e-4 mm², arc approximation) and the segment count falls.
dekink and gloss, rule R: shorter by more than 1 µm, or the same length with fewer bends; 90° and 135° turns never increase;
Cstrictly falls. Length is never traded for bends. Among equal-cost options, the one hugging same-class neighbours tightest wins, and an edit saving less than 0.2 mm is declined if it loosens adjacency.corridor: per member no added bend and at most 0.2 mm of extra length (drag-only moves; a blocked full shift is bisected to the largest legal one); per stack the adjacency metric X falls by at least 0.05 mm² and the window’s dead space DS does not grow.
Metrics. L (eligible length), bends (
bends_allcounts every degree-2 vertex), X (the sampled gap to same-class neighbours within 2 mm, minus the required clearance), T (length packed at minimum pitch), DS (free area no track of the class can use) and A2/A3 (area usable by a 2- or 3-track bus). X and the hug score do not depend on which way a segment is drawn: each segment is sampled from its canonical (sorted) first end, and a ray that meets a same-class parallel neighbour and other copper at the same distance (a neighbour’s vertex) counts the neighbour. The source sampled from the drawn first end and broke such ties by an order that followed the drawing direction: one merged segment drawn the other way changed X by 0.155 mm² on a ladder board with the same copper.python -m pnr.gloss --measure BOARD... --rules R --out Jreports them with the cold DRC, the objective and the audit.
5. Transactions and the legalizer override¶
Per transaction. One inventory worker plans a step; edits are packed into batches of up to 16 with distinct nets and disjoint influence boxes (4 corridor stacks; normalize is one batch). A trial worker applies a batch, re-checks every edit on the applied board (L1-L8, the edit rule, the group cap), drops failures, refills and collects facts; then a cold KiCad DRC. The gate requires: the same pad partition, no lost connection, no lost or newly bad pad entry, reference failures a subset, no new forbidden via, sub-width, unjustified sub-width, unqualified pairs and pair skews not up, no new DRC violation key, opens and dangling items not up, the objective not worse in any component, and a positive gain. A rejected batch drops the edits the findings name, else is halved (4 levels); an edit rejected alone is blacklisted for the pass.
Phase end. The last checkpoint is checked against the pre-pass board with the strongest headless checks (cold DRC, facts, audit; the SI report when SI nets were edited). On failure the controller bisects the checkpoints, drops the failing transaction, replays the later ones (each gated again), and after 3 rounds reverts to the byte-identical input.
The loop’s gate.
native_loopruns its own inspect, check and DRCgate()on the pass output, as for cleanup and bank consolidation, and keeps the pre-pass board on failure.Later legalizers. Glossed copper has no special status: refinement rip-up, shove, regional blocker plans, cleanup, coalescing and pad-entry repair override it like any other signal copper.
Budgets (global, never per board): 240 s per pass, checked before each inventory and transaction;
48 transactions; a deterministic per-chain planning budget (6000 shape and contact checks), with a
120 s inventory safety net that is reported when hit. Every worker runs under its pnr.proc
deadline; a signal exit is retried once, a deadline kill is not. The 240 s and 120 s are wall
clock: a slower machine can stop a pass on time_budget where a faster one finishes. The pass
reports why it stopped (stop: time_budget, max_transactions or null), its budget and its
planning totals (deadline_hits); the ladder keeps them in result.json. For an A/B across
machines, raise PNR_GLOSS_SECONDS well above the pass’s need and bound the pass by
PNR_GLOSS_MAX_TRANSACTIONS, so both arms stop for the same reason.
Energy proposal integration¶
PNR_GLOSS_ENERGY=1 selects the optional witness-growth energy proposer for the
gloss step, with stricter joint-refill electrical evidence gates. It is off by
default. See energy-track integration for exact eligibility,
refusal reasons, dependency ABI handling and the recorded native animation.
6. Flags¶
None is read unless PNR_GLOSS=1.
Flag |
Default |
Meaning |
|---|---|---|
|
unset |
master switch; unset: no import, label, event or key |
|
|
steps (the order is fixed) |
|
|
loop passes |
|
|
SI nets may enter normalize, dekink and gloss (G3) |
|
|
budget per pass |
|
|
|
|
|
edits per transaction |
|
|
same-class adjacency tie-breaks in dekink and gloss |
|
|
2: a final gloss and corridor sweep |
|
unset |
functional groups file (§7) |
|
unset |
derive groups: |
|
|
cross-group cap in mm; needs one of the two above |
|
rejected |
the in-cycle pass and un-glossing are not implemented |
A malformed value, or a groups file or rules that give no functional groups, stops native_loop
before any phase runs. PNR_STOP_AFTER_PHASE accepts the two gloss labels only with the flag set
(and its error then lists them). With the flag, progress.json gains gloss (per pass: the
summary, accepted, status and cost, its wall and CPU seconds) and gloss_key, and
evaluation.json the side fields gloss_summary and gloss_metrics (the metrics worker measures
the passes’ functional groups); the objective vector is unchanged.
Keys. The router key (pnr.feedback.signals.current_key) gains gloss: null with the flag
unset, else pnr.gloss.settings_key, a digest of every sub-flag’s effective value and of the
groups file’s content (never its path). key_string adds a gloss= field only then, so flag-off
key strings are what they were. A record’s gloss key comes from its progress.json, and
check_import refuses an evaluation whose gloss key differs from the run’s: the two arms of a
gloss A/B, or two gloss configurations, never mix in a feedback library or a halving import.
pnr.gloss and pnr.gloss_geometry are evaluation code (part of the code key) only with
PNR_GLOSS=1, as pnr.shove is only with PNR_SHOVE=1; with the flag the key also covers
pnr.shove.gates, whose unjustified sub-width check the pass runs under any router. Gloss edits
therefore never change a flag-off code key; the hooks in native_loop and full_iteration
changed the plain-router code key once, when they landed.
7. Functional groups and the cross-group cap¶
Packing tracks at minimum pitch over long runs couples them. The owner’s rule: parallel run at
minimum pitch is unlimited within a functional group and capped at 10 mm between groups
(a net in no group is a group of its own). The measure: for two tracks of different nets on one
layer within 30° of parallel, the part of each centreline whose foot lies on the other track and
whose distance is at most the minimum pitch + 0.1 mm; the run C(a, b) is the mean of both
directions, summed over layers. An edit may never raise a cross-group pair above
max(allowance, C before the pass), so a pair already over the cap may stay or fall but never
grow. The allowance comes from one hook, gloss_geometry.allowed_parallel_mm, which a
noise-budget model can replace with per-pair allowances. The planner, the trial worker and the
gates all enforce it.
Groups file (PNR_GLOSS_CLASSES):
{
"classes": {
"GROUP": ["NET", "NET"],
"OTHER": { "nets": ["NET"], "interface": "free text", "provenance": ["free text"] }
}
}
A group lists net names, either directly or under nets; other keys are documentation. A net in
two groups is an error. docs/examples/gloss-groups-chaser.json is the file of ladder case
07-chaser-20 (timer, clock and reset, LED drive).
Derived groups (PNR_GLOSS_CLASSES_FROM, a comma list of netclasses, pairs, si,
length_match): each rules net class, differential pair, @pnr-si intent or length-match group
becomes a group. Derived groups with the same members are one group. A net derived into groups
with different members joins the most specific one: the fewest members, then the first source in
the order above. A differential pair inside a wider net class is thus a group of its own, and the
class keeps its other nets (the more specific group caps more pairs, the conservative choice). A
groups-file entry wins for its net. The groups are checked against the rules at controller start
(si needs the board and is resolved by the pass).
E4 still limits edits to Default-class nets; admitting named signal classes is a later
decision.
8. The ladder stage¶
The regression ladder has no native loop. run.py --gloss runs one pass with 07g semantics on the
refilled board, before the audit, transactional and gated as in the loop, then gated again by the
kicad-cli DRC that judges the case, as strictly as the pass’s own transaction gate
(via_coalesce.violation_keys): if opens rise, a violation is new by its type and items (one
that moved to other items counts, even when its type’s count holds) or dangling tracks or vias
rise, routed.pre-gloss.kicad_pcb (always kept) is restored. A failing stage restores the board
and fails the case (gloss_error). --gloss-flag PNR_GLOSS_NAME=VALUE passes sub-flags (the
runner strips ambient PNR_* variables); a groups file is copied into source-freeze and read
from there, and provenance.json records the sub-flags and the file by name and sha256, never by
path. --gloss-measure measures each final board, for both arms of an A/B. Each case’s
result.json gains a path-free gloss block (pass summary with stop, budget and the planning
totals, metrics before and after, the outer gate, the pre- and post-gloss board and copper hashes,
the sub-flags and the groups file by name and sha256); per-stage CPU is cpu_stages and
cpu_seconds, as on the hard-rungs branch. --trace snapshots the board after the stage. The
KiCad-lane test gloss_e2e_test runs the stage on the public case 04-inverter-leds-8, and the
nightly ladder runs it on 04-inverter-leds-8 and 07-chaser-20 (seed 0): a stage error fails
the job, a stage that keeps no edit on either case is a warning.
hardware/pnr/regression/run.py --repo . --out .yapnr/ladder/AB-OFF --seed 0 --seed 1 \
--showcases --gloss-measure ...
hardware/pnr/regression/run.py --repo . --out .yapnr/ladder/AB-ON --seed 0 --seed 1 \
--showcases --gloss --gloss-measure ...
Writeback gives tracks random uuids, so each case also records copper_sha256, a hash of its
copper without uuids and without the direction a segment is drawn in (it raises on a board whose
track or via blocks it cannot parse, rather than hashing nothing). An on-arm case pairs with its
off-arm twin when its
pre_gloss_copper_sha256, placed.json and routes.json match the twin’s. The ladder
measures what the pass does to a finished board; it cannot measure completion, because the pass
runs after a complete route. Results:
Regression ladder.
9. The port¶
The engine here descends from Splanc’s src15 snapshot plus the Electrical221 integration
(import manifest). Normalized, the source’s native_loop.py
differs from src15 only by the gloss hunks, and every engine API the pass calls keeps its
signature; src16 and src17 changed the pass’s dependencies only behind an opt-in flag this engine
does not have. Differences from the source:
black and isort; flake8 clean without a baseline; comments scrubbed of private references.
apply_specdeletes replaced copper withboard.Delete(neverRemove;test_board_deletehas a gloss case). Delete invalidates the old tracks’ wrappers, so the trial worker scores a corridor edit’s planned state before applying it (the source scored it after, through the pre-apply board, whichRemoveleft valid); the value is the same.Workers run through
pnr.proc.run_status, retried once after a signal exit only.The tests’ board-derived geometry is generated, with the same asserted properties, and net names are neutral.
The ray metric (X and the hug score) samples from a segment’s canonical end and counts a same-class neighbour at a tie (§4); the source depended on the drawing direction. The same patch is handed back to the source.
New: derived functional groups (the most specific group wins), the ladder stage and the public example groups file; the gloss settings in the router key and the flag-gated code key (§6); the passes’ cost in
progress.json; the functional groups infull_iteration’s metrics.
Identity: the port and the source engine were run on three replay points of a private board
(a finished board as 07g, with and without groups, and a 06-signals capture as 06g), each with a
fresh DRC cache; the evidence stays private. Before the ray-metric fix, the port reproduced the
source exactly on all three: the same output copper (a uuid-free hash, also equal to the source’s
archived run), the same transaction sequence and accepted count, the same edits per step and the
same metrics; the cold DRC, the objective and the audit are unchanged by the pass in both
engines. The first run diverged at the first corridor transaction (the Delete difference
above) and led to that fix. After the ray-metric fix, the port is again exact against the source
with the same patch on all three points (the run with groups needs a budget above 240 s in both
engines: under load the source’s pass stopped on its wall-clock budget one transaction short,
the variance §5 describes). Against the unpatched source the fix moves a few decisions: one gloss
edit more on one point, one corridor edit fewer on another; length within 0.03 mm, bends equal,
DRC, objective and audit unchanged. With the flag unset, the stubbed loop controller of this
branch and of main produce identical outputs, and pnr.gloss is not imported.
10. Open points¶
Default-on (resolved, 2026-10-06): the native-loop A/B this needed ran on GCP (PR #62, campaign
20261005-ladder-4b88dd): ladder + showcases +09-mcu-usb-31+ the two UFBGA-201 rungs, seeds 0 and 1, gloss off vs on. 52 of 60 tasks passed; the 8 failures are a pre-existing, unrelatedjlc-pofvBGA fanout via-drill mismatch, identical in both arms. Over the 26 remaining paired cells: 0 regressions (opens and DRC violations stay 0 in every cell, both arms); bends -19.6 %, track segments -38.0 %, copper length -1.4 %, vias unchanged, CPU +393 %.--glossis now the runner’s own default (ladder-v2,docs/decisions.md).06g routability on public boards is unmeasured: the ladder runs the pass after a complete route. A real native loop with the flag on a public ladder board (no annotation sources, two refinement cycles) ran both passes with real workers:
06g-gloss(open-net guard) kept two transactions, 4 fewer bends and 0.7 mm less length, the loop’s gate accepted it, and the loop ended with the same opens as the same run without the flag. One board, one seed: a smoke test, not evidence about completion.Cost. On the ladder the stage costs a roughly fixed 30 to 125 s of CPU per case (KiCad worker start-up and three cold DRCs dominate on small boards), so the overhead is largest on the smallest cases (see the ladder A/B). In the native loop each pass adds its own inspect, check and DRC workers to the evaluation, and
full_iterationone metrics worker; on the private board each pass took 2 to 4 minutes of wall time.Gloss may loosen adjacency where it saves at least 0.2 mm (router cost ranks first).
Whole open nets are frozen (deterministic, conservative).
Corridor moves are drag-only; no jogs, no co-mitred bus corners.
E4 limits edits to the
Defaultnetclass.No crosstalk budget beyond the cross-group cap.
No fixture has more than two copper layers; a four-layer gloss fixture belongs with the N-layer stackup work. The KiCad-lane tests (
gloss_native_test,gloss_e2e_test) aremanual, so only the nightly ladder’s gloss stage runs the pass on KiCad in CI.When the hard rungs land, their independent
checksstage runs after the gloss stage on the final board; the gloss outer gate does not consult it, so a pass that broke a declared constraint would fail the rung rather than be reverted.