fix(layout): seat an orphaned half-pitch branch on a full grid row

A half-pitch offset draws a two-way symmetric fork as one compact grid
unit, so both members are placed together and each only reads as
deliberate because it balances the other across the trunk.  When Stage
6.10's _align_terminus_to_upstream pulls a terminus member onto its
producer's trunk Y, the surviving member holds an offset that straddles
nothing and renders as a branch stranded between two grid rows.

Add Stage 6.18, _expand_orphaned_half_grid_stations: mirror each marked
station's offset about the section's LR/RL port anchor and, with the
opposite slot empty, seat the branch one full row from the anchor on the
side it already sits.  Gated to stations at a genuine half pitch, since
the marker set also carries members already a whole number of rows out.

An earlier gate cannot do this.  _layout_once runs up to seven times per
render and the motivating section carries two structurally identical
half-pitch pairs, only one of them broken, so every predicate tried
inside _recenter_full_bundle_columns or _align_terminus_to_upstream
flipped the section into a different fixpoint and bent the trunk.

_half_grid_frame and _straddles_nothing are shared with the invariant
test, as _iter_symmetric_diamonds already does, so the oracle and the fix
cannot disagree about which stations are legitimately half-pitch.

Rename the exercising fixture to paired_input_fan_branch_tree and give it
generic labels and station ids.  The replacements are width-matched to
what they replace, so its geometry is coordinate-for-coordinate identical
and the three regressions it locks all still reproduce: the input-fan
bypass-V band, the reconverging-diamond entry-port centring, and the new
half-pitch straddle.  Its stage_a4 branch now sits level with the out_a1
branch instead of half a row above the trunk.

Register the resulting off-track reanchor divergence, tracked in #1566.

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

Author: pinin4fjords

examples/topologies/paired_input_fan_branch_tree.mmd

@@ -0,0 +1,69 @@
+%%metro title: Paired-track demo
+%%metro diamond_style: symmetric
+%%metro style: dark
+%%metro legend: bl
+%%metro files: pairs_in | FILE | Input set
+%%metro files: out_a1 | OUT | Track A
+%%metro file: out_a2 | OUT | Output A2
+%%metro file: out_a3 | OUT | Output three
+%%metro file: out_b | OUT | Probe value
+%%metro files: out_c | OUT | Chain out
+%%metro line: track_a | Track A | #0570b0
+%%metro line: track_b | Track B | #d94801
+
+graph LR
+    subgraph input_sec [Inputs]
+        pairs_in[ ]
+        convert_a[Convert one\ntrack a]
+        convert_b[Convert two\ntrack b]
+
+        pairs_in -->|track_a| convert_a
+        pairs_in -->|track_b| convert_b
+    end
+
+    subgraph branch_sec [Branching stage]
+        stage_a1[Upstream\nprimary stage]
+        stage_a2[Filter step]
+        stage_a3[Fork\nannotation]
+        stage_a4[Terminal\nsegment]
+        out_a1[ ]
+        out_a2[ ]
+        out_a3[ ]
+
+        pairs_in -->|track_a| stage_a1
+        pairs_in -->|track_b| stage_a1
+        stage_a1 -->|track_a,track_b| stage_a2
+        stage_a2 -->|track_a,track_b| out_a1
+        stage_a2 -->|track_a,track_b| stage_a3
+        stage_a3 -->|track_a,track_b| out_a2
+        stage_a3 -->|track_a,track_b| stage_a4
+        stage_a4 -->|track_a,track_b| out_a3
+    end
+
+    subgraph probe_sec [Hub]
+        stage_b1[merge node]
+        out_b[ ]
+
+        convert_a -->|track_a| stage_b1
+        convert_b -->|track_b| stage_b1
+        stage_b1 -->|track_a,track_b| out_b
+    end
+
+    subgraph chain_sec [Downstream chain]
+        split_a[Region split\ntrack a]
+        split_b[Region split\ntrack b]
+        stage_c1[Assemble\nstage]
+        stage_c2[Collate\nmerge step]
+        stage_c3[Fit and rank\nstage]
+        stage_c4[Adjust to\nscale]
+        out_c[ ]
+
+        convert_a -->|track_a| split_a
+        convert_b -->|track_b| split_b
+        split_a -->|track_a| stage_c1
+        split_b -->|track_b| stage_c1
+        stage_c1 -->|track_a,track_b| stage_c2
+        stage_c2 -->|track_a,track_b| stage_c3
+        stage_c3 -->|track_a,track_b| stage_c4
+        stage_c4 -->|track_a,track_b| out_c
+    end

scripts/gallery.yaml

@@ -1837,9 +1837,9 @@ gallery:
     source_dir: examples/topologies
     category: Feature Showcase
     description:
-      "A paired-track map: the input source fans to two stacked
-      converters and threads the two-track bundle cleanly between them to
-      the somatic caller, whose dead-end outputs peel off without crowding
+      "A paired-input map: the source fans to two stacked converters and
+      threads the two-track bundle cleanly between them to the branch tree,
+      whose dead-end outputs peel off onto full grid rows without crowding
       their neighbours."
   - id: single_line_dual_source_stacked_exit
     source_dir: examples/topologies

src/nf_metro/layout/CONTRACT.md

@@ -247,9 +247,10 @@ pass:
   grid snap (6.4).
 - `graph.half_grid_station_ids` - written by Stage 6.3 (`center_ports` only)
   and Stage 6.17 (`diamond_style='symmetric'`); read by the Stage 6.4 grid
-  snap, which must skip these half-pitch stations. Stage 6.17 runs after the
-  last snap, so its writes mark branches for the invariant tests / straddle
-  guard rather than feeding a later snap.
+  snap, which must skip these half-pitch stations. Stage 6.18 both reads the
+  set and clears the marking off any station it seats back on a full row, so
+  the post-layout readers (the straddle guard, the co-fanned drop-clearance
+  rule in `routing/intra_handlers.py`) see only stations still at half pitch.
 - `graph.symfan_trunk_station_ids` - written by Stage 6.3 (`center_ports` only);
   read by the Stage 6.4 grid snap, which must skip these source/trunk stations
   so they stay on the symfan's local frame instead of snapping to a rowspan
@@ -878,7 +879,8 @@ in pipeline order.
 - **Related tests**: `test_symfan_pairs_share_y`.
 - **Lifecycle:** invariant - 2-branch symfan pairs keep their half-pitch
   offsets at the final boundary (Stage 6.4 skips
-  `graph.half_grid_station_ids`).
+  `graph.half_grid_station_ids`); only Stage 6.18 may seat one on a full
+  row, and only once its straddling partner has moved away.
 
 ### Stage 6.4: snap all Y to grid (engine.py)
 - **Purpose**: Final pass snapping every station and port Y to the
@@ -959,7 +961,9 @@ in pipeline order.
   are temporarily broken; both are restored before leaving the
   `if center_ports:` block.
 - **Lifecycle:** invariant - full-bundle columns are symmetric around
-  the row's final trunk Y at the boundary; no later stage re-fans them.
+  the row's final trunk Y at the boundary; no later stage re-fans them,
+  though Stage 6.18 seats a half-pitch member on a full row once its
+  straddling partner has moved away.
   *liftable:* no - one-shot, order-dependent (computes against the final
   trunk Y, so a premature run is wrong).
 
@@ -1223,10 +1227,10 @@ in pipeline order.
   Per-diamond, so a diamond compacts even when it shares a section with a
   wider fan (which keeps its full-pitch slots) and regardless of
   `center_ports`. Records the branches on
-  `MetroGraph.half_grid_station_ids`. Runs last, after every
-  trunk-settling pass, so the branches straddle the section trunk's final
-  Y exactly; the compaction only moves them inward toward the trunk, so it
-  never breaks bbox containment.
+  `MetroGraph.half_grid_station_ids`. Runs after every trunk-settling
+  pass, so the branches straddle the section trunk's final Y exactly; the
+  compaction only moves them inward toward the trunk, so it never breaks
+  bbox containment.
 - **Helper**: `_apply_half_grid_symmetric_diamonds`.
 - **Precondition**: Trunk Ys settled (post-6.16); `diamond_style`
   is `symmetric`.
@@ -1239,7 +1243,41 @@ in pipeline order.
   `test_symmetric_diamond_both_branches_deviate`,
   `_guard_symmetric_diamond_branches_straddle_trunk`.
 - **Lifecycle:** invariant - symmetric diamond branches keep their
-  half-pitch offsets at the final boundary (no later Y mutation).
+  half-pitch offsets at the final boundary; only Stage 6.18 may move one,
+  and only when its straddling partner is gone.
+
+### Stage 6.18: orphaned half-pitch expansion (engine.py)
+- **Purpose**: A half-pitch offset encodes one side of a symmetric pair
+  straddling the section trunk, so the pair reads as one compact grid
+  unit. Stage 6.10's `_align_terminus_to_upstream` may pull a terminus
+  member onto its producer's trunk Y, leaving the other member holding an
+  offset that straddles nothing and rendering as a branch stranded
+  between two grid rows. `_straddles_nothing` mirrors each marked
+  station's offset about the section's LR/RL port anchor; with no station
+  at the mirrored slot, the branch is seated one full row from the anchor
+  on the side it already sits, its half-grid marking cleared, and the
+  section bbox grown over the moved branch alone. Stations marked
+  half-grid whose settled Y is already a whole number of rows from the
+  anchor are left alone.
+- **Helper**: `_expand_orphaned_half_grid_stations`
+  (`phases/fan_bundles.py`), sharing `_half_grid_frame` /
+  `_straddles_nothing` with the invariant test.
+- **Precondition**: Every pass that places or dissolves a half-pitch pair
+  has run (post-6.17), so the half-grid marks are final.
+- **Postcondition**: No station in `graph.half_grid_station_ids` sits half
+  a pitch off its section's LR/RL port anchor with the mirrored slot
+  empty.
+- **Invariants preserved**: Trunk station Y, ports, bbox containment.
+  Deliberately not preserved: the half-grid marker set (the seated
+  station's id is discarded, so the post-layout readers see only stations
+  still at half pitch) and the section bbox extent, which grows over the
+  seated branch. No runtime `_guard_*` arms this postcondition:
+  `test_half_grid_stations_straddle_in_pairs` covers it across the corpus
+  without the abort risk a live guard would add to novel input.
+- **Related tests**: `test_half_grid_stations_straddle_in_pairs`.
+- **Lifecycle:** invariant - the expanded branch keeps its full-row Y at
+  the final boundary (no later Y mutation). The cleared marker reaches the
+  next `_layout_once` pass, which re-derives the marks from scratch.
 
 ## Unclear / structural-debt signals
 

src/nf_metro/layout/engine.py

@@ -110,6 +110,7 @@
     _center_lr_entry_ports_on_fork,
     _convergence_source_ys,
     _divergence_target_ys,
+    _expand_orphaned_half_grid_stations,
     _iter_symmetric_diamonds,
     _recenter_full_bundle_columns,
     _redistribute_fanout_siblings,
@@ -2007,6 +2008,13 @@ def _finalize_layout(
         _apply_half_grid_symmetric_diamonds(graph, y_spacing)
         _snap(graph, "6.17")
 
+    # Stage 6.18: Seat orphaned half-pitch stations on a full grid row (see
+    # _expand_orphaned_half_grid_stations and CONTRACT.md Stage 6.18).  Must
+    # follow every pass that places or dissolves a half-pitch pair, so the
+    # half-grid marks are final.
+    _expand_orphaned_half_grid_stations(graph, y_spacing, section_y_padding)
+    _snap(graph, "6.18")
+
     if validate:
         if graph._defer_final_guards:
             graph._after_final_deferred = True

src/nf_metro/layout/phase_state.py

@@ -63,7 +63,7 @@
     "4.1", "4.2", "4.3", "4.4", "4.5", "4.6", "4.7", "4.8", "4.9", "4.10",
     "5.1", "5.2", "5.3", "5.4", "5.5",
     "6.1", "6.2", "6.3", "6.4", "6.5", "6.6", "6.7", "6.8", "6.9", "6.10",
-    "6.11", "6.12", "6.13", "6.14", "6.15a", "6.15", "6.16", "6.17",
+    "6.11", "6.12", "6.13", "6.14", "6.15a", "6.15", "6.16", "6.17", "6.18",
 )  # fmt: skip
 
 
@@ -106,23 +106,24 @@ class PhaseFieldSpec:
     "_row_y_grid_info": PhaseFieldSpec(
         name="_row_y_grid_info",
         writer_stage="1.2",
-        reader_stages=("4.2", "6.3", "6.4"),
+        reader_stages=("4.2", "6.3", "6.4", "6.18"),
         enforcement=FieldEnforcement.REQUIRE_WRITER,
         why=(
             "row-grid metadata from Stage 1.2's _align_row_y_grids; the grid-group "
-            "port snap, fan re-centre, and grid snap read it to group same-row "
-            "sections onto a shared pitch"
+            "port snap, fan re-centre, grid snap and half-pitch expansion read it "
+            "to group same-row sections onto a shared pitch"
         ),
     ),
     "half_grid_station_ids": PhaseFieldSpec(
         name="half_grid_station_ids",
         writer_stage="6.3",
-        reader_stages=("6.4",),
+        reader_stages=("6.4", "6.18"),
         enforcement=FieldEnforcement.REQUIRE_WRITER,
         why=(
             "2-branch symfan stations Stage 6.3 places at half-pitch; Stage 6.4's "
             "grid snap must skip them or it snaps their intentional half-grid Y to "
-            "the full grid"
+            "the full grid, and Stage 6.18 reads the set to find members whose "
+            "pair partner moved to a full row"
         ),
         run_condition_attr="center_ports",
     ),

src/nf_metro/layout/phases/fan_bundles.py

@@ -2,14 +2,15 @@
 
 from __future__ import annotations
 
+import math
 from collections import defaultdict
 from collections.abc import Iterator
 
 from nf_metro.layout.constants import (
     SAME_COORD_TOLERANCE,
     SECTION_Y_PADDING,
 )
-from nf_metro.layout.geometry import shift_section
+from nf_metro.layout.geometry import lanes_run_along_x, shift_section
 from nf_metro.layout.phase_state import require_phase_field
 from nf_metro.layout.phases._common import (
     _fan_offsets,
@@ -989,13 +990,7 @@ def _carry_symmetric_branch_continuations(
             for s in section.station_ids
             if s in graph.stations and not graph.stations[s].is_port
         ]
-        if content_ys:
-            grow_section_bbox_min_edge(
-                graph, section, "y", min(content_ys) - section_y_padding
-            )
-            grow_section_bbox_max_edge(
-                graph, section, "y", max(content_ys) + section_y_padding
-            )
+        _grow_section_bbox_over_ys(graph, section, content_ys, section_y_padding)
 
 
 def _section_lr_entry_port(graph: MetroGraph, section: Section) -> str | None:
@@ -1240,3 +1235,116 @@ def _pull_continuation_onto(
     for sid in carried:
         graph.stations[sid].y = branch.y
     return carried
+
+
+def _section_occupants(graph: MetroGraph, section: Section) -> list[Station]:
+    """The section's visible stations -- the ones that can occupy a row slot."""
+    return [
+        st
+        for sid in section.station_ids
+        if (st := graph.stations.get(sid)) is not None
+        and not st.is_port
+        and not st.is_hidden
+    ]
+
+
+def _grow_section_bbox_over_ys(
+    graph: MetroGraph, section: Section, ys: list[float], section_y_padding: float
+) -> None:
+    """Grow *section*'s bbox so *ys* sit inside it with padding on both edges."""
+    if not ys:
+        return
+    grow_section_bbox_min_edge(graph, section, "y", min(ys) - section_y_padding)
+    grow_section_bbox_max_edge(graph, section, "y", max(ys) + section_y_padding)
+
+
+def _half_grid_frame(
+    graph: MetroGraph, section: Section, y_spacing: float
+) -> tuple[float, float] | None:
+    """``(anchor_y, row_pitch)`` for *section*, or None when it has no frame.
+
+    The anchor is the LR/RL port Y that the half-pitch passes fan about, so a
+    vertical flow (which stacks its lines along X) and a section without an
+    LR/RL port both have nothing to measure against.
+    """
+    if lanes_run_along_x(section.direction):
+        return None
+    anchor = _section_lr_port_anchor_y(graph, section)
+    if anchor is None:
+        return None
+    pitch = _section_row_pitch(graph, section.id, y_spacing)
+    return (anchor, pitch) if pitch > 0 else None
+
+
+def _straddles_nothing(
+    station: Station, anchor: float, pitch: float, occupants: list[Station]
+) -> bool:
+    """True when *station* sits half a pitch off *anchor* with its mirror empty.
+
+    A half-pitch offset is meaningful only as one side of a pair straddling the
+    anchor, so the slot at the mirrored offset has to be occupied for the offset
+    to buy anything.  Stations a whole number of rows from the anchor are
+    already on the grid and never qualify.
+    """
+    offset = station.y - anchor
+    if abs(abs(offset) - 0.5 * pitch) > SAME_COORD_TOLERANCE:
+        return False
+    mirror = anchor - offset
+    return not any(
+        other is not station and abs(other.y - mirror) < SAME_COORD_TOLERANCE
+        for other in occupants
+    )
+
+
+def _expand_orphaned_half_grid_stations(
+    graph: MetroGraph,
+    y_spacing: float,
+    section_y_padding: float = SECTION_Y_PADDING,
+) -> None:
+    """Seat on a full row any half-pitch station whose pair partner moved away.
+
+    ``_recenter_full_bundle_columns``, ``_apply_half_grid_2branch_symfan`` and
+    ``_apply_half_grid_symmetric_diamonds`` place both members of a two-way
+    fork at ``anchor +/- 0.5 * pitch`` together, and
+    ``_carry_symmetric_branch_continuations`` marks each member's onward chain
+    on that member's Y.  ``_align_terminus_to_upstream`` is entitled to pull a
+    terminus member onto its producer's Y, and :func:`_straddles_nothing`
+    detects the partner left behind.
+
+    Seating derives the new Y from the row pitch rather than doubling the
+    measured offset, so the branch lands exactly on the row even though it
+    qualified within a tolerance band.
+
+    An off-track icon counts as a straddle partner while never being seated
+    itself: the off-track lift owns its Y, so it can hold a slot it must not be
+    moved out of.
+    """
+    require_phase_field(graph, "half_grid_station_ids")
+    half_grid = graph.half_grid_station_ids
+    if not half_grid:
+        return
+    for section in graph.sections.values():
+        marked = [sid for sid in section.station_ids if sid in half_grid]
+        if not marked:
+            continue
+        frame = _half_grid_frame(graph, section, y_spacing)
+        if frame is None:
+            continue
+        anchor, pitch = frame
+        occupants = _section_occupants(graph, section)
+        moved_ys: list[float] = []
+        for sid in marked:
+            st = graph.stations.get(sid)
+            if st is None or st.is_port or st.off_track or st.is_hidden:
+                continue
+            if not _straddles_nothing(st, anchor, pitch, occupants):
+                continue
+            st.y = anchor + math.copysign(pitch, st.y - anchor)
+            half_grid.discard(sid)
+            moved_ys.append(st.y)
+        if not moved_ys:
+            continue
+        # Only the expanded branch can have crossed an edge; sizing against the
+        # whole section instead would hand the bbox slack that the row-compact
+        # passes then take up by dragging unrelated content off its row.
+        _grow_section_bbox_over_ys(graph, section, moved_ys, section_y_padding)