Merge pull request #1567 from seqeralabs/fix/symfan-terminus-half-pitch

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

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)